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:

Feb. 00 Original version
$Log: marsjplstereo.pdf,v $
Revision 1.1  2000/03/10   abi Initial revision
Revision 1.2  2000/04/16   abi Minor bugs eliminated 
Revision 1.3  2000/09/26   abi Linux compatibility issue resolved
Revision 1.4  2003/01/16   rgd Converted to use PIG library; cleaned up for MER;
                               support for 16-bit input images.
Revision 2.0  2003/01/28   rgd Installed new version of correlator from
                               M. Maimone's group; added Uncertainty parameter
Revision 2.1  2016/05/31   rgd Added automatic downsampling for large images.

COGNIZANT PROGRAMMER:  Bob Deen


PARAMETERS:


INP

Left/right stereo pair images

OUT

Output disparity map

NAVTABLE

Corrected navigation filename

PYRLEVEL

Pyramid level

WINDOWSIZE

Size of correlation window in pixels. Default 7.

MINDISP

Minimum disparity value

MAXDISP

Maximum disparity value

BLOBSIZE

Minimum size of "blobs" (regions of connected pixels) to accept.

UNCERTAINTY

Enable and set value for uncertainty filtering.

PERCENT

Percent stretch limit for HALF->BYTE conversion.

SEPARATE

Specifies separate stretches for input images.

SEPARATION

Set maximum Euclidean separation for trinocular stereo only

THRESHOLD

Set uncertainty threshold for trinocular stereo only

CONFIG_PATH

Path used to find configuration/calibration files.

MATCH_METHOD

Specifies a method for pointing corrections.

MATCH_TOL

Tolerance value for matching pointing params in pointing corrections file.

POINT_METHOD

Specifies a mission- specific pointing method to use

NOSITE

Disables coordinate system sites.

DATA_SET_NAME

Specifies the full name given to a data set or a data product.

DATA_SET_ID

Specifies a unique alphanumeric identifier for a data set or data product.

RELEASE_ID

Specifies the unique identifier associated with the release to the public of all or part of a data set. The release number is associated with the data set, not the mission.

PRODUCT_ID

Specifies a permanent, unique identifier assigned to a data product by its producer.

PRODUCER_ID

Specifies the unique identifier of an entity associated with the production a data set.

PRODUCER_INST

Specifies the full name of the identity of an entity associated with the production of a data set.

TARGET_NAME

Specifies a target.

TARGET_TYPE

Specifies the type of a named target.

RSF

Rover State File(s) to use.

DEBUG_RSF

Turns on debugging of RSF parameter.

COORD

Coordinate system to use.

COORD_INDEX

Coordinate system index for some COORD/mission combos.

FIXED_SITE

Which site is FIXED for rover missions.

SOLUTION_ID

Solution ID to use for pointing correction.

See Examples:


Cognizant Programmer: