Help for MARSCORR

PURPOSE:
To compute, from a stereo pair of images, the line and sample disparity
of every pixel in the scene.  The output is typically run through the
program MARSXYZ to generate X,Y,Z coordinates over the entire image.

This is a general-purpose correlation program, which does not make use of
any pointing or camera model information.  The input images do not have to
be registered or epipolar aligned, as long as appropriate seed point(s) are
provided.

This program is derived from Mars Pathfinder's MPFTPT.

EXECUTION:
marscorr inp=(left,right) out=(line_disparity,samp_disparity) mask=mask params

where:
left is the left eye image of a stereo pair
right is the corresponding right eye image of a stereo pair
line_disparity is the right eye line value, for each pixel in the left image.
samp_disparity is the right eye sample value, for each pixel in the left image.
mask is a completion status.  

Although "left" and "right" are used above, there is no actual restriction
that the first image be left and the second be right.  Correlations are done
from the first image to the second.  Output images (disparity and mask)
correspond to the first image, containing matching coordinates in the second
image.  However, for convenience, "left" and "right" are used throughout
this help.

Additionally, out_quality can be used to name an output file which will
contain the correlation qualities for each pixel.

METHOD:
A seed point is used as an initial guess to obtain an initial correlation,
using a wide search area (defined by AMAX(2)).  A region is grown from the
seed outward in a spiral-like pattern until the picture is filled.

For each pixel, the 8 neighbors are examined to find the one with the best
correlation value so far.  This neighbor is used as the initial guess for
the pixel in question (modified +/-1 as appropriate).  If no correlated
neighbors are found, the pixel is skipped.  The correlation window is
defined via the TEMPLATE and SEARCH parameters.

Once the region has grown to the size of the image (or TPTLIMIT pixels have
been correlated), a second pass goes through the region and attempts to
fill gores, or pixels that did not correlate on the first pass, by again
examining all of its neighbors (since neighbors on the other side, which
were not done previously, might provide a better starting location, which
will correlate, especially near edges).  This process continues until no
more gores are filled in a pass.

If an input tiepoint file (generated by MARSTIE) was provided, the tiepoints
in that file are used as multiple seeds.  The entire process above is repeated
in turn for each seed.  If a seed point has already been correlated via a
region grown from a previous seed, the new seed is ignored.  Multiple seed
points are good for areas separated from the rest of the image by large
disparity displacements or uncorrelateable areas such as undifferentiated
sand.

All correlations are performed using the gruen correlation routine.  See
the gruen documentation for details of the algorithm.  Seed points are
always correlated using mode 3 (linear followed by amoeba) to handle large
offsets.  The rest of the points may be correlated using any gruen mode
via the MODE parameter:

linear:            gruen mode 0
annealing:         gruen mode 1
amoeba:            gruen mode 2
linear_amoeba:     gruen mode 3
annealing_amoeba:  gruen mode 4
amoeba2:           gruen mode 5
linear_amoeba2:    gruen mode 6

Of the above, only amoeba and amoeba2 (modes 2 and 5) are recommended.  The
others are provided only for experimentation, and may significantly increase
the execution time of the program.  The annealing modes are not fully
implemented in the code at this time, but it would be trivial to do so if
desired.

The amoeba mode uses a full 6 degree of freedom search from the starting point
(derived from the best neighbor).  The starting point must be within 2 pixels.
The amoeba2 mode uses only 2 degrees of freedom (x/y offsets only) so it will
be faster, at the possible expense of accuracy.  The starting point must also
be within 2 pixels.  amoeba2 is not recommended for images that are not derived
from a stereo camera, e.g. using different instruments or involving motion
between the two frames.  The other modes generally do not have a 2 pixels
starting point limitation, so they might be useful for scenes with wildly
varying disparity values.  However, they are so slow that it will usually be
better to supply multiple seed points in each area using MARSTIE.

The template (correlation patch) and search area sizes may be rectangular
instead of square.  For landed images such as Mars Pathfinder or the Mars 98
lander, it may be advantageous to specify areas that are much wider than
they are tall.

Output file contents:

All output files are in the coordinates of the first (left eye) image.
For example if the sample disparity file has a value of 56.67 at sample 50
it means that the sample location of a tiepoint located at sample 50 in the
left eye image corresponds to sample 56.67 in the right eye image.   

The line and sample disparities are normally in two separate files.  However,
if only one filename is provided, both are written to a single, 2-banded
file, with line in the first band and sample in the second.

First output (or band): A REAL image containing the line disparity.  The
line/sample coordinate of each pixel in the output defines the position
in the left eye.  The value of the pixel contains the line coordinate of
the corresponding pixel in the right eye image.

Second output (or band): A REAL image containing the sample disparity.  The
line/sample coordinate of each pixel in the output defines the position
in the left eye.  The value of the pixel contains the sample coordinate of
the corresponding pixel in the right eye image.

If both line & sample disparity values are 0.000 the point has no value
(meaning correlation failed for that point).

Note that all disparity values use 1-based coordinates for the right
image, per VICAR conventions.

Mask file (optional): A BYTE image showing the coverage of tiepoints.
 0 dn means the pixel could not be reached in order to be correlated
   (i.e. there were no neighbors to supply an initial value, or TPTLIMIT
   was reached).
 128 dn means a correlation was successfully performed at this location.
 255 dn means a correlation was attempted at this location but it failed,
   usually because of low correlation quality.

Output quality file (optional): A REAL image containing the correlation
quality of each pixel attempted, from 0 to 1.  0 indicates either a
correlation failure unrelated to the QUALITY setting, or a pixel that was
not reached (the MASK output can distinguish).  Note that the file will
contain just a thin border of poor-quality pixels around each area,
because poor-quality pixels prevent the correlator from searching farther
in that direction.

HISTORY:
12-1-95  Initial MPFTPT program by J Lorre. 
July 99  Signficant internal restructuring and addition of features.
         Program renamed to marscorr.  Bob Deen
COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: