Help for MARSXYZ

PURPOSE:
To compute, from a disparity map, the XYZ coordinates of each point in
a stereo pair.

This is a multimission program derived from Mars Pathfinder's mpfxyz.
It supports any mission, instrument, and camera model supported by the
Planetary Image Geometry (Pig) software suite.

The XYZ coordinates are in a coordinate system defined by the COORD and
COORD_INDEX parameters.  This defaults to the Fixed frame for the mission
(see the COORD and COORD_INDEX parameters).

Best results are obtained if the images are actually a stereo pair, but
this is in theory not a requirement.  Images from different locations
and instruments should be usable, as long as disparity maps can be
generated.

EXECUTION:
marscorr inp=(left,right) out=(line_disparity,sample_disparity) ...
marsxyz inp=(left,right) dispar=(line_disparity,sample_disparity)    out=xyz.img err_file=error.img parameters
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 computed by marscorr or other
  correlator.
sample_disparity is the right eye sample value computed by marscorr or other
  correlator.
xyz.img is a 3-band file with the X, Y, and Z values at that pixel in meters.
error.img is the view ray miss distance in meters

Any correlation program producing the correct kind of disparity map may
be used; marscorr is simply an example.

METHOD:
Marsxyz computes, for each pixel, two view rays using the input camera models 
and the disparity maps.
It locates the closest approach point for the two vectors. These become the xyz
coordinates in local level mars coordinates (for MPF, M98).

Input file contents:

INP: left eye view, right eye view

Note that there's no actual requirement that the first input be left or the
second right.  The two images can be given in any order.  The first image,
though, is the "master" image; the disparity maps and output files match the
first image's pixels.  Convention places left first, however.

Also, the actual image pixels are not used from these files; only the label
information (to get the pointing and thus camera models) are used.

DISPAR: REAL-formatted images giving the line and sample disparity.  Either
two files may be given (line, sample order), or a single file with two bands.

The disparities are interpreted as follows:  Each pixel in the disparity
map corresponds to the same pixel in the first (left) input.  The value of
the pixel in the disparity map is the line and sample of the point in the
second (right) image, which matches this location in the first (left).  Note
that these are standard VICAR 1-based file coordinates.  If both line and
sample disparity values are 0, the point has no value.

Output file contents:

OUT:  marsxyz will generate either three separate one-band files (x, y, z), or
a single 3-band file, depending on the number of filenames given.  The output
files are in the coordinates of the first (left eye) image. This means there
is a 1:1 correspondence between pixels and the first input file.

Units of XYZ are in meters, in the coordinate system specified by the
COORD and COORD_SYS parameters.

ERR_FILE:  This is the miss distance between the view rays for each pixel,
in meters.  It is also in coordinates of the first (left) image.


There are various reasons points are rejected by MARSXYZ, most of them
controllable via parameters.  A summary of points rejected for each reason,
as well as successfully computed points, is printed at the end of the run.
They are:

Rejected n points for missing correlation
    These points failed to correlate.  This is normally a large number.
Rejected n points for excessive line disparity
    Adjusted by LINEDISP parameter.
Rejected n points for exeeding average line disparity
    These points exceeded the local average line disparity.  Adjusted by
    AVGLINEDISP, BOX_WIDTH, and BOX_HEIGHT parameters.
Rejected n points as not computable
    The miss-distance calculation failed, possibly due to parallel rays.
    Should always be 0.
Rejected n points for excessive absolute miss distance (abserror)
    Adjusted by ABSERROR parameter.
Rejected n points for excessive miss distance per range (error)
    Adjusted by ERROR parameter.
Rejected n points for exceeding Z limits
    Adjusted by ZLIMITS parameter
Rejected n points due to diverging rays
    Diverging rays put the XYZ point "behind" the camera and are always
    rejected.  Should always be 0; if not, a bad camera model or bad
    correlations are likely suspects.
Rejected n points for exceeding range limit
    Adjusted by RANGE_LIMIT and RANGE_FACTOR parameters.  The actual range
    limit used is printed out early in the log.
Rejected n points for exceeding spike value
    The point differs from its neighbors in XYZ space by more than a threshold.
    Adjusted by SPIKE and SPIKE_BOX parameters.
Rejected n points for exceeding spike value per range
    As above, but the threshold is based on the range to the point.
    Adjusted by SPIKE_RANGE and SPIKE_BOX parameters.
Rejected n points for being outliers
    Points that do not have enough valid neighbors are defined as outliers.
    Adjusted by OUTLIER and OUTLIER_BOX parameters.
Computed n valid XYZ points
    The number of valid XYZ points in the file.


COGNIZANT PROGRAMMER:  Bob Deen

HISTORY:
  1995-12-1  J Lorre - Initial mpfxyz
  1999-03    B. Deen - Multimission conversion
  2003-02    B. Deen - Additional rejection filtering; rejection reasons reported
  2004-02    B. Deen - Added AVGLINEDISP and ABSERROR
  2007-08    B. Deen - Added spike and outlier filters
  2019-12-12 W. Bunch - Initialized some variables; cleaned up -Wall warnings; added unit test
  2020-05-26 W. Bunch - Replaced sprintfs

PARAMETERS: