# estimateGeometricTransform

Estimate geometric transform from matching point pairs

## Syntax

``tform = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType)``
``````[tform,inlierpoints1,inlierpoints2] = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType)``````
``[___,status] = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType)``
``[___] = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType, Name,Value)``

## Description

example

````tform = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType)` returns a 2-D geometric transform object, `tform`. The `tform` object maps the inliers in `matchedPoints1` to the inliers in `matchedPoints2`.The function excludes outliers using the M-estimator SAmple Consensus (MSAC) algorithm. The MSAC algorithm is a variant of the Random Sample Consensus (RANSAC) algorithm. Results may not be identical between runs because of the randomized nature of the MSAC algorithm. NoteThis function will be removed in a future release. Use the `estimateGeometricTransform2D` or `estimateGeometricTransform3D` function which offer greater functionality. ```

example

``````[tform,inlierpoints1,inlierpoints2] = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType)``` returns the corresponding inlier points in `inlierpoints1` and `inlierpoints2`.```

example

````[___,status] = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType)` returns a status code of `0`, `1`, or `2`. If you do not request the `status` code output, the function returns an error for conditions that cannot produce results.```
````[___] = estimateGeometricTransform(matchedPoints1,matchedPoints2,transformType, Name,Value)` uses additional options specified by one or more `Name,Value` arguments.```

## Examples

collapse all

Read an image and display it.

```original = imread('cameraman.tif'); imshow(original) title('Base Image')```

Distort and display the transformed image.

```distorted = imresize(original,0.7); distorted = imrotate(distorted,31); figure imshow(distorted) title('Transformed Image')```

Detect and extract features from the original and the transformed images.

```ptsOriginal = detectSURFFeatures(original); ptsDistorted = detectSURFFeatures(distorted); [featuresOriginal,validPtsOriginal] = extractFeatures(original,ptsOriginal); [featuresDistorted,validPtsDistorted] = extractFeatures(distorted,ptsDistorted);```

Match and display features between the images.

```index_pairs = matchFeatures(featuresOriginal,featuresDistorted); matchedPtsOriginal = validPtsOriginal(index_pairs(:,1)); matchedPtsDistorted = validPtsDistorted(index_pairs(:,2)); figure showMatchedFeatures(original,distorted,matchedPtsOriginal,matchedPtsDistorted) title('Matched SURF Points With Outliers');```

Exclude the outliers, estimate the transformation matrix, and display the results.

```[tform,inlierIdx] = estimateGeometricTransform2D(matchedPtsDistorted,matchedPtsOriginal,'similarity'); inlierPtsDistorted = matchedPtsDistorted(inlierIdx,:); inlierPtsOriginal = matchedPtsOriginal(inlierIdx,:); figure showMatchedFeatures(original,distorted,inlierPtsOriginal,inlierPtsDistorted) title('Matched Inlier Points')```

Use the estimated transformation to recover and display the original image from the distorted image.

```outputView = imref2d(size(original)); Ir = imwarp(distorted,tform,'OutputView',outputView); figure imshow(Ir); title('Recovered Image');```

## Input Arguments

collapse all

Matched points from image 1, specified as either a `KAZEPoints`, `cornerPoints` object, `SIFTPoints`, `SURFPoints` object, `MSERRegions` object, `ORBPoints` object, `BRISKPoints`or an M-by-2 matrix of [x,y] coordinates. The function excludes outliers using the M-estimator SAmple Consensus (MSAC) algorithm. The MSAC algorithm is a variant of the Random Sample Consensus (RANSAC) algorithm.

Matched points from image 2, specified as either a `KAZEPoints`, `cornerPoints` object, `SIFTPoints`, `SURFPoints` object, `MSERRegions` object, `ORBPoints` object, `BRISKPoints`or an M-by-2 matrix of [x,y] coordinates. The function excludes outliers using the M-estimator SAmple Consensus (MSAC) algorithm. The MSAC algorithm is a variant of the Random Sample Consensus (RANSAC) algorithm.

Transform type, specified as one of three character strings. You can set the transform type to either `'similarity'`, `'affine'`, or `'projective'`. The greater the number of matched pairs of points, the greater the accuracy of the estimated transformation. The minimum number of matched pairs of points for each transform type:

Transform TypeMinimum Number of Matched Pairs of Points
`'similarity'`2
`'affine'`3
`'projective'`4

Data Types: `char`

### Name-Value Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'Confidence'`,`99` sets the confidence value to `99`.

Maximum number of random trials for finding the inliers, specified as the comma-separated pair consisting of '`MaxNumTrials`' and a positive integer scalar. Increasing this value improves the robustness of the results at the expense of additional computations.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Confidence of finding the maximum number of inliers, specified as the comma-separated pair consisting of '`Confidence`' and a percentage numeric scalar in the range (0 100). Increasing this value improves the robustness of the results at the expense of additional computations.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Maximum distance in pixels, from a point to the projection of its corresponding point, specified as the comma-separated pair consisting of '`MaxDistance`' and a positive numeric scalar. The corresponding projection is based on the estimated transform.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

## Output Arguments

collapse all

Geometric transformation, returned as either an `affine2d` object or a `projective2d` object.

The returned geometric transformation matrix maps the inliers in `matchedPoints1` to the inliers in `matchedPoints2`. When you set the `transformType` input to either `'similarity'` or `'affine'`, the function returns an `affine2d` object. Otherwise, it returns a `projective2d` object.

Status code, returned as the value `0`, `1`, or `2`.

`status`Description
`0`No error.
`1``matchedPoints1` and `matchedPoints2` inputs do not contain enough points.
`2`Not enough inliers found.

If you do not request the `status` code output, the function will throw an error for the two conditions that cannot produce results.

Data Types: `double`

Inlier points in image 1, returned as the same type as the input matching points.

Inlier points in image 2, returned as the same type as the input matching points.

## References

[1] Hartley, R., and A. Zisserman, "Multiple View Geometry in Computer Vision," Cambridge University Press, 2003.

[2] Torr, P. H. S., and A. Zisserman, "MLESAC: A New Robust Estimator with Application to Estimating Image Geometry," Computer Vision and Image Understanding, 2000.

## Extended Capabilities

Introduced in R2013a