Help for MARSJPLSTEREO

PURPOSE:
This program computes disparity maps from a stereo pair. The images
are assumed to be aligned (CAHV linearized), hence only the sample
disparity map is computed. The line disparity map is output as 0
disparity (i.e. DN matches line number).  In contrast to MARSCORR,
this program relies on camera model to do the computations.  The
camera model is derived from the PIG (Planetary Image Geometry)
library in the standard way.

The resulting line and sample disparity maps can be used as input to
MARSXYZ routine to convert disparity maps to XYZ images.  That output
can further be sent to MARSRANGE to generate range maps.  The disparity
map file format is compatible with the output of MARSCORR; see the help
for that program for file format details.

This program is also in theory capable of performing trinocular stereo
matching with left, right and bottom cameras.  However, THIS HAS NOT
BEEN TESTED.

The underlying correlation library works with 8-bit data only.  Since
most mission data is 16 bits (really 12, in a 16-bit image), a percent
linear stretch is done to convert to byte before sending the image into
the correlator.  This results in some loss of precision but shouldn't
cause too much trouble in practice.  Normally the histograms for all
inputs are combined so a single stretch is performed, but if the cameras
are of unequal brightness, the SEPARATE flag will cause the images to be
stretched independently.  The correlator is rather sensitive to overall
brightness levels.

This routine is based on the JPL Stereo code developed in the JPL
Robotics Division.  Great deal of help and explanation was provided by
Mark Maimone <mwm@helios.jpl.nasa.gov>. 

In this program, input images must be projected from CAHVOR/CAHVORE
space to CAHV space, i.e. run MARSCAHV routine to remove distortion. 
The underlying correlation library supports CAHVOR/CAHVORE models,
but simply does an internal warp to CAHV before correlating.  It was
thus decided that the complexity of supporting CAHVOR/CAHVORE directly
was not worthwhile, since CAHV images are normally created anyway.

If pyramid level is not zero, image dimensions are truncated(if necessary)
to the max. multiple of pyramid level.  For example if pyramid=2 and image
size is 258x258, the correlation will be done on 256x256 subframe and the 
extra input pixels will be ignored.

The underlying JPL Stereo code can only handle images up to 2048 x 2048.
If the image is larger than that, it is automatically downsampled until it
fits within 2048 x 2048.  The pyramid level is reduced as well, so that
the effective result is identical to what would have happened if JPL Stereo
could handle larger images (i.e. the downsizing is transparent).  However,
the pyramid level must be big enough to accommodate this; if it goes negative
the program will abend.

EXECUTION:
  
  marsjplstereo inp=(left.img, right.img) out=disparity.img params
or
  marsjplstereo inp=(left.img, right.img, lower.img) out=disparity.img) params

  left.img - left image of the stereo pair
  right.img - right image of the stereo pair
  lower.img - lower image for the trinocular stereo. Not used for binocular stereo
  disparity.img - output disparity map.  Can be a single 2-band file or two
      1-band files.
  parameters : see below.

NOTE. 
  Parameter space for this routine has not been explored fully. Some
comments on the default values and their ranges are given in the
parameter section. 

EXAMPLE

Convert images from CAHVOR space to CAHV and update camera model
information in the labels : 

  marscahv left.img left_cahv
  marscahv right.img right_cahv

Run the JPL Stereo algorithm with window size 15 : 

  marsjplstereo inp=(left_cahv, right_cahv) out=(disparity.img) window = 15

Convert from disparity to XYZ maps

  marsxyz inp=( left_cahv, right_cahv ) dispar=disparity.img out=xyz.img 

OPERATION :
 
  This algorithm is descried in part in Matthies [1992]. Here's a quote
from the abstract of this paper. 
" .. The statistical and algorithmic aspects employ random field models 
of the disparity map, Bayesian formulations of single-scale matching,
and area-based image comparison. The implementation builds bandpass
pyramids and produces disparity maps... ". 
  

REFERENCES : (kindly supplied by Mark Maimone)

(in order of relevance) 

L. H. Matthies, 1992 ,Stereo vision for planetary rovers: stochastic modeling
to near real-time implementation, Int. Jour. of Computer Vision, 8(1), pp71-91

L. Matthies, A. Kelly, T. Litwin, G. Tharp, 1996, Obstacle
Detection for Unmanned Ground Vehicles: A Progress Report, in Robotics
Research: the 7th International Symposium, Springer-Verlag

Yalin Xiong, Larry Matthies, 1997, Error Analysis of a Real-Time
Stereo System, in CVPR, pp. 1087-1093, 
URL "http://www.cs.cmu.edu/~yx/papers/StereoError97.pdf"


DEVELOPER NOTES

All files in this package with the exception of marsjplstereo.* and
cmod_fp_stubs.h, are part of the correlator package obtained from Mark
Maimone.  Many have been modified to compile in the VICAR environment or
to fix bugs (e.g. more blobs than a short can handle, changed to long;
precision differences between Solaris and Linux).  However, an attempt has
been made to keep the changes to a minimum.  The original delivery is in
B. Deen's "mer" email folder if needed.


FUTURE WORK

- Loosen the ultra conservative approach to the Maximum
  Disparity. Currently the left edge of valid dispairty map values
  starts at the maximum disparity value.
- Allow min/maxdisp to be expressed in meters of range (for user convenience)
- Add parameter to turn off LRLOS (reverse correlation check) option.  That
  would only be useful for investigation of problems.
- Add ability to output disparity space for a given row, again to investigate
  bad correlations (SetRowsToSearch() in the correlator code).
- Separate horizontal/vertical window size parameters


HISTORY:

  2000-02        - Original version
  2000-03-10 abi - Revision 1.1 Initial revision
  2000-04-16 abi - Revision 1.2 Minor bugs eliminated 
  2000-09-26 abi - Revision 1.3 Linux compatibility issue resolved
  2003-01-16 rgd - Revision 1.4 Converted to use PIG library; cleaned up for MER;
                                support for 16-bit input images.
  2003-01-28 rgd - Revision 2.0 Installed new version of correlator from
                                M. Maimone's group; added Uncertainty parameter
  2016-05-31 rgd - Revision 2.1 Added automatic downsampling for large images.
  2019-10-02 wlb - IDS-7926 - Initialized some variables;
                   IDS-7928 - Corrected some printf formatting directives 
                              (pointers should have been %lx, not %x);
                   Commented some unused variables; Added explicit return types
                   for some functions; Added includes for open and creat. Added
                   tst.pdf and tst.log to test dir.
  2019-12-23 wlb - IDS-7926 - Initialized a variable.
  2020-03-24 wlb - IDS-7927 - Replaced sprintf() calls.

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: