Documentation Center

  • Trial Software
  • Product Updates

vision.GeometricTransformEstimator System object

Package: vision

Estimate geometric transformation from matching point pairs

Description

    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 [x1 y1; x2 y2; ...; xN yN ] 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.

Construction

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).

Properties

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.

Methods

cloneCreate geometric transform estimator object with same property values
getNumInputsNumber of expected inputs to step method
getNumOutputsNumber of outputs from step method
isLockedLocked status for input attributes and nontunable properties
release Allow property value and input characteristics changes
stepCalculate transformation matrix mapping largest number of valid points from input arrays

Examples

expand all

Recover Transformed Image Using SURF Feature Points

Detect, extract, and match SURF features from two images.

Read and transform input images

Iin  = imread('cameraman.tif'); imshow(Iin); title('Base image');
Iout = imresize(Iin, 0.7); Iout = imrotate(Iout, 31);
figure; imshow(Iout); title('Transformed image');

Detect and extract features from both images.

ptsIn  = detectSURFFeatures(Iin);
ptsOut = detectSURFFeatures(Iout);
[featuresIn   validPtsIn]  = extractFeatures(Iin,  ptsIn);
[featuresOut validPtsOut]  = extractFeatures(Iout, ptsOut);

Match feature vectors.

index_pairs = matchFeatures(featuresIn, featuresOut);

Get matching points.

matchedPtsIn  = validPtsIn(index_pairs(:,1));
matchedPtsOut = validPtsOut(index_pairs(:,2));
figure; showMatchedFeatures(Iin,Iout,matchedPtsIn,matchedPtsOut);
title('Matched SURF points, including outliers');

Compute the transformation matrix using RANSAC.

gte = vision.GeometricTransformEstimator;
gte.Transform = 'Nonreflective similarity';
[tform inlierIdx] = step(gte, matchedPtsOut.Location, matchedPtsIn.Location);
figure; showMatchedFeatures(Iin,Iout,matchedPtsIn(inlierIdx),matchedPtsOut(inlierIdx));
title('Matching inliers'); legend('inliersIn', 'inliersOut');
 

Recover the original image.

agt = vision.GeometricTransformer;
Ir = step(agt, im2single(Iout), tform);
figure; imshow(Ir); title('Recovered image');

Transform an Image According to Specified Points

Create and transform a checkboard image to specified points.

Create a checkerboard input image.

input = checkerboard;
[h, w] = size(input);
inImageCorners = [1 1; w 1; w h; 1 h];
outImageCorners = [4 21; 21 121; 79 51; 26 6]; 
hgte1 = vision.GeometricTransformEstimator('ExcludeOutliers', false);
tform = step(hgte1, inImageCorners, outImageCorners);

Use tform to transform the image.

hgt = vision.GeometricTransformer;
output = step(hgt, input, tform);
figure; imshow(input); title('Original image');
figure; imshow(output); title('Transformed image'); 

Troubleshooting

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.

Algorithms

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.

See Also

| | | |

Was this topic helpful?