Help for M20REACH

PURPOSE:

M20REACH computes the "reachability" for 6 different M2020 Arm instruments
at each pixel.  The result is a map showing which pixels can be reached by
each instrument in each of the various arm configuration modes.  If the 
optional Digital Elevation Model (DEM) file is also provided, then it performs
collision analysis as well.

*** THIS IS AN M2020-SPECIFIC PROGRAM ***

The inputs for M20REACH are the XYZ image (created by MARSXYZ) and the
surface normal (UVW) image (created by MARSUVW).  The XYZ and UVW data
must have the same number of lines and the same number of samples per
line.  The third input, Digital Elevation Model (DEM), is optional.  DEM is 
created by MARSORTHO program.

M20REACH calls a python code, reach.py, to perform the reachability 
computations.  M20REACH creates a pair of temporary XYZ/UVW files for input to 
reach.py.  The data contents of these temporary XYZ/UVW files are the same as 
the data contents of the input files INP and UVW but converted into RMECH 
coordinate system.  The output of the python code reach.py is also a temporary 
product, and its data (image) is copied to the output file OUT.  The three 
parameters TMP_XYZ, TMP_UVW and TMP_REACH are used to provide the filenames for 
the three temporary products.  TMP_XYZ and TMP_UVW are used for the temporary 
inputs to the python code with xyz and uvw data respectively.  TMP_REACH is 
used for the temporary output of the python code.  The default values of 
TMP_XYZ, TMP_UVW and TMP_REACH should never be changed.  The default values are
used as templates and the 'XXXXXX' strings (6 uppercase X's) in the filename 
templates are replaced with random 6 character strings composed of uppercase 
and lowercase alphanumeric characters.  For example, after 'XXXXXX' replacement,
the filenames (paths) may look like
   /tmp/___xyz___Y6srVJ
   /tmp/___UVW___khbWef
   /tmp/___REACH___yeA7WK
These temporary files should not be "captured" and used.  The labels in the
temporary files will have errors.  They are deleted by M20REACH before it ends.

The optional input DEM filename is simply passed to reach.py if provided.  The
data in the input DEM file must be in RMECH coordinate system.  Unlike the 
input XYZ/UVW data, M20REACH does not try to convert the input DEM data into
RMECH coordinate system before passing it to the python reachability code.

EXECUTION:

m20reach 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 surface normal unit vector for each pixel.
data.reach is an output 6-band image of type HALF.

OUTPUT FILE FORMATS:

The reachability output is a single 6-band file in half (16-bit int) format.
Each band has reachability information for one instrument, which are listed in 
INSTRUMENT_BAND_ID.  They are, in order:

Band	Instrument
----	----------
  1	DRILL
  2	GDRT
  3	SHERLOC_WATSON
  4	SHERLOC
  5	PIXL
  6	FCS

For each instrument, there are 8 possible arm configurations.  Each
configuration contains 2 bits of data, which define results of two tests:
inverse kinematics (IK) (implemented) and a ground collision test (not implemented).
All values other than 11 (binary) indicate a failure.

Decimal	Binary	Description
-------	------	-----------
  0	  00	not reachable due to inverse kinematics and collision failure
  1	  01	not reachable due to inverse kinematics failure 
  2	  10	not reachable due to collision failure 
  3	  11	no issues (best)

These two bits for each of the 8 configurations are packed into the 16-bit
integer in the file.  The table below shows which pair of bits are allocated
to a given arm configuration, where bit 15 and bit 0 are the most significant
bit and the least significant bit respectively:

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 geometry of the reachability output 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).

The input XYZ and UVW data must be internally converted into RMECH coordinate
system for reachability computation.  Hence, the COORD keyword must always be
RMECH (the default).


HISTORY:
Core algorithms: Junggon Kim and Ian Colwell
2020-08-26 Initial m20reach by E. Sarkissian
2021-02-17 Drill placement integrated B.Crocco
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: