ISIS Application Documentation
smtk | Standard View | TOC | Home |
Generate a digital elevation map (DEM) from two images using the Stereo Matcher ToolKit (SMTK)
Description
Categories
Groups
History
This application creates a digital elevation model (DEM) from two images. It uses coregistration of selected corresponding points to determine match points. Each coregistered match point is then used to add additional match points in the nearby (SUBCBOX) neighborhood. Additionally, potential match point candidate are grown from the seed match points that provide full DEM coverage.
Initially, seed points are required to provide a starting point to DEM generation. Seed points can come either from a control net file (see the ISIS qnet application) or is created automatically by the application.
Automatic seed point generatation is accomplished using the Gruen co-registration algorithm. A grid of control points is created using the SPACE parameter to determine line and sample increments of the center of each point. The sizes of the "chips" are defined by the contents of the REGDEF parameter. This REGDEF file follows the ISIS AutoRegistration design for generic specifications of matching algorithm definitions.
Here is an example of a REGDEF file:
Object = AutoRegistration Group = Algorithm Name = AdaptiveGruen Tolerance = 0.005 MaximumIterations = 30 AffineTolerance = 1.5 SpiceTolerance = 5.0 AffineTranslationTolerance = 0.1 AffineScaleTolerance = 0.3 AffineShearTolerance = 0.3 # RadioShiftTolerance = 256 # RadioGainMinTolerance = -0.75 # RadioGainMaxTolerance = 3.0 # DefaultRadioShift = 0.0 # DefaultRadioGain = 0.0 EndGroup Group = PatternChip Samples = 21 Lines = 21 ValidPercent = 75.0 MinimumZScore = 1.7 EndGroup Group = SearchChip Samples = 31 Lines = 31 ValidPercent = 75.0 EndGroup EndObject
Parameter | Description |
---|---|
Name | Name of the algorithm that the set of parameters description apply to. This should be AdaptiveGruen. |
Tolerance | This constrains the eigenvalues of the registration result. Registrations with GoodnessOfFit larger than this value are rejected. It is highly recommended this value be utilized as it will result in better fits. (Default: Unbounded) (ISIS2 Equivalent: MAXEV) |
MaximumIterations | Maximum number of iterations allowed for the registration processing to converge. (Default: 30) (ISIS2 Equivalent: GITER) |
AffineTolerance | The amount of offset in pixels an Affine derived points is allowed to deviate from the orginal match point. (Default: Unbounded)(ISIS2 Equivalent: DAFFINE) |
SpiceTolerance | The amount of offset in pixels a registration is allowed to deviate from a registered point. (Default: Unbounded)(ISIS2 Equivalent: DSPICE) |
AffineTranslationTolerance | Specifies the threshold convergence value of the Affine translation shift in line/sample between each Gruen match iteration. If the amout of this value computed in the Gruen algorithm is less than this value, it is deemed a match point concerning the translation portion of the registered point. (Default: 0.1) (ISIS2 Eqivalent: THRESH1) |
AffineScaleTolerance | Specifies the threshold convergence value of the Affine scale in line/sample between each Gruen match iteration. If the amout of this value computed in the Gruen algorithm is less than this value, it is deemed a match point concerning the scaling portion of the registered point. (Default: 0.3) (ISIS2 Eqivalent: THRESH2) |
AffineShearTolerance | Specifies the threshold convergence value of the Affine shear in line/sample between each Gruen match iteration. If the amout of this value computed in the Gruen algorithm is less than this value, it is deemed a match point concerning the shearing portion of the registered point. (Default: AffineScaleTolerance) (ISIS2 Eqivalent: THRESH2) |
RadioShiftTolerance | Specifies the threshold convergence value for the radiometric shift of the pixel value between each Gruen match iteration. If the amout of this value computed in the Gruen algorithm is less than this value, it is deemed a match point concerning the radiometric shift portion of the registered point. (Default: Unbounded) (ISIS2 Equivalent: 256) |
RadioGainMinTolerance | Specifes the threshold convergence minimum value for the radiometric gain of the pixel value between each Gruen match iteration. If the amout of this value computed in the Gruen algorithm is greater than this value and less than RadioGainMaxTolerance, it is deemed a match point concerning the radiometric gain portion of the registered point. (Default: Unbounded) (ISIS2 Equivalent: 0.25) |
RadioGainMaxTolerance | Specifes the threshold convergence maximum value for the radiometric gain of the pixel value between each Gruen match iteration. If the amout of this value computed in the Gruen algorithm is less than this value and greater than RadioGainMinTolerance, it is deemed a match point concerning the radiometric gain portion of the registered point. (Default: Unbounded) (ISIS2 Equivalent: 4.0) |
DefaultRadioShift | Sets the default value for the radiometric shift value used as a starting point in the Gruen algorithm. (Default: 0) |
DefaultRadioGain | Sets the default value for the radiometric gain value used as a starting point in the Gruen algorithm. (Default: 0) |
Once the full grid of control points is generated, a subset of points are selected using various algorithms. The NSEED parameter determines the total number of seed points that will be selected from the result of the grid of control points. If NSEED >= 1.0, then this is taken as the total number of seed points to select. If NSEED > 0.0 but < 1.0, then NSEED is used as a fraction of the total number of control points selected. Otherwise, 5% of the control points will be selected.
The seed point selection process is governed by SEEDSAMPLE. If SEEDSAMPLE <= 0.0, then the points are selected from the best matching points as registered by the Gruen algorithm. Otherwise, a specially crafted randomized selection algorithm is used. This algorithm uses the range of control point goodness of fit (or eigenvalues in the case of the Gruen algorithm measure of registration) to compute a randomized value that is added to each eigenvalue and tested against the best (smallest) one. This algorithm is repeated until all seed points are selected.
A random number generator is required to make this algorithm work. smtk uses the GSL Random Number Generator. The default GSL random number generator used is the Mersenne Twister. Other GSL algorithms can be selected with the use of environment variables
Once the seed points are selected, generation of the DEM begins. The best registering points are selected first off the list of seed points. Each seed point is added to the final DEM point if a point does not already exist for the given line/sample coordinate. The list of final DEM match points are continually added to with points cloned from registered points at intervals SUBCBOX lines and samples if and only if the current registration point is better than the existing one at those surrounding points.
The candidate list of points are grown at adjacent line/sample coordinates by cloning the points using the Affine parameters computed for the original match point. These points are tested for validity in terms of points within the image boundary and geometric mapping. The progress of the growth stack is reported as it grows.
The DEM generation is complete when the (growth) match point stack is depleted.
The DEM is created by computing stereo elevations from the left (FROM) and right (MATCH) points. Vectors from the target (planet center) to the spacecraft and target to the surface registration points are computed for each point. From these points, the elevation is computed.
From these points, a three band cube is generated from the FROM file. The first band is elevation, second is the error in the elevation and the third is the goodness of fit (eigenvalue).
This application works best on level2 projected images that have not been mosaiced.
Name | Description |
---|---|
FROM | Input Image to be matched |
MATCH | The file that will be geometrically (affined) matched |
REGDEF | The Gruen Auto Registration paramter file |
Name | Description |
---|---|
CNET | Input control net used to determine the seed points |
SPACE | Growth spacing value |
NSEED | Specify how to select seed points |
SEEDSAMPLE | Specify method for choosing best seed point |
SUBCBOX | Growth replication box size |
Name | Description |
---|---|
TO | Output Cube |
PLOTDIST | Plot tolerance from match pixel for DEM determination |
BOXSIZE | Size of box around box around center match pixel |
Name | Description |
---|---|
OSEEDNET | Control network of selected seed points |
ONET | Pvl file of ControlNet |
This cube will be used as the pattern or fixed image. It will correspond to the output image DEM generated by smtk.
Type | cube |
---|---|
File Mode | input |
Filter | *.cub |
This cube will be geometrically matched to the FROM image using an interative (AdaptiveGruen) algorithm.
Type | cube |
---|---|
File Mode | input |
Filter | *.cub |
File containing parameters that are provided to the Gruen algorithm that provide definitions, defaults and constraints for registration processing.
Type | filename |
---|---|
File Mode | input |
Default Path | $ISISROOT/appdata/templates/autoreg |
Default | $ISISROOT/appdata/templates/autoreg/coreg.adaptgruen.p1515s3030.def |
Filter | *.def |
The sample, line values of non-ignored control measures in the input (FROM) cube will be used as seed points.
Type | filename |
---|---|
Internal Default | Create a grid |
Filter | *.net |
This parameter specifies the spacing of lines and samples around a seed point to grow a seed point. This value added to the surrounding sample and line of a 3x3 box around a match point. The FROM image latitude and longitude values is used at that line/sample location to determine the MATCH line/sample point. The affine of the match point is then applied to the MATCH line/sample point and its parameters are added to the grow stack for futher population considerations. As such, it should not to large a value as the affine translation validity is not too strong very far away from the match point.
Type | integer |
---|---|
Default | 3 |
When computing seed values not coming from a control net, this parameter specifies how many to keep from the succesful list generated from the first pass. If 0, then save 5 percent of the total number computed seed points. If > 0 and < 1, this is the percentage to use. If > 1, specifies the number of points to select.
Type | double |
---|---|
Default | 0.0 |
This parameter specifies what process to use to select the best seed points from the first pass (automatic seed point generation) of the matcher. If 0, use the smallest eigen value to the largest (essentially preferring the best points). If > 0, sample from minimum to maximum eigen with exponetial distribution where SEEDSAMPLE is the curvature.
Type | double |
---|---|
Default | 0.0 |
This parameter specifies the number of lines and samples around a seed point to replicate in the growth algorithm. These points are added to the final point set when comparison against existing points results in the new point having a better registration value.
Type | integer |
---|---|
Default | 5 |
Output cube containing the translated or warped data.
Type | cube |
---|---|
File Mode | output |
Pixel Type | real |
Filter | *.cub |
This parameter provides a tolerance when determining searching for points that fall within the output plot buffer. smtk plots by tile so points on the border my fall outside the boundary of a tile. To ensure all possible points are included in the appropriate output tile, this parameter will include matchpoints that are outside the boundary of the output tile by this amount.
Type | double |
---|---|
Default | 5.0 |
Minimum | 0.0 (inclusive) |
This parameter specifies the size of the box around the match pixel to compute DEM output values for. If the BOXSIZE is 1, then only the center pixel is used. If the BOXSIZE is 3, then a 3x3 box around the center pixel is used to computed output pixel values and each match pixel may add 9 total pixels to the DEM.
Type | integer |
---|---|
Default | 3 |
Minimum | 1 (inclusive) |
This file will be created from the set of chosen seed points generated by this application. It can be used to discern the quality of the automatic and randomly generated point set from which all others are defined. It will not be created if one is provided. To evaluate the points, create a list of FROM and MATCH files. Then use the ISIS program qnet to select the list and then this file. It will display the two images and plot all the seed points on the two images. Points can be updated, deleted and added to the control network and then provided in subsequent runs of smtk as the seed control network file, CNET.
Type | filename |
---|---|
File Mode | output |
Internal Default | None |
Filter | *.net |
This file will be created that contains all the DEM points created by the smtk application. The data will be in Pvl format.
Type | filename |
---|---|
File Mode | output |
Internal Default | None |
Filter | *.net |
Kris Becker | 2009-09-16 | Original Version |
Steven Lambright | 2011-03-24 | Implemented growing algorithm |
Kris Becker | 2011-06-03 | Made significant changes to Gruen and smtk to better implement the ISIS2 version of the application. |
Debbie A. Cook | 2012-07-06 | Updated Spice members to be more compliant with Isis coding standards. References #972. |
Debbie A. Cook | 2012-10-11 | Updated to use new Target class. References Mantis numbers #775 and #1114. |
Jeannie Backer | 2016-04-22 | Modified to use the FROM cube labels to set output control net target instead of the TargetName. References #3892 |