Documentation |
Package: vision
Estimate geometric transformation from matching point pairs
Note: It is recommended that you use the new estimateGeometricTransform function in place of the vision.GeometricTransformEstimator object. |
The GeometricTransformEstimator object estimates geometric transformation from matching point pairs and returns the transform in a matrix. Use this object to compute projective, affine, or nonreflective similarity transformations with robust statistical methods, such as, RANSAC and Least Median of Squares.
Use the step syntax below with input points, MATCHED_POINTS1 and MATCHED_POINTS2, the object, H, and any optional properties.
TFORM = step(H,MATCHED_POINTS1, MATCHED_POINTS2) calculates the transformation matrix, TFORM. The input arrays, MATCHED_POINTS1 and MATCHED_POINTS2 specify the locations of matching points in two images. The points in the arrays are stored as a set of [x_{1} y_{1}; x_{2 }y_{2}; ...; x_{N }y_{N }] coordinates, where N is the number of points. When you set the Transform property to Projective, the step method outputs TFORM as a 3-by-3 matrix. Otherwise, the step method outputs TFORM as a 3-by-2 matrix.
[TFORM,INLIER_INDEX] = step(H, ...) additionally outputs the logical vector, INLIER_INDEX, indicating which points are the inliers.
H = vision.GeometricTransformEstimator returns a geometric transform estimation System object, H. This object finds the transformation matrix that maps the largest number of points between two images.
H = vision.GeometricTransformEstimator(Name,Value) returns a geometric transform estimation object, H, with each specified property set to the specified value. You can specify additional name-value pair arguments in any order as (Name1, Value1,...,NameN,ValueN).
Transform |
Transformation type Specify transformation type as one of Nonreflective similarity | Affine | Projective. Default: Affine |
ExcludeOutliers |
Whether to exclude outliers from input points Set this property to true to find and exclude outliers from the input points and use only the inlier points to calculate the transformation matrix. When you set this property to false, all input points are used to calculate the transformation matrix. Default: true |
Method |
Method to find outliers Specify the method to find outliers as one of Random Sample Consensus (RANSAC) | Least Median of Squares. Default: Random Sample Consensus (RANSAC). |
AlgebraicDistanceThreshold |
Algebraic distance threshold for determining inliers Specify a scalar threshold value for determining inliers as a positive, scalar value. The threshold controls the upper limit used to find the algebraic distance for the RANSAC method. This property applies when you set the Transform property to Projective and the Method property to Random Sample Consensus (RANSAC). This property is tunable. Default: 2.5. |
PixelDistanceThreshold |
Distance threshold for determining inliers in pixels Specify the upper limit of the algebraic distance that a point can differ from the projection location of its associating point. Set this property as a positive, scalar value. This property applies when you set the Transform property to Nonreflective similarity or to Affine, and the Method property to Random Sample Consensus (RANSAC). This property is tunable. Default: 2.5. |
NumRandomSamplingsMethod |
How to specify number of random samplings Indicate how to specify number of random samplings as one of Specified value | Desired confidence. Set this property to Desired confidence to specify the number of random samplings as a percentage and a maximum number. This property applies when you set the ExcludeOutliers property to true and the Method property to Random Sample Consensus (RANSAC). Default: Specified value. |
NumRandomSamplings |
Number of random samplings Specify the number of random samplings as a positive, integer value. This property applies when you set the NumRandomSamplingsMethod property to Specified value. This property is tunable. Default: 500. |
DesiredConfidence |
Probability to find largest group of points Specify as a percentage, the probability to find the largest group of points that can be mapped by a transformation matrix. This property applies when you set the NumRandomSamplingsMethod property to Desired confidence. This property is tunable. Default: 99. |
MaximumRandomSamples |
Maximum number of random samplings Specify the maximum number of random samplings as a positive, integer value. This property applies when you set the NumRandomSamplingsMethod property to Desired confidence. This property is tunable. Default: 1000. |
InlierPercentageSource |
Source of inlier percentage Indicate how to specify the threshold to stop random sampling when a percentage of input point pairs have been found as inliers. You can set this property to one of Auto | Property. If set to Auto then inlier threshold is disabled. This property applies when you set the Method property to Random Sample Consensus (RANSAC). Default: Auto. |
InlierPercentage |
Percentage of point pairs to be found to stop random sampling Specify the percentage of point pairs that needs to be determined as inliers, to stop random sampling. This property applies when you set the InlierPercentageSource property to Property. This property is tunable. Default: 75. |
RefineTransformMatrix |
Whether to refine transformation matrix Set this property to true to perform additional iterative refinement on the transformation matrix. This property applies when you set the ExcludeOutliers property to true. Default: false. |
TransformMatrixDataType |
Data type of the transformation matrix Specify transformation matrix data type as one of single | double when the input points are built-in integers. This property is not used when the data type of points is single or double. Default: single. |
clone | Create geometric transform estimator object with same property values |
getNumInputs | Number of expected inputs to step method |
getNumOutputs | Number of outputs from step method |
isLocked | Locked status for input attributes and nontunable properties |
release | Allow property value and input characteristics changes |
step | Calculate transformation matrix mapping largest number of valid points from input arrays |
The success of estimating the correct geometric transformation depends heavily on the quality of the input point pairs. If you chose the RANSAC or LMS algorithm, the block will randomly select point pairs to compute the transformation matrix and will use the transformation that best fits the input points. There is a chance that all of the randomly selected point pairs may contain outliers despite repeated samplings. In this case, the output transformation matrix, TForm, is invalid, indicated by a matrix of zeros.
To improve your results, try the following:
Increase the percentage of inliers in the input points. |
Increase the number for random samplings. |
For the RANSAC method, increase the desired confidence. |
For the LMS method, make sure the input points have 50% or more inliers. |
Use features appropriate for the image contents |
Be aware that repeated patterns, for example, windows in office building, will cause false matches when you match the features. This increases the number of outliers. |
Do not use this function if the images have significant parallax. You can use the estimateFundamentalMatrix function instead. |
Choose the minimum transformation for your problem. |
If a projective transformation produces the error message, "A portion of the input image was transformed to the location at infinity. Only transformation matrices that do not transform any part of the image to infinity are supported.", it is usually caused by a transformation matrix and an image that would result in an output distortion that does not fit physical reality. If the matrix was an output of the GeometricTransformationEstimator object, then most likely it could not find enough inliers. |
This object implements the algorithm, inputs, and outputs described on the Estimate Geometric Transformation block reference page. The object properties correspond to the block parameters.