Help for TRACKER3

PURPOSE:
To acquire tiepoints between two images. Tiepoints can be on a sparse grid 
or as close as every pixel. The program operates in batch mode only.
There are two tiepoint acquisition strategies:

1. To acquire points on a regular grid.
2. To read tiepoint locations from an input tiepoint file and correlate these
   locations only. Chaining of tiepoints is permitted.

To edit tiepoints already in a tiepoint file you can use interactive program
tptedt or batch program tptedt2.
This program obsoletes TRACKER and TRACKER2

EXECUTION STATEMENT:

Creating a new grid of tiepoints:
    tracker3 inp=(left,right) out=x 

Reading initial tiepoint locations from a tiepoint file:
    tracker3 inp=(left,right,x) out=y

Chaining the same tiepoints through several images:
    tracker3 inp=(a.img,b.img) out=t1.pts grid=40
    tracker3 inp=(b.img,c.img,t1.pts) out=t2.pts 'extend
    tracker3 inp=(c.img,d.img,t2.pts) out=t3.pts 'extend

METHOD:
  The program has two basic modes and a choice of 5 correlation schemes.

Mode 1:
   For two input files a grid is created on the first input image.
A corresponding grid is created on the second input image at the same
locations and each intersection is correlated. Only the right grid
intersections are permitted to move.

Mode 2:
   For three input images the third input file is read and interpreted as 
initial tiepoint locations. No grid is generated. Each tiepoint is
assumed to consist of 4 numbers representing the first and second input
image locations first(line,sample) coordinates and second(line,sample)
coordinates. Either all 4 are read and applied to their respective images 
or only the second pair is read (see EXTEND keyword). If only the second pair
is read it will be copied and used on both images. This permits chaining
of tiepoints through a movie sequence.

  This program offers a suite of correlation schemes most of which provide
the Gruen correlation method. This method permits distortion of the 
correlation area in order to accomodate parallax, and can provide excellent
accuracy in cases where linear correlators fail completely.
  The Gruen scheme used here permits distortions between correlation areas of
the form:
newline=line*A+sample*B+C
newsamp=line*D+sample*E+F
The task of the correlator is to determine the coefficients A-F which permit 
the best correlation value.
  All the correlation schemes use the same figure of merit or objective
function. This is a least squares fit between the template and the search
area. The correlation value is the coefficient of determination for this fit.
It ranges from 0 to 1. Zero means no correlation at all, and one means perfect
correlation or anti-correlation.
  The effect of the above is that two areas can correlate well even if the
data has been:
1. Multiplied, added to, or complemented (any linear intensity mapping 
   is handled).
2. Rotated, scaled, flipped, transposed, or skewed.

The correlation options include:

LINEAR    
  This is a conventional image domain correlator performed on integral
pixel boundaries followed by an interpolation to achieve sub pixel precision.
No gruen correlation is available here.
Best for large area searches where little rotation or scale differences
occur. Best precision is 1/10 pixel. Fastest method.

ANNEAL
  This is an unconventional non-deterministic search based upon the annealing
algorithm Metropolis. Best for large area searches where rotation and
scale are unknown. Slowest method by far. User tailorable using the 
parameters LIMIT and COEFRANG. Best precision is user determined.
The default value of LIMIT should give a precision of about 1/20 pixel with
clean data.

AMOEBA
  This is a deterministic downhill simplex search. Slightly slower than LINEAR.
Provides the highest precision (to 1/100 pixel) and unlimited distortion 
capability. 
Limitation: The initial guess must be within the correlation peak or else 
the tiepoint will be in error. This might mean that the 6 polynomial
mapping coefficients should ALL be close to the correct result. The only
way to assure this in extreme rotation cases is to use the ANNAMO mode.
(This is not an easy problem even for humans.)

LINAMO   (the default mode)
  This uses the LINEAR mode first to get a starting position and finishes
with the AMOEBA mode as the end game.

ANNAMO
  This uses the ANNEAL mode first to get a starting position and finishes
with the AMOEBA mode as the end game.

KQKKOR
 This mode uses a correlation technique from 
Ackermann F. (1984). Digital image correlation : performance and 
potential application in photogrammetry. 

 It is ultimately uses a least squares fit for 6 parameters described
above. KQKKOR is also used in VICAR TP program. Tests showed that
KQKKOR generally works faster than LINAMO technique. KQKKOR demonstrated 6 
to 10 times improvement in speed over LINAMO. However, the number of matches
produced by KQKKOR was less than number of matches produced by LINAMO
by about 80%. On other hand KQKKOR returns less noisy tiepoints. If
you have a lot of images to do the tracking, we recommend compare
LINAMO and KQKKOR using samples from the sequence and decide which
method works better. Be careful, if the template window size (nlw) is
getting small ( < 5 pixels). Correlator might not have enough
information to find the answer. 

For those of you who wish to embed the Gruen correlator into their own C 
programs just copy out of Tracker3 the subroutine Gruen and it's called
routines into your source code. You only need the two #define statements
# define MAX_LEFT_AREA n  ( n is the max template size dimension, ie: n by n)
# define MAX_RIGHT_AREA m  ( m is the max search size dimension, ie: m by m)

PROGRAM HISTORY

Author: Jean Lorre
Revisions:
  2000-06-15 abi - Added KQKKOR correlation mode. 
  2017-08-11 wlb - Removed DEBUG from imake.
  2019-08-06 wlb - IDS-7923 - removed sprintfs, cleaned up most -Wall warnings, still a
  	     	   few incompatible pointer types being passed around, added seed to tst 
		   gausnois for test repeatability.