Help for MARSREACH

PURPOSE:

MARSREACH computes the "reachability" for the MER IDD (Instrument
Deployment Device) at each pixel.  The result is a map show which pixels
can be reached by each instrument in each of its various configuration modes.

*** THIS IS A MER-SPECIFIC PROGRAM ***

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

The output is a single 16-band file in byte format.  The bands are described
by the INSTRUMENT_BAND_ID and CONFIGURATION_BAND_ID, but use the following
layout:

Band  Instrument  Configuration
----  ----------  -------------
  1       MI      ELBOW_UP_WRIST_UP
  2       MI      ELBOW_UP_WRIST_DOWN
  3       MI      ELBOW_DOWN_WRIST_UP
  4       MI      ELBOW_DOWN_WRIST_DOWN
  5       RAT     ELBOW_UP_WRIST_UP
  6       RAT     ELBOW_UP_WRIST_DOWN
  7       RAT     ELBOW_DOWN_WRIST_UP
  8       RAT     ELBOW_DOWN_WRIST_DOWN
  9       MB      ELBOW_UP_WRIST_UP
  10      MB      ELBOW_UP_WRIST_DOWN
  11      MB      ELBOW_DOWN_WRIST_UP
  12      MB      ELBOW_DOWN_WRIST_DOWN
  13      APXS    ELBOW_UP_WRIST_UP
  14      APXS    ELBOW_UP_WRIST_DOWN
  15      APXS    ELBOW_DOWN_WRIST_UP
  16      APXS    ELBOW_DOWN_WRIST_DOWN

For the MI, MB, and APXS instruments, the value is either 0 (not reachable)
or 255 (reachable).  For the RAT bands, the value is either 0 (not
reachable), or a non-0 integer which represents the maximum "preload" in
Newtons that the RAT can apply at that point.

The geometry of the image matches that of the input XYZ file (and the UVW
file, which should match the XYZ).

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.

EXECUTION:

marsreach inp=data.xyz out=data.reach 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.
data.reach is an output 16-band image of type BYTE

METHOD:

Algorithm description TBD.  Kinematic models of the arm are used.

Collision detection of the arm with the terrain is normally enabled.
The TERRAIN parameter can turn this off, if desired.  The MASK parameter
can specify a file to use as a mask to remove pixels from consideration
by this collision detection.

This version includes low-level filtering of the XYZ's in the rechability
code itself.  This filtering is done in image space and removes any XYZ's
on the stowed arm.  It only takes place on full-res (1024x1024) images;
downsampled or subframed images do not have the arm filtered out.  This
filtering is controlled by the FILTER parameter.  With FILTER on, it is
performed when possible (full-res only).  With it off, this internal filtering
is disabled.  With AUTOFILTER, it is disabled if a MASK is provided, or
enabled otherwise (the idea being that the mask does the same, but
presumably more extensive, filtering).

The actual algorithm and core code was developed by Bob Bonitz and
Chris Leger of Section 348.


HISTORY:
06-20-03  Initial marsreach by B. Deen, based on code from Bob Bonitz (348).
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: