matchFeaturesInRadius

Find matching features within specified radius

Syntax

indexPairs = matchFeaturesInRadius(features1,features2,points2,centerPoints,radius)

[indexPairs,matchMetric] = matchFeaturesInRadius(___)

[indexPairs,matchMetric] = matchFeaturesInRadius(___,Name,Value)

Description

indexPairs = matchFeaturesInRadius(features1,features2,points2,centerPoints,radius) returns the indices of the features most likely to correspond between the input feature sets within the specified radius or radii around each expected match location.

[indexPairs,matchMetric] = matchFeaturesInRadius(___) also returns the distance between the features in a matched pair in indexPairs.

[indexPairs,matchMetric] = matchFeaturesInRadius(___,Name,Value) specifies options using one or more name-value arguments in addition of the input arguments in previous syntaxes.

Examples

Match Features Between Two Images

Load a MAT file containing an image and camera data into the workspace.

data = load('matchInRadiusData.mat');

Convert the camera pose to extrinsics.

orientation = data.cameraPose2.Rotation;
location = data.cameraPose2.Translation;
[rotationMatrix,translationVector] = cameraPoseToExtrinsics(orientation,location);

Project the 3-D world points associated with feature set one onto the second image.

centerPoints = worldToImage(data.intrinsics,rotationMatrix,translationVector,data.worldPoints);

Match features between the two feature sets within spatial constraints.

indexPairs1 = matchFeaturesInRadius(data.features1,data.features2, ...
        data.points2,centerPoints,data.radius,'MatchThreshold',40, ...
        'MaxRatio',0.9);

Match features between the two feature sets without using spatial constraints.

indexPairs2 = matchFeatures(data.features1,data.features2, ...
        'MatchThreshold',40,'MaxRatio',0.9);

Visualize and compare the results between the two ways of matching features.

figure
subplot(2,1,1)
showMatchedFeatures(data.I1,data.I2,data.points1( ...
    indexPairs1(:,1)),data.points2(indexPairs1(:,2)));
title(sprintf('%d pairs matched with spatial constraints',size(indexPairs1,1)));

subplot(2,1,2)
showMatchedFeatures(data.I1,data.I2,data.points1( ...
    indexPairs2(:,1)),data.points2(indexPairs2(:,2)));
title(sprintf('%d pairs matched without spatial constraints',size(indexPairs2,1)));

Input Arguments

features1 — Feature set one

binaryFeatures object | M1-by-N matrix

Feature set one, specified as a binaryFeatures object or an M1-by-N matrix. The matrix contains M1 features, and N corresponds to the length of each feature vector.

You can obtain the binaryFeatures object using the extractFeatures function with the fast retina keypoint (FREAK), oriented fast and rotated brief (ORB), or binary robust invariant scalable keypoints (BRISK) descriptor method.

Data Types: logical | int8 | uint8 | int16 | uint16 | int32 | uint32 | single | double | binaryFeature object

features2 — Feature set two

M2-by-N matrix | binaryFeatures object

Feature set two, specified as a binaryFeatures object or an M2-by-N matrix. The matrix contains M2 features, and N corresponds to the length of each feature vector.

You can obtain the binaryFeatures object using the extractFeatures function with the fast retina keypoint (FREAK), oriented fast and rotated brief (ORB), or binary robust invariant scalable keypoints (BRISK) descriptor method.

Data Types: logical | int8 | uint8 | int16 | uint16 | int32 | uint32 | single | double | binaryFeature object

points2 — Feature points of feature set two

M2-by-2 matrix | M2-element feature point array

Feature points of feature set two, specified as either an M2-by-2 matrix in the format [x y] or an M2-element feature point array. For a list of point feature types, see Point Feature Types.

Data Types: single | double | point feature type

centerPoints — Expected matched locations

M1-by-2 matrix

Expected matched locations in the second image that correspond to the feature points from features1, specified as an M1-by-2 matrix of coordinates in the format [x y].

Data Types: single | double

radius — Search radius associated with center points

scalar | M1-element vector

Search radius associated with the center points, specified as a scalar or an M1-element vector. When you specify the radius as a scalar value, the function uses the same search radius for all center points.

Data Types: single | double

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: 'Metric','SSD' specifies the sum of squared differences metric for feature matching.

MatchThreshold — Matching threshold

10.0 or 1.0 (default) | scalar value in the range (0, 100]

Matching threshold, specified as a scalar value in the range (0,100]. The default values are 10.0 for binary feature vectors or 1.0 for nonbinary feature vectors. You can use the matching threshold to select the strongest matches. The threshold represents a percent of the distance from a perfect match.

Two feature vectors match when the distance between them is less than the threshold set by 'MatchThreshold'. The function rejects a match when the distance between the features is greater than the value of 'MatchThreshold'. Increase the value to return more matches.

Inputs that are binaryFeatures objects typically require a larger value for the match threshold. The extractFeatures function returns a binaryFeatures object when extracting FREAK, ORB, or BRISK descriptors.

MaxRatio — Ratio threshold

0.6 (default) | scalar value in the range (0, 1]

Ratio threshold, specified as a scalar value in the range (0, 1]. Use the ratio to reject ambiguous matches. Increase this value to return more matches.

Metric — Feature matching metric

'SSD' (default) | 'SAD'

Feature matching metric, specified as either 'SAD' or 'SSD'.

'SAD'	Sum of absolute differences
'SSD'	Sum of squared differences

This property applies when you specify the input feature sets, features1 and features2, as matrices. When you specify the features as binaryFeatures objects, the function uses the Hamming distance to compute the similarity metric.

Unique — Unique matches

false or 0 (default) | true or 1

Unique matches, specified as a logical 0 (false) or 1 (true). Set this value to true to return only unique matches between features1 and features2.

When you set Unique to false, the function returns all matches between features1 and features2. Multiple features in features1 can match to one feature in features2.

When you set Unique to true, the function performs a forward-backward match to select a unique match. After matching features1 to features2, it matches features2 to features1 and keeps the best match.

Output Arguments

indexPairs — Indices of corresponding features

P-by-2 matrix

Indices of corresponding features between the two input feature sets, returned as a P-by-2 matrix. Pis the number of matched pairs of features. Each index pair corresponds to a matched feature between the features1 and features2 inputs. The first element indexes the feature in features1. The second element indexes the matching feature in features2.

matchMetric — Distance between matching features

P-by-1 vector

Distance between matching features, returned as a P-by-1 vector. The ith element in matchMetric corresponds to the ith row in the indexPairs output matrix. The values of the distances are based on the metric selected, but a perfect match is always 0. When Metric is set to either SAD or SSD, the feature vectors are normalized to unit vectors before computation. The function returns matchMetric as a double data type when features1 and features2 are of type double. Otherwise, the returned vector is of type single.

Metric	Range
SAD	[0, 2*sqrt(size(features1,2))].
SSD	[0, 4]
Hamming	[0, features1.NumBits]

Note

You cannot select the Hamming metric. The metric is selected automatically when the features1 and features2 inputs are binaryFeatures.

Data Types: single | double

Tips

• Use this function when the 3-D world points that correspond to feature set one features1, are known. centerPoints can be obtained by projecting a 3-D world point onto the second image. You can obtain the 3-D world points by triangulating matched image points from two stereo images.

• You can specify a circular area of points in feature set two to match with feature set one. Specify the origin as centerPoints with a radius specified by radius. Specify the points to match from feature set two as points2

  .

References

[1] Fraundorfer, Friedrich, and Davide Scaramuzza. “Visual Odometry: Part II: Matching, Robustness, Optimization, and Applications.” IEEE Robotics & Automation Magazine 19, no. 2 (June 2012): 78–90. https://doi.org/10.1109/MRA.2012.2182810.

[2] Lowe, David G. “Distinctive Image Features from Scale-Invariant Keypoints.” International Journal of Computer Vision 60, no. 2 (November 2004): 91–110. https://doi.org/10.1023/B:VISI.0000029664.99615.94.

[3] Muja, Marius, and David G. Lowe. “Fast Approximate Nearest Neighbors With Automatic Algorithm Configuration:” In Proceedings of the Fourth International Conference on Computer Vision Theory and Applications, 331–40. Lisboa, Portugal: SciTePress - Science and and Technology Publications, 2009. https://doi.org/10.5220/0001787803310340.

[4] Muja, Marius, and David G. Lowe. "Fast Matching of Binary Features." In 2012 Ninth Conference on Computer and Robot Vision, 404–10. New York: Institute of Electrical and Electronics Engineers, 2012. https://doi.org/10.1109/CRV.2012.60.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• 'Method' and 'Metric' must be compile-time constants.