DescriptorMatcher

Objective-C

@interface DescriptorMatcher : Algorithm

Swift

class DescriptorMatcher : Algorithm

Abstract base class for matching keypoint descriptors.

It has two groups of match methods: for matching descriptors of an image with another image or with an image set.

Member of Features2d

Methods

  • Clones the matcher.

    Declaration

    Objective-C

    - (nonnull DescriptorMatcher *)clone:(BOOL)emptyTrainData;

    Swift

    func clone(emptyTrainData: Bool) -> DescriptorMatcher

    Parameters

    emptyTrainData

    If emptyTrainData is false, the method creates a deep copy of the object, that is, copies both parameters and train data. If emptyTrainData is true, the method creates an object copy with the current parameters but with empty train data.

  • Clones the matcher.

     that is, copies both parameters and train data. If emptyTrainData is true, the method creates an
 object copy with the current parameters but with empty train data.

    Declaration

    Objective-C

    - (nonnull DescriptorMatcher *)clone;

    Swift

    func clone() -> DescriptorMatcher

  • Declaration

    Objective-C

    + (DescriptorMatcher*)create:(MatcherType)matcherType NS_SWIFT_NAME(create(matcherType:));

    Swift

    class func create(matcherType: MatcherType) -> DescriptorMatcher

  • Creates a descriptor matcher of a given type with the default parameters (using default constructor).

    Declaration

    Objective-C

    + (nonnull DescriptorMatcher *)create2:
    (nonnull NSString *)descriptorMatcherType;

    Swift

    class func create(descriptorMatcherType: String) -> DescriptorMatcher

    Parameters

    descriptorMatcherType

    Descriptor matcher type. Now the following matcher types are supported:

    • BruteForce (it uses L2 )
    • BruteForce-L1
    • BruteForce-Hamming
    • BruteForce-Hamming(2)
    • FlannBased

  • Returns true if there are no train descriptors in the both collections.

    Declaration

    Objective-C

    - (BOOL)empty;

    Swift

    func empty() -> Bool

  • Returns true if the descriptor matcher supports masking permissible matches.

    Declaration

    Objective-C

    - (BOOL)isMaskSupported;

    Swift

    func isMaskSupported() -> Bool

  • Returns a constant link to the train descriptor collection trainDescCollection .

    Declaration

    Objective-C

    - (nonnull NSArray<Mat *> *)getTrainDescriptors;

    Swift

    func getTrainDescriptors() -> [Mat]

  • Adds descriptors to train a CPU(trainDescCollectionis) or GPU(utrainDescCollectionis) descriptor collection.

     If the collection is not empty, the new descriptors are added to existing train descriptors.

    Declaration

    Objective-C

    - (void)add:(nonnull NSArray<Mat *> *)descriptors;

    Swift

    func add(descriptors: [Mat])

    Parameters

    descriptors

    Descriptors to add. Each descriptors[i] is a set of descriptors from the same train image.

  • Clears the train descriptor collections.

    Declaration

    Objective-C

    - (void)clear;

    Swift

    func clear()

  • Finds the k best matches for each descriptor from a query set.

    Declaration

    Objective-C

    - (void)knnMatch:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:
                 (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
                   k:(int)k
                mask:(nonnull Mat *)mask
       compactResult:(BOOL)compactResult;

    Swift

    func knnMatch(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, k: Int32, mask: Mat, compactResult: Bool)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    mask

    Mask specifying permissible matches between an input query and train matrices of descriptors.
    matches

    Matches. Each matches[i] is k or less matches for the same query descriptor.
    k

    Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
    compactResult

    Parameter used when the mask (or masks) is not empty. If compactResult is false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

    These extended variants of DescriptorMatcher::match methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::match for the details about query and train descriptors.

  • Finds the k best matches for each descriptor from a query set.

    Declaration

    Objective-C

    - (void)knnMatch:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:
                 (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
                   k:(int)k
                mask:(nonnull Mat *)mask;

    Swift

    func knnMatch(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, k: Int32, mask: Mat)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    mask

    Mask specifying permissible matches between an input query and train matrices of descriptors.
    matches

    Matches. Each matches[i] is k or less matches for the same query descriptor.
    k

    Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

    These extended variants of DescriptorMatcher::match methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::match for the details about query and train descriptors.

  • Finds the k best matches for each descriptor from a query set.

    Declaration

    Objective-C

    - (void)knnMatch:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:
                 (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
                   k:(int)k;

    Swift

    func knnMatch(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, k: Int32)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object. descriptors.
    matches

    Matches. Each matches[i] is k or less matches for the same query descriptor.
    k

    Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

    These extended variants of DescriptorMatcher::match methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::match for the details about query and train descriptors.

  • Declaration

    Objective-C

    - (void)knnMatch:(nonnull Mat *)queryDescriptors
          matches:(nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
                k:(int)k
            masks:(nonnull NSArray<Mat *> *)masks
    compactResult:(BOOL)compactResult;

    Swift

    func knnMatch(queryDescriptors: Mat, matches: NSMutableArray, k: Int32, masks: [Mat], compactResult: Bool)

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Matches. Each matches[i] is k or less matches for the same query descriptor.
    k

    Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
    masks

    Set of masks. Each masks[i] specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image trainDescCollection[i].
    compactResult

    Parameter used when the mask (or masks) is not empty. If compactResult is false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

  • Declaration

    Objective-C

    - (void)knnMatch:(nonnull Mat *)queryDescriptors
         matches:(nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
               k:(int)k
           masks:(nonnull NSArray<Mat *> *)masks;

    Swift

    func knnMatch(queryDescriptors: Mat, matches: NSMutableArray, k: Int32, masks: [Mat])

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Matches. Each matches[i] is k or less matches for the same query descriptor.
    k

    Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
    masks

    Set of masks. Each masks[i] specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image trainDescCollection[i]. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

  • Declaration

    Objective-C

    - (void)knnMatch:(nonnull Mat *)queryDescriptors
         matches:(nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
               k:(int)k;

    Swift

    func knnMatch(queryDescriptors: Mat, matches: NSMutableArray, k: Int32)

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Matches. Each matches[i] is k or less matches for the same query descriptor.
    k

    Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total. descriptors and stored train descriptors from the i-th image trainDescCollection[i]. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

  • Finds the best match for each descriptor from a query set.

    Declaration

    Objective-C

    - (void)match:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:(nonnull NSMutableArray<DMatch *> *)matches
                mask:(nonnull Mat *)mask;

    Swift

    func match(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, mask: Mat)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    matches

    Matches. If a query descriptor is masked out in mask , no match is added for this descriptor. So, matches size may be smaller than the query descriptors count.
    mask

    Mask specifying permissible matches between an input query and train matrices of descriptors.

    In the first variant of this method, the train descriptors are passed as an input argument. In the second variant of the method, train descriptors collection that was set by DescriptorMatcher::add is used. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, queryDescriptors[i] can be matched with trainDescriptors[j] only if mask.at<uchar>(i,j) is non-zero.

  • Finds the best match for each descriptor from a query set.

    Declaration

    Objective-C

    - (void)match:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:(nonnull NSMutableArray<DMatch *> *)matches;

    Swift

    func match(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    matches

    Matches. If a query descriptor is masked out in mask , no match is added for this descriptor. So, matches size may be smaller than the query descriptors count. descriptors.

    In the first variant of this method, the train descriptors are passed as an input argument. In the second variant of the method, train descriptors collection that was set by DescriptorMatcher::add is used. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, queryDescriptors[i] can be matched with trainDescriptors[j] only if mask.at<uchar>(i,j) is non-zero.

  • Declaration

    Objective-C

    - (void)match:(nonnull Mat *)queryDescriptors
      matches:(nonnull NSMutableArray<DMatch *> *)matches
        masks:(nonnull NSArray<Mat *> *)masks;

    Swift

    func match(queryDescriptors: Mat, matches: NSMutableArray, masks: [Mat])

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Matches. If a query descriptor is masked out in mask , no match is added for this descriptor. So, matches size may be smaller than the query descriptors count.
    masks

    Set of masks. Each masks[i] specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image trainDescCollection[i].

  • Declaration

    Objective-C

    - (void)match:(nonnull Mat *)queryDescriptors
      matches:(nonnull NSMutableArray<DMatch *> *)matches;

    Swift

    func match(queryDescriptors: Mat, matches: NSMutableArray)

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Matches. If a query descriptor is masked out in mask , no match is added for this descriptor. So, matches size may be smaller than the query descriptors count. descriptors and stored train descriptors from the i-th image trainDescCollection[i].

  • For each query descriptor, finds the training descriptors not farther than the specified distance.

    Declaration

    Objective-C

    - (void)radiusMatch:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:
                 (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
         maxDistance:(float)maxDistance
                mask:(nonnull Mat *)mask
       compactResult:(BOOL)compactResult;

    Swift

    func radiusMatch(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, maxDistance: Float, mask: Mat, compactResult: Bool)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    matches

    Found matches.
    compactResult

    Parameter used when the mask (or masks) is not empty. If compactResult is false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.
    maxDistance

    Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)!
    mask

    Mask specifying permissible matches between an input query and train matrices of descriptors.

    For each query descriptor, the methods find such training descriptors that the distance between the query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are returned in the distance increasing order.

  • For each query descriptor, finds the training descriptors not farther than the specified distance.

    Declaration

    Objective-C

    - (void)radiusMatch:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:
                 (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
         maxDistance:(float)maxDistance
                mask:(nonnull Mat *)mask;

    Swift

    func radiusMatch(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, maxDistance: Float, mask: Mat)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    matches

    Found matches. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.
    maxDistance

    Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)!
    mask

    Mask specifying permissible matches between an input query and train matrices of descriptors.

    For each query descriptor, the methods find such training descriptors that the distance between the query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are returned in the distance increasing order.

  • For each query descriptor, finds the training descriptors not farther than the specified distance.

    Declaration

    Objective-C

    - (void)radiusMatch:(nonnull Mat *)queryDescriptors
    trainDescriptors:(nonnull Mat *)trainDescriptors
             matches:
                 (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
         maxDistance:(float)maxDistance;

    Swift

    func radiusMatch(queryDescriptors: Mat, trainDescriptors: Mat, matches: NSMutableArray, maxDistance: Float)

    Parameters

    queryDescriptors

    Query set of descriptors.
    trainDescriptors

    Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
    matches

    Found matches. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.
    maxDistance

    Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)! descriptors.

    For each query descriptor, the methods find such training descriptors that the distance between the query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are returned in the distance increasing order.

  • Declaration

    Objective-C

    - (void)radiusMatch:(nonnull Mat *)queryDescriptors
            matches:
                (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
        maxDistance:(float)maxDistance
              masks:(nonnull NSArray<Mat *> *)masks
      compactResult:(BOOL)compactResult;

    Swift

    func radiusMatch(queryDescriptors: Mat, matches: NSMutableArray, maxDistance: Float, masks: [Mat], compactResult: Bool)

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Found matches.
    maxDistance

    Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)!
    masks

    Set of masks. Each masks[i] specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image trainDescCollection[i].
    compactResult

    Parameter used when the mask (or masks) is not empty. If compactResult is false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

  • Declaration

    Objective-C

    - (void)radiusMatch:(nonnull Mat *)queryDescriptors
            matches:
                (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
        maxDistance:(float)maxDistance
              masks:(nonnull NSArray<Mat *> *)masks;

    Swift

    func radiusMatch(queryDescriptors: Mat, matches: NSMutableArray, maxDistance: Float, masks: [Mat])

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Found matches.
    maxDistance

    Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)!
    masks

    Set of masks. Each masks[i] specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image trainDescCollection[i]. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

  • Declaration

    Objective-C

    - (void)radiusMatch:(nonnull Mat *)queryDescriptors
            matches:
                (nonnull NSMutableArray<NSMutableArray<DMatch *> *> *)matches
        maxDistance:(float)maxDistance;

    Swift

    func radiusMatch(queryDescriptors: Mat, matches: NSMutableArray, maxDistance: Float)

    Parameters

    queryDescriptors

    Query set of descriptors.
    matches

    Found matches.
    maxDistance

    Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)! descriptors and stored train descriptors from the i-th image trainDescCollection[i]. false, the matches vector has the same size as queryDescriptors rows. If compactResult is true, the matches vector does not contain matches for fully masked-out query descriptors.

  • Declaration

    Objective-C

    - (void)read:(NSString*)fileName NS_SWIFT_NAME(read(fileName:));

    Swift

    func read(fileName: String)

  • Trains a descriptor matcher

     Trains a descriptor matcher (for example, the flann index). In all methods to match, the method
 train() is run every time before matching. Some descriptor matchers (for example, BruteForceMatcher)
 have an empty implementation of this method. Other matchers really train their inner structures (for
 example, FlannBasedMatcher trains flann::Index ).

    Declaration

    Objective-C

    - (void)train;

    Swift

    func train()

  • Declaration

    Objective-C

    - (void)write:(NSString*)fileName NS_SWIFT_NAME(write(fileName:));

    Swift

    func write(fileName: String)