Level 2 Help for MARSNAV

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.

Note that normally only the label is used from the input images.  They
are typically image files for convenience and compatibility with marstie et al.
However, Dynamic XYZ tiepoints require the corresponding input file to be an
XYZ image.

Output navigation table, containing the updated pointing and surface model
information.  It should also contain rover localization if used, but this is
not yet implemented.

This is either an XML file, or an ASCII table, depending on the value of
FORMAT.

The input tiepoint file, as generated by MARSTIE (or a previous run of
MARSNAV).  This file must be specified.  It can be in either the old text
format, or the new XML format (it detects this automatically).

The output tiepoint file, which holds changes to the tiepoints made by either
batch or interactive editing modes of MARSNAV.  This file is always written
in the new XML tiepoint format.  It can be converted to the old format using
marstie.

The optional input navigation table.  If provided, this allows the user to
provide an initial nav solution, which is then tweaked by the marsnav process.
This allows a pointing solution created by other means, (such as MICA) or via
an earlier marsnav run, to be adjusted.  This may be used to better globally
distribute error or accomodate new tiepoints, among other things.

Note that there is no guarantee the result will bear any resemblance to the
input nav file.  It is merely a starting point, and marsnav may go off in a
completely different direction.

The output format of navigation file.
If format=TXT, then the output is an ASCII table with a header,
then one record per input picture giving:
Number of Parameters (N), N Original Parameters, N Corrected Parameters
If images come from different instruments, the number of pointing parameters
may be different for each one.  The parameters are often 2 (Azimuth, Elevation)
but that depends on the instrument.  See the Pig documentation.

If format=XML, then the output is a xml file in following format:
<?xml version="1.0" encoding="UTF-8"?>
<pointing_correction ...>
   ...
  <priority>
    <entry solution_id=.../> 
  </priority>
  <solution ...>
    <image filter=... frame_id=... image_id=... instrument=...>
       <original_parameters type=...>
         <parameter id=... value=.../>
       </original_parameters>
    </image>
    <pointing_parameters type=...>
       <parameter id=... value=.../>
    </pointing_parameters>
    <camera_model type=...>
       <parameter id=... type=... value=.../>
       ...
       <reference_frame name=... index=.../>
    </camera_model>
  </solution>
  ...
</pointing_correction>

Solution id for the OUTPUT navigation file in XML format.
If solution id is missing when FORMAT=XML, then the output
navigation file can not be created (therefore the parameter is required).

Specifies which solution ID to use for the INPUT nav file (if present).

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.  Normally
it is not used.

Controls whether tiepoint editing (performed when a residual is > ERROR) is
performed interactively or automatically.  See the METHOD section of the
program help.

Specifies which image (if any) are reference images.

Reference images are assumed to be correctly navigated and will not be
adjusted (but see ADJREF).

Defaults to the image with the greatest number of connected images once
tiepoints have been culled to one per pair.

REFIMAGE=-1 means no reference image.

EFIMAGE can be a single image, or a list of images.  Each image in the
list will be a reference image.  (see also UNTIL).  This allows any arbitrary
images to be selected as references.  If an image number is negative, it
means all images from the previous number through (the absolute value of)
this one will be references.  For example a list:

1,3,-6,8,11,-15

will cause the following images to be reference imgaes:

1,3,4,5,6,8,11,12,13,14,15

Numbering of images starts at 1.

Means that all images from 1 to the first value of REFIMAGE inclusive are
treated as reference images.  The pointing of these will not change.  Any
additional images listed in REFIMAGE will also be reference images.

The functionality of this parameter has been subsumed by the negative number
feature of REFIMAGE.  For example, REF=5 -UNTIL is the same as REF=\(1,-5\).

If given ADJREF specifies how many parameters to keep constant for reference
images.  Parameters beyond ADJREF get adjusted even if the image is a reference
image.  This allows, for example, twist to be adjusted even when the locations
are fixed (MER 3dof pointing model).

Parameter numbers are 1-based.

Specifies a list of images that will be ignored.  Tiepoints containing this
image will be ignored and excluded from consideration (but see IGNORE_INTRA).
This has two purposes.  First, for very large tiepoint files, when adjusting
only a few images (via REFIMAGE), the presence of spurious tiepoints can be a
significant performance drain.  Second, this allows you to exclude a tiepoint
that is known to be problematic.  This might occur, for example, when matching
a foreground mastcam image to a background navcam image - even though the
foreground to background connections are correct, they may pull the foreground
solution out of alignment.

Ignored tiepoints still appear in the output tiepoint file (if one is written).

Ignored images should always be reference images (although this is not checked
nor enforced).  A non-reference (active) image cannot be adjusted if all
tiepoints containing that image are removed.

Like REFIMAGE, IGNORE accepts negative numbers to indicate ranges.  So a value
of 4,-7 means 4,5,6,7 are all ignored.  See REFIMAGE for more examples.

This flag causes all tiepoints between non-reference (active) images to be
ignored.  Only tiepoints between non-reference and reference images will be
considered.

The use case for this is as follows:  Say you are insetting images (e.g.
mastcam on MSL) into a background (e.g. navcam) mosaic that has already been
tiepointed and nav'd.  You want to coregister the images to the background.
This flag allows you to use autotie to get a complete set of tiepoints but
then only use the ones tying the foreground to the background.  This is
beneficial because the normal autotie modes will create many more overlap
ties than full-image ties, making the overlap ties overwhelm the full-image
ties.  Since you want the full-image ties, this flag lets you ignore the
overlap ties.

The final pixel tiepoint residual error that is permitted. Points 
exceeding this residual are candidates for removal in batch mode
(potentially after recycles), or will be edited if the INTERACT mode
is used.  Default is 0.1 pixels, which makes sense only with -noremove.
A value like 7 (the old default) would be better in removal mode.

This parameter is only used in batch mode (not interactive), when a tiepoint's
residual exceeds ERROR.  RECYCLE specifies the number of times to re-run the
solution, starting where the previous one ended, before deleting the offending
point.  Once a point is deleted, the solution is re-started at its initial
conditions, with a potential for RECYCLE more reruns until the residual is
acceptable.

Specifies the minimum number of tiepoints for an image.  If at the end of
the run, an image has fewer than MINTIE tiepoints still active, it is reset
to its initial conditions - the adjustments are ignored.  This is to prevent
uncontrolled drift when there are no tiepoints.  INERTIA is supposed to fix
this, but has been shown to be ineffective in some cases.

Caution should be exercised with this, as if there is a systematic motion of
nearby frames, the frames with too few tiepoints will not participate in this
systematic motion.

This is not exactly the same as setting the image to be a reference image,
because the few tiepoints that DO exist do still pull on their partners.  This
could cause them to get pulled out of position, potentially.  Generally there
should be enough other tiepoints to mitigate this.

The default is 0, which disables all resetting.  Suggested values are 1
(reset those with just one tiepoint) or 4 (enough to overconstrain a solution
so it doesn't rotate and scale uncontrollably, as could happen with 2 or 3).

Tolerance value for amoeba.  Specifies how accurate the answer should be.
(more precisely, amoeba terminates when the amount of change in the cost
function is less than this amount).  Larger numbers can greatly speed up
runtime.  For marsnav, values of .001 are probably sufficient for most
cases, but this has not been rigorously tested.  The default is .0001.

Default is pretty arbitrary but seems to work well...

This keyword specifies whether or not pointing should be adjusted.  It defaults
to on.  You may wish to turn off pointing correction if you were only
interested in a surface model or localization adjustment.  Note that a nav
file is still written even if NO_POINTING is on; it simply specifies no
adjustment.

This keyword specifies whether or not the surface model should be adjusted.
It defaults to off (NO_SURFACE).  Allowing the surface model adjust can be
helpful for unusual situations, such as MER-MI mosaics or the inside of the
MER-B landing crater.  If you turn on surface model adjustment, you should
have a good number of very high-quality tiepoints, that are well distributed
over the image overlaps.

Note that the resulting surface model is not written to a file anywhere; the
results are simply printed to the stdout log.  This happens at each iteration,
as well as again at the end of the program.  For convenience, they are
printed out in a form that can be easily cut-and-pasted into other programs'
command lines.

The surface model will be printed out at the end of the run in both the frame
specified by SURF_COORD, and (if different) the one specified in COORD.  This
allows for example the ROVER frame to be used for adjustment, but the SITE
frame used for specifying the surface to later programs.

Specifies which rover locations are to be adjusted.  This changes the XYZ
location of the rover only; it does NOT adjust the rover orientation (see
DO_ORIENTATION).

When marsnav runs, it prints out a list of all sites used by the input files.
Note that a "site" in this sense is any rover position, NOT just formally a
Site frame.  This list is indexed by a single number (counting 0 to n).
DO_LOCATION is a list of these numbers specifying which of the locations to
adjust.  These are not Site indexes (e.g. as defined by MER); they are
indexes into the printed-out table.  Note that this means you must normally
run marsnav once to get this table printed, kill it, and rerun with
DO_LOCATION specified.

For example, if the following is printed:

List of Sites used by input files:
  Site 0,'MER_ROVER: (11,55,73,367,167)',count=9. Adj loc=0,ori=0. match loc=-1,ori=-1
  Site 1,'MER_ROVER: (11,55,111,396,291)',count=7. Adj loc=0,ori=0. match loc=-1,ori=-1
  Site 2,'MER_ROVER: (11,55,119,403,291)',count=23. Adj loc=0,ori=0. match loc=-1,ori=-1
  Site 3,'MER_ROVER: (11,59,0,0,0)',count=42. Adj loc=0,ori=0. match loc=-1,ori=-1

it says that 9 images use the "MER_ROVER: (11,55,73,367,167)" position, which
is called 0 in marsnav.  42 use "MER_ROVER: (11,59,0,0,0)", which is called
3, and so on.  If you wanted to adjust the last two locations, you would give
DO_LOCATION=(2,3).  Check to make sure the appropriate "adj loc" values change
to 1.

Ignore match loc at the moment.  Eventually the plan is to allow sites to
be glued together such that one value changes both, but this is not yet
implemented.

*IMPORTANT*  The results of the localization are printed to stdout, as
with DO_SURFACE.  These results are NOT written into an RMC file.  They
should be, but implementation time during ops did not allow for this.  So,
you must create an RMC file by hand, and cut-and-paste the printed values
into it.  The XYZ and quaternion are conveniently formatted for cut-and-paste
into an RMC file.

Note:  in some cases you may want to take the resulting XYZ value and use
it as a Site vector (SVF file) rather than a Rover vector (RVF).  However,
any simultaneous adjustment of positions within the same site would have to
be adjusted to account for the site offset.  Position 0 is by definition at
offset (0,0,0) to the Site, so any adjustment of Position 0 really needs to
be a Site update.  But that adjustment would not be reflected in the other
positions within the site so the value would have to be subtracted from the
other calculated positions in order to maintain consistency.

Note that DO_LOCATION cannot be used with OMP_ON.

Specifies which rover orientations are to be adjusted.  This changes the
Euler angles (and thus the quaternion) of the rover only; it does NOT
adjust the rover location (see DO_LOCATION).

When marsnav runs, it prints out a list of all sites used by the input files.
Note that a "site" in this sense is any rover position, NOT just formally a
Site frame.  This list is indexed by a single number (counting 0 to n).
DO_ORIENTATION is a list of these numbers specifying which of the orientations
to adjust.  These are not Site indexes (e.g. as defined by MER); they are
indexes into the printed-out table.  Note that this means you must normally
run marsnav once to get this table printed, kill it, and rerun with
DO_ORIENTATION specified.

For example, if the following is printed:

List of Sites used by input files:
  Site 0,'MER_ROVER: (11,55,73,367,167)',count=9. Adj loc=0,ori=0. match loc=-1,ori=-1
  Site 1,'MER_ROVER: (11,55,111,396,291)',count=7. Adj loc=0,ori=0. match loc=-1,ori=-1
  Site 2,'MER_ROVER: (11,55,119,403,291)',count=23. Adj loc=0,ori=0. match loc=-1,ori=-1
  Site 3,'MER_ROVER: (11,59,0,0,0)',count=42. Adj loc=0,ori=0. match loc=-1,ori=-1

it says that 9 images use the "MER_ROVER: (11,55,73,367,167)" position, which
is called 0 in marsnav.  42 use "MER_ROVER: (11,59,0,0,0)", which is called
3, and so on.  If you wanted to adjust the second and fourth orientations,
you would give DO_ORIENTATIONS=(1,3).  Check to make sure the appropriate
"adj ori" values change to 1.

Ignore match ori at the moment.  Eventually the plan is to allow sites to
be glued together such that one value changes both, but this is not yet
implemented.

*IMPORTANT*  The results of the localization are printed to stdout, as
with DO_SURFACE.  These results are NOT written into an RMC file.  They
should be, but implementation time during ops did not allow for this.  So,
you must create an RMC file by hand, and cut-and-paste the printed values
into it.  The XYZ and quaternion are conveniently formatted for cut-and-paste
into an RMC file.

Note that DO_ORIENTATION cannot be used with OMP_ON.

If NOREMOVE is specified, the program will not remove the worst tiepoint
in batch mode.  Instead, when recycles are exhausted, it will simply exit
with the current solution.  The default is NOREMOVE.

This mode can be helpful when adjusting a surface model, or when all tiepoints
are known to be good.

Specifies a threshold for residuals.  Any tiepoint above this residual will be
removed during the editing process.

Specifies a maximum number of loops for the remove-tiepoint process.
When tiepoints are removed, the whole solution is restarted from the
beginning (so as to not be influenced by the now-gone tiepoints).  If
MAX_REMOVE is specified, it sets a limit on the number of times this
restart can happen, independent of whether the other loop termination
criteria (error or max residual) are reached.

The INERTIA parameter modifies the residual used for function minimiziation
by adding a factor that makes the images tend to stay in place.  For each
pointing parameter, the difference between the original value of the pointing
parameter and the current value is multiplied by the corresponding INERTIA
value, and the result is added to the residual.  Each pointing parameter can
have a different value for INERTIA.  The result of this is that, depending on
the weight imparted by INERTIA, images will tend to stay where they are,
adjusting less in response to tiepoints than they otherwise would.  This has
the beneficial effect of preventing "drift" of the entire solution.  For
example, for a typical cylindrical projection, you can add some value to all
of the azuimuths and not affect the residual at all.  The solution could thus
"random walk" around in azimuth, giving incorrect results.  INERTIA can prevent
that by introducing an error term whenever the azimuth moves.

Selecting an appropriate value for INERTIA is a dicey proposition.  The unit
of the residual is a distance in pixel space, squared.  Pointing parameters
can be any unit, but are typically in degrees.  Thus the units for INERTIA
itself are typically pixels^2/degree.  It is best selected by trial and error.
Experience has shown that values in the range of 5 to 20 are appropriate for
MER pointing parameters (coincidentally enough, both for mast camera angles
and for MI joint angles).  Note that it is not uncommon to have different
inertia values for each pointing parameter.  An INERTIA of (5,20,10) might
be useful for the right side of a stereo mosaic.  The 20 weights elevation
changes heavily, which tends to reduce vertical disparity.  The weights for
azimuth and twist are less, allowing them to change more.

Note that INERTIA applies only to image pointing parameters.  Pointing
parameters relating to surface models or rover localizations do not participate
in any INERTIA.

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.

This keyword determines the type of error values used by amoeba when
correcting pointing parameters. TRADITIONAL uses line/sample space
tiepoint differences. MISS_DISTANCE uses the minimum distance between
the projected rays in XYZ space, scaled by the MISS_MULT parm value.
BOTH sums the two errors, with the miss distance error scaled by
multiplying with MISS_MULT. The default is TRADITIONAL.

This real-valued parameter is used as a scale multiplier for the miss
distance in miss-distance tiepoints.  The default value is 333.3.  The xyz
errors are scaled to control the relative strengths of xyz and pixel
space errors when both errors are combined, for example when mixing
Traditional and Miss Distance tiepoints, or when using Traditional
tiepoints with TRAD_MODE=BOTH.

When using miss-distance tiepoints, it is possible to get tiepoints whose
rays are very close to parallel (e.g. distant tiepoints, near the horizon).
Miss distance becomes very sensitive to noise when the rays are very close
to parallel.  This parameter sets a limit on how close to parallel rays can
be and still be considered; those tiepoints that exceed this threshold are
ignored.  The value is specified as the dot product of the two vectors, in
other words the cosine of the angle between them.  The default is 0.9999.

Specifies whether or not to scale miss-distance tiepoints by their range.
Scaling causes nearby points to "count" more, on the theory that they are
more accurate (because farther points' rays become closer to parallel and
are thus more susceptible to noise).  In addition, the error of one far-away
point can swamp a bunch of nearby points if not scaled by range.  This is
off by default, i.e. errors are not scaled by range.

Turns on or off parallel processing using OMP, which uses multiple cores on
a single host machine.  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.

Overrides the degree of parallelism used, which affects how the pamoeba
algorithm behaves but also affects how many parallel threads are used.
A value of 1 is (almost) equivalent to the serial amoeba algorithm.  See the
main help for details.

The local surface normal vector in the coordinate system specified by
SURF_COORD (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 the coordinate system specified by SURF_COORD
(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 the user needs to be extra careful in specifying
SURF_COORD values.  For example COORD=local would be correctly interpreted
to mean LOCAL_LEVEL because of the 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 the 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.

Specifies a method for reading the nav file.

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

Applies only to an input nav file, if given (not to the output nav file).

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

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 marsnav, except for one place.  It is
here for compatibility with subroutines used by other programs (see
e.g. marsmap).

If DO_SURFACE is specified, then the final surface model is printed out
in the coordinate system specified by COORD as well as SURF_COORD.  This
allows for example the input surface to be specified in ROVER frame, and
ROVER frame will be used to adjust it.  But the final surface will be
printed in both ROVER and SITE frames.  This allows the SITE frame value
to be used in subsequent steps, which more closely follows normal practice.

This parameter is ignored by marsnav (except in one case; see COORD).  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.