Help for CORRELATE1D

PURPOSE:
  To compute 1-d correlated tiepoints between two images.
  The input stereo pair must have horizontal epipolar lines.
  The left image is fixed. The right image is variable.

EXECUTION:
   correlate1d inp=left,right out=ldis,sdis parameters
where:
   left is an image where templates are selected at every pixel.
   right is an image which is searched over to refine tiepoint locations.

   ldis and sdis are disparity images. The integer index
   in these images corresponds to the left image coordinate. The value
   at the index corresponds to the right image location. ldis is the
   line disparity and sdis is the sample disparity.

   for example: (sample,line)
   if sdis(10,100) is 11.3 and ldis(10,100) is 102.1 then the left image
   coordinate at (10,100) lies at sample 11.3 and line 102.1 in the right
   image. Inspect the "delta" keyword for an alternative format. A value of
   zero for ldis or sdis means the pixel could not be correlated well.


METHOD:
  This is a simple 1-d correlator which is executed on each input pixel
location. You can include more than one line at a time. At each input pixel a
template NSW by NLW pixels is correlated within a search area of width +-
MOTION pixels. When the highest correlation is located a quadratic is fitted
to the 3 nearest points to give a sub pixel estimate. 
   One of the hazards of stereo pair correlation from rover images is the
occlusion of background by foreground rocks. To avoid the correlator including
terrain at different distances within the same window the left and right
halves of the NSW template is correlated independently. The resulting
correlation quality is the larger of the two. Thus if NSW=41 then the
actual correlation width will be 21.
   An analysis is performed to determine the vertical offset between the
two input images. 20 lines are selected and a patch N pixels wide in the 
center is correlated across the entire image width and up and down by
+- M lines ( see GEOM=M,N parameter). The best vertical offset is added to
a histogram of offsets. The offset with the most counts gives the vertical
shift between images. Parameter OFFSET overrides this step. 
   In order to minimize the search an analysis is performed to locate the 
horizontal displacement between lines as a function of line number. 
This is performed by correlating the central N pixels (see GEOM=M,N parameter)
of every line across the entire image. The result gives the horizontal offset
for each line. This is used to start correlations near the correct offset
so that the correct correlation match will lie within +- MOTION pixels.
Note that this will not work well if the cameras are severely tilted.
To erase bad results the offset table is convolved by a median filter
31 lines long. 
   The correlator relies upon a single figure of merit which is maximized. This
is the correlation value, sometimes called Pearson's r. It is the quality of a
least squares fit between the dn (intensity) vales in the template and the
search area. If x and y are the template and search dn's then r is computed
from:                 sum(x*y)-sum(x)*sum(y)/n
  r^2=--------------------------------------------------
        [sum(x*x)-(sum(x))^2/n][sum(y*y)-(sum(y))^2/n]
Notice that the correlation quality is independent of scale or offset.
   After all correlations are performed the disparity images (outputs) are
used to permit a second correlation in the reverse direction, from right to 
left. This should give results similar to the left to right operation, but 
never exactly, since the correlation is sub pixel and the template is 
always begun on an integer pixel boundary. Those points which match to within
THRESH pixels are kept. The rest are set to zero. This test will often locate
image areas where terrain is visible to one eye but not to the other.
Tiepoints in error are unlikely to match in both directions.
   Finally the user can invoke a gore removal scheme (see NOGORES keyword).
This step only interpolates over gores which are 1 line or 1 sample thick.

HISTORY:
11-1-2003  J Lorre. 
COGNIZANT PROGRAMMER:  Jean Lorre