Help for MARSERRDISP

PURPOSE:
Compute disparity line and sample errors from inverse scene activity coefficients
and compression.

The inputs for MARSERRDISP are 
- left and right stereo pair.  Left and right images may be of different dimensions.
- Optional: Correlation coefficient image, such as that created by the MARSCOR3 program,
            is an optional and is currently not used in calculations.

EXECUTION:

./MARSERRDISP  INP=\( LEFT RIGHT \)  OUT=DISPARITY_ERROR  LS_ORDER=LEAST_SQ_ORDER  DISP_UNC=INV_SCENE_ACTIVITY_COEFF  POINT=CM=LABEL

./MARSERRDISP  INP=\( LEFT RIGHT \)  OUT=\( DISPARITY_LINE_ERROR DISPARITY_SAMPLE_ERROR \)  LS_ORDER=LEAST_SQ_ORDER  DISP_UNC=INV_SCENE_ACTIVITY_COEFF  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
disparity_error - output - 2-band file containing disparity line and sample errors
disparity_line_error - output - disparity line error 
disparity_samp_error - output - disparity sample error
inv_scene_activity_coeff - output - inverse scene activity coefficient

ls_order - specifies the order of the least squares fit (model). ls_order = 1 is the only
           supported choice.
corrcoeff - input - correlation coefficient image computed by marscor3 - currently not used

EXAMPLES:

MER FCAM:
./MARSERRDISP  INP=\( ~/MER_DATA/2F137291704RAL4406P1212L0M1.IMG ~/MER_DATA/2F137291704RAL4406P1212R0M1.IMG \)  OUT=DISPERR1.VIC   DISP_UNC=DISP_UNC.VIC  WSIZE=25  POINT=CM=LABEL

MSL test:
./MARSERRDISP  INP=\( ~/MARSXYZ_DATA/FLA_406377036RADLF0010000FHAZ02504Z1.IMG ~/MARSXYZ_DATA/FRA_406377036RADLF0010000FHAZ02504Z1.IMG \)  OUT=DISPERR1.VIC  DISP_UNC=DISP_UNC.VIC  WSIZE=25  POINT=CM=LABEL

MER NCAM:
./MARSERRDISP  INP=\( ~/COMPRESSION4/L3.IMG ~/COMPRESSION4/R3.IMG \)  OUT=DISPERR1.VIC  DISP_UNC=DISP_UNC.VIC  WSIZE=25  POINT=CM=LABEL


METHOD:
MARSERRDISP computes disparity line and sample errors for each pixel.
The program calculates inverse scene activity coefficients and uses it together with
compression rate in order to compute the errors for each pixel.
Correlation coefficient map is not used.

Linear model (based on least squares fit) is used in order to map given 
inverse scene activity coefficients to disparity error values. The coefficients 
for the least squares model were computed using test images in a Matlab program.

Input file contents:

INP: left eye view, right eye view

The pixel data from the left image is used in order to calculate inverse 
scene activity (ISA) coefficients, and hence, the first input should be 
the left image.  The label information is used to determine the pointing 
and camera models.  The pixel data from the right image is NOT used.

CORRCOEFF: single-band file, containing correlation coefficients for each
pixel, and is generated by marscor3 program.  This input is optional, and
is currently not used for calculations.

Output file contents:

OUT: marserrdisp will generate either two separate one-band files 
  (disparity_line_error, disparity_sample_error), or a single 2-band file, depending 
  on the number of filenames given.

DISP_UNC: optional output containing inverse scene activity coefficients (ISA).
  ISA is used in the program to calculate disparity line and sample errors.  
  Smaller values of ISA suggest the scene has many features.
  Larger values suggest the scene is flat.



HISTORY:
  2003-01-13 I. Yanovsky and B. Deen - Initial marserrdisp
  2020-02-06 W. Bunch - IDS-7928 - corrected format strings to match args, cleaned up -Wall warnings, added test case.

COGNIZANT PROGRAMMER: I. Yanovsky

PARAMETERS: