User's Guide

PICMATCH

Matches two input images along a cutline

Function:

Image correlation routine used to match two input images along a cutline.

Parameters:

IN1
First input image. The first image to be correlated. The image must be a single band. No windowing is allowed. The input image may be BYTE, INTEGER*2, INTEGER*4, or REAL*4.

IN2
Second input image. The second image to be correlated. The image must be a single band. No windowing is allowed. The input image may be BYTE, INTEGER*2, INTEGER*4, or REAL*4.

TVAL1
First tie point line/sample values. Three to ten tie points in the first input image. The number of values specified in TVAL1 and TVAL2 must be equal. These values are to be filled in as tiepoint1 line, tiepoint1 sample, tiepoint2 line, tiepoint2 sample ...

TVAL2
Second tie point line/sample values. Three to ten corresponding tie points in the second input image. The number of values specified in TVAL1 and TVAL2 must be equal. These values are to be filled in as tiepoint1 line, tiepoint1 sample, tiepoint2 line, tiepoint2 sample ...

OUTFILE
Output file. Output image based information system (IBIS) graphics file. Contains the pairs of matching coordinate locations along with editing information. The format of this file is: first input line location, first input sample location, second input line location, second input sample location, first input Z value, second input Z value, correlation value, and sequence number.

INFILE(-- )
Input cutline file. Input IBIS graphics file containing the coordinates for the cutline or polygonal contours of the second input image to be used as the correlation point set. The polygon must be closed. The default value indicates that a cutline is not being used. If an input cutline (INFILE) and point increment (PNTINC) are specified, the correlation point set is spaced along the cutline. Otherwise, if no input cutline is given, a grid of points is used as defined by the GRIDSPEC, NROWS, and NCOLS parameters.

PNTINC(200)
Point increment. Spacing to be followed along the cutline. This is a required parameter when using an input cutline file (INFILE). If the GRIDSPEC parameter is used, then PNTINC is ignored.

STRSSIZ(128)
Starting search size. The initial size of the search area in the first input image. The search area is a STRSSIZ x STRSSIZ square region. The maximum starting size is 128.

MINSSIZ(50)
Minimum search size. The minimum size to which the search area could be reduced upon successful matching.

SCALFACT(1.,1.)
Scale factors. The values to be applied to the line and sample dimensions of the search area.

KERNDIM(10)
Kernel dimensions. The size of the square kernel grid used to calculate the average radiometric value (Z value) for the matching coordinates.

THRVAL(1000)
Threshold value. The number of pixel values in the kernel equal to zero that are accepted before the point is rejected. When a point is rejected, the value of 25 is written to the output graphics file in place of the average radiometric value.

MINCORR(180.)
Minimum correlation. The minimum correlation value for acceptance of a new point into the image-to-image geometric model.

HPFFLG(YES)
High-pass filter flag. Allows the default high-pass filter in the correlation to be shut off.


  = YES:  Apply high-pass filter.
  = NO:   Do not apply high-pass filter.

SPFLG(YES)
Subpixel correlation flag. Specifies whether or not the subpixel correlation is to be calculated.


  = YES:  Perform subpixel correlation.
  = NO:   No subpixel correlation.

EDGEFLG(NO)
Edge enhancement flag. Allows a simple 3 x 3 edge enhancement to be applied to both input subimages prior to correlation.


  = YES:  Perform edge enhancement.
  = NO:   No edge enhancement.

RETSPEC(--)
Retry specification. The retry specification allows more tries to be made near a location if a certain correlation threshold is not achieved. The first value specifies the number of retries (up to four). The second value is the correlation threshold. The third value is the distance to move in the line, sample direction from the current location. The retry pattern is to successively move to the corners of a square at this distance from the location. The default value indicates that no retries are attempted.

PRINT(TERM)
Output destination. The destination of the output.


  = TERM:      Terminal.  Output is sent to the user's
               terminal.
  = LP:        Line printer.  Output is sent to the 
               printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is 
               sent to the user-supplied file with 
               the extension ".prt".

GRIDSPEC(--)
Grid boundary specifications. Using line/sample coordinates, specify the upper-left (line then sample) and lower-right (line then sample) corners of the grid in the second image to be used as the correlation point set instead of the cutline. The default value indicates that a grid is not being used. If both a cutline (INFILE) and GRIDSPEC are specified, then the cutline will be used.

NROWS(--)
Number of rows. The number of grid cell rows in the grid. This parameter is required when using the GRIDSPEC option.

NCOLS(--)
Number of columns. The number of grid cell columns in the grid. This parameter is required when using the GRIDSPEC option.

Example:

  1. LAS> picmatch in1=us1 in2=us2 tval1=(100 100 3000 5000 5000 3000) tval2=(100 100 3000 5000 5000 3000) outfile=us infile=uscut pntinc=200 strssiz=64

    The input images US1;IMG and US2;IMG are correlated using the coordinates from USCUT;IBIS.GRAPH with a spacing of 200 as the correlation point set. The results are written to US;IBIS.GRAPH.

Description/Algorithm:

The program begins with the standard initialization and retrieval of user-specified parameters. The input images, the IBIS graphics file containing the coordinates of the cutline, and the output IBIS graphics file are opened. A geometric model is set up relating the two images. The geometric model is used to estimate a search location and to specify a resampling of the first image to match the raster gridding of the second image. Initially, the model is a linear least squares fit to the input tie points.

The second step is to set up the correlation point set in the second image by one of two methods. If an input cutline (INFILE) and point increment (PNTINC) are specified, the correlation point set is spaced along the cutline. Otherwise, if no input cutline is given, a geometric grid of points is used as defined by the GRIDSPEC, NROWS, and NCOLS parameters.

The iteration over the correlation point set then proceeds. At the requested point in the second input image, a 32 x 32 subimage is extracted. If the point is a fractional pixel location, the center of extraction is moved to align with pixel spacing to avoid interpolation. Interpolation will occur only if a nonintegral value is specified in the SCALFACT parameter. A search area in the first input image is then calculated using the geometric model. If this is a fractional pixel location, it is also aligned with pixel spacing to minimize interpolation near the center. A subimage of the determined size is then extracted from the first image. The size will be somewhere between the values of STRSSIZ and MINSSIZ. This subimage is extracted by bilinear interpolation at a rotation and pixel size to match the second input geometry as specified by the geometric model. If the user specified that edge enhancement should be performed, a simple 3 x 3 edge enhancement is applied to both subimages.

Correlation is performed on 32 x 32 windows of the subimages. The 32 x 32 pieces of the two inputs are each subjected to a complex valued Discrete Fourier Transform (DFT) via the Fast Fourier Transform (FFT) algorithm. One of the DFT arrays has its low frequency terms set to zero by zeroing the first row and the first column unless the user specified that the high-pass filter should not be applied. The DFT's are multiplied element by element (one DFT is conjugated), and also each product is divided by the absolute value of its multiplicands to give phase correlation. An inverse FFT is applied to this result and the peak and its eight neighbors are saved. The window is moved over the search area with an increment of at most 12 pixels. When the entire search area is covered, the largest peak is taken to be the correlation point. A final FFT correlation is performed at the correlation peak to get a refined correlation. Then, if specified by the user, a subpixel match is obtained by fitting a quadratic to the peak and its eight neighbors. The match point is calculated back to the original image location via the inverse of the geometric model and incorporating alignment shifts performed in both images.

If the user specified the RETSPEC parameter, the maximum correlation value for the current location is checked against the specified correlation threshold and more tries near the location are made if the threshold is not achieved. The retry pattern is to move to the corners of a square at the specified distance from the location.

After the matching locations have been determined, the average radiometric value of the kernel around the point is also determined for each image. The results are written to the output IBIS graphics file. Also, while the program is running, relevant information such as search size and the correlation maximum value are printed out. If correlation fails, nothing is written to the output IBIS graphics file, but a failure number is given in the output print-out under the FNR column heading. The failure numbers are:


	1       over 100 grid points outside image	
	2       correlation peak unreliable
	3	subpixel correlation failure
	4	failure of retry option

Points determined to be completely outside of either image are ignored.
Finally, the input and output files are closed and a completion message
is output.

Nonfatal Error Messages:

  1. [picmatch-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The output IBIS graphics file is still valid. The message that is displayed immediately preceding this message is the specific error that was encountered. Processing continues.

  2. [picmatch-window] Windowing is not allowed [picmatch-window] Full image size for <XXX> will be used

    The input images may not be windowed. Processing will continue using the full input image.

Fatal Error Messages:

  1. [picmatch-bands] Too many bands in <XXX> image

    Only single-band input images can be processed.

  2. [picmatch-fatal] Fatal error encountered

    A fatal error was encountered during processing. The output IBIS graphics file may or may not be deleted. The message that is displayed immediately preceding this message is the specific error that was encountered.

  3. [picmatch-grdspec] Missing grid specification

    Since an input cutline file was not specified, it is assumed that a grid is being used instead as the correlation point set. However, one of the parameters GRIDSPEC, NROWS, and NCOLS is missing or invalid so the grid could not be determined.

  4. [picmatch-open] Error opening <XXXXXX>

    An error was encountered while trying to open the specified file.

  5. [picmatch-read] Error reading cutline file

    An error was encountered while trying to read the coordinates of the cutline from the input IBIS graphics file.

  6. [picmatch-unequal] The number of values in TVAL1 and TVAL2 are not equal

    The TVAL1 and TVAL2 parameters work together and the same number of values must be entered for each one.

  7. [picmatch-write] Error writing output file

    An error was encountered while trying to write to the output IBIS graphics file.

User Note:

  1. Currently, the option to use a grid in the second input image (instead of a cutline) as the correlation point set has never been needed in production work and therefore has not been tested. The option was left in since it may prove useful in the future; however, the results are not guaranteed.