Help for MARSC2UVW

PURPOSE:
Creates a surface normal (UVW) map given a correlator coefficients
file (as output by marscor3) as well as the disparity map and input stereo
files.

This program supports any mission, instrument, and camera model supported by
the Planetary Image Geometry (Pig) software suite.

The UVW coordinates are in a coordinate system defined by the COORD and
COORD_INDEX parameters.  In keeping with marsuvw, This defaults to the
instrument frame (typically ROVER or LANDER frame).

EXECUTION:
marscor3 inp=(left,right) out=disparity coef_out=coef ...
marsc2uvw inp=(left,right) out=uvw dispar=disparity coef=coef
where:
left is the left eye image of a stereo pair
right is the corresponding right eye image of a stereo pair
uvw is the output UVW file
disparity is the disparity file as output from marscor3
coef is the coefficients file as output from marscor3


METHOD:
Marsc2uvw works by doing the following for each pixel:

1) Determine the corresponding R-side pixel using the disparity map.

2) Project the L and R pixel coordinates through the camera model and
determine the XYZ location.  This is the tail of the vectors.

3) Move the coordinate up in line by the amount in DIST_LINE (i.e. subtract
the DIST_LINE value).  This creates a 2-D vector in image space.

4) Use the perspective transform specified by the coefficients to determine
the corresponding point in the R site.

5) Project those points into XYZ space.  That, along with the tail defined
above, establishes a vector in 3D space corresponding to the 2D vector.

6) Do the same thing except move the coordinate to the left in sample by
the amount in DIST_SAMP (by subtracting DIST_SAMP).  Transform and project
into XYZ, this along with the common tail establishes a second vector in 3D
space.

7) Take the cross product of the two 3D vectors.  The (normalized) result is
the normal to the plane established by the two vectors.  Since those vectors
lie in the plane defined by the perspective transform, this result is the
final UVW value.

FILES

The input left and right files are used only for their labels (to find the
camera model).  The pixel values are not used.

The output file is normally a single 3-band output file.  However, separate
u,v,w files can be supplied.

The disparity file is usually a 2-band file in (line,sample) order where the
value at each pixel is the 1-based coordiante of the matching pixel in the
"right" file (see marscor3).  However, separate line and sample disparity files
can be supplied.

The coef file is a 6-band floating point file containing the a,b,d,e,g,h
components of the perspective transform (c and f are the constant terms, which
come from the disparity file).

The transform is:

x' = a*x + b*y + c + g*x*y
y' = d*x + e*y + f + h*x*y


HISTORY:
2014-09-26 rgd	Initial version.
COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: