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 brightnexx correction file. This is an XML file describing the parameters (additive and multiplicative factors) used to correct each input file. See the main help for file format.
The input overlap file, generated by a program such as MARSMAP (using OVR_OUT). This file must be specified. It is an XML file; see the main help for file format.
The optional input navigation table. Since pointing and camera models are not used currently, this parameter is not really needed.
Solution id for the OUTPUT brightness correction file in XML format. This parameter is required.
Specifies which solution ID to use for the INPUT nav file (if present). Unused for MARSBRT.
Specifies which image (if any) are reference images. Reference images are assumed to be correct and will not be adjusted. Defaults to no reference, which can also be explicitly specified via REFIMAGE=-1. 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 radiometry 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. Overlaps containing this image will be ignored and excluded from consideration (but see IGNORE_INTRA). This has two purposes. First, for very large overlap files, when adjusting only a few images (via REFIMAGE), the presence of spurious overlaps can be a significant performance drain. Second, and more important, this allows you to exclude a match that is known bad. For example if trying to adjust a single tile (only one non-reference image), a neighbor that has a different shadow, or bad rover parallax, could be ignored without having to hand-edit or regenerate the overlap file. Ignored overlaps still appear in the output overlap 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 overlaps 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 overlaps between non-reference (active) images to be ignored. Only overlaps between non-reference and reference images will be considered. The use case for this is as follows: Say you are doing a color mosaic (e.g. Mastcam on MSL) which has already been corrected, and you want to fill in gaps with navcam images. This flag allows you to mark the entire color set as reference images, with the navcams active. Then when adjusting navcams, only the nav-mast borders will be considered. This is beneficial because that is the interface that is of most interest, and the navcams are likely to contain large bits of the rover itself, which do not brightness-match well due do parallax. The navcams match their neighbors but not each other.
This flag modifies the behavior of IGNORE slightly. By default, if an overlap contains an ignored image, the entire overlap is thrown out. However, sometimes that is not desirable. For example, a small mastcam mosaic on top of a navcam (MSL) will have 100% overlap with the navcam. But you want to match the mastcams to each other, not the navcam. You can't ignore the navcam though because every overlap contains it - there would be none left. With IGNORE_PARTIAL, the ignored images are removed from overlaps, rather than disqualifying the entire overlap. The overlap is ignored entirely only if there are one or fewer images left after removing the ignored ones. In the example scenario above, ignoring the navcam will preserve all the intra-mastcam overlaps.
RECYCLE specifies the number of times to re-run the solution, starting where the previous one ended. This happens after any outlier rejection.
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 marsbrt, values of .001 are probably sufficient for most cases, but this has not been rigorously tested. The default is .00001.
This keyword specifies which parameters should be adjusted. The default of DO_LINEAR allows both additive and multiplicative factors to vary. Specifying DO_ADD or DO_MULT limits changes to just one parameter.
Controls whether or not the overlap mean statistics are used from the overlap file. The default is on. If you turn this off, you may have to change DO_WHAT to ensure there are enough degrees of freedom to accommodate all the parameters being changed.
Controls whether or not the overlap standard deviation statistics are used from the overlap file. The default is on. If you turn this off, you may have to change DO_WHAT to ensure there are enough degrees of freedom to accommodate all the parameters being changed.
Specifies whether to use normal or overall statistics (or both, or neither) in the function minimization process. This should almost always be NORMAL. It is possible to have overall overlaps considered during the function minimization process but this has not worked well in testing. It is far better to preprocess them (using -PRE_OVERALL) instead. Thus OVERALL and BOTH should rarely if ever be used. NONE can be useful if you ONLY want to do the overall preprocessing.
Turns on the preprocessing step for overall statistics which, as described in "Initial Conditions" in the main help, will compute initial conditions based on the overall statistics. Combining this with -NORMAL (WHICH_OVR parameter) makes the overall be used only in this preprocessing step, which is almost always what you want.
Target value for the overall preprocessing mean. The default is the average of all the overall overlaps' means.
Target value for the overall preprocessing standard devations. The default is the average of all the overall overlaps' standard devations.
Specifies whether to use normal or HSI colorspace overlaps. Normally this should be left to the default PER_OVERLAPS, which uses whichever mode the overlaps are set to in the input file.
The INERTIA parameter modifies the residual used for function minimiziation by adding a factor that makes the radiometry of the images tend to stay in place. For each brightness parameter, the difference between the original value of the parameter and the current value is multiplied by the corresponding INERTIA value, and the result is added to the residual. Each 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 overlaps than they otherwise would. This has the beneficial effect of preventing "drift" of the entire solution. For example, you can multiply everything in a mosaic by a constant value and the mosaic will still look the same, with the same residuals. INERTIA can prevent that by introducing an error term whenever the parameter moves. Selecting an appropriate value for INERTIA is a dicey proposition. The unit of the residual is hard to define, since both differences in mean and differences in stdev are combined (each is normalized by the average and then squared). It is best selected by trial and error. For a typical image (DN's in the 0-4k range) a good value might be (0.1, 0.0001). For IFF-style images (floating-point I/F radiances) in a 0-0.5 range, use (0.1, 0.1). For IFF's in 0-0.1 range, try (0.1,1.0). Some experimentation may be required. Note that the first element of INERTIA always refers to the multiplicative factor, while the second element always refers to the additive. This is true even if one or the other is turned off via DO_WHAT. The additive component of INERTIA should vary in order of magnitude with the range of the input DN. See the discussion in the main help.
Starting key number for the overlap file. Overlap files contain a list of images, each of which is associated with an integer key. Setting START_KEY to some value allows overlap 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.
Specifies the lambda, or length scale, for the multiplicative factor. This is the value used by amoeba to decide how much to move the parameters when starting off. It will not generally need to change.
Specifies the lambda, or length scale, for the additive factor. This is the value used by amoeba to decide how much to move the parameters when starting off. Unlike LAMBDA_MULT, it will likely need to vary in order of magnitude with the range of the input DN. See the discussion in the main help.
Specifies a drift weight to use to keep the solution in place. This has not performed well in testing and should be used advisedly; see the main help for details. The first element always applies to the multiplicative factor and the second the additive, regardless of whether something is turned off via DO_WHAT. The additive component of DRIFT_WT should vary in order of magnitude with the range of the input DN. See the discussion in the main help.
Turns on or off the normalization process, which is preferred over DRIFT_WT as a means to keep the solution centered around mult=1.0 and add=0.0. See the discussion in the main help.
Specifies the number of iterations to perform while removing outliers. If at any point there are no outliers to remove, the remaining iterations are bypassed. Each iteration restarts the solution from initial conditions (unlike RECYCLE) to avoid "contamination" by the removed outliers.
Specifies what an outlier is. This is a factor multiplied by the standard deviation of the errors to set a threshold for elimination. So a value of 3 is equivalent to rejecting 3-sigma outliers. See the discussion on outlier rejection in the main help.
An optional output overlap file, which holds changes to the overlap made by the outlier rejection mechanism.
A brightness correction file (such as produced by an earlier run of marsbrt) that specifies the starting point for images. By setting those images mentioned in the BRTCORR file as references, the mosaic can be added to without disturbing the existing images.
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). Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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. Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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. Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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. Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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. Pointing and camera models are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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). Pointing and camera models are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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.... Pointing and camera models are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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. Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for 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. Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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). Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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. Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for potential future use.
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). Surface normals and coordinates are not currently used by MARSBRT, therefore this parameter is ignored. It is retained for 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.
Surface normals and coordinates are not currently used by MARSBRT, therefore
this parameter is ignored. It is retained for potential future use.