Match key points

A superclass for tools that match objects based on key point coordinates and their associated feature descriptors.

This tool maintains a database of object models as feature points and quickly retrieves matching models for unknown objects. Each feature point is described by point coordinates and a feature vector (a.k.a “descriptor”). The point coordinates specify the location of the feature point with respect to the model. The tool can handle two- and three-dimensional point coordinates.

There can be an unlimited number of models, each containing an unlimited number of feature points. Furthermore, each model may have an associated class index. This makes it possible to have multiple models for a class of objects.

This tool implements a fast key point database search algorithm but does not specify a geometric model for the arrangement of the matched key points. Different geometric models are needed in different applications, and these are implemented by inherited tools such as rigid 2D matching.

Inputs

• keyPoints: The locations of key points in world coordinates. A N-by-X matrix in which each row contains X-dimensional point coordinates (usually 2, but may be 3). Each point must have a corresponding feature vector in features. Otherwise, a run-time error will be generated.

• features: A feature vector for each point. An N-by-D matrix in which each row stores a feature point descriptor (D-dimensional vector).

• modelPoints: The locations of model key points in world coordinates. A P-by-X matrix.

• modelFeatures: A feature vector for each model key point. A P-by-D matrix.

• modelIndices: The index of the model the key points belong to. A P-by-1 matrix.

• modelFrames: An optional parameter specifying a coordinate frame for each model, in world coordinates. A 4M-by-4 matrix. If a match for a model is found, this coordinate frame will be transformed based on its location and reported as the *frame* of the match. If model frames are not provided, the tool automatically places the frame to the upper left corner of the axis-aligned bounding box of the model’s key points. IfmodelFrames* is non-empty, modelSizes must be provided as well.

• modelSizes: An optional parameter specifying the size of each model in world coordinates. A M-by-2 matrix. If model sizes are not provided, the tool automatically uses the size of the axis-aligned bounding box of the model’s key points. If modelSizes is non-empty, modelFrames must also be provided. Note that the frame and size of a model may specify any area in world coordinates; the key points don’t need to be enclosed by it.

• modelClasses: Class indices for each model. If this matrix is non-empty, there must be a class index for each of the M models, resulting in a M-by-1 matrix. If this matrix is empty, the class and model indices will be the same.

• classNames: A C-by-1 table that contains the names of the classes. The modelClasses parameter may not contain values that are greater than C - 1.

• maxMatches: The maximum allowed number of matches. Setting maxMatches to one returns the best match only. Zero disables this limit.

• closestMatchCount: The number of closest matches against which each query point will be compared. By default, only the closest match in the model database will be considered. A greater value means higher accuracy and lower speed.

• maxEvaluations: The maximum number of evaluations when searching the database for matching feature vectors. Setting maxEvaluations to zero makes the search algorithm perform an exact search: for each feature vector, the closest match(es) will be found with a probability of one. Limiting the number of evaluations may be useful if the model database is large. The limit turns the exact search into an approximate one that returns the probably closest neighbors if it runs out of time. Choosing maxEvaluations appropriately makes it possible to return correct matches for the majority of feature points while making the search much faster.

Outputs

• frame: The location of the matched object in world coordinates. The matcher first finds the transformation between points and the matching model. The model’s frame is then transformed according to it. This output parameter contains the transformed frame(s). A 4*N-by-4 matrix.

• size: The size of the matched object in world coordinates. An N-by-2 matrix.

• modelIndex: The index of the model that matched. An N-by-1 matrix.

• classIndex: The class index of the matching model. An N-by-1 matrix.

• className: The class name of the matching model. An N-by-1 table.

• confidence: Confidence of the match (0…1). The bigger the value, the better the match. An N-by-1 matrix.

enum MatchingMode

Strategies for selecting matching models.

Values:

enumerator ManyMatchesPerModel

The input image is searched for any number of matches of any of the database objects.

As a result, zero or more matches may be found, and the same model may be found multiple times. This mode is suitable if objects may overlap and many similar objects may be present.

enumerator OneMatchPerModel

The input image is searched for any number of objects, but at most one match is allowed for each model.

This mode is suitable if only the existence of an object matters.