Level 2 Help for MARSTIE

There are two options for describing input images. 

Either:
List the image file names 

Or:
provide an ascii file with the file names listed, one per record.

Output tiepoint table.  Can be in the old text format, or in XML (the
default).

The program checks to make sure this file does not exist before running.
This should prevent (all too common) accidental overwrites.

The old format consists of an ASCII table with a header, a record indicating
the number of tiepoints, then a series of records, one per tiepoint.  Values
in the record are:
laft_image, right_image, left_sample, left_line, right_sample, right_line,
corrected_sample, corrected_line, quality, interactive_flag

The new XML format contains similar information in a reasonably self-descriptive
XML format.

The input tiepoint file.  If not specified, tiepoints are automatically
generated around the edges of the images.

Note:  currently, if IN_TPT is given but -interactive is not, then the
program will do nothing except write the output.  This can be used to
convert tiepoint file formats.  If you wish to auto-gen more tiepoints
for pairs that don't have any, you can add to a tiepoint file (or merge
them) using -ADD_PAIR.

The vicar image band number. Defaults to 1

The width of a border all around the image to avoid in selecting
pixels for correlation.
Also is the width added to the template area all around to permit
rotation of the template.
 Defaults to 9.
 

The business threshold.
Any correlation area must have a business above BUSY to be correlated.
Business=mean pixel difference in sample + mean pixel difference in line.
Defaults to 1.0

Correlation size. Must be an odd number. Defaults to 25 square.

Correlation search area. Must be an odd number. Defaults to 49 square.
SEARCH >> TEMPLATE. If search is only a bit larger than template then
many correlations will abort because they will be prohibited from
searching in promising directions. 

Minimum acceptable correlation quality. 
In batch, correlations with qualities below QUALITY will be rejected. 
Interactively, correlations with qualities below QUALITY will be displayed
for interactive editing.  Setting QUALITY to 1.0 will force all tiepoints
to be displayed (this is not recommended for batch mode!).
Qualities range from 0 (poor) to 1 (excellent).
Defaults to 0.6  

When an input tiepoint file is given (using IN_TPT), and -interactive is
on, then normally only tiepoints which have not already been interactively
viewed will be available for editing.  This is because a tiepoint's quality
is set to 1.0 after it has been interactively edited (presumably the user
got it spot-on).  If you wish to review old tiepoints again, however, simply
specify a QUALITY greater than 1.  This will force *all* tiepoints in the
file to be interactively edited again.

TBD:  Use the interactive flag in the file, rather than setting quality to 1.0.

To select tiepoints manually.
MARSTIE will select and correlate tiepoints automatically and will display the
successful tiepoints on the images. The user can then edit the bad ones 
or add new ones.  Interactive points are not correlated by MARSTIE to refine
them, but the "tp" program has a built-in correlator if desired.

To keep only the CULL best quality tiepoints per image pair.
Defaults to 1

Keep tiepoints within SIGMA standard deviations of the mean shift
for each pair.

When tiepoints are automatically generated, they may be rejected due to
excessive shift in the line and/or sample values.  This prevents the
correlator from introducing extremely bad tiepoints.  Sometimes, however,
the pointing may be so bad that excessive shifts are needed to bring the
mosaic into line.  Raising this parameter will allow such large shifts.
Or, if the pointing is already good, and the correlator gives bad results,
this parameter may be reduced to eliminate some of the bad points.

Default: 100.0 pixels

SINGLE_EDIT mode is the traditional default.  It brings up one tiepoint at
a time in tp, based on the correlation quality.

MULTI_EDIT mode is a new mode.  It brings up ALL tiepoints for each overlap,
allowing you to see them all in tp at once.  See the main help for details.

Note that the edit type is ignored unless -INTERACT is on.  Also, QUALITY
is ignored with -MULTI_EDIT on.

MULTI_EDIT is required for ALL_PAIRS, NEW_PAIRS or ADD_PAIRS to take effect.

This parameter is only effective if -INTERACT and -MULTI_EDIT are on.

With the default, -TIE_PAIRS, only image pairs that have one or more
tiepoints will be presented in tp.  This is best for large mosaics, as the
combinatorial explosion issue would make ALL_PAIRS extremely painful.

With -NEW_PAIRS, it is like the above, but the only pairs that are brought
up are those that contain a tiepoint with the interactive flag false.  The
interactive flag is the last value in the tiepoint file.  This allows you to
pick up where you left off in -MULTI_EDIT mode.  Set special exit status,
save the tiepoint pair, and the program exits.  When you run marstie again,
set -new_pairs, and the pairs you've already edited will not be presented
again.

This is also useful to change just a few pairs.  By editing the tiepoint file
and changing the interactive flag, only those pairs will be edited.

With -ALL_PAIRS, every possible image pair is brought up in tp, whether or
not a tiepoint is found.  This is useful for small mosaics (such as MER MI),
if the automatic tiepoint finder doesn't find anything.  It's also useful for
mixed-instrument mosaics, for which tiepoints are rarely automatically found.

With -ADD_PAIRS, an input tiepoint file must be given.  First, the automatic
procedure for determining which pairs have overlaps is performed (as with
-TIE_PAIRS or -NEW_PAIRS when no input tiepoint file is given).  Then, the
input tiepoint file is examined.  If any tiepoints exist for a given pair
in the input tiepoint file, then the automatic tiepoints for that image pair
are deleted.  The auto tiepoints are then merged with the input tiepoints, and
it proceeds as in -NEW_PAIRS.

The -ADD_PAIRS mode is good for merging tiepoint sets done at different times.
If a section of a larger mosaic has already been tiepointed, -ADD_PAIRS can
be used to accept all those points, and add whatever is missing from the new
images.  You can also merge two sets done independently into one input tiepoint
file, then -ADD_PAIRS will find and present the tiepoints between the sets.

Note that if all tiepoints of a pair were deleted originally, that pair will
come up again if the auto tiepoint finder thinks there is an overlap.

Maximum separation angle for image pairs.  If the camera orientations are
separated by more than this angle, the pair is skipped.  This provides a
quick efficiency boost by rejecting spurious pairs.

Typical values:  sep_angle=53 for MER navcam
                 sep_angle=36 for MER pancam

TBD: This should be calculated from the camera FOV in the future.

Starting key number for the tiepoint file (XML format only).  Tiepoint files
contain a list of images, each of which is associated with an integer key.
Setting START_KEY to some value allows tiepoint files to be merged easily,
without the keys conflicting.  It is acceptable to have the same image in
different sections of a merged file (with different keys); they are properly
merged when read in.

There are two tiepoint file formats: "old" is the simple text-based list,
as used for most of MER, while "xml" is an XML-based format that supports
additional tiepoint types.  The FORMAT parameter controls which one to use.
Over time the use of "old" should be phased out and eventually the FORMAT
parameter will disappear.

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).

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.  
    

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.

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 options are surface=INFINITY which means no surface
is used, surface=PLANE (the default case). If surface = PLANE then the plane
is defined by the NORMAL and GROUND parameters.  For the cases when PLANE 
doesn't match local topography sufficiently well, here are two sphere surface
models: surface=SPHERE1 and surface=SPHERE2.  SPHERE1 is useful to model
convex surfaces like hills, it returns closest(first) ray-surface intersection 
point.  SPHERE2 is useful to model concave surfaces, like crater when the
camera point is outside looking in, it returns farthest(second) ray-surface 
intersection point.  For the case when camera is inside the sphere surface, 
like rover sitting in the crater, there is only a single intersection point
and SPHERE1 and SPHERE2 behave exactly the same. Last, MESH is a surface
model defined by a mesh file (.obj) which path is given with 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.

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).

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:

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.

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.

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.

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).

This parameter is ignored by marstie.  It is here for compatibility
with subroutines used by other programs (see e.g. marsmap).

This parameter is ignored by marstie.  It is here for compatibility
with subroutines used by other programs (see e.g. marsmap).

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.