Help for NSYTWKSP

PURPOSE:

NSYTWKSP computes a mask showing the workspace boundaries for the
InSight mission.  The boundaries are computed by comparing the XYZ
coordinates with precomputed polygons indicating the edges of the
workspace.

The output is a single-band BYTE image, containing a code 0-7 showing
which polygons the point is inside.  See below for values.

This program could easily by multimission-ized.

EXECUTION:

nsytwksp inp=data.xyz out=data.wss -seis
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).

METHOD:

The actual core algorithm was developed by Steven Myint from Section 347.
It was then refactored to meet VICAR standards by Bob Deen.

The algorithm is simple: for each point, it checks if the XY coordinate
is within the boundary specified by the input polygon file.  Z is ignored.
The XYZ coordinate is converted to the coordinate system specified in
COORD first.

The files are different based on instrument: HP3 and SEIS (actually a
combination of SEIS and WTS).  Selection is made via a parameter.

OUTPUT FORMAT:

The output is a 1-band file in BYTE format.

For HP3 the possible values are:

  0 = no data
  1 = outside HP3 boundary, or no data
  2 = HP3 footplane (footprint) boundary
  3 = n/a
  4 = IDA grapple workspace --- IDA grapple kinematically reachable zone for
      HP3 deployment
  5 = nominal (IDA grapple workspace) zone for HP3 deployment
  6 = inside HP3 grapple point boundary, but ICC view partially occluded
  7 = inside HP3 grapple point boundary, but more maneuvering required for 
      collision prevention 

For SEIS/WTS the possible values are:

  0 = no data
  1 = outside all SEIS/WTS areas, or no data
  2 = WTS footplane (footprint) boundary
  3 = SEIS footplane (footprint) boundary
  4 = IDA grapple workspace --- IDA grapple kinematically reachable zone for 
      SEIS/WTS deployment
  5 = nominal (IDA grapple workspace) zone for SEIS/WTS deployment
  6 = inside SEIS/WTS grapple point boundary, but ICC view partially occluded
  7 = inside SEIS/WTS grapple point boundary, but more maneuvering required for 
      collision prevention

The value 5 is assigned to the "best" workspace, in order to maintain
consistency across all InSight masks.  The values above 5 are
technically acceptable for placement, but are sub-optimal due to their
constraints.  The goodness program will accept all of 5-7 as "good".

Note: it is assumed the polygons strictly nest, with higher numbers above
being smaller than previous polygons.  If not, the highest number wins
(in other words, polygons are traversed in order from highest to lowest, and
once a number is assigned to a given pixel, no other polyons are checked).

POLYGON FILES:

The program reads polygon vertices from five polygon files provided by
Won Kim (347). These files are found using the standard MARS_CONFIG_PATH
mechanism in the "param_files" directory.  The files are:

param_files/NSYT_wksp_hp3_boundary.txt
param_files/NSYT_wksp_hp3_grapple_kinematic.txt
param_files/NSYT_wksp_hp3_grapple_nominal.txt
param_files/NSYT_wksp_hp3_grapple_ICC.txt
param_files/NSYT_wksp_hp3_grapple_maneuvering.txt
param_files/NSYT_wksp_wts_boundary.txt
param_files/NSYT_wksp_seis_boundary.txt
param_files/NSYT_wksp_seis-wts_grapple_kinematic.txt
param_files/NSYT_wksp_seis-wts_grapple_nominal.txt
param_files/NSYT_wksp_seis-wts_grapple_ICC.txt
param_files/NSYT_wksp_seis-wts_grapple_maneuvering.txt

where "NSYT" is actually the host ID (NSYT for flight, NSYTTBC for the
testbed, etc).

The polygon files may be replaced with different ones if the lander ends
up with a significant tilt (because the tilt affects how the grapple hangs).


HISTORY:
2015-05-02	rgd	Initial version, based on code from Steven Myint (347)
2017-12-11  Steven Lu   Read polygon files from MARS_CONFIG_PATH.
2018-01-18  Steven Lu   Implement radial and cross-radial offsets for WTS.
2018-04-03  Steven Lu   Add addtional polygons and change assigned numbers.
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: