Help for MARSDISPINVERT

PURPOSE:

This program takes a disparity map, such as generated by marscor3 or
marsjplstereo, and "inverts" it, or flips the eyes.  That is, if the
input disparity map is in the left eye geometry giving coordinates of
matching pixels in the right eye, the output will be a disparity map
in the right eye geometry giving coordinates of matching pixels in the
left eye.

Missing values in the inverted disparity image
(both line and sample values) will be filled in if both 
of the parameters s_fill_value and l_fill_value are given.
These values are  best guess values, perhaps determined by inspection.
This is useful because a pixels in a disparity image are ignored by 
the program marscor3 if the pixel value is 0.

The intent of this is to enable use of marsjplstereo (perhaps combined
with marsunlinearize) to generate seeds for marscor3.  The 1-D correlator
at the heart of marsjpstereo only likes generating positive disparities
(which result in L->R correlations on MER).  Doing a R->L correlation
requires negative disparities, which the 1-D correlator cannot do.
This program will take the L->R correlation and produce an equivalent
R->L disparity map.

It is NOT recommended that the result of this program be used directly.
It should be used only as a seed file for something like marscor3.
The reason is that this is not an entirely invertible operation.  If
two pixels in the input map to the same pixel in the output, only one
of those pixels will be represented (officially indeterminate, but most
likely the last one encountered in scanline order).  Also, no attempt
is made to preserve subpixel disparity values: the output will be all
integer disparities.

Note that the disparity files must be single two-band files.  Separate
line and sample disparities, while acceptable to most correlator programs,
are not supported in this program.

Note on forwarding extra correlation information:
Starting with M2020, correlation file labels contain some extra information
(number of valid pixel, average scale difference between L/R, and percentage
of overlap between L/R). This information is forwarded to the inverted 
disparity file the following way:
- Number of valid pixels: Simple counter of the valid pixels in the input
disparity map which have been successfully "inverted". 
- Average scale difference: 1/input disparity average scale difference
- Percentage of overlap between L/R: ratio between number of valid inverted 
pixels and total number of pixels of the inverted disparity image. Note that 
this value could differ significantly from the input disparity percentage of 
overlap even if the L/R image fov is about the same. The reason being that the 
input disparity might contain an "estimate" of the overlap (defined from the
cam geometry only, i.e., pre-correlation), whereas the inverted disparity 
contains the actual overlap w.r.t. to valid pixels. 

EXECUTION:

marsjplstereo inp=(left,right) out=disp1d.lr
marsdispinvert inp=(right, left) out=disp1d.rl in_disp=disp1d.lr
marscor3 inp=(right,left) out=disp2d.rl in_disp=disp1d.rl

The program can also handle pyramid (downsampled) disparity maps, by
specifying the disp_pyr pyramid level (note that this only changes the
output size; the results are otherwise identical).  The pyramid level cannot
be changed by this program.

marsjplstereo (left,right) disp1d.lr pyramid=1
marsdispinvert (right, left) disp1d.rl in_disp=disp1d.lr disp_pyr=1
marscor3 inp=(right,left) out=disp2d.rl in_disp=disp1d.rl disp_pyr=1

OPERATION:

The process works by looping over the disparity map.  For each pixel (i,j),
the value of the disparity map is retrieved.  This represents the location
of the corresponding pixel in the right image (i',j').  This value is rounded
off to integers.  The disparity map for the right image at (i',j') is then
filled with the value (i,j) to represent the backwards mapping.

HISTORY:
July 05		Initial version by Bob Deen
Sept 09         Minor modification (added fill values)by Mathew Yeates
Sept 11         Changed input parameters to generated proper label -Oleg Pariser
Oct  13		Modified to work for different-size images; added disp_pyr
Aug  20		Forwarding of extra correlation information

PARAMETERS: