Help for MARSROUGH

PURPOSE:

MARSROUGH computes a measure indicating the roughness of the surface for
each pixel, given XYZ and UVW (surface normal) images as input.  This
roughness value is a floating-point number representing the maximum peak-to-
peak deviation from the plane perpendicular to the normal, measured in the
same coordinate system that the XYZ's are expressed in.

The inputs for MARSROUGH are an XYZ image such as that created by the MARSXYZ
program, and a UVW image such as that created by MARSUVW.  These can each
be single 3-band files or three 1-band files; see MARSXYZ and MARSUVW for
details.

The output of MARSROUGH is a single 1-band file of type REAL.  As with
XYZ images, the output image may contain holes (missing data), defined
by MISSING_CONSTANT.  In addition, values for which roughness could not
be calculated are assigned a different constant, specified by the BAD_ROUGH
parameter identified by the INVALID_CONSTANT label.

There will likely be many more holes than in the input images, since the
roughness algorithm requires a patch around each pixel.

EXECUTION:

marsrough inp=data.xyz out=data.rough uvw=data.uvw
where:
data.xyz is an input 3-band image of type REAL with the X, Y and Z values
at that pixel in meters (the unit is actually irrelevant).
data.uvw is an input 3-band image of type REAL with the U, V, and W components
of the unit vector for each pixel.

Any program producing 3D position could be used; marsxyz is simply an example.

METHOD:

NOTE:  At the present time, it is ASSUMED that the input XYZ image is in
Site coordinates, while the input UVW image is in Rover coordinates.  This
matches what is generated for MER.  This will soon be updated to read the
coordinate system directly from the label.

The actual algorithm and core code was developed by Chris Leger of Section 348.
Description from him:

The surface roughness algorithm attempts to quantify the suitability of a
surface for RAT placement.  At each point in an image, the algorithm examines
points lying within an inner disc and outer annulus about the 3D point at the
current pixel.  The highest and lowest points (relative to the local surface
normal) lying in the annulus are recorded, as is the highest point in the
disc.  The surface roughness is computed as MAX(max_disc_height,
max_annulus_height) - min_annulus height.  The rationale is that the RAT
contact sensors could touch the surface at the low points in the annulus, and
the rest of the RAT hardware will be safe only if the high points in the
annulus and disc are less than 1cm above the low points.  Low points in the
inner disc do not affect the RAT's safety.

The parameters have been tuned for MER RAT.  While the algorithm may be
applicable to other missions, the parameters almost certainly would need
tweaking.

The output will be expressed in units defined by the coordinate system
specified by the COORD and COORD_INDEX parameters.


HISTORY:
06-30-03  Initial marsuvw by B. Deen, based on code from Chris Leger (348).
12-10-03  Major revamp of algorithm by C. Leger
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: