Help for MSLROUGH

PURPOSE:

MSLROUGH computes a measure indicating the roughness of the surface for
each pixel, given XYZ and UVW (surface normal) images or an XYZ image and a 
single UVW surface normal vector as input.  If a single UVW vector is 
provided, then it is used at every point in the XYZ input image file.  This
roughness value is a floating-point number representing the maximum peak-to-
peak deviation from the plane perpendicular to the normal.

By requesting the program calculate curvature instead, the program calculates
two floating point numbers, an estimate of concavity and convexity. Concavity
is calculated by finding, in the filtered area for each point, the difference 
between the farthest point below the surface plane and the mean of all the 
distances to surface plane. Convexity is similarly calculated for the farthest
point above the surface plane.

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. It is being used for 
M2020 as well.

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.  Alternatively, the input UVW can be a single surface normal vector,
the vector and its coordinate system are provided as input through the 
input parameters UVW_VECTOR and UVW_COORD respectively.  If the UVW surface
normal vector(s) are provided both as an input image and as an input single
vector, then the image takes precedence and the single vector is ignored.

The output of MSLROUGH when calculating roughness 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.

The output of MSLROUGH when calculating curvature is a single 3-band file of 
type REAL, containing flags indicating whether the data met curvature criteria,
as well as the two curvature values (see below for details). As with XYZ images, 
the output image may contain holes (missing data), defined by MISSING_CONSTANT.
Curvature is only calculated for the patch region. -do_ring is not valid when
calculating curvature.

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
or
mslrough inp=data.xyz out=data.rough uvw_vector=\(<x>,,\) uvw_coord=""
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).
In the first case, 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.
In the second case, <x>,  and  are replaced with the numeric values
of the single surface normal vector components, and <type> is replaced with
the coordinate system name in which the UVW vector is given.

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

To generate curvature instead of roughness:
mslrough inp=data.xyz out=data.rough uvw=data.uvw -do_curvature 

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 PATCH_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. The parameters
allow for a gap between the patch and the ring:

     -------ring outer-------             
    / ++++++++++++++++++++++++\
   /++++----ring innner----++++\ 
  /+++/                     \+++\
 |+++|                       |+++|
 |+++|     -patch outer-     |+++|
 |+++|    / ........... \    |+++|
 |+++|   |.............. |   |+++|     


 However the patch can include or extend beyond the outer ring as it does in MSL: 

     ---ring outer/patch ---
   / ++++++++++++++++++++++++\
  /++++----ring innner----++++\ 
 /+++/.....................\+++\
|+++|.......................|+++|
|+++|.......................|+++|
|+++|.......................|+++|
|+++|.......................|+++|

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.

The algorithm for the curvature calculation was developed by Kris Wehage and 
Curtis Collins from section 347.

When used to computer curvature, the algorithm for point selection and filtering
are identical to roughness. Instead of calculating the peak to peak distance in
the area, concavity reports the distance between the farthest point below
the surface plane and the mean distance of the other points within the specified 
area. Concavity reports the distance between the farthest point above the surface
plane and the mean.

Concavity has two thresholds that are checked CONCAVE_HIGH, a more relaxed
threshold that is farther from the mean plane, and CONVCAVE_LOW, a more stringent
threshold closer to the mean plane. Convexity has two parameters CONVEX_HIGH and
CONVEX_LOW which identical purposes. The thresholds are arranged as:

 ---- curvature: convexity threshold high ----

 ---- curvature: convexity threshold low  ----

 +++++++++++ surface mean plane ++++++++++  ---- curvature: concavity threshold low  ----
 
 ---- curvature: concavity threshold high ----

OUTPUT FORMAT:

The output when calculating roughness is a 2- or 3-band file in REAL format.
The output when calculating curvature is a 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 for roughness 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 possible values for curvature are:

0.0 = No solution
1.0 = Both concavity and convexity exceed thresholds
2.0 = Convexity exceeds one or more threshold
3.0 = Concavity exceeds one or more threshold
4.0 = -- skipped --
5.0 = Curvature within high thresholds, exceeded one or more low threshold
6.0 = Curvature within all low (and high) thresholds (good)

For roughness products:

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.

For curvature products:

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

The curvature 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
2020-05-25 updated by E.  Sarkissian to optionally use a single surface normal
vector UVW instead of many provided through an input image file.
2020-10-23 updated by B. Crocco to optionally calculate curvature using code from
Kris Wehage and Curtis Collins (347)

PARAMETERS: