Help for MARSGREACH

PURPOSE:

This program generates an overall goodness product by looking at the 
reachability bands of selected instruments in the input reachability file.

This program is not specific to any project; however, some assumptions 
are made on the input reachability product. Read the METHOD section.

EXECUTION:

marsgreach inp=data.reach out=data.goodness
where:
data.reach is an input 6-band reachability image file.
data.goodness is a 1 or 2 band image file of type BYTE.


METHOD:

This program generates an overall goodness product by looking at the 
reachability bands in the input reachability file.  This is not an M2020
specific program; however, the output of M20REACH for M2020 project is a 
good example of input to MARSGREACH.

The reachability input is a single multi-band file in HALF (16-bit int) 
format.  Each band has reachability information for one instrument on the
mechanical arm of the rover.  The instruments gone through reachability 
analysis should be listed in the label INSTRUMENT_BAND_ID of the input file.  
In the case of M2020 for example, they are, in order:

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

For each instrument band in the input file, a pixel is a 16-bit integer 
containing the instrument target reachability information associated with 
the pixel.  A 16-bit reachability pixel for an instrument is divided into 8
groups of 2 bits for 8 arm configurations.  Therefore, 2 bits are used in the
input file per instrument per target pixel per arm configuration to record the 
measure of the reachability of the instrument to the target with the given arm 
configuration.  With two bits, the reachability measure can only be on the
scale of 0 to 3 with 0 being not reachable and 3 being the best reachability
expected.  For example, in the case of a reachability input generated by
M2020, the reachability measures and what they mean are the following:

Decimal	Binary	Description
-------	------	-----------
  0	  00	not reachable
  1	  01	standoff reachable
  2	  10	close (0cm) reachable 
  3	  11	standoff and close reachable (best)

MARSGREACH assumes an instrument band pixel is a 16-bit integer divided into
eight groups of two bits, hence it assumes eight arm configurations.  For a
concrete example, in the case of M2020 the bit allocations for the eight 
possible arm configurations are given in the table below:

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

CONFIGURATION_BIT_ID label in the input file should give a list of the arm
configurations listed from left (most significant bits here) to right (least
significant bits here).

MARSGREACH goes through the following conceptual steps to generate its 
output:

First, MARSGREACH ignores all the input bands that are not selected through
BANDS parameter.

Second, MARSGREACH collapses the selected input bands into a single band with
the same number of lines, the same number of samples-per-line and the same 
format (HALF) as the input bands.  In the resulting band, the two bits
associated with a given target pixel and a given arm configuration is 
set to the smallest (worst reachability) value from the same target pixel
and the same arm configuration 2-bit values across all the selected input 
bands.

Third, MARSGREACH takes the conceptual product of the second step and 
generates another conceptual band.  This new band also has the same number
of lines and the same number of samples-per-line as the result of the 
second step; however, the result of the third step is in BYTE format.  In
the product of the third step, each pixel is treated as a single value, and 
it is set to the largest (best reachability) of the 8 2-bit values from the 
same target pixel of the result of the second step.

Fourth, MARSGREACH generates the goodness single band image that is the 
required band in its output product.  In this step, the program maps every 
pixel value from the product of the third step to one of the "standard 
goodness values".  The table below shows the mapping in decimal:

Reachability Values (Decimal)     Goodness Values (Decimal)
-----------------------------     -------------------------
0                                 0
1                                 1
2                                 3
3                                 5

Fifth, MARSGREACH generates an optional second output band if BEST_CONF 
keyword is set.  This optional output band has the same number of lines, the 
same number of samples-per-line and the same format (BYTE) as the first 
output band (the product of the fourth step).  However, in the second
optional output band, each pixel (8-bits) is not treated as a single value
but as 8 1-bit flags one per each arm configuration.  For this step, the
program depends on the results of the second and the third steps.  For a 
given pixel and arm configuration, if the 2-bit reachability value for the arm 
configuration from the result of the second step is equal to the pixel value 
from the result of the third step, then the bit in the same pixel of the 
second optional output band for the arm configuration is set to 1 otherwise, 
it is set to 0.  There is one exception to this flag setting rule.  If the 
pixel value in the product of the third step is zero, then all flags in the
same pixel of the optional second band are set to 0 rather than 1.  The 
purpose of the second output band is to flag the arm configurations for a 
target pixel that their reachability values are equal to the best conservative 
reachability value determined in the third step.


OUTPUT FILE FORMATS:

The output of MARSGREACH has one or two bands.  The second band is optional
and both bands have BYTE format.  The number of the lines and the number of
the samples-per-line of both bands are the same as the number of the lines 
and the number of the samples-per-line in the input file.

The required first band is the product of the fourth step explained in the 
METHOD section, and the optional second band is the product of the fifth 
step explained in the METHOD section.  The second band is created if the
optional BEST_CONF keyword is set.

HISTORY:
2020-09-24 Initial marsgreach by E. Sarkissian,

PARAMETERS: