Help for MARSERROR

PURPOSE:
Given XYZ coordinates, disparity map, disparity errors, and perturbations 
in positions of left (reference) pixels, compute range errors in down-range, 
cross-range 1, and cross range 2 coordinate frame, along with an associated 
error ellipsoid volumes for each pixel. Compute range errors in x-y-z 
coordinate frame, along with associated error ellipsoid volumes for each pixel. 
Compute the magnitude of range error for each pixel.

This multimission program supports any mission, instrument, and 
camera model supported by the Planetary Image Geometry (Pig) software 
suite.

The inputs for MARSERROR are 
- left and right stereo pair.  Left and right images may be of different dimensions.
- a disparity image such as that created by the MARSCORR program.
  This can be a single 2-band file or two 1-band files.
- a disparity error image created by the MARSERRDISP program.
  This can be a single 2-band file or two 1-band files.
- an XYZ image such as that created by the MARSXYZ program.
  This can be a single 3-band file or three 1-band files; 
  see MARSXYZ for details.


EXECUTION:

./MARSERROR INP=\( LEFT RIGHT \)  OUT=RANGE_ERROR_VECTOR  DISPAR=DISPARITY  XYZ=XYZ  DISP_ERR=DISPARITY_ERROR  MASK=MASK  RANGE=RANGE_VALUES  RNG_ERR_MAGNT=RANGE_ERROR_MAGNITUDE  RNG_ERR_VOL=RANGE_ERROR_VOLUME  XYZ_ERR=XYZ_ERROR_VECTOR  XYZ_ERR_VOL=XYZ_ERROR_VOLUME  DELTA_REF_LINE=LINE_PERTURBATION_IN_REFERENCE  DELTA_REF_SAMP=SAMPLE_PERTURBATION_IN_REFERENCE  DELTA_DISP_LINE=LINE_PERTURBATION_IN_DISPARITY  DELTA_REF_SAMP=SAMPLE_PERTURBATION_IN_DISPARITY  POINT=CM=LABEL

./MARSERROR INP=\( LEFT RIGHT \)  OUT=\( DOWN_RANGE_ERROR CROSS1_RANGE_ERROR CROSS2_RANGE_ERROR \)  DISPAR=(\ LINE_DISPARITY SAMPLE_DISPARITY \)  XYZ=\( X Y Z \)  DISP_ERR=\( DISPARITY_LINE_ERROR DISPARITY_SAMP_ERROR \)  MASK=MASK  RANGE=RANGE_VALUES  RNG_ERR_MAGNT=RANGE_ERROR_MAGNITUDE  RNG_ERR_VOL=RANGE_ERROR_VOLUME  XYZ_ERR=XYZ_ERROR_VECTOR  XYZ_ERR_VOL=XYZ_ERROR_VOLUME  DELTA_REF_LINE=LINE_PERTURBATION_IN_REFERENCE  DELTA_REF_SAMP=SAMPLE_PERTURBATION_IN_REFERENCE  DELTA_DISP_LINE=LINE_PERTURBATION_IN_DISPARITY  DELTA_REF_SAMP=SAMPLE_PERTURBATION_IN_DISPARITY  POINT=CM=LABEL

where:

left - input - the left eye image of a stereo pair
right - input - the corresponding right eye image of a stereo pair
line_disparity - input - right eye line value computed by marscorr or other
  correlator.
sample_disparity - input - the right eye sample value computed by marscorr or other
  correlator.
disparity - input - 2-band file containing line_disparity and sample_disparity. 
XYZ - input - 3-band file with the X, Y, and Z values at that pixel in meters.
delta_ref_line  - specifies line perturbation in reference pixel.
delta_ref_samp  - specifies sample perturbation in reference pixel.
delta_disp_line - specifies line perturbation in disparity.
delta_disp_samp - specifies sample perturbation in disparity.
disparity_error - input - 2-band file containing disparity line and sample errors;
  computed by marserrdisp
disparity_line_error - input - disparity line error computed by marserrdisp 
disparity_samp_error - input - disparity sample error computed by marserrdisp
mask - output - 1-band file containing information on pixels 
  with valid XYZ coordinates.
range - output - 1-band image where each value is a distance between 
  reference point (by default camera position) and (x,y,z) point.
range_error_magnitude - output - 1-band file containing range error magnitude.
down_range_error - output - 1-band file containing down-range error
  for each pixel.
cross1_range_error - output - 1-band file containing cross-range 1 error
  for each pixel.
cross2_range_error - output - 1-band file containing cross-range 2 error
  for each pixel.
range_error_vector - output - 3-band file containing 
  down_range_error, cross1_range_error, and cross2_range_error.
range_error_volume - output - 1-band file containing volume of error ellipsoid
  for each pixel in down-range/cross-range coordinate frame.
xyz_error_vector - output - 3-band file containing x-y-z errors.
xyz_error_volume - output - 1-band file containing volume of error ellipsoid
  for each pixel in x-y-z coordinate frame.

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


EXAMPLES:

***** MSL data: *****

*** With two-band disp_err file specified: ***

$MARSLIB/marserror  inp=\( /home/yanovsky/marsxyz_data/FLA_406377036RADLF0010000FHAZ02504Z1.IMG /home/yanovsky/marsxyz_data/FRA_406377036RADLF0010000FHAZ02504Z1.IMG \)  out=rng_err.vic  dispar=/home/yanovsky/marsxyz_data/FLA_406377036DSPLF0010000FHAZ02504Z1.IMG  disp_err=/home/yanovsky/marserrdisp1/disperr2.vic  xyz=/home/yanovsky/marserror_v2_2/XYZ.vic  mask=mask.vic  range=range.vic  rng_err_magnt=rng_err_magnitude.vic  rng_err_vol=rng_err_vol.vic  xyz_err=xyz_err.vic  xyz_err_vol=xyz_err_vol.vic  delta_ref_line=0.1  delta_ref_samp=0.1  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label

*** No disp_err file (default disparity errors are assigned): ***

$MARSLIB/marserror  inp=\( /home/yanovsky/marsxyz_data/FLA_406377036RADLF0010000FHAZ02504Z1.IMG /home/yanovsky/marsxyz_data/FRA_406377036RADLF0010000FHAZ02504Z1.IMG \)  out=rng_err.vic  dispar=/home/yanovsky/marsxyz_data/FLA_406377036DSPLF0010000FHAZ02504Z1.IMG  xyz=/home/yanovsky/marserror_v2_2/XYZ.vic  mask=mask.vic  range=range.vic  rng_err_magnt=rng_err_magnitude.vic  rng_err_vol=rng_err_vol.vic  xyz_err=xyz_err.vic  xyz_err_vol=xyz_err_vol.vic  delta_ref_line=0.1  delta_ref_samp=0.1  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label

$MARSLIB/marserror  inp=\( /home/yanovsky/marsxyz_data/FLA_406377036RADLF0010000FHAZ02504Z1.IMG /home/yanovsky/marsxyz_data/FRA_406377036RADLF0010000FHAZ02504Z1.IMG \)  out=\( down_range.vic cross1_range.vic cross2_range.vic \)  dispar=/home/yanovsky/marsxyz_data/FLA_406377036DSPLF0010000FHAZ02504Z1.IMG  xyz=/home/yanovsky/marserror_v2_2/XYZ.vic  mask=mask.vic  range=range.vic  rng_err_magnt=rng_err_magnitude.vic  rng_err_vol=rng_err_vol.vic  xyz_err=\( x_error.vic y_error.vic z_error.vic \)  xyz_err_vol=xyz_err_vol.vic  delta_ref_line=0.1  delta_ref_samp=0.1  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label

$MARSLIB/marserror  inp=\( /home/yanovsky/marsxyz_data/FLA_406377036RADLF0010000FHAZ02504Z1.IMG /home/yanovsky/marsxyz_data/FRA_406377036RADLF0010000FHAZ02504Z1.IMG \)  out=\( down_range.vic cross1_range.vic cross2_range.vic \)  dispar=/home/yanovsky/marsxyz_data/FLA_406377036DSPLF0010000FHAZ02504Z1.IMG  xyz=\(x.vic,y.vic,z.vic\)  mask=mask.vic  range=range.vic  rng_err_magnt=rng_err_magnitude.vic  rng_err_vol=rng_err_vol.vic  xyz_err=\( x_error.vic,y_error.vic,z_error.vic \)  xyz_err_vol=xyz_err_vol.vic  delta_ref_line=0.1  delta_ref_samp=0.1  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label


***** MER data: *****

*** With two-band disp_err file specified: ***

$MARSLIB/marserror  inp=\( /home/yanovsky/Compression4/l3.IMG /home/yanovsky/Compression4/r3.IMG \)  out=rng_err1.vic  dispar=/home/yanovsky/Compression4_other/cor3disp_LeftRight3.vic  disp_err=/home/yanovsky/marserrdisp_v2/disperr1.vic  xyz=/home/yanovsky/Compression4_other/XYZ_cor3disp_LeftRight3.vic  mask=mask1.vic  range=range1.vic  rng_err_magnt=rng_err_magnitude1.vic  rng_err_vol=rng_err_vol1.vic  xyz_err=xyz_err1.vic  xyz_err_vol=xyz_err_vol1.vic  delta_ref_line=0.1  delta_ref_samp=0.1  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label

