Level 2 Help for MARSCAHV

INP

Input image.


OUT

Output image.

If BAND is not specified, the output will have the same number of bands
as the input, and all bands will be processed. If BAND is specified, the 
output will have a single band.


NAVTABLE

Corrected navigation filename.
If marsnav was run on the input images it created a table of corrected
pointing parameters. If you refer to this table using NAVTABLE it
will override the pointing parameters (e.g. azimuth and elevation) in the
picture labels, giving you a better registered output.


STEREO_PARTNER

VICAR image which camera model forms a pair of almost aligned camera models 
with input image's camera model.  If stereo_partner is not present, the 
program tries to find stereo partner of the input image based on mission, 
instrument etc. info of the input image.  The presence of stereo_partner 
input parameter is an unconditional overwrite of that process.
Note that for a generic camera, there is absolutely no way to tell what the
stereo partner might be, or even if there is one.  Thus using stereo_partner
input parameter is the ONLY way to specify stereo pair for generic image.


FULLSIZE

Overrides size of the input image.  If the input image is a subframe and the 
camera model in the label corresponds to the fullframe image, FULLSIZE would
specify the size of the fullframe.  Moreover, the presence of this input 
parameter would tell us that we are in the situation described above and need
to deal with it accordingly.


OUTSIZE

Overrides size of the output image.  (NL, NS) order.


AUTOSIZE

Sets size of output image to be the minimum or maximum of each dimension in
both inputs.  Ignored if stereo_partner is not given.


OUTOFF

Overrides x/y offset values for output.  This offset is the distance from the
camera coordinate origin to the image origin (0-based) and affects where the
center of the projection falls in the output.


BAND

The BSQ input file band number. Default is to process all bands (e.g. color).
Providing a value will cause only that one band to be processed.


NORMAL

The local mars surface normal vector coordinate system specified by SURF_COORD 
parameter (defaults to surface fixed).
For most pan/tilt cameras, if the lander is not tilted this vector
would be: normal=(0,0,-1).  ie: x_component=0, y_component=0, z_component=-1.
This need not be a unit vector.  This vector is used to define the
surface plane to which image points are projected in order to minimize
parallax.
For SPHERE1/2 surface models, normal's first parameter is used to
denote sphere's radius.  Thus to describe sphere of radius R, user
would specify normal=(R, 0, 0).


GROUND

Any point on the surface, in coordinate system specified by SURF_COORD parameter
(defaults to surface fixed).  This defines where the tilted plane is in space.  
Although any point may be used, normally the point just "under" the origin is selected.
Defaults:
Mars Pathfinder:  (0.0, 0.0, 0.0)       (lander zero point is on the ground)
Mars 98 Lander:   (0.0, 0.0, 1.64)      (lander zero point is on top of deck)
MER           :   (0.0, 0.0, 0.294)
For MER images taken on top of the lander, the ground is roughly at (0.0, 0.0, 0.7)
For SPHERE1/2 surface models, GROUND parameter is used to denote sphere's
center.  
    


SURF_COORD

The coordinate system that surface parameters like GROUND and NORMAL are defined in.
For valid values refer to COORD parameter description.  The interpretation of the 
values is dependent on the mission. Defaults to surface fixed coordinate system.
Note that no validation is done for input strings because COORD is using the same
values.  So user needs to be extra careful in specifying SURF_COORD value.  For 
example COORD=local would be correctly interpreted to mean LOCAL_LEVEL because of
validation process.  On the other hand specifying SURF_COORD=local would lead
to underlying code treating the input value as invalid and reverting to default
which is FIXED frame.  So the values for SURF_COORD should be spelled exactly as
found in the list of valid values for COORD parameter.


RADIUS

Radius of surface sphere.


SURFACE

The type of mars surface to use. The surface is used to intercept view rays
emanating from the cameras in order to model out parallax between the
stereo cameras. The two options are surface=INFINITY which means no surface
is used or surface=PLANE (the default case). If surface =PLANE then the plane
is defined by the NORMAL parameters. If surface = SPHERE then the sphere is 
defined by radius and center. Last, MESH is a surface model defined by a mesh 
file (.obj) which path is given with SURF_MESH.


SURF_MESH

Mesh OBJ file to use as the surface model. For the mesh to be used,
SURFACE must be set to MESH. The coordinates of the mesh vertices can be 
expressed in any CS. However the mesh CS must be supplied via SURF_CSFILE.
If SURF_CSFILE is not used, then the mesh is assumed to be to the CS that
results from COORD or SURF_COORD

VARI SURF_CSFILE 
File name of a vicar file whose CS (contained in the labels) will be read and
assigned to the SURFACE model. The type of image and its content are of no
interest, we are just reading the CS. That CS will supersede any other surface 
CS definition (COORD or SURF_COORD). Its typical use is to supply a CS to a
given mesh file (expectedly the XYZ from which the mesh is computed from, but
doesn't have to). But SURF_CSFILE could be use to define a CS in which NORMAL 
and GROUND for a PLANE surface are expressed in.


RAD

Keyword parameter that turns on or off radiometric correction of the input
images.  RAD (the default) enables the correction (for missions/instruments
which support it), while NORAD disables it.


DNSCALE

DN scaling factor.  This factor is used to convert between physical
radiometric units (watts/(meter**2, steradian, micron)) and DN's for the
output.  The formula is:

true_radiance = offset + (factor * DN)

where "offset" is 0.0 in the current implementation, and "factor" is
1.0 / DNSCALE (making the formula equivalently:  offset + (DN / DNSCALE)).
The offset and factor (1.0/DNSCALE) are written to the output label.
 


CONFIG_PATH

A colon-separated list of directories in which to look for configuration
and calibration files.  Environment variables are allowed in the list
(and may themselves contain colon-separated lists).  The directories are
searched in order for each config/cal file when it is loaded.  This allows
multiple projectes to be supported simultaneously, and allows the user to
override any given config/cal file.  Note that the directory structure below
the directories specified in this path must match what the project expects.
For example, Mars 98 expects flat fields to be in a subdirectory named
"flat_fields" while Mars Pathfinder expects them to be directly in the
directory specified by the path (i.e. no intermediate subdirectories).


MATCH_METHOD

Specifies a method for pointing corrections.

Loose method matchs with pointing parameters of the image.
Tight method matchs with unique id of the image.


MATCH_TOL

Tolerance value for matching pointing parameters in the pointing corrections file.
Used if MATCH_METHOD=LOOSE
Default value is pretty arbitrary, though seems to work well so far....


POINT_METHOD

Specifies a mission-specific pointing method to use.  Normally this
parameter is not used, in which case the "default" pointing methods
are used.  Some missions may have special, or alternate, pointing
methods available, which are indicated by this string (for example,
backlash models, using arm joint angles instead of x/y/z/az/el, etc).
A substring search is used, so multiple methods (where that makes sense)
can be specified by separating the keywords with commas.

Note that nav files created using one pointing method will most likely
not be compatible with a mosaic created using a different pointing method.

The methods available vary per mission, but some methods available at
the time of this writing are:

CAHV_FOV: All Missions using CAHV-based camera models.  Valid values are:
* MIN or INTERSECT:    Aligning stereo-pair cameras produces virtual camera 
                       with FOV equal to INTERSECTION area of two input 
	               cameras. (default) As a result, the output image is 
                       missing,sometimes a significant, (depending on camera 
                       geometry) part of overlap area between two cameras but 
                       there are no black areas on the side.  The image data
	               is stretched in horizontal direction.

* MAX or UNION:        Aligning stereo-pair cameras produces virtual camera 
                       with FOV equal to UNION area of two input cameras.
         	       The result is the opposite of the MIN option: 
                       wide black areas on the side, but the stereo-pair's 
	               intersection area is preserved.  The image data
	               is squeezed in horizontal direction.

Note that the above two entries have two names each, which are equivalent
and it's up to the user to decide which one is more intuitive to him/her.

* LINEAR:              Uses only CAHV vectors and ignores higher order terms 
                       OR(E) while aligning the cameras.  As a result, this
                       mode has advantage of best preserving horizontal
	               aspect ratio.  The features in the image look
                       similar, scale-wise, to the original.

BACKLASH : Mars 98 SSI only.  Selects a backlash pointing model,
which adjusts the telemetered azimuth and elevation values based on
knowledge of the camera's mechanical backlash and the direction the
motor was travelling when the image was taken.


NOSITE

Disables all label-derived parameters to the Site mechanism which underlies
coordinate systems.  This forces all sites to be identical, with all rotations
and offsets set the same.  In the case of MPF or Mars 98, this disables
the lander quaternion and offset (sets them to identity and 0, respectively).
This option should not be used with images taken from different vantage
points (e.g. the spacecraft moved, or mixing a lander and a rover) or
invalid results will be obtained.  The use of this option invalidates the
Fixed coordinate frame; any values reported in the Fixed frame will not
correctly reflect the orientation of the lander/rover.

Obviously, this option should be rarely used; it is intended for when the
image labels defining the site are invalid or inconsistent.


INTERP

Keyword parameter that turns on or off interpolation of the output
images pixel values.  INTERP (the default) enables the interpolation, 
while NOINTERP disables it.


UNSUB

The UNSUB mode will "un-subframe" the image before linearizing it.
When this mode is on, the program looks up the nominal size of the camera
frame (using the camera mapping file), and sets the output to be that size.
It then puts the input in the right position in the output according to the
subframe start (FIRST_LINE and FIRST_LINE_SAMPLE labels for most missions).
From then on, it proceeds as if a full-frame image had been given.  This is
useful for cameras like the MSL Mastcam, where the differential zoom on both
eyes causes them to often do different subframes on the two eyes.  Removing
the subframe puts it all back in the same geometry again, so downstream
programs that need the same image size for both eyes can work.


OMP_ON

Turns on or off parallel processing.  The default is on.  The main help
describes some environment variables that can further control parallel
processing.  Note that this program uses standard OpenMP (which is built in
to the gcc/g++ compilers), so further details can be found in the OpenMP
documentation.


DATA_SET_NAME

The DATA_SET_NAME typically identifies the instrument that acquired the
data, the target of that instrument, and the processing level of the data.
This value is copied to the output label, property IDENTIFICATION,
keyword DATA_SET_NAME.


DATA_SET_ID

The DATA_SET_ID value for a given data set or product is constructed
according to flight project naming conventions.  In most cases the
DATA_SET_ID is an abbreviation of the DATA_SET_NAME.
This value is copied to the output label, property IDENTIFICATION,
keyword DATA_SET_ID.


RELEASE_ID

When a data set is released incrementally, such as every three months during
a mission, the RELEASE_ID is updated each time part of the data set is released.
For each mission(or host id if multiple spacecrafts), the first release of a data
set should have a value of "0001".
This value is copied to the output label, property IDENTIFICATION,
keyword RELEASE_ID.


PRODUCT_ID

Specifies a permanent, unique identifier assigned to a data product by
its producer. Most commonly, it is the filename minus the extension.
This value is copied to the output label, property IDENTIFICATION,
keyword PRODUCT_ID.


PRODUCER_ID

Specifies the unique identifier of an entity associated with the
production of a data set. This value is copied to the output label,
property IDENTIFICATION, keyword PRODUCER_ID.


PRODUCER_INST

Specifies the identity of a university, research center, NASA center or other
institution associated with the production of a data set.
This value is copied to the output label, property IDENTIFICATION, keyword
PRODUCER_INSTITUTION_NAME.


TARGET_NAME

Specifies a target.  The target may be a planet, satelite, ring, region, feature,
asteroid or comet.  This value is copied to the output label, property
IDENTIFICATION, keyword TARGET_NAME.


TARGET_TYPE

Specifies the type of a named target. This value is copied to the output
label, property IDENTIFICATION, keyword TARGET_NAME.


RSF

Rover State File.  This is a list of filenames to load containing
Rover State information.  These files contain position and orientation
information for a rover (or other mobile spacecraft) at various sites.
They are in XML format.  See the "Rover Motion Counter (RMC) Master File SIS
"
for details on these files.

Rover State Files have a priority order.  The files listed first have
the highest priority.

Environment variables may be used in the list.

For MER, if a directory is specified, then that directory is searched for
RMC Master files and any found are loaded.  The directory structure and
filename convention is covered in the RMC SIS.  The directory specified
is the one containing "master", so if <dir> is the name specified in the
RSF parameter, the following files will be searched for:

<dir>/master/_Master.svf
<dir>/master/_Site__Master.rvf
The name of each file loaded is printed to the stdout log for reference.


DEBUG_RSF

If enabled, this causes the internal database of RMC locations to be
printed out to the stdout log.  This is after the RSF files have been
loaded and the coordinate systems read from the input label(s).


COORD

The coordinate system to use for the output camera model.  Also the coordinate
system used for the actual ray tracing.  Note that the surface model parameters
are always expressed in the Fixed site, however.

The interpretation of the values is dependent on the mission.  Some
representative missions are listed here:

Fixed - The Fixed frame (default).  This is the ultimate reference frame
    (see also FIXED_SITE for rover missions).
Instrument - The "natural" frame for the instrument (of the first input
    image).  MPF: Lander or Rover; M98: MVACS; MER: Rover.
Site - A major Site frame.  For rover missions, COORD_INDEX specifies which
    Site frame to use.  Non-rover missions treat this as Fixed.
Rover - An instance of the Rover frame.  For rover missions, COORD_INDEX
    specifies which instance of the rover frame to use.  Non-rover mission
    use the spacecraft frame (e.g. Lander for M98).
Local_Level - An instance of a Local Level frame.  This is typically
    coincident with the Rover frame (in XYZ) but oriented toward North
    like the Site and Fixed frames.  For MER, this is an instance of a
    Drive index move.


COORD_INDEX

The index specifies which instance of a coordinate system to use.  It is
currently applicable only to rover-based missions, but could have other
uses.  The index is equivalent to the Rover Motion Counter (RMC) for MER
and FIDO.

For MER/FIDO, there are many Site frames.  Each is numbered with a single
index.  For Site Frames, coord_index specifies which to use.  Likewise,
there are many Local_Level and Rover frames, corresponding to values of
the RMC.  The multiple instances of this frame are selected by COORD_INDEX.

Generally COORD_INDEX defaults sensibly so you don't usually need to
specify it.  It will default to the instance used by the first input.


FIXED_SITE

Specifies which major Site is the "Fixed" Site for this run.

Historically, MPF and M98 had a single "Surface Fixed" frame which never
moved, and which all other coordinate system frames were referenced to.
With the advent of long-range rovers (such as MER and FIDO), that became
insufficient.  The rover traverses far enough that errors in knowledge of
coordinate system offset and orientation become unacceptable.

For this reason, a system of major Sites was introduced.  Periodically
during the mission, a Site frame is declared.  This then becomes the
reference frame for all activities until the next Site is declared.
References are kept local, and errors don't propogate across Sites.

However, if images from more than one Site are combined together, the
Site's must be placed relative to each other.  Therefore a single reference
frame is still needed to combine different sites.

The FIXED_SITE parameter controls which of the major Site frames is
the reference ("fixed") site for this program run.  This fixed frame
can vary in different program runs, but is constant throughout one
execution.

If not specified, FIXED_SITE defaults to the minimum Site number (i.e.
lowest numbered, or earliest chronologically) used in all input images.
Normally this default is sufficient; rarely must FIXED_SITE be specified.

One or more Rover State Files must usually be specified in order to combine
image from more than one Site.  These describe the relationship between
sites.  See the RSF parameter.


SOLUTION_ID

Specifies which solution ID to use for pointng corrections.

There are potentially many different definitions for the same coordinate
system.  These are identified via a unique Solution ID.  If this parameter
is given, only the specified solution's definition is searched for.