Help for PICMTCH4

PURPOSE

     "picmtch4"  is a batch oriented image correlation routine 
     which incorporates the following features.

     1. Correlation  of  image  to image.

     2. Sampling  of one image to match the geometry of  the 
        other  image (e.g.  one image could be at  different 
        scale or rotation).

     3. Regular or phase correlation in the FFT domain.
     4. Specification of a magnification factor to correlate 
        a larger area without increasing computation.

     5. Use  of  a geometric model to estimate the  matching 
        locations  and  feedback of matches  to  refine  the 
        geometric model.

     6. Matching of images along a polygonal contour.

     7. Use  of  standard  data formats for  all  input  and 
        output data sets.

     8. Apodization is used for elimination of false peaks due
        to strong edge effects and for enhancement of subpixel
        matching.

     TAE COMMAND LINE FORMAT

     picmtch4 INP=(A,B,C) OUT=D      PARAMS

     where

     A                   is the first image to be correlated.

     B                   is   the   second   image   to   be 
                         correlated.

     C                   is  an ibis file containing the points
                         to match in columns (1,2) and 9 more
                         empty columns.

     D                   is an output image containing visuals
                         of the matching areas.  


OPERATION

     First,  "picmtch4" sets up a geometric model relating the 
     two images using the ITIE-OTIE parameters.   The points 
     originally  given  are supplemented  by  matches  in the
     second image.   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.   The model is a linear least squares fit to the 
     control  points.   For normal image to image  matching, 
     only  ITIE-OTIE  points  are  needed.   Their  accuracy 
     should be sufficient to yield a match within the search 
     area  specified  by parameters SEARCH and  MINSRCH  taking 
     into account nonlinearities in the data.
     
     If no ITIE-OTIE points are given, the program  will try
     to find GeoTIFF labels,  and will use them  to generate
     a  set of  ITIE-OTIE points  using the  labels and  the
     corners of the first image.
     
     For each point from the IBIS file taken in the first data
     set, the iteration over the correlation  point  set now 
     proceeds.   At the predicted point in the second input, 
     a FFTSIZxFFTSIZ sub-image is extracted. If the point is  a 
     fractional pixel location,  the center of extraction is 
     moved   to   align   with  pixel   spacing   to   avoid 
     interpolation.   In fact, interpolation will occur only 
     if  the keyword MAGNIFY is used with a nonintegral  value.  
     The  geometric  model  is used to  calculate  a  search 
     location in the first input.   If this is a  fractional 
     pixel  location,  then  it is also aligned  with  pixel 
     spacing  to minimize interpolation near the center.   A 
     sub-image is extracted of size WxW where W is somewhere 
     between  the values given by the parameters SEARCH  and 
     MINSRCH.  This  sub-image  is  extracted  by   bilinear 
     interpolation at a rotation and pixel size to match the 
     second  input  geometry as specified by  the  geometric 
     model discussed earlier.

     The FFTSIZxFFTSIZ pieces of the two inputs
     are each subjected to a complex valued DFT via the  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 parameter NOHPF is  specified.  
     Then  the DFT's are multiplied element by element  (one 
     DFT is  conjugated).  An  inverse  FFT  is  applied  to
     this  result and  the  peak  and  its  eight  neighbors 
     are saved.     The  subwindow 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 correla-
     tion is performed at the correlation peak to get a refined 
     correlation.   Unless NOSUBPIX is specified a subpixel 
     match is  obtained by  fitting a quadratic  to the peak  
     and  its  eight neighbors. The match point is transformed 
     back to  the original image location  via  the  inverse  
     of   the geometric  model  and  incorporating  alignment  
     shifts performed in both images.  

     The results are written to the IBIS interface (tabular)
     file with one row for each tiepoint.  The following 
     column format is used:

     Column       Description			   Format

        1     First input line or East             real*4
        2     First input sample or North          real*4
        3     First input line                     real*4
        4     First input sample                   real*4
        5     First input z-value                  real*4
        6     Second input line                    real*4
        7     Second input sample                  real*4
	8     Second input z-value                 real*4
        9     Correlation value                    real*4
       10     line-residual                        real*4
       11     sample-residual                      real*4
       optional (must use ELVCOR keyword)
       12     line-elevation offset                real*4
       13     sample-elevation offset              real*4

    Information about each matching point is printed out unless 
    the NOPRINT keyword is specified.   The printed information
    is as follows:

        1   SEQ			Sequence number
	2   SECOND LOCATION	Tiepoint location in second image
	3   ESTIMATED LOCATION	Estimated location in first image
	4   FIRST LOCATION	Matching location in first image
				    (from correlation search)
	5   CORREL		Correlation value (between 0 and 1)
	6   WIN			Current search window size
	7   RESID		Residual distance (between estimated 
				    location and correlation location)
	8   FN			Failure number

     If correlation  fails,  nulls are written into the ibis 
     file  and  a failure number is given  in  the  printout 
     under the column heading FN.  The failure numbers are:

              1             point on edge of second image 
				(more than zerolim percent of chip off image)
              2             failure of RETRY option to exceed threshold
              4             correlation peak unreliable
              5             subpixel correlation failure


     Points  completely outside of either image are ???.




PRECISION

Due to the iterative nature of the subroutine llsq, the programs results will
vary from machine to machine.  When prnt in llsq's test program was temporarily
changed to a write statement, it was observed that the resulting output varied
from machine to machine.  The following table will provide some idea of the
differential between machines.

                PORTED VMS  ALPHA &     SUN        SGI        SOLARIS
                            UNPORT VAX
FINAL FIT: LINE -81.20914   -81.20914   -81.20908  -81.20908  -81.20908
FINAL FIT: SAMP  15.19182    15.19181    15.19191   15.19190   15.19191



RESTRICTIONS

     The ground control chip file option (use of IBIS graphics-2 
     files)  is not currently supported.


REFERENCES

     C.  D.  Kuglin and D.  C. Hines, "The phase correlation 
     image alignment method," Proc.  IEEE 1975 International 
     Conference on Cybernetics and Society, September, 1975, 
     pp. 163-165.


Original Programmer:  A. L. Zobrist    12 October 1981

REVISIONS:
  1981-10-12 ALZ - Original version.
  1995-05    CRI - Made portable for UNIX
  2000-09-09 ALZ - Rewritten in C including the FFT subroutines.
  2002-08-27 ALZ - lsq routine uses normalization for keystone, quad, cubic, but
             not in the fit yet.
  2002-11-03 ALZ - quad added to fit, redo param added.
  2007-12-29 WLB - Switched to USES_ANSI_C AND LIB_CARTO; misc cleanup.
  2016-03-07 WLB - Migrated to MIPL.
  2017-08-11 WLB - Removed DEBUG from imake.
  2019-09-06 WLB - IDS-7922 - Initialized some variables; cleaned up -Wall warnings.
  2022-07-14 B. Crocco afids to opensource
  

PARAMETERS: