Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions

Public Release
8.2.0
8.1.0
8.0.0
7.2.0
7.1.0
7.0.0
6.0.0
3.9.0
3.5.0

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation


smtk

Printer Friendly View | TOC | Home

Generate a digital elevation map (DEM) from two images using the Stereo Matcher ToolKit (SMTK)

Overview Parameters

Description

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
      

Here is a description of all the parameters that are utilized by the smtk application. Defaults that are set within the program are indicated where applicable. If a default is provided, the presence of the keyword is not required in the REGDEF file. The ISIS2 equivalent is provided where applicable:

Gruen AutoReg Parameters

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)

Other ISIS2 parameters CBOX (Samples, Lines), LOW (ValidMinimum), HIGH (ValidMaximum), GMPTS (ValidPercent) are specified in the PatternChip and SearchChip groups. See the coreg application documentation for the details on these and other additional parameters that may be used to refine or constrain match conditions.

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.


Acknowledgements

This application is derived from the ISIS2 application SMTK suite (matcher, stereo, and xyzplot). ISIS2 SMTK was developed by Sarah Andre and Troy Andre.


Categories


Related Objects and Documents

Applications


History

Kris Becker2009-09-16 Original Version
Steven Lambright2011-03-24 Implemented growing algorithm
Kris Becker2011-06-03 Made significant changes to Gruen and smtk to better implement the ISIS2 version of the application.
Debbie A. Cook2012-07-06 Updated Spice members to be more compliant with Isis coding standards. References #972.
Debbie A. Cook2012-10-11 Updated to use new Target class. References Mantis numbers #775 and #1114.
Jeannie Backer2016-04-22 Modified to use the FROM cube labels to set output control net target instead of the TargetName. References #3892

Parameter Groups

Input Files

Name Description
FROM Input Image to be matched
MATCH The file that will be geometrically (affined) matched
REGDEF The Gruen Auto Registration paramter file

Input Seeding and Growing

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

Output Options

Name Description
TO Output Cube
PLOTDIST Plot tolerance from match pixel for DEM determination
BOXSIZE Size of box around box around center match pixel

Other Output Files

Name Description
OSEEDNET Control network of selected seed points
ONET Pvl file of ControlNet
X

Input Files: FROM


Description

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
Close Window
X

Input Files: MATCH


Description

This cube will be geometrically matched to the FROM image using an interative (AdaptiveGruen) algorithm.

Type cube
File Mode input
Filter *.cub
Close Window
X

Input Files: REGDEF


Description

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
Close Window
X

Input Seeding and Growing: CNET


Description

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
Close Window
X

Input Seeding and Growing: SPACE


Description

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
Close Window
X

Input Seeding and Growing: NSEED


Description

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
Close Window
X

Input Seeding and Growing: SEEDSAMPLE


Description

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
Close Window
X

Input Seeding and Growing: SUBCBOX


Description

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
Close Window
X

Output Options: TO


Description

Output cube containing the translated or warped data.

Type cube
File Mode output
Pixel Type real
Filter *.cub
Close Window
X

Output Options: PLOTDIST


Description

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)
Close Window
X

Output Options: BOXSIZE


Description

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)
Close Window
X

Other Output Files: OSEEDNET


Description

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
Close Window
X

Other Output Files: ONET


Description

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
Close Window