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 file containing the list of selected keyframes and other information (if specified through parameters) regarding the computed cost matrix and other intermediate values. This is is a .TXT file.
The input tiepoint file, as generated by MARSAUTOTIE2 (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).
Specifies which image (if any) are reference images. Reference images are assumed to be correctly navigated and will not be adjusted. 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. REFIMAGE 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\).
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.
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.
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.
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. 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. NOTE: This parameter is currently ignored by keyframe_selection, but kept for compatibility with other programs and potential future use.
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). NOTE: This parameter is currently ignored by keyframe_selection, but kept for compatibility with other programs and potential future use.
NOTE: This parameter is currently ignored by keyframe_selection, but kept for compatibility with other programs and potential future use.
NOTE: This parameter is currently ignored by keyframe_selection, but kept for compatibility with other programs and potential future use.
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.
NOTE: This parameter is currently ignored by keyframe_selection, but
kept for compatibility with other programs and potential future use.
If ON, the connectivity matrix of the images will be printed to the stdout.
The connectivity matrix shows the connection of the images between each other
trough the number of tiepoints each pair shares.
An example of a printed out connectivity matrix for 10 images is:
0: 0 615 6 5 5 4 7 3 3 0
1: 0 0 614 3 2 5 2 6 5 6
2: 0 0 0 292 2 1 3 1 1 2
3: 0 0 0 0 676 3 3 5 4 2
4: 0 0 0 0 0 677 2 7 3 2
5: 0 0 0 0 0 0 441 4 0 4
6: 0 0 0 0 0 0 0 772 1 1
7: 0 0 0 0 0 0 0 0 502 2
8: 0 0 0 0 0 0 0 0 0 568
9: 0 0 0 0 0 0 0 0 0 0
NOTE: This matrix is symmetric, so only the upper-triangular portion should be
interpreted. Eventually, the format will be replaced to match the DISP_CONNECT
parameter from marsnav2:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
0 . 1 . . . . . . . . . . . . . 2 . . .
1 3 1 . . . . . . . . . . . 1 1 1 . .
2 5 1 . . . . . . 1 1 1 . 1 1 1 . 1
3 1 . . . . . . 2 4 1 . . 2 9 . .
4 4 1 . . . . 9 10 . . . 1 1 2 5
5 3 1 . 1 1 5 . . . . 1 3 2 .
6 1 . . . . . . . . . 2 . .
7 . . 1 . . . . . . . . .
8 . . . . . . . . . . .
9 1 . 1 . . . . . . .
10 7 1 . . . . 1 . .
11 8 . . . 1 . . .
12 8 . . 2 6 1 .
13 1 . . 1 . .
14 . . . . .
15 5 1 . .
16 7 1 .
17 . .
18 7
19
A dot (".") indicates no connection between the two images. A number
indicates the number of connections between the two images, i.e., the number of
tracks containing both images.
Obviously, if the number of image is large, the printing of the connectivity
matrix will pose problem. In such case, the printing could be disabled
(NODISP_CONNECT).
If ON, the cost matrix of the pairwise cost function values will be printed to
the stdout.
An example of a printed-out cost matrix for 5 images is:
0: 1: 2: 3: 4:
0: 0 0.5 -2 0.7 1.1
1: 0 0 0.2 -5 1.2
2: 0 0 0 5.2 1.0
3: 0 0 0 0 0.6
4: 0 0 0 0 0
A "0" indicates no connection between the two images. A number indicates the
cost function value between the two images. The following explain the different error codes, for keyframe scores:
-1: not enough matches
-2: H matrix failed to compute
-3: F matrix failed to compute
-4: negative relative GRIC score obtained
-5: no relative motion between pair
-6: pure rotation detected
Notice that there should be a "0" for any image against itself, for example
(1,1), (2,2), etc. Also notice how the matrix is upper-triangular, since it's symmetric and a value for each pair only needs to be computed once. It also
makes traversal simpler than if the entire matrix is filled. If the number of
images is large, the printing of the connectivity matrix will pose a problem. In such cases, the printing could be disabled (NODISP_COST).
Percentage from all edges of the image to discard matches from, to account for fisheye lens adverse effects on homography and fundamental matrix computation. Most computer vision algorithms from estimating these 3x3 matrices assume the pinhole camera model, for which fisheye lenses with CAHVORE parameters result in inaccurate estimates. Eventually, fisheye-specific methods may be incorporated. The default value is set to 0.05; larger values can result in a greatly-reduced number of matches available for homography and fundamental matrix computation.
Type of keyframe selection to perform; choose between sequential and global
("nosequential").
Sequential processing: this method is preferred for sequential, mainly linear
motion over time, such as the flight path of the Mars helicopter. In this
scenario, frames share tiepoints mainly with their adjacent neighbors. The
algorithm first finds the first keyframe based on the highest average score for
the first few frames, and then fills a list of the highest scores per line and
their respective pairs. The method is simple but works surprisingly well.
Global processing: in this case, the motion model is more general and includes scenarios where locations are revisited and where frames can share tiepoints
with many other frames, without any expectation of adjacency. The motion of a robotic arm or a rover traversing over previous locations are good examples of
this. The keyframe scores matrix is viewed as a whole, regardless of frame
ordering, and the highest X% of average keyframe scores is chosen.
An important future improvement is to look for “optimal paths” on a graph. If
the keyframe scores matrix is treated as a graph, composed of nodes (image
pairs) and links (weights) representing the keyframe score, algorithms such as "Djikstra’s shortest path” algorithm, the "longest path problem", and others can
be implemented to traverse the graph.
Percentage of top-scoring frames to keep during global keyframe selection. The selection algorithm computes the average score per frame, sorts by value, and the top X% are selected as the final keyframes.