Help for MSLREACH

PURPOSE:

MSLREACH computes the "reachability" for 5 different MSL Arm instruments
at each pixel.  The result is a map show which pixels can be reached by each
instrument in each of its various configuration modes.

Additionally, MSLREACH can compute the min/max preload values for the drill
instrument.

*** THIS IS AN MSL-SPECIFIC PROGRAM ***

The inputs for MSLREACH are the XYZ image (created by MARSXYZ) and the
surface normal (UVW) image (created by MARSUVW).

EXECUTION:

mslreach inp=data.xyz out=data.reach uvw=data.uvw preload=data.preload
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 surface normal unit vector for each pixel.
data.reach is an output 5-band image of type HALF
data.preload is an optional output 2- or 8-band image of type HALF

OUTPUT FILE FORMATS:

The reachability output is a single 5-band file in half (16-bit int) format.
Each band corresponds to an instrument, which are listed in INSTRUMENT_BAND_ID.
They are, in order:

Band	Instrument
----	----------
  1	DRILL
  2	DRT (Dust Removal Tool)
  3	MAHLI
  4	APXS
  5	SCOOP_TIP

For each instrument, there are 8 possible arm configurations.  Each
configuration contains 2 bits of data, which define a degree of reachability,
from 00 (not reachable) to 11 (easily reachable):

Decimal	Binary	Description
-------	------	-----------
  0	  00	Not reachable
  1	  01	Reachability quality 1
  2	  10	Reachability quality 2
  3	  11	Reachability quality 3 (best)

These two bits for each of the 8 configurations are packed into the 16-bit
integer in the file.  In the table below, 15=MSB and 0=LSB

Bit Numbers	Configuration
-----------	-------------
15-14		Shoulder Out, Elbow Up, Wrist Up
13-12		Shoulder Out, Elbow Up, Wrist Down
11-10		Shoulder Out, Elbow Down, Wrist Up
9-8		Shoulder Out, Elbow Down, Wrist Down
7-6		Shoulder In, Elbow Up, Wrist Up
5-4		Shoulder In, Elbow Up, Wrist Down
3-2		Shoulder In, Elbow Down, Wrist Up
1-0		Shoulder In, Elbow Down, Wrist Down

The order is also defined in CONFIGURATION_BIT_ID.

The (optional) Preload output file consists of 2 or 8 bands in HALF (16-bit
integer) format.  Which you get is controlled by the TYPE_PRELOAD parameter.

The default is EIGHT_BAND.  This creates an 8-band product where each band
represents an arm configuration.  The value is the maximum allowable preload,
in Newtons, that can be applied by the drill at that point when in the given
configuration.  The configurations are defined in CONFIGURATION_BAND_ID and
are in the same order as listed above (Shoulder Out, Elbow Up, Wrist Up is
first).

The TWO_BAND preload is an older 2-band format.  These bands represent the
minimum (band=1) and maximum (band=2) allowable preload, in Newtons, that can
be applied by the drill at that point.

For both reachability and preload products, the geometry of the image matches
that of the input XYZ file (and the UVW file, which should match the XYZ).
The input files can be expressed in any coordinate system supported by PIG
as long as they are properly labeled.  However, normally XYZ will be expressed
in Site frame and UVW in Rover Nav frame.  Either Left-side or Right-side
XYZ/UVW files may be used, but the XYZ and UVW must be consistent (using the
same eye).

A mask file may optionally be provided; the XYZ's are masked off using this
file if present (0 means to let the pixel through; 255 means to remove it).
This removes the rover from consideration for the arm collision detection
algorithm (see TERRAIN).  See marsfilter for more on masking.

METHOD:

Algorithm description TBD.  Flight software kinematic models of the arm
are used.

The APPROACH, OVERDRIVE, and TWEAK parameters control how the reachability
model works.  Descriptions of these parmaeters are TBD.

Collision detection of the arm with the terrain is not yet implemented for
MSL.  The TERRAIN parameter will turn it on or off, once it is implemented.
The MASK parameter can specify a file to use as a mask to remove pixels from
consideration by this collision detection (it also removes those pixels from
the output).  FILTER is likewise not implemented yet.

The actual algorithm and core code was developed by Chris Leger of
Section 347.


HISTORY:
2011-06-16 Initial mslreach wrapper by B. Deen, based on marsreach (MER program)
2012-03-01 Support 8 bands, update to FSW 10.5
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: