Level 2 Help for MARSCOR3

First left eye image, then right eye image.

There is nothing actually requiring left/right order, other than convention.
If left/right is unclear (e.g. the images are not from a stereo camera) then
either order is acceptable.  If the output is used with MARSXYZ, the same
order must be used.  The order must also match that of the program used to
calculate input disparities (typically MARSJPLSTEREO).

The line and sample disparity files.  If one filename is given, a two-banded
file is created with line disparity as band 1 and sample disparity as band 2.
If two filenames are given, two single-band files are created.  Line disparity
is in file 1, and sample disparity is in file 2.

See the main program help for output file contents and formatting.

The input disparity images.  If one filename is given, a two-banded file
is expected with line disparity as band 1 and sample disparity as band 2.
If two filenames are given, the first file is expected to contain line
disparities and the second, sample disparities.

The size of the disparity image compared with the input images must be
related as specified by the DISP_PYRAMID parameter.

See the main program help for output file contents and formatting.

Optional output file showing the coverage of tiepoints (correlated pixels),
in BYTE format.
 0 dn means the pixel could not be reached in order to be correlated.
   (i.e. the input file had no disparity for the pixel).
 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 available in the input.

This file could be used in conjunction with a very low quality setting
to allow correlation in low-quality areas, with the result filtered
afterwards using a higher quality (i.e. use the output quality file as
a mask).  Unlike marscorr/marscor2, this is a reasonably safe operation,
as long as no gore passes were performed.  Gore passes, however, run the
same risk as marscorr/marscor2: if there is any kind of repeating pattern
in the image, the correlator could get "stuck" on the wrong match for the
pattern and propogate that error.

The IN_COEFS parameter allows the user to directly specify the transform on
a per-pixel basis.  The input file should be a 6-band file the same size
as the input disparity file, containing the parameters a,b,d,e,g,h.  Note
that the translation terms, c and f, are not included because they come from
the input disparity file.  Note that OUT_COEF can be used to save the
final coefficients, in the same file format.

The OUT_COEFS parameter specifies an optional file to contain the output
coefficients from the transform.  This will be a 6-band file the same size
as the output disparity file, containing the parameters a,b,d,e,g,h.  Note
that the translation terms, c and f, are not included because they are in
the output disparity file.  Note that IN_COEFS uses the same file format.

The vicar image band number for the input images.  Defaults to 1

Correlation size.  Must be an odd number.  Defaults to 15 square.

If only one value is given, a square template is used.  If two values are
given, the first is the template height (line direction) and the second is
the template width (sample direction).  Rectangular templates that are
wider than they are tall should be useful for lander images.

Correlation search area.  Must be an odd number.  Defaults to 35 square.
SEARCH must be > TEMPLATE.  If SEARCH is only a bit larger than TEMPLATE
then many correlations will abort because they will be prohibited from
searching in promising directions. 

If only one value is given, a square search area is used.  If two values are
given, the first is the search height (line direction) and the second is
the search width (sample direction).  Rectangular search areas that are
wider than they are tall should be useful for lander images.

Minimum acceptable correlation quality.  Correlations with qualities below
QUALITY will be rejected. Qualities range from 0 (poor) to 1 (excellent).

Note that this value is the square of the correlation coefficient.  The
definition of correlation coefficient is a/sqrt(b); we maximize a**2/b
instead to avoid the square root calculation (negative correlations are
checked for and given a negative result).  Therefore if a quality value of
(for example) 0.36 is given, that corresponds to a correlation coefficient
of 0.6.  The difference does not matter except insofar as people are used
to using the correlation coefficient number.

Defaults to 0.6  

Specifies whether or not gore passes are performed.  The default is not to
do them.  See the main help for details.

Specifies the maximum number of gore passes through the image to perform.
If the value is 0, the number of passes is unlimited.  The program will
stop making gore passes once a pass produces no more tiepoints, even if
GORE_PASSES has not yet been reached.

Limiting the number of gore passes prevents the correlator from "breaking
in" to invalid areas and getting "lost", such as often happens with
marscorr/marscor2.  Similar limiting may also be done via a high
GORE_QUALITY.

Specifies the correlation quality to be used during gore passes.  If not
specified, the value for QUALITY is used.

Usually, a reasonably low quality, such as 0.36, is acceptable for the main
correlation.  This is because we know a priori that all points considered
have passed the first correlation program, which acts as a kind of filter.
So it is quite likely that the point is good, even with a lower quality.

However, in gore filling, that filter no longer applies.  Any point could
be considered for correlation.  By setting GORE_QUALITY quite high (perhaps
.6 OR .8), WE INSURE THAT ONLY VERY GOOD POINTS ARE INCLUDED WITHOUT THE
benefit of the filter.  This prevents the correlator from getting "lost"
such as often happens with marscorr/marscor2 and generating spurious results.
Points not filled in by the first correlator may still be good for marscor3,
since the first correlator usually does only a square mapping, not a
quadrilateral mapping, from left to right, and square doesn't always work
very well.

This value is the square of the correlation coefficient, as with QUALITY.

Normally, gore passes are processed top-to-bottom, left-to-right.  As
each pixel is filled in, it becomes eligible to be a neighbor to the next
pixel.  So a gore pass can fill in arbitrarily far to the right or down,
but can only fill in one pixel to the left or up.  This often leads to
diagonal edges in coverage (moving down and to the left), as each successive
line is only able to move one pixel farther left.  Filling much up/left
requires a huge number of gore passes.

Turning on GORE_REVERSE enables a second iteration through the data in each
gore pass.  This second iteration processes in the reverse order... bottom-
to-top, right-to-left.  This allows it to fill in up and to the left as well
as down/right.  Note that one gore pass consists of going *both* directions.

The reverse pass can leave diagonal coverage edges moving up and to the right.
If 0 degrees is to the right and angles increase counterclockwise, then the
areas between 0 and 45 degrees, and between 180 and 225 degrees, will not be
filled by a single gore pass.  (Without reverse, the unfilled area is 0 to 225).
For this reason, it is recommended that at least two gore passes be used if
reverse is turned on.

Specifies the "pyramid level" of the input disparities.  The input is zoomed
down by a factor of 2 ^ DISP_PYRAMID.  This corresponds directly to the
PYRLEVEL parameter to MARSJPLSTEREO.

A value of 1, 2, or 3 is generally recommended.  Pyramids of 0 (no zoom) are
often susceptible to minor variations in the camera model and sometimes
produce sparse images out of MARSJPLSTEREO.  Higher pyramid levels are less
sensitive to the accuracy of the camera model and generally produce better
coverage.

See the main help for a discussion of the input file format and how it
relates to DISP_PYRAMID.

The STOP_PYRAMID parameter can be used in conjunction with DISP_PYRAMID and
MULTIPASS to stop the pyramid process prematurely.  Normally STOP_PYRAMID
is 0, meaning go all the way to full-res.  But if STOP_PYRAMID is non-0,
the process stops there.  A value of 1 would produce a half-scale output,
2 would produce quarter-scale, etc.  At least one pass is done regardless
of STOP_PYRAMID.  The intent of this is to facilitate debugging by being
able to examine the intermediate pyramid results; operational use is not
anticipated.  Note that the output can be fed back into another run of
marscor3 by adjusting DISP_PYRAMID to the prior STOP_PYRAMID value.

Specifies which mode of the gruen correlator to use.

All correlations are performed using the gruen correlation routine.  See
the gruen documentation for details of the algorithm.

The MODE parameter is fully described in the main program help.  Only the
five "amoeba*" modes are recommended.

Adds linear search to any MODE.  This can help when the initial point is more
than a pixel or two away from the true point, since the various amoeba modes
don't generally like walking more than that in the parameter space.  However,
the linear mode is limited to a square transform, so it may not match the
cemra geometry very well.  See the MODE parameter and description in the
main program help.

FTOL specifies the tolerance, or accuracy, in the function minimization
process (the correlation quality).  While directly related to accuracy of
the results, this relationship is not simple.  See the main help for a
more involved discussion.

Higher values of FTOL cause the program to run faster, sometimes MUCH faster,
at the expense of some accuracy.

Typical values range from .000001 (historically the only value; probably too
tight a tolerance) to .001 or .004.  This parameter should be experimented
with for each new type of data.

If non-zero, turns on reverse-check mode.  After every point is correlated
(whether in the main or gore passes), the pixel is again correlated in
reverse.  Instead of left-to-right, it goes right-to-left (right is the
template) using the current result as the starting point.  Thus a left-side
coordinate is obtained that matches the right-side image.

This coordinate is then compared to the original left-side coordinate.  If
they differ by more than CHECK pixels, the point is rejected.  (This is a
square window; line and sample are compared independently).

The result is that more "bad" pixels are filtered out, at the expense of
some time.  This may allow the quality to be lowered without getting too
many bad matches.

Note that CHECK should not be run with DECILEFT or ROTATION or X/YSCALE
as the inverse affine transformation is not fully implemented yet.

See also CHECK_QUALITY; the reverse check is omitted if the quality is
higher than CHECK_QUALITY.

Note that CHECK is not all that useful in the amoeba-only modes, because
we start at a known peak already.  The reverse check could be more useful
when combined with a -LINEAR search.  A true reverse check would do an
independent, complete right->left correlation, then compare the results.

Minimum threshhold at which the reverse check is performed.  The theory
is, if the quality is good enough, a reverse check is unnecessary.  See
the CHECK parameter.

If the pyramid value is more than 1, then it is quite likely that the
initial point obtained from the input disparity is off by more than amoeba
can handle, giving very "patchy" results.  The amoeba algorithm really
needs to start within a pixel or so for reliable results.

To handle this case, MULTIPASS may be specified.  If MULTIPASS is turned on
and DISP_PYRAMID is greater than 1, then the entire correlation process is
repeated multiple times.  At each iteration, the input image is downsampled
so it is twice the size of the input correlation map, for an effective
pyramid level of 1.  The result then becomes the input disparity map for
the next iteration.

So, for example, with MULTIPASS and DISP_PYRAMID=3, then input disparity
map is 1/8 the size of the input.  The first correlation is performed with
a 1/4 scale image pair (the full correlation, including gore passes).
The resulting 1/4 scale disparity is then correlated with a 1/2 scale image,
then the result of that is correlated with the full scale image to produce
the final result.

The default is not to do multiple passes.

Turns on a pre-correlation low-pass filter of the images.  This can tend
to reduce interpolation noise; see Quality of Results Discussion in the
main help.

Note that the filter is applied only to the full-res image.  If -MULTIPASS
is also used, only the last pass is filtered.  (Downsampling does an inherent
filtering so it is not needed).

The specific filter used is simply an NxN average of surrounding pixels,
with N given by FILTER_SIZE.  So with FILTER_SIZE=3, the 9 surrounding pixels
(including the central pixel) are averaged.

Specifies the size of the averaging window for -FILTER.  Must be an odd
number.  See -FILTER.

If one value is given, it applies to both the left and right inputs.  If
two values are given, the first applies to the left and the second to the
right.  This allows differential filtering levels, for use e.g. when
correlating different-scale images (such as the MSL mastcams).

Specifies where the primary input labels come from.  The default is
PI_FROM_DISP, meaning that the labels are transferred from the (first)
disparity input.  This preserves the history labels that the 1-D correlator
added.  However, it presumes that the 1-D correlator itself transferred
labels from the input images.

In the uncommon case of a disparity file where the labels are insufficient,
PI_FROM_INP can be used.  This causes the label to be transferred from the
first INP parameter.  This might be necessary if e.g. a synthetic disparity
map were created which did not have all the labels of the input.

Specifies the overall frame rotation (in degrees) between the two images.
A positive value says the right image should be rotated clockwise by that
amount in order to match the left.

This is not normally needed for standard stereo pairs.  However, for repointed
pairs, or arm-camera pairs, this can significantly improve amoeba's results.
The solution is more stable because amoeba is less likely to go off in bad
directions looking for the proper transform, especially when the correlations
are marginal due to noise.

Similar to ROTATION, but specifies the overall X-direction scaling factor
between the images.  This factor applied to the right image should produce
an image closely matching the left image's scale.

See ROTATION or the main help for more.

Excactly like XSCALE, except it applies in the Y direction (line) instead.

If FEEDBACK_COEFS is on, the perspective transform coefficients are
"remembered" from one pyramid pass to the next.  So for the next stage
of the pyramid, the starting point uses the coefficients derived from the
previous stage.  This helps retain the "shape" of the correlation window
mapping across pyramid levels.

Establishes limits for the allowed rotation values.  This is accomplished
by setting limits on the transform coefficients based on the range input,
so it is not a perfect limit (see discussion in main help).  If SCALE_RANGE
is given but ROT_RANGE is not, ROT_RANGE defaults to -5 to +5 degrees.

Establishes limits for the allowed scale.  This is accomplished by setting
limits on the transform coefficients based on the scale input, so it is not
a perfect limit (see discussion in main help).  If ROT_RANGE is given but
SCALE_RANGE is not, SCALE_RANGE defaults to 0.9 to 1.1.

Turns on or off parallel processing.  The default is on.  The main help
describes some environment variables that can further control parallel
processing.  Note that this program uses standard OpenMP (which is built in
to the gcc/g++ compilers), so further details can be found in the OpenMP
documentation.

The DATA_SET_NAME typically identifies the instrument that acquired the
data, the target of that instrument, and the processing level of the data.
This value is copied to the output label, property IDENTIFICATION,
keyword DATA_SET_NAME.

The DATA_SET_ID value for a given data set or product is constructed
according to flight project naming conventions.  In most cases the
DATA_SET_ID is an abbreviation of the DATA_SET_NAME.
This value is copied to the output label, property IDENTIFICATION,
keyword DATA_SET_ID.

When a data set is released incrementally, such as every three months during
a mission, the RELEASE_ID is updated each time part of the data set is released.
For each mission(or host id if multiple spacecrafts), the first release of a data
set should have a value of "0001".
This value is copied to the output label, property IDENTIFICATION,
keyword RELEASE_ID.

Specifies a permanent, unique identifier assigned to a data product by
its producer. Most commonly, it is the filename minus the extension.
This value is copied to the output label, property IDENTIFICATION,
keyword PRODUCT_ID.

Specifies the unique identifier of an entity associated with the
production of a data set. This value is copied to the output label,
property IDENTIFICATION, keyword PRODUCER_ID.

Specifies the identity of a university, research center, NASA center or other
institution associated with the production of a data set.
This value is copied to the output label, property IDENTIFICATION, keyword
PRODUCER_INSTITUTION_NAME.

Specifies a target.  The target may be a planet, satelite, ring, region, feature,
asteroid or comet.  This value is copied to the output label, property
IDENTIFICATION, keyword TARGET_NAME.

Specifies the type of a named target. This value is copied to the output
label, property IDENTIFICATION, keyword TARGET_NAME.

Whether or not to decimate the left template image if the difference
of resolution between the left and right images allows it, that is, if
left image resolution is at least twice higher than right image. See main 
program help for more information.

This parameter is used only if DECILEFT is ON.
If GLOBAL_DECI, then a unique factor of left image decimation is defined based 
of ROTATION, XSCALE and YSCALE. This decimation is happening whether or not 
COEFF_IN and/or FEEDBACK is activated. For each correlation pixel, the left 
image is decimated according to the decimation factor inferred from ROTATION,
XSCALE and YSCALE, and the affine parameters coefficients are adjusted
accordingly.
If LOCAL_DECI then decimation is decided for each pixel according to the 
affine transform coefficients. This option is only useful if COEFS_IN and/or
FEEDBACK is activated.
In either case, decimation occurs only if there is at least of a resolution
difference of at least 2 (left having 2 times more resolution than right).