First left eye image, then right eye image. There is nothing actually requiring left/right order, other than convention. If left/right is unclear (e.g. the images are not from a stereo camera) then either order is acceptable. If the output is used with MARSXYZ, the same order must be used. The order must also match that of the program used to calculate input disparities (typically MARSJPLSTEREO).
The line and sample disparity files. If one filename is given, a two-banded file is created with line disparity as band 1 and sample disparity as band 2. If two filenames are given, two single-band files are created. Line disparity is in file 1, and sample disparity is in file 2. See the main program help for output file contents and formatting.
The input disparity images. If one filename is given, a two-banded file is expected with line disparity as band 1 and sample disparity as band 2. If two filenames are given, the first file is expected to contain line disparities and the second, sample disparities. The size of the disparity image compared with the input images must be related as specified by the DISP_PYRAMID parameter. See the main program help for output file contents and formatting.
Optional output file showing the coverage of tiepoints (correlated pixels), in BYTE format. 0 dn means the pixel could not be reached in order to be correlated. (i.e. the input file had no disparity for the pixel). 128 dn means a correlation was successfully performed at this location. 255 dn means a correlation was attempted at this location but it failed, usually because of low correlation quality.
Output quality file (optional): A REAL image containing the correlation quality of each pixel attempted, from 0 to 1. 0 indicates either a correlation failure unrelated to the QUALITY setting, or a pixel that was not available in the input. This file could be used in conjunction with a very low quality setting to allow correlation in low-quality areas, with the result filtered afterwards using a higher quality (i.e. use the output quality file as a mask). Unlike marscorr/marscor2, this is a reasonably safe operation, as long as no gore passes were performed. Gore passes, however, run the same risk as marscorr/marscor2: if there is any kind of repeating pattern in the image, the correlator could get "stuck" on the wrong match for the pattern and propogate that error.
The IN_COEFS parameter allows the user to directly specify the transform on a per-pixel basis. The input file should be a 6-band file the same size as the input disparity file, containing the parameters a,b,d,e,g,h. Note that the translation terms, c and f, are not included because they come from the input disparity file. Note that OUT_COEF can be used to save the final coefficients, in the same file format.
The OUT_COEFS parameter specifies an optional file to contain the output coefficients from the transform. This will be a 6-band file the same size as the output disparity file, containing the parameters a,b,d,e,g,h. Note that the translation terms, c and f, are not included because they are in the output disparity file. Note that IN_COEFS uses the same file format.
The vicar image band number for the input images. Defaults to 1
Correlation size. Must be an odd number. Defaults to 15 square. If only one value is given, a square template is used. If two values are given, the first is the template height (line direction) and the second is the template width (sample direction). Rectangular templates that are wider than they are tall should be useful for lander images.
Correlation search area. Must be an odd number. Defaults to 35 square. SEARCH must be > TEMPLATE. If SEARCH is only a bit larger than TEMPLATE then many correlations will abort because they will be prohibited from searching in promising directions. If only one value is given, a square search area is used. If two values are given, the first is the search height (line direction) and the second is the search width (sample direction). Rectangular search areas that are wider than they are tall should be useful for lander images.
Minimum acceptable correlation quality. Correlations with qualities below QUALITY will be rejected. Qualities range from 0 (poor) to 1 (excellent). Note that this value is the square of the correlation coefficient. The definition of correlation coefficient is a/sqrt(b); we maximize a**2/b instead to avoid the square root calculation (negative correlations are checked for and given a negative result). Therefore if a quality value of (for example) 0.36 is given, that corresponds to a correlation coefficient of 0.6. The difference does not matter except insofar as people are used to using the correlation coefficient number. Defaults to 0.6
Specifies whether or not gore passes are performed. The default is not to do them. See the main help for details.
Specifies the maximum number of gore passes through the image to perform. If the value is 0, the number of passes is unlimited. The program will stop making gore passes once a pass produces no more tiepoints, even if GORE_PASSES has not yet been reached. Limiting the number of gore passes prevents the correlator from "breaking in" to invalid areas and getting "lost", such as often happens with marscorr/marscor2. Similar limiting may also be done via a high GORE_QUALITY.
Specifies the correlation quality to be used during gore passes. If not specified, the value for QUALITY is used. Usually, a reasonably low quality, such as 0.36, is acceptable for the main correlation. This is because we know a priori that all points considered have passed the first correlation program, which acts as a kind of filter. So it is quite likely that the point is good, even with a lower quality. However, in gore filling, that filter no longer applies. Any point could be considered for correlation. By setting GORE_QUALITY quite high (perhaps .6 OR .8), WE INSURE THAT ONLY VERY GOOD POINTS ARE INCLUDED WITHOUT THE benefit of the filter. This prevents the correlator from getting "lost" such as often happens with marscorr/marscor2 and generating spurious results. Points not filled in by the first correlator may still be good for marscor3, since the first correlator usually does only a square mapping, not a quadrilateral mapping, from left to right, and square doesn't always work very well. This value is the square of the correlation coefficient, as with QUALITY.
Normally, gore passes are processed top-to-bottom, left-to-right. As each pixel is filled in, it becomes eligible to be a neighbor to the next pixel. So a gore pass can fill in arbitrarily far to the right or down, but can only fill in one pixel to the left or up. This often leads to diagonal edges in coverage (moving down and to the left), as each successive line is only able to move one pixel farther left. Filling much up/left requires a huge number of gore passes. Turning on GORE_REVERSE enables a second iteration through the data in each gore pass. This second iteration processes in the reverse order... bottom- to-top, right-to-left. This allows it to fill in up and to the left as well as down/right. Note that one gore pass consists of going *both* directions. The reverse pass can leave diagonal coverage edges moving up and to the right. If 0 degrees is to the right and angles increase counterclockwise, then the areas between 0 and 45 degrees, and between 180 and 225 degrees, will not be filled by a single gore pass. (Without reverse, the unfilled area is 0 to 225). For this reason, it is recommended that at least two gore passes be used if reverse is turned on.
Specifies the "pyramid level" of the input disparities. The input is zoomed down by a factor of 2 ^ DISP_PYRAMID. This corresponds directly to the PYRLEVEL parameter to MARSJPLSTEREO. A value of 1, 2, or 3 is generally recommended. Pyramids of 0 (no zoom) are often susceptible to minor variations in the camera model and sometimes produce sparse images out of MARSJPLSTEREO. Higher pyramid levels are less sensitive to the accuracy of the camera model and generally produce better coverage. See the main help for a discussion of the input file format and how it relates to DISP_PYRAMID.
The STOP_PYRAMID parameter can be used in conjunction with DISP_PYRAMID and MULTIPASS to stop the pyramid process prematurely. Normally STOP_PYRAMID is 0, meaning go all the way to full-res. But if STOP_PYRAMID is non-0, the process stops there. A value of 1 would produce a half-scale output, 2 would produce quarter-scale, etc. At least one pass is done regardless of STOP_PYRAMID. The intent of this is to facilitate debugging by being able to examine the intermediate pyramid results; operational use is not anticipated. Note that the output can be fed back into another run of marscor3 by adjusting DISP_PYRAMID to the prior STOP_PYRAMID value.
Specifies which mode of the gruen correlator to use. All correlations are performed using the gruen correlation routine. See the gruen documentation for details of the algorithm. The MODE parameter is fully described in the main program help. Only the five "amoeba*" modes are recommended.
At the deepest loop in the gruen correlator, the right image is interpolated using a bilinear interpolator by default. If using CUBIC_GRUEN, a bicubic interpolator is used. Early experiments shows that correlations based on the bilinear correlator are ~2-3 times faster than the bicubic one. However, bicubic interpolation is a better one and could improve the quality of the correlation.
Adds linear search to any MODE. This can help when the initial point is more than a pixel or two away from the true point, since the various amoeba modes don't generally like walking more than that in the parameter space. However, the linear mode is limited to a square transform, so it may not match the cemra geometry very well. See the MODE parameter and description in the main program help.
FTOL specifies the tolerance, or accuracy, in the function minimization process (the correlation quality). While directly related to accuracy of the results, this relationship is not simple. See the main help for a more involved discussion. Higher values of FTOL cause the program to run faster, sometimes MUCH faster, at the expense of some accuracy. Typical values range from .000001 (historically the only value; probably too tight a tolerance) to .001 or .004. This parameter should be experimented with for each new type of data.
If non-zero, turns on reverse-check mode. After every point is correlated (whether in the main or gore passes), the pixel is again correlated in reverse. Instead of left-to-right, it goes right-to-left (right is the template) using the current result as the starting point. Thus a left-side coordinate is obtained that matches the right-side image. This coordinate is then compared to the original left-side coordinate. If they differ by more than CHECK pixels, the point is rejected. (This is a square window; line and sample are compared independently). The result is that more "bad" pixels are filtered out, at the expense of some time. This may allow the quality to be lowered without getting too many bad matches. Note that CHECK should not be run with DECILEFT or ROTATION or X/YSCALE as the inverse affine transformation is not fully implemented yet. See also CHECK_QUALITY; the reverse check is omitted if the quality is higher than CHECK_QUALITY. Note that CHECK is not all that useful in the amoeba-only modes, because we start at a known peak already. The reverse check could be more useful when combined with a -LINEAR search. A true reverse check would do an independent, complete right->left correlation, then compare the results.
Minimum threshhold at which the reverse check is performed. The theory is, if the quality is good enough, a reverse check is unnecessary. See the CHECK parameter.
If the pyramid value is more than 1, then it is quite likely that the initial point obtained from the input disparity is off by more than amoeba can handle, giving very "patchy" results. The amoeba algorithm really needs to start within a pixel or so for reliable results. To handle this case, MULTIPASS may be specified. If MULTIPASS is turned on and DISP_PYRAMID is greater than 1, then the entire correlation process is repeated multiple times. At each iteration, the input image is downsampled so it is twice the size of the input correlation map, for an effective pyramid level of 1. The result then becomes the input disparity map for the next iteration. So, for example, with MULTIPASS and DISP_PYRAMID=3, then input disparity map is 1/8 the size of the input. The first correlation is performed with a 1/4 scale image pair (the full correlation, including gore passes). The resulting 1/4 scale disparity is then correlated with a 1/2 scale image, then the result of that is correlated with the full scale image to produce the final result. The default is not to do multiple passes.
Turns on a pre-correlation low-pass filter of the images. This can tend to reduce interpolation noise; see Quality of Results Discussion in the main help. Note that the filter is applied only to the full-res image. If -MULTIPASS is also used, only the last pass is filtered. (Downsampling does an inherent filtering so it is not needed). There are two low-pass filtering techniques available: -FILTER is simply an NxN average of surrounding pixels (boxcar filtering), with N given by FILTER_SIZE. So with FILTER_SIZE=3, the 9 surrounding pixels (including the central pixel) are averaged. Default value is 3. -GAUSSFILTER uses a Gaussian convolution to lowpass the image. The sigma (or standard deviation) of the gaussian is given by FILTER_SIZE. Default value is 0.9 (which roughly corresponds to a 3x3 boxcar filtering).
Specifies the size of the averaging window for -FILTER or the sigma for -GAUSSFILTER. Must be an odd in case of box filter. See -FILTER. In case of GAUSSFILTER use, the sigma of the gaussian low pass is set with FILTER_SIZE. One way to decide which sigma is needed/wanted, is to think about the output "resolution" equivalent you want to achieve. For instance, if you wanted to filter the image such that you could decimate it with a factor of 2 ( size reduction of 2) without introducing too much aliasing, how would you relate that factor of 2 with the sigma ? There is no one answer, but a general relationship that is used in the literature which gives reasonable results is: sigma = 0.8 * sqrt(T^2 -1). With T, the output virtual sampling step (would be T=2 for our example above). If you wanted to smooth a bit the image, you could use T=1.2 for instance and compute what sigma should be. If one value is given, it applies to both the left and right inputs. If two values are given, the first applies to the left and the second to the right. This allows differential filtering levels, for use e.g. when correlating different-scale images (such as the MSL mastcams).
Specifies where the primary input labels come from. The default is PI_FROM_DISP, meaning that the labels are transferred from the (first) disparity input. This preserves the history labels that the 1-D correlator added. However, it presumes that the 1-D correlator itself transferred labels from the input images. In the uncommon case of a disparity file where the labels are insufficient, PI_FROM_INP can be used. This causes the label to be transferred from the first INP parameter. This might be necessary if e.g. a synthetic disparity map were created which did not have all the labels of the input.
Specifies the overall frame rotation (in degrees) between the two images. A positive value says the right image should be rotated clockwise by that amount in order to match the left. This is not normally needed for standard stereo pairs. However, for repointed pairs, or arm-camera pairs, this can significantly improve amoeba's results. The solution is more stable because amoeba is less likely to go off in bad directions looking for the proper transform, especially when the correlations are marginal due to noise.
Similar to ROTATION, but specifies the overall X-direction scaling factor between the images. This factor applied to the right image should produce an image closely matching the left image's scale. See ROTATION or the main help for more.
Excactly like XSCALE, except it applies in the Y direction (line) instead.
If FEEDBACK_COEFS is on, the perspective transform coefficients are "remembered" from one pyramid pass to the next. So for the next stage of the pyramid, the starting point uses the coefficients derived from the previous stage. This helps retain the "shape" of the correlation window mapping across pyramid levels. FEEDBACK_COEFS is also used for gores transform initialization. If ON, the transform coefficient of the best neighbor are used to initialize the current pixel. See main help for further details.
Establishes limits for the allowed rotation values. This is accomplished by setting limits on the transform coefficients based on the range input, so it is not a perfect limit (see discussion in main help). If SCALE_RANGE is given but ROT_RANGE is not, ROT_RANGE defaults to -5 to +5 degrees.
Establishes limits for the allowed scale. This is accomplished by setting limits on the transform coefficients based on the scale input, so it is not a perfect limit (see discussion in main help). If ROT_RANGE is given but SCALE_RANGE is not, SCALE_RANGE defaults to 0.9 to 1.1.
Only used with IN_COEFS. If ON, the limit on the coefficients transforms will be set based on IN_COEFS. The min/max of each coefficients will be the limit on each coefficients.
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.
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.
Whether or not to decimate the left template image if the difference of resolution between the left and right images allows it, that is, if left image resolution is at least twice higher than right image. See main program help for more information.
Maximum scale difference between the Left and Right images. This is to prevent unrealistic scale difference that would render the process very long with poor results. In the process, if the ratio is exceeded, the transform ratio between the two images is limited to MAX_RATIO. MAX_RATIO needs to be >=1, otherwise it defaults to 1.
If the transform coefficients limits are set globally (from SCALE_RANGE, ROT_RANGE, or IN_COEF_RANGE), this allow to adjust further these limits. COEFS_SCALE is a percentage. Positive values will increase the limit, negative values will decrease the values. For instance, if COEFS_SCALE=30, then the limit [min, max] of a coefficient will be increased to [min-0.3min, max+0.3max]. If the limits are set locally (via LOCAL_LIMIT), then COEFS_SCALE sets the limit based on each pixel transfrom coefficients. For instance, for initial parameter a (of a,b,d,e for affine transform), the limit will be set to [a-0.3a, a+0.3a] (if COEFS_SCALE=30). Negative value of COEFS_SCALE have no effect for local limit COEFS_SCALE is either a 1-value or 6-values parameters. In case of 1-value, the same scaling is applied to the 6 transform parameters (a,b,f, d,e,g). Otherwise a value for each is necessary. Note that not all transfrom parameters are used. It depends on the amoeba selected.
Will activate local-only limits. All global method to set transform limit will be invalidated. The transform coefficients limits are defined based on the transform coefficients and COEFS_SCALE.
If SCALING is ON, activates the possible scaling (i.e., enlargement) of the TEMPLATE patch and/or SEARCH patch to insure that the number of "real" pixels in the correlated patches corresponds to user input TEMPLATE and SEARCH.
In theory, as soon as the Left image is higher resolution than the Right, ie, scaling between L and R < 1, the upscale of the Left template is activated (If SCALING is on). However, even for a pair of image with the same theoretical resolution (say a Nav pair), the computed scaling ratio is going to be around 1, but not a perfect 1. So upscale could go ON, although it is not really needed. To alleviate this problem, the upscaling is actually done if the computed scaling ratio is less than SCALING_THRESH. Default is 0.8. Note that when scaling is not activated, the correlated patches are just a subset of the main images taken as-is. If activated, the EWA resampler is used. If one wants the EWA resampler to be used no matter if scaling is needed (for noisy image, this resampler has a light low-pass filtering component), set SCALING_THRESHOLD to 1.
If TILING is ON, activates the scaling of the correlated patches due to difference in tiling levels between the images. This option implies that SCALING must be ON (if not, SCALING is automatically turned ON).
When left/right patches are scaled up to insure that they have at least TEMPLATE and/or SEARCH "real" pixels, their increased size lead to longer processing time. However, these increased patches are oversampled by construction, whether because of geometric scaling or tiling scaling. In order to limit the processing time, if DECIMATION is ON, the patches are going to be downsampled in such a way that their size is equal to TEMPLATE and SEARCH. Decimation of the patches only happens if the scaling factor is at least 2. There is no interpolation, only decimation on integer grid.
This is a convenience parameter for backward compatibility with previous version of marscor3. Essentially when DECILEFT is ON, then SCALING is ON TILING is OFF DECIMATION is ON Also, only the left patch is scaled and decimated (if that is possible), not the SEARCH. For new use of marscor3, this parameter should not be used.
This parameter activate a median-of-sort filter applied to the disparity
maps. This is meant to remove outliers, and *patch* of similarly-valued
outliers.
In a truly randomly-distributed outliers situation, a regular median filter
usually doesa good job at removing them. The problem with dense correlation,
i.e., correlation done for each pixel of the Left image with a TEMPLATE, is that
a bogus value has high chances to be replicated in the neighbooring pixels. The
reason is that the TEMPLATE content of a neighbooring pixel has more or
less the same content that the content of the pixel. Hence, whatever in the
TEMPLATE content caused a bogus measurement for a particular pixel is likely to
be present in the TEMPLATE content of the neighboor pixel and cause a similar
bogus measurement. It's related to the fattening effect, a well known effect in
correlation. As a consequence, the correlation map is polluted with *patches* of
outliers that are hard to remove with a standard median filter.
The STAT_FILTER is based on the assumption that disparity changes smoothly, so
we're checking that the neighborood of a given pixel has a disparity similar to
that given pixel. To overcome the fattening effect, the neighborood is defined
as the correlation template size (TEMPLATE) slightly augmented by a few pixels.
As explained above, the reason is that a salient feature will be seen in a
series of neighbooring correlation window (depends on the TEMPLATE size). This
may cause a patch of uniform outliers which may satisfy the smoothness criteria.
Therefore a neighborood slightly larger than the template size is taken.
Two thresholds are used to check the validity of a pixel:
- the allowed disparity amplitude difference between the queried pixel and the
ones in the neighborood
- the minimum number of pixels in the neighborood that need to satisfy the
disparity amplitude criteria to deem the current pixel not an outlier
The filter works like this (think of it as sort or median filter):
For a given pixel:
- Compute the disparity difference between the pixels of the neighborood and
the disparity of that queried pixel ("remove" the line/samp offset before).
- Count the number of pixel whose difference is less than a threshold
- If that number is larger than a threshold, the current pixel is valid.
Otherwise, it is deemed an outlier.
The number of pixels beyond the TEMPLATE size that will define the neighborood. Default is 2. So, for instance, if TEMPLATE=9 and STAT_EXTENT=2, then the neighborood will be a 13x13 patch.
This variable indicates the amount of variation in terms of disparity changes that is allowed in the neighborood. The default is 1.2. Note that the line/samp disparity has been removed as well as the scale factor between the left and right image.
Percentage (values between 0 and 100) of the required number of *smooth* pixels in the neighborood to validate the current pixel as a good one. Default is 50. A large value will force smoothness which will remove more outliers but which may also remove good values that are in an area of strong disparity changes. A small value will have the opposite effect, that is keep as much inliers are possible but letting more outliers in.