Input files contain the XYZ coordinates. If three filenames are given, they all should be single band files each containing X, Y and Z values in that order. If only one filename is given, it should be a 3-band file with bands in (X,Y,Z) order. The input files are in REAL (float) format.
Output file containing the roughness values. The file will be in 2 or 3 band REAL (float) format. See "OUTPUT FORMAT" in the main help for the file format.
Input files contain the UVW coordinates. If three filenames are given, they all should be single band files each containing U, V and W values in that order. If only one filename is given, it should be a 3-band file with bands in (U,V,W) order. UVW coordinates provided through the image files take precedence over the single UVW vector provided through UVW_VECTOR parameter The input files are in REAL (float) format.
A single surface normal vector to be used at every XYZ point. The image file(s) input through UVW parameter provide one UVW vector for each point of the XYZ image file(s) input through INP parameter. However, the caller can use UVW_VECTOR parameter to provide as input only one UVW parameter to be used at every point in the entire XYZ image. UVW parameter takes precedence over UVW_VECTOR parameter.
Coordinate system of the single UVW vector provided through UVW_VECTOR parameter. This parameter is also ignored if UVW_VECTOR is ignore.
Inner radius (in XYZ space) of the ring, in meters. Note that INNER_RADIUS must be less than (or equal to) OUTER_RADIUS. INNER_RADIUS is not used if -NO_RING is specified (internally, it is set equal to OUTER_RADIUS). Suggested value is 0.06 for MSL Drill, N/A for MSL DRT.
Outer radius (in XYZ space) of the ring, in meters. Also the radius of the overall roughness circle. Suggested value is 0.075 for MSL Drill, 0.035 for MSL DRT.
Outer radius (in XYZ space) of the ring, in meters. Also the radius of the overall roughness circle. Suggested value is 0.075 for MSL Drill, 0.035 for MSL DRT.
Upper limit on roughness values for the ring. If a valid roughness exceeds this value, it will change the flag in band 1 of the output. Note that unlike MARSROUGH, roughness values are not clipped; the ring roughness in band 3 (if present) will show values greater than this threshold. The parameter is ignored if -NO_RING is specified. Suggested value is 0.015 for Drill, N/A for MSL DRT.
Upper limit on overall roughness values (across the entire OUTER_RADIUS circle). If a valid roughness exceeds this value, it will change the flag in band 1 of the output. Note that unlike MARSROUGH, roughness values are not clipped; the overall roughness in band 2 will show values greater than this threshold. Suggested value is 0.04 for Drill, 0.005 for MSL DRT.
This setting is an optional test to rejects points that are nearby in pixels but distant in meters (3D). The use case is to filter points that are within the cylindrical projection but are in front or behind the point being tested (happens often with near horizontal normals). This test is not ideal as it will include points on the backsides of small peaks behind the point of interest and will ignore real hazards such as overhangs farther than the radius along the direction of the normal. A good setting might be a bit larger than the largest cylindrical radius provided (+ ~10% is what is used currently)
Value to use to indicate lack of roughness data. Must be >= ROUGH_RING and ROUGH_OVERALL. This value is reflected in the MISSING_CONSTANT label item. Suggested value is 1.0.
This parameter is used to control the outlier filter. Points with a roughness larger than filter*sigma where sigma is the standard deviation of all points within outer_radius, will be discarded. This helps to eliminate spikes and noise hits in the XYZ data. Suggested value is 1.0.
Conservative guess at maximum window size (in line/sample space) in which points falling into the radius will be found. This is used to prevent infinite loops, and a zero or negative value will cause a default of MIN(num_rows, num_cols)/8 to be used (which should be acceptable given the spatial resolution of the stereo data relative to the radius). Suggested value is 150 pixels, which allows full coverage of the ring at 1mm/pixel close-in hazcam resolution.
Minimum number of points in the region required to compute a roughness. Should be greater than or equal to MIN_POINTS used in the MARSUVW program. Suggested value is 6 or higher.
Center of bounding box (in XYZ space). Points lying outside the box will not have roughness computed for them. This is used to limit computation to the arm workspace. The bounding box is measured in the coordinate system specified by COORD (usually ROVER). Suggested value is 2.0 for MSL.
Half-width of bounding box, in meters. Points more than this distance away from X/Y_CENTER in either X or Y will not be computed (note, it is an axis- aligned square box, not a circle).
Turns on or off ring computation. The default is to do both overall and ring roughness, which is appropriate for the MSL Drill. Specifying -NO_RING turns off the ring, leaving only overall roughness. This changes the output from 3 to 2 bands, limits the valid flag values in band 1, and may cause mission-specific output label differences (for example, on MSL, -DO_RING is assumed to be for the Drill, while -NO_RING is assumed to be for the DRT). The INNER_RADIUS and ROUGH_RING parameters are ignored if -NO_RING is set.
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 projects 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.
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 the output roughness (really just determines
the unit of measurement). The interpretation of the values is dependent on
the mission. Some representative missions are listed here:
Fixed - The Fixed frame. This is the ultimate reference frame
(see also FIXED_SITE for rover missions).
Instrument - (default) 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.VARI Y_CENTER.VARI DO_CURVATURE
Specifies whether to
compute curvature not roughness.
Value that represents missing or invalid curvature.
Far threshold for allowed convex curvature
Closer threshold for allowed convex curvature
Closer threshold for allowed concave curvature
Far threshold for allowed
concave curvature
Center of bounding box (in XYZ space). Points lying outside the box will not
have roughness computed for them. This is used to limit computation to the
arm workspace. The bounding box is measured in the coordinate system
specified by COORD (usually ROVER).
Suggested value is -0.4 for MSL.
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).
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.
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.
Turns on or off parallel processing. 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.