$MARSLIB/marserror  inp=\( /home/yanovsky/Compression4/l3.IMG /home/yanovsky/Compression4/r3.IMG \)  out=rng_err1.vic  dispar=/home/yanovsky/Compression4_other/cor3disp_LeftRight3.vic  disp_err=/home/yanovsky/marserrdisp_v2/disperr1.vic  xyz=/home/yanovsky/Compression4_other/XYZ_cor3disp_LeftRight3.vic  mask=mask1.vic  range=range1.vic  rng_err_magnt=rng_err_magnitude1.vic  rng_err_vol=rng_err_vol1.vic  xyz_err=xyz_err1.vic  xyz_err_vol=xyz_err_vol1.vic  delta_ref_line=0.0  delta_ref_samp=0.0  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label

*** No disp_err file  (default disparity errors are assigned): ***

$MARSLIB/marserror  inp=\( /home/yanovsky/Compression4/l3.IMG /home/yanovsky/Compression4/r3.IMG \)  out=rng_err2.vic  dispar=/home/yanovsky/Compression4_other/cor3disp_LeftRight3.vic  xyz=/home/yanovsky/Compression4_other/XYZ_cor3disp_LeftRight3.vic  mask=mask2.vic  range=range2.vic  rng_err_magnt=rng_err_magnitude2.vic  rng_err_vol=rng_err_vol2.vic  xyz_err=xyz_err2.vic  xyz_err_vol=xyz_err_vol2.vic  delta_ref_line=0.1  delta_ref_samp=0.1  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label

$MARSLIB/marserror  inp=\( /home/yanovsky/Compression4/l3.IMG /home/yanovsky/Compression4/r3.IMG \)  out=rng_err2.vic  dispar=/home/yanovsky/Compression4_other/cor3disp_LeftRight3.vic  xyz=/home/yanovsky/Compression4_other/XYZ_cor3disp_LeftRight3.vic  mask=mask2.vic  range=range2.vic  rng_err_magnt=rng_err_magnitude2.vic  rng_err_vol=rng_err_vol2.vic  xyz_err=xyz_err2.vic  xyz_err_vol=xyz_err_vol2.vic  delta_ref_line=0.0  delta_ref_samp=0.0  delta_disp_line=0.5  delta_disp_samp=0.5  point=cm=label



METHOD:
MARSERROR computes, for each pixel:
- range error magnitude;
- range error vector in down/cross-range coordinate frame (dr-c1-c2 coordinate frame);
- volume of error ellipsoid in dr-c1-c2 coordinate frame;
- range error vector in x-y-z coordinate frame;
- volume of error ellipsoid in x-y-z coordinate frame;
The program uses input camera models, disparity maps, XYZ coordinates for each pixel,
and line/sample perturbation values for pixels in left and right images.
Similar to marsxyz, the program calculates XYZ values for each perturbed pair
for each pixel.  The error is found when comparing perturbed XYZ coordinates with 
MARSXYZ program's calculated XYZ points, giving the range error vector in x-y-z
coordinate frame.  The error is projected onto down-range, cross-range 1, and 
cross-range 2 axis, resulting in range error in dr-c1-c2 coordinate frame.

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.

DISP_ERR: marserrdisp-generated. It consists of either two separate one-band
  files (disparity line error, disparity sample error), or a single 2-band
  file.

XYZ:  marsxyz(or similar)-generated. It consists of either three separate 
  one-band files (x, y, z), or a single 3-band file.  
  Units of XYZ input file(s) are in meters, in the coordinate system specified 
  by the COORD and COORD_SYS parameters.

Output file contents:

OUT:  marserror will generate either three separate one-band files 
  (down-range, cross-range1, cross-range2), or a single 3-band file, depending 
  on the number of filenames given.

RNG_ERR_VOL: single-band file with volume of error ellipsoid in
  dr-c1-c2 coordinate frame, for each pixel.

MASK: single-band image file with values equal 100 for pixels containing
  valid XYZ coordinates, and values equal 0 for pixels missing XYZ coordinates.

RANGE: single-band image where each value is a distance between reference point 
  (by default camera position) and (x,y,z) point.  This is the same product that 
  can be generated using marsrange program.

RNG_ERR_MAGNT: single-band image with range error magnitude values.

XYZ_ERR: 3-band file with range error vector in x-y-z coordinate frame.

XYZ_ERR_VOL: single-band file with volume of error ellipsoid in
  x-y-z coordinate frame, for each pixel. 



HISTORY:
  2012-06-07 I. Yanovsky and B. Deen - Initial marserror
  2013-03-01 Igor Yanovsky. - Added functionality for accepting disparity line and error file
             as input.  Disparity error file contains pixel-to-pixel estimates 
             of error and is generated with marserrdisp program.
  2019-10-16 W. Bunch - IDS-7926 - initialized some variables; cleaned up -Wall warnings.
  2020-03-20 W. Bunch - IDS-7927 - replaced sprintfs calls.

COGNIZANT PROGRAMMER: I. Yanovsky

PARAMETERS: