Help for MARSFILTER

PURPOSE:

MARSFILTER computes a mask for an XYZ image, intdended to remove points
that are not of interest.  This is normally used to exclude the spacecraft
(e.g. rover) itself from the generated range data, but can also be used to
remove artifacts or other problems with the range data.

The input for MARSFILTER is an XYZ image such as that created by the MARSXYZ
program.  It can be a single 3-band file or three 1-band files; see MARSXYZ
for details.  The image is converted to Instrument (Rover for MER) coordinates
internally; the filter data is interpreted in that frame.  (The frame may be
overridden by COORD et al, but the filter data would also have to change.)

The program also requires a filter description file, which is an XML text
file describing the filters to be applied.  See below for the file format.
The program will automatically look for the filter file via CONFIG_PATH, or
it can be explicitly specified via FILTER.  Some filters may be modified
via numeric parameters given in PARAMS.

A second filter file can be specified with EXTRA_FILTER, which is combined
with the first.  The intent is for the first to be common filters that apply
to everything, while EXTRA_FILTER is something specific to this image, such
as what is produced by mslfilter.

The output of MARSFILTER is a single 1-band byte file, where 0 represents
something not in the filter, and 255 represents something to be filtered out.
Note that this is reversed from what you might expect at first glance, but
is intentional: it is easier to see what is being removed from the data this
way.  Labels are updated in the file, to indicate the type of image (mask),
the mask filter filenames, and the horizon value.

EXECUTION:

marsfilter inp=data.xyz out=data.mask filter=filter.xml
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.mask is an output 1-band image of type BYTE containing the mask.
filter.xml is an optional file containing the filter description.  (A
    description file is mandatory but the parameter is optional; see below).

Any program producing 3D position could be used; marsxyz is simply an example.

Note: With the -NO_XYZ option, the input need not be an XYZ image, but rather
can be anything with a PIG-compatible label describing the camera model
geometry.  However, in this case you lose the capabilty to do Volume masks.

METHOD:

MARSFILTER reads a "filter" file or files containing a description of the
mask to be generated.  While this file is mandatory, the parameter is optional.
If omitted, MARSFILTER will use the CONFIG_PATH parameter (which is usually
set to $MARS_CONFIG_PATH) to find the file:

param_files/MER1_rover_filter.xml

where "MER1" is replaced with the host ID (or mission name if only one
host) found in the XYZ image's label.  Each directory in CONFIG_PATH is
searched in turn until the file is found.  An error results if the file is
not found after the entire path is searched.

A second filter file can be provided via EXTRA_FILTER; these are combined
in the output.

The filter file is then searched for <camera> elements that apply to this
image.  There are two ways to match a filter to the image.  Both can be used
simultanously; if so, both have to match.

The first is by the camera id ("id" attribute).  This must match the instrument
name derived from the input label.  An attribute of "any" will match any
camera (thus disabling this check).  The camera ID check is best when there
are image-space mask elements, such as for a hazcam.

The second is by RMC.  Any rmc1, rmc2, ... attributes given in <camera> must
match the corresponding elements in the RMC of the image label.  Attributes
not listed do not have to match (thus if no attributes are listed, the RMC
check is disabled).  The RMC check can also be disabled by -NO_RMC.  The intent
of the RMC check is to allow filters that follow a rover's articulation state,
such as are produced by the program MSLFILTER.  Those filters that match the
image's articulation state are used, while others are ignored.

After finding the right <camera> elements, the filter entries inside are
processed one by one, adding each to the mask.

Finally, the completed mask is written to the output file.


Types of Filters
----------------

There are three fundamental types of filters, with potentially several shapes
available in each type:  IMAGE, PROJECTED, and VOLUME.

Some filters can be modified at runtime (for example, a rotation angle).
This is accomplished using the PARAMS parameter.  Numeric parameters are
supplied here; how they are used is specified by the individual filter.

IMAGE Type
----------

The filter is a shape in image space.  This becomes a constant area in the
output regardless of the input.  Note though that this is the "nominal"
image space, i.e. for MER it's based on a 1024x1024 image.  Any subframing
or downsampling is applied to these nominal coordinates.

The intent of this filter type is to remove constant obscurations for fixed
cameras (or obscurations that move with the camera).  For MER, this is used
for the underside of the rover deck for the rear hazcams, and the area
covered by the stowed IDD for the front hazcams.

There is one IMAGE shape available:

POLYGON:  A list of (x,y) coordinates of arbitrary length.  It should be a
    convex polygon, although the current implementation seems not to care.
    (The current implementation is slow, so to provide room for later
    replacement with a faster implementation, the convex polygon constraint
    should apply).  The polygon is assumed to be closed, i.e. the initial
    point need not be repeated at the end.

  Shape specified by:

    List of (x,y) vertices in nominal-image space.


PROJECTED Type
--------------

This filter is a shape in XYZ space.  The shape is projected through the
image's camera model into image space to greate a polygon, and then that
polygon is filtered as with the IMAGE-Polygon type (although without
additional subframe/downsample adjustment, since those are built in to
the camera models).

The intent of this filter is to remove items which are fixed in space (in
the coordinate system used) but which may appear in different parts of the
image due to articulation of the camera.  This mode is preferred to the
VOLUME mode when the area behind the shape is completely and statically
obscured because it removes all points in the area.  If a point in the
area mis-correlated such that it would be outside of the volume, it would
still get masked by this filter.

For MER, this type is used to model the top of the rover deck as seen by
the navcam and pancam, and to cut off the horizon.

For MSL, this type is used for almost all filters, via the mission-specific
program MSLFILTER.  This program looks at the vehicle articulation state
described in the label and computes a custom set of polygons for use by
that specific image (or other images at the same articulation state).  This
obviates the need for Volume spaces, and cuts out much less good data, e.g.
due to modeling the wheel positions rather than taking their maximum possible
volume.

There are two TRIANGLE shapes available:

POLYGON:  A list of (x,y,z) coordinates forming a closed, convex polygon
    (see the Image polyon).  Points should all be co-planar.  This works
    by projecting each point into the image, doing some cropping, and then
    onverting the result to an Image polygon.  Non-coplanar points could
    cause unexpected results.

  Shape specified by:
    List of (x,y) vertices in XYZ space.

HORIZON:  Cuts off anything above the given elevation (defined as projecting
    the pixel through the camera model and looking at the elevation component
    of that projection).  Note that the elevation is defined in the SITE
    frame, regardless of the setting of the COORD parameter.  The given
    elevation can be overridden by the HORIZON parameter (but only if the
    horizon shape exists in the file).

  Shape specified by:
    Maximum elevation above which the image is masked.

TRIANGLE:  This is a special case of POLYGON.  It is retained for
    backwards compatibility, but POLYGON should be used instead for
    new filters.

VOLUME Type
-----------

This filter looks at the XYZ values in the input image, and removes those
that are within a defined shape in 3-D space.  Unlike the other two, this
looks at actual XYZ values, so the mask will only have a value if the XYZ
image has a value at the given point.

The intent of this filter is to remove objects which are not easily modeled
by the other two.  For example, MER uses this for two things.  The wheels
as seen by the hazcams can articulate left/right and up/down.  Since they can
vary quite a bit in image space, removing them via an image filter runs the
risk of throwing out too much good data.  The volume filter captures the
wheels without hurting the surrounding terrain too much.

The other MER usage is for the superstructure above the rover deck for navcam
and pancam.  The HGA antenna moves, and the LGA is too close to the camera
to be accurately modeled in image space.  So, a large cylinder above the rover
deck removes any points on this superstructure.  Of course, points that
correlated wrong may not be removed.

The volumes can optionally be rotated arbitrarily in 3-D space, so they do
not have to align with the coordinate axes.

If the -NO_XYZ option is used, then the Volume types are not available and
will be silently ignored (a general warning is printed if -NO_XYZ is on).

There are three VOLUME shapes available:

BOX:  A rectangular space aligned with the axes.

  Shape specified by:
    Min and max extents for each of (x,y,z)
    Optional rotation

Z_CYLINDER:  A cylinder with its axis parallel to the Z axis.

  Shape specified by:
    Location of the axis in X and Y
    Radius of the cylinder
    Min and max extents of the cylinder in Z (the end caps)
    Optional rotation

Y_WASHER:  A "washer"-shaped area with its axis parallel to the Y axis.
    This could also be described as a donut with a rectangular cross-section,
    or as a cylinder aligned with Y, with a central cylinder removed from the
    volume.

  Shape specified by:
    Location of the axis in X and Z
    Min and max radii of the washer (point must be between them)
    Min and max extents of the washer in Y (the end caps, or washer faces).
    Optional rotation


FILTER FILE FORMAT
------------------

The filter file is in XML format, and is pretty straightforward.  Rather than
a formal DTD or Schema, the syntax is described by example below.  Comments
are used to further explain elements and are not part of the format (although
they are allowed as per the XML spec).  Ellipses (...) indicate potentially
repeated items and are not part of the file.  Indents and blank lines are
not required but are allowed for readability.

<?xml version="1.0" encoding="UTF-8"?>

<mesh_filter host_id="sim2">    

  <camera id="NAVCAM_LEFT">     
				<!-- id="any" will match all instruments -->

    <image shape="polygon">
      <vertex x="1.0" y="2.0" />
      <vertex x="2.0" y="3.0" />
      <vertex x="3.0" y="4.0" />
       ...
    </image>

    <projected shape="triangle">	
      <vertex x="1.0" y="2.0" z="3.0" />
      <vertex x="2.0" y="3.0" z="4.0" />
      <vertex x="3.0" y="4.0" z="5.0" />
    </projected>

    <projected shape="polygon">
      <vertex x="1.0" y="2.0" z="3.0" />
      <vertex x="2.0" y="3.0" z="4.0" />
      <vertex x="3.0" y="4.0" z="5.0" />
      <vertex x="4.0" y="5.0" z="6.0" />
      ...
    </projected>

    <projected shape="horizon">
      <max elevation="-1.0" />
    </projected>

    <volume shape="box">
      <min x="2.0" y="4.0" z="0.0" />
      <max x="4.0" y="8.0" z="1.0" />
      <rotate ... />
    </volume>

    <volume shape="z_cylinder">
      <axis x="1.0" y="2.0" />
      <min z="3.0" />
      <max z="4.0" radius="5.0" />
      <rotate ... />
    </volume>

    <volume shape="y_washer">
      <axis x="1.0" z="2.0" />
      <min y="3.0" radius="4.0" />
      <max y="5.0" radius="6.0" />
      <rotate ... />
    </volume>

  </camera>

  <camera id="PANCAM_LEFT">                
    <volume shape="y_washer">
      <axis x="1.0" z="2.0" />
      <min y="3.0" radius="4.0" />
      <max y="5.0" radius="6.0" />
    </volume>
    ...
  </camera>

  <camera id="any" rmc1="4" rmc2="2" rmc4="10">	
    ...
  </camera>

  ...

</mesh_filter>

Note that <projected shape="triangle"> is an old name preserved for backward
compatibility; the more general <projected shape="polygon"> is preferred.

The <rotate> tag in the three volume elements is optional. If present, it
specifies how the entire mask volume should be rotated.  The syntax of this
element is as follows:

<rotate x="1.2" y="2.1" z="0.0" axis_x="0.0" axis_y="0.0" axis_z="1.0" angle="10.2" add_angle="1" />

The x, y, and z attributes specify the center of rotation - what point are we
rotating around.  The axis_x, axis_y, and axis_z attributes represent a unit
vector describing the axis around which the rotation will take place.  The
angle attribute specifies how much rotation to apply.  The optional "add_angle"
attribute specifies which element from the PARAM parameter list will be added
to the angle (1-based).  This allows the amount of rotation to be adjusted
at runtime.  Angle, and the value from PARAM if used, are both specified in
degrees.

Note that the specified horizon elevation can be overridden by the HORIZON
parameter.  But the <horizon> element must be present; i.e. specifying HORIZON
without the <horizon> element does nothing.


HISTORY:
2012-04-27 Added RMC checking (rgd)
2012-03-22 Added proj poly, no_xyz, multiple files and camera elements, id=any
2011-10-26 Added HORIZON parameter (rgd)
2004-09-04 Added projected horizon type (rgd).
2003-12-08 Initial marsfilter by B. Deen.  Acknowledgement to Chris Leger (348)
          for simple polygon fill routine.
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: