Help for PHXREACH

PURPOSE:

PHXREACH computes the "reachability" for the Phoenix RA (Robotic Arm)
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 PHOENIX-SPECIFIC PROGRAM ***

The inputs for PHXREACH are the XYZ image (created by MARSXYZ).  Unlike
its close cousin marsreach (for MER), the surface normal (UVW) is NOT
required.

The output is a single 12-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   SCOOP       ELBOW_UP
  2   SCOOP       ELBOW_DOWN
  3   SCOOP_BTM   ELBOW_UP
  4   SCOOP_BTM   ELBOW_DOWN
  5   BLADE       ELBOW_UP
  6   BLADE       ELBOW_DOWN
  7   ISAD1       ELBOW_UP
  8   ISAD1       ELBOW_DOWN
  9   ISAD2       ELBOW_UP
  10  ISAD2       ELBOW_DOWN
  11  TECP        ELBOW_UP
  12  TECP        ELBOW_DOWN

For all instruments, the value is either 0 (not reachable) or 255 (reachable).

The geometry of the image matches that of the input XYZ file.

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 historically removes the lander from consideration for the arm collision
detection algorithm (TERRAIN in marsreach); however, terrains and collision
detection are not implemented for PHXREACH.  See marsfilter for more on masking.

EXECUTION:

phxreach inp=data.xyz out=data.reach
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.reach is an output 12-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 not implemented in this
version.  The MASK parameter is retained however; it can specify a file to
use as a mask to remove pixels from consideration.

The actual algorithm and core code was developed by Bob Bonitz and
Matthew Robinson of Section 348.


HISTORY:
  2003-06-20 B. Deen - Initial marsreach based on code from Bob Bonitz (348).
  2007-03-17 B. Deen - Initial phxreach based on marsreach and PHX reachability
                       code from Bob Bonitz and Matthew Robinson.
  2019-12-24 W. Bunch - IDS-7926 - Initialized a variable; cleaned up -Wall warnings except:
                          ra_command.c:972:59: warning: cast from pointer to integer of different size [-Wpointer-to-int-cast]
                          wdStart(act_timer, loop_time, ra_act_timer_cback, (int)act_sem); /* should this be int64? */
                        Added unit test.
  2019-02-06 W. Bunch - IDS-7928 - Switched to constant format string in one, but not all cases.

COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: