Help for MSLROUGH

PURPOSE:

MSLROUGH 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.

This program is very similar to MARSROUGH, but the algorithm is tuned for
the specifics of the MSL arm.  It is not mission-specific per se; it could
be used for any data for which the algorithm applies.

The inputs for MSLROUGH 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 MSLROUGH is a single 2- or 3-band file of type REAL, containing
flags indicating whether the data met roughness criteria, as well as the
actual roughness values (see below for details).  As with XYZ images, the
output image may contain holes (missing data), defined by MISSING_CONSTANT.

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

EXECUTION:

mslrough 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:

The actual algorithm and core code was developed by Matt Robinson (based on
earlier MER code from Chris Leger), both from Section 347.

The surface roughness algorithm attempts to quantify the suitability of a
surface for placement of the MSL Drill or Dust Removal Tool (DRT).

At each point in the image, the surface normal is used to define a reference
plane.  The XYZ values of pixels that meet the criteria (below) are gathered,
and the distance from them to the plane is computed.  Outliers are thrown
out (see FILTER_SCALE).  For the remainders, the minimum and maximum distances
from the plane are found.  Roughness is defined as the distance between this
min and max.

Two roughnesses are computed.  The first is an overall measurement based on
the OUTER_RADIUS and considers all points within that radius of the central
pixel.  For MSL, this is used for the DRT, and the drill body.  The second
(used only if -DO_RING is set) is a ring between the INNER_RADIUS and
OUTER_RADIUS.  For MSL, this is used for the drill stabilizer bars.

In each case, the computed roughness is compared to a threshold, which
determines whether the point is "good" or not.

The points are additionally filtered by a XYZ-space window (X_CENTER, Y_CENTER,
BOX_RADIUS) which encloses the entire arm workspace, and a local pixel-space
window centered on each pixel (MAX_WINDOW).  If fewer than MIN_POINTS pixels
remain, roughness is not calculated for that pixel.

OUTPUT FORMAT:

The output is a 2- or 3-band file in REAL format.

The first band is the State.  This band consists of a set of flags, stored in
float format simply because files must be of a consistent data format.  The
possible values are:

0.0 = No solution
1.0 = Both ring and overall roughnesses exceed thresholds
2.0 = Overall roughness (only) exceeds its threshold
3.0 = Ring roughness (only) exceeds its threshold
4.0 = Roughnesses within threshold (good)

Note that if -NO_RING is specified, then the values 1.0 an 3.0 cannot occur.

The second band is the actual Overall roughness measurement.  Unlike most
other products, 0.0 does NOT indicate a missing value.  Rather, the value
in BAD_ROUGH (default 1.0) is used.  This value shows up in MISSING_CONSTANT
in the label.

The third band contains the Ring roughness measurement, and is present only
if -DO_RING is specified.  It is otherwise similar to the second band.

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


HISTORY:
2011-11-21 Initial mslrough by B. Deen, based on code from Matt Robinson (347)
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: