Two files containing the input stereo pair images. The pixel data from these files are not used; only the label information is used to determine the pointing and camera models. A single file list file may also be specified (a la marsmos, etc.), but the file list must have only two entries. Note that there's no actual requirement that the first input be left or the second right. The two images can be given in any order. The first image, though, is the "master" image; the disparity maps and output files match the first image's pixels. Convention places left first, however.
Output files containing the XYZ coordinates. If three filenames are given, three separate 1-band files will be created, one each for X, Y, and Z. If only one filename is given, a single 3-band file will be created, with bands in (X,Y,Z) order. The output files are in REAL (float) format.
REAL-formatted images giving the line and sample disparity. Either two files may be given (line, sample order), or a single file with two bands. The disparities are interpreted as follows: Each pixel in the disparity map corresponds to the same pixel in the first (left) input. The value of the pixel in the disparity map is the line and sample of the point in the second (right) image, which matches this location in the first (left). Note that these are standard VICAR 1-based file coordinates. If both line and sample disparity values are 0, the point has no value.
A REAL-formatted output file containing the view ray miss distance, in meters. This file is not required and will not be generated if ERR_FILE is not specified.
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 different (and presumably better) output coordinates.
Maximum permitted view ray miss distance per meter of range. Any two projected view rays through a pixel will miss by some value M meters. If M divided by the range to that pixel (in meters) exceeds ERROR the point will be rejected. Default is .0025 (or 2.5 millimeter per meter).
Maximum permitted view ray miss distance in absolute terms (not adjusted for range). Any two projected view rays through a pixel will miss by some value M meters. If M exceeds ABSERROR the point will be rejected. Note that the absolute error should not be larger than the camera baseline (distance between the cameras); that would indicate a divergent ray. The value should be somewhat less than that, although testing with MER data shows a .05 is a good cutoff regardless of baseline. Default is .05 (or 0.5 centimeters).
Maximum permitted line disparity. If the line values of a tiepoint differ by over LINEDISP pixels then the point will be rejected. Default is 2.5 pixels. Accuracy depends upon the camera models themselves so tolerances cannot be set too small.
Maximum permitted line disparity from local average. If enabled, a delta line disparity image is created internally (delta line disparity meaning the line disparity from the file minus the line number - most people think of this as the true disparity). If any line disparities exceed LINEDISP, they are discarded. For all remaining pixels, a box filter is run over the line disparity image (see BOX_WIDTH, BOX_HEIGHT) to compute the average line disparity in the local area around each pixel. The line disparity is then compared to this average. If the difference exceeds AVGLINEDISP, the pixel is rejected. The effect of this is to adapt to camera models that are not precisely epipolar aligned. The line disparities can "drift" while still preserving a very tight tolerance on the line disparities (which helps to reject noise). Recommended values are 0.5 for AVGLINEDISP, 4.0 for LINEDISP, and 51 for BOX_WIDTH and BOX_HEIGHT. A negative value for AVGLINEDISP turns off the check and disables the box filter.
Width of the box filter used by AVGLINEDISP. Must be odd.
Height of the box filter used by AVGLINEDISP. Must be odd.
Two values representing the lowest and the highest values of Z permitted. Values of Z outside this range will be rejected. Defaults to (-10,+10) meters.
Override for the range limit. If this parameter is specified, RANGE_FACTOR is ignored. The range limit is the maximum distance from the reference (left) camera that an XYZ point can have. Any points farther than this are rejected, since range accuracy diminishes to the point of uselessness beyond a certain point, as the view rays become more and more parallel.
This is the normal way to specify the range limit. This is a factor that is multiplied by the camera baseline (distance between the two cameras) in order to derive the range limit. The range limit is the maximum distance from the reference (left) camera that an XYZ point can have. Any points farther than this are rejected, since range accuracy diminishes to the point of uselessness beyond a certain point, as the view rays become more and more parallel.
Enables the spike filter, and specifies an absolute threshold. The spike filter works by computing the average XYZ value of all pixels within a box surrounding the pixel in question (see SPIKE_BOX). A distance is then computed from the pixel to the average in XYZ space. If this distance is greather than the SPIKE threshold, then the pixel is considered a "spike" (something unlikely to happen in a real scene) and is rejected. Note that all average XYZ values are computed at once, before anything is rejected by the spike filter. Therefore, rejecting one spike will not affect a neighbor's computation. Spikes seem to occur as a result of the marscor3 algorithm, but the detailed reason for them is not known. If SPIKE and SPIKE_RANGE are not specified, no spike filtering is done. Recommended value: none (use SPIKE_RANGE instead)
Enables the spike filter (see SPIKE). However, instead of using a constant threshold, the spike threshold is adjusted based on range from the camera (via spike_range * range). So, the farther away the point is, the larger the allowable spike. This compensates for increasing noise as you go farther away from the camera. Note that it is okay to have both SPIKE and SPIKE_RANGE active at the same time. One average is computed, then the distance is compared to both thresholds. Recommended value: 0.04
Specifies the size of the box used to compute the average XYZ for the spike filter. If one value is specified, the result is a square box. If two are specified, a rectangular box of (height, width) is used. Note that both height and width of the box must be odd.
This filter attempts to remove "outliers", defined as pixels with too few computed neighbors. The theory is that pixels should have neighbors, because the scene is generally continuous. Having too few neighboring good pixels is thus likely the result of a bad correlation. Neighbors are defined as any pixel within a box (see OUTLIER_BOX) that has a valid result. A binary image is defined, such that missing pixels are 0 and valid pixels are 1. A box filter is then run over this image. If the result of this box filter is less than the OUTLIER threshold, the pixel is rejected. If OUTLIER is set to 0.5, this has the same effect as running a median filter, which is where this idea originated. If OUTLIER is greater than 0.5, the effect is to erode away the edges of the valid area. At 0.5, the "average" edge is retained, while removing those pixels beyond the edge (which still might be connected to the valid area). Below 0.5, the effect tends more towards removing only more isolated pixels. Thus, a value of 1.0 is maximum filtering (only pixels with the entire box filled will be retained - not recommended) and 0.0 effectively disables the filter. Note that this is NOT the same as a "blob" filter. It does not look at connectedness in the sense of disparities being close to each other. It only looks at how many valid neighbors there are. This is the last filter, thus valid neighbors have already passed all the other tests. Recommended value: 0.5
Specifies the size of the box used to compute the outlier filter. If one value is specified, the result is a square box. If two are specified, a rectangular box of (height, width) is used. Note that both height and width of the box must be odd.
If specified, the program will write an updated camera model to the output file. This camera model is for the left image, as modified by the nav file. The purpose of this is to be able to create a properly-labeled XYZ file from unmodified FFL (linearized) files and a nav file, for the purpose of pointing-correction of a mesh. Note that point=cm=label should NOT be specified, as that will override the nav file. Also, you may need to specify point=cahv_fohv=xxx (often, "max"), in order for the camera model to match the FFL. Basically, whatever is given to marscahv, should be given in this case as well.
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 method for pointing corrections. Loose method matchs with pointing parameters of the image. Tight method matchs with unique id of the image.
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....
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.
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.
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.
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.
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.
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.
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.
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.
Specifies the type of a named target. This value is copied to the output label, property IDENTIFICATION, keyword TARGET_NAME.
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).
The coordinate system to use for all input parameters and output values,
and the XYZ points themselves. 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). For MSL, this is the
Rover Nav frame.
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.
RMECH - For MSL, this is the Rover Mechanical frame. It should not normally
be used except for testing.
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.
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.
Specifies which solution ID to use when specifying the coordinate system. 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. Without it, the "best" available solution is chosen. It is extremely rare that this parameter should be needed. The default will be sufficient in almost every case. Note that the current MER implementation requires that a value for COORD_INDEX also be provided, in order for this parameter to take effect.