Help for MARSJPLSTEREO
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
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
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 <firstname.lastname@example.org>.
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.
marsjplstereo inp=(left.img, right.img) out=disparity.img params
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
parameters : see below.
Parameter space for this routine has not been explored fully. Some
comments on the default values and their ranges are given in the
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
This algorithm is descried in part in Matthies . 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,
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.
- 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
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
Left/right stereo pair images
Output disparity map
Corrected navigation filename
Size of correlation window
in pixels. Default 7.
Minimum disparity value
Maximum disparity value
Minimum size of "blobs" (regions
of connected pixels) to accept.
Enable and set value for
Percent stretch limit for HALF->BYTE
Specifies separate stretches for
The vicar image
Defaults to 1
Set maximum Euclidean separation
for trinocular stereo only
Set uncertainty threshold for
trinocular stereo only
Path used to find
Specifies a method
for pointing corrections.
Tolerance value for
matching pointing params
in pointing corrections file.
Specifies a mission-
method to use
Specifies the full name given
to a data set or a data product.
Specifies a unique alphanumeric
identifier for a data set or data
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.
Specifies a permanent, unique
identifier assigned to a data
product by its producer.
Specifies the unique identifier
of an entity associated with the
production a data set.
Specifies the full name of the
identity of an entity associated
with the production of a data set.
Specifies a target.
Specifies the type of a named target.
Rover State File(s) to use.
Turns on debugging of RSF
Coordinate system to use.
Coordinate system index for
some COORD/mission combos.
Which site is FIXED for
Solution ID to use for