Help for M20FILTER

PURPOSE:

M20FILTER looks at the kinematic state of the M2020 rover (as described in
image labels) and uses it to compute an XML filter file suitable for use with
MARSFILTER.  This is used to create a rover mask, such that all bits of the
rover are masked off.

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

Bits of the Flight Software (FSW) are used to compute the kinematic state of
articulating devices, apply that to a volume collision model, and convert that
to a set of polygons.  These polygons are then bundled up in a manner usable
by MARSFILTER.  The use of the FSW routines makes this an M2020-specific program.
Note that the FSW contains the collision model as well as the code that uses it.

The input for M20FILTER is any M2020-labeled image (EDR or single-frame RDR).

EXECUTION:

m20filter inp=image.img out=image.xml
where:
image.img is any M2020-labeled VICAR (or dual-label VICAR) image.  This can be
an image EDR, or any of the single-frame RDR's.
image.xml is the XML representation of the filter mask.

OPERATION:

The output file is an XML file in the format expected by MARSFILTER.  See
the help for MARSFILTER for a detailed explanation of the XML.

This program relies on the kinematic state of the rover.  In other words,
where is the arm, where are the wheels, where is the high-gain antenna.
Note that the small articulations (turret devices, inlet covers) are ignored
here as not relevant, since they don't change the mask appreciably.  Also the
RSM state itself is ignored, because the RSM head is not actually visible from
any of the cameras mounted on it.  (it could matter for the arm-mounted Watson,
but the RSM head nodes are currently excluded from the collision mask).  So
in reality, only the Site, Drive, Pose, Arm, and HGA components of the RMC
matter.  This means the same mask can be applied to any image with the same
site, drive, pose, arm, and hga RMC indices.

In order to accommodate this, those RMC indices are written out in the
<camera> tag to identify the kinematic state.  The mask can then be used with
any image sharing that state, as identified by the RMC.  The RMC_INDEX parameter
lets you control which indices are written to the file, but changing it should
not be necessary.

If a list of images is given, by default it compares these RMC indices to the
prior image.  If they're the same, the mask is not re-written.  This greatly
reduces file size in a mosaic situation (say, if the mask is going to be used
with marsautotie or the marsmap/marsbrt brightness correction) and increases
performance.  The UNIQUE parameter controls this.

The arm kinematic state is sometimes uninitialized, such as on rover boot.
In that case, the joint angles are all 0, but that doesn't actually make
physical sense.  Since the arm is generally stowed during such a boot, the
default STOW_MODE replaces an all-0 joint angle set with the appropriate angles
for the stowed arm.  You can turn this off, or force the arm to be stowed all
the time (e.g. if you wanted to not mask the arm).

An unknown value for a joint will cause it to use a "swept volume", i.e. assume
all possible values for that joint.  Currently, the HGA ONLY implements swept
volume; its articulation is not used.  (This may be fixed in the future).

The arm kinematic state can be forced to a value other than the value
described in the image labels via the ARM_JOINTS parameter.  This can be used
for example to create a predictive mask showing what the situation will be
after a planned arm motion.  All 5 joints must be specified if any are given.
A value of 1e30 will cause that joint to use a swept volume.

The collision checking uses a tolerance value to set how close the mask comes
to the rover.  Default is 1.5cm (.015).
EXCLUSION LIST:

The FSW maintains a list of "objects" in its collision model.  Some of these
objects cause problems with the masks, for example they might be in front of
one of the hazcams.  For this reason there is an "exclusion list" of objects
that are excluded from the mast.

This list is maintained in a file pointed to by the MARS_CONFIG_PATH mechanism.
It looks for param_files/<host>_filter_exclude.txt (for example,
param_files/M20_filter_exclude.txt).  The format of the file is simple:
comments start with '#' in the first character, blank lines are ignored, and
otherwise the line is either a number (which excludes the object for all
cameras), or "camera_name: number" which excludes it for just the given
camera.  For example:

# Remove the MEDA masts as they stick out way too far and do not cover any
# real terrain.
404
405
406
# Blocks sticking out in front of the FHAZ's.  Unfortunately it must be fhaz
# only, because the area is visible to the right navcam.
FRONT_HAZCAM_LEFT_A: 300
FRONT_HAZCAM_RIGHT_A: 300
FRONT_HAZCAM_LEFT_B: 300
FRONT_HAZCAM_RIGHT_B: 300

The object list is maintained in the FSW and can be viewed using
rcm_col_dp_view from the FSW src/rcm/tools directory.  There's a version
here on the 2020 project machines:

/proj/m2020/fsw/tools/bin/rcm_col_dp_view

So for example:

/proj/m2020/fsw/tools/bin/rcm_col_dp_view RcmColModel_0616230310-20645-1.iv &

The object number is included in the output, as an "id=" attribute.  This
can be used with marsfilter -numbers to help flush out objects that are
problematic.

PARAMETER FILES:

The software relies on FSW parameters, which contain the actual collision
model.  Defaults of these are built in to the program, so if the default is
sufficient, nothing extra need be done.  However, if adjustments need to be
made to the collision model, that can be accomplished via NPM parameter files.
These are created by the FSW team (Justin Huang and Vandi Verma, primarily).

NPM files go in the calibration directories searched by $MARS_CONFIG_PATH
(or the CONFIG_PATH) parameter.  The first one of the dirs in that path that
contain a subdir named "arm_params/HOSTID/" where HOSTID is MSL, MSLVSTB, etc.,
will be the directory used to load parameters from.  All NPM files (of the
form section_*.dat) from that directory will be loaded.

METHOD:

The program gathers the kinematic state from the various articulation
device angles in the label.  These are then packaged up and fed to the FSW.
A request is made to articulate the collision model, then that model is
extracted as a list of polygons, which are written to the output file in
the proper format.  For multiple images, the UNIQUE check tests the RMC
against the previous RMC (only for those elements specified by RMC_INDEX).
If they are the same, the image is skipped.  Note that only the immediately
prior image is checked, so if the file list is not sorted by RMC, there is
the possibility of multiple entries for the same RMC state in the output file.
This will not hurt anything other than file size and execution time.

The portion of the FSW used by this program was written by Justin Huang and 
Vandi Verma of Section 347.


HISTORY:
2020-02-06 rgd	Initial m20filter (based on mslfilter by B. Deen)
COGNIZANT PROGRAMMER: E. Sarkissian