modules/features2d/doc/common_interfaces_of_descriptor_matchers.rst

   1 Common Interfaces of Descriptor Matchers
   2 ========================================
   3
   4 .. highlight:: cpp
   5
   6 Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
   7 between different algorithms solving the same problem. This section is devoted to matching descriptors
   8 that are represented as vectors in a multidimensional space. All objects that implement ``vector``
   9 descriptor matchers inherit the
  10 :ocv:class:`DescriptorMatcher` interface.
  11
  12 .. note::
  13
  14    * An example explaining keypoint matching can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
  15    * An example on descriptor matching evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_matcher_evaluation.cpp
  16    * An example on one to many image matching can be found at opencv_source_code/samples/cpp/matching_to_many_images.cpp
  17
  18 DescriptorMatcher
  19 -----------------
  20 .. ocv:class:: DescriptorMatcher : public Algorithm
  21
  22 Abstract base class for matching keypoint descriptors. It has two groups
  23 of match methods: for matching descriptors of an image with another image or
  24 with an image set. ::
  25
  26     class DescriptorMatcher
  27     {
  28     public:
  29         virtual ~DescriptorMatcher();
  30
  31         virtual void add( InputArrayOfArrays descriptors );
  32
  33         const vector<Mat>& getTrainDescriptors() const;
  34         virtual void clear();
  35         bool empty() const;
  36         virtual bool isMaskSupported() const = 0;
  37
  38         virtual void train();
  39
  40         /*
  41          * Group of methods to match descriptors from an image pair.
  42          */
  43         void match( InputArray queryDescriptors, InputArray trainDescriptors,
  44                     vector<DMatch>& matches, InputArray mask=noArray() ) const;
  45         void knnMatch( InputArray queryDescriptors, InputArray trainDescriptors,
  46                        vector<vector<DMatch> >& matches, int k,
  47                        InputArray mask=noArray(), bool compactResult=false ) const;
  48         void radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors,
  49                           vector<vector<DMatch> >& matches, float maxDistance,
  50                           InputArray mask=noArray(), bool compactResult=false ) const;
  51         /*
  52          * Group of methods to match descriptors from one image to an image set.
  53          */
  54         void match( InputArray queryDescriptors, vector<DMatch>& matches,
  55                     InputArrayOfArrays masks=noArray() );
  56         void knnMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches,
  57                        int k, InputArrayOfArrays masks=noArray(),
  58                        bool compactResult=false );
  59         void radiusMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches,
  60                           float maxDistance, InputArrayOfArrays masks=noArray(),
  61                           bool compactResult=false );
  62
  63         virtual void read( const FileNode& );
  64         virtual void write( FileStorage& ) const;
  65
  66         virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
  67
  68         static Ptr<DescriptorMatcher> create( const String& descriptorMatcherType );
  69
  70     protected:
  71         vector<Mat> trainDescCollection;
  72         vector<UMat> utrainDescCollection;
  73         ...
  74     };
  75
  76
  77 DescriptorMatcher::add
  78 --------------------------
  79 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.
  80
  81 .. ocv:function:: void DescriptorMatcher::add( InputArrayOfArrays descriptors )
  82
  83     :param descriptors: Descriptors to add. Each  ``descriptors[i]``  is a set of descriptors from the same train image.
  84
  85
  86 DescriptorMatcher::getTrainDescriptors
  87 ------------------------------------------
  88 Returns a constant link to the train descriptor collection ``trainDescCollection`` .
  89
  90 .. ocv:function:: const vector<Mat>& DescriptorMatcher::getTrainDescriptors() const
  91
  92
  93
  94
  95
  96 DescriptorMatcher::clear
  97 ----------------------------
  98 Clears the train descriptor collections.
  99
 100 .. ocv:function:: void DescriptorMatcher::clear()
 101
 102
 103
 104 DescriptorMatcher::empty
 105 ----------------------------
 106 Returns true if there are no train descriptors in the both collections.
 107
 108 .. ocv:function:: bool DescriptorMatcher::empty() const
 109
 110
 111
 112 DescriptorMatcher::isMaskSupported
 113 --------------------------------------
 114 Returns true if the descriptor matcher supports masking permissible matches.
 115
 116 .. ocv:function:: bool DescriptorMatcher::isMaskSupported()
 117
 118
 119
 120 DescriptorMatcher::train
 121 ----------------------------
 122 Trains a descriptor matcher
 123
 124 .. ocv:function:: void DescriptorMatcher::train()
 125
 126 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`` ).
 127
 128
 129
 130 DescriptorMatcher::match
 131 ----------------------------
 132 Finds the best match for each descriptor from a query set.
 133
 134 .. ocv:function:: void DescriptorMatcher::match( InputArray queryDescriptors, InputArray trainDescriptors, vector<DMatch>& matches, InputArray mask=noArray() ) const
 135
 136 .. ocv:function:: void DescriptorMatcher::match(InputArray queryDescriptors, vector<DMatch>& matches, InputArrayOfArrays masks=noArray() )
 137
 138     :param queryDescriptors: Query set of descriptors.
 139
 140     :param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
 141
 142     :param 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.
 143
 144     :param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
 145
 146     :param 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]``.
 147
 148 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.
 149
 150
 151
 152 DescriptorMatcher::knnMatch
 153 -------------------------------
 154 Finds the k best matches for each descriptor from a query set.
 155
 156 .. ocv:function:: void DescriptorMatcher::knnMatch(InputArray queryDescriptors,   InputArray trainDescriptors,       vector<vector<DMatch> >& matches,       int k, InputArray mask=noArray(),       bool compactResult=false ) const
 157
 158 .. ocv:function:: void DescriptorMatcher::knnMatch( InputArray queryDescriptors,           vector<vector<DMatch> >& matches, int k,      InputArrayOfArrays masks=noArray(),       bool compactResult=false )
 159
 160     :param queryDescriptors: Query set of descriptors.
 161
 162     :param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
 163
 164     :param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
 165
 166     :param 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]``.
 167
 168     :param matches: Matches. Each  ``matches[i]``  is k or less matches for the same query descriptor.
 169
 170     :param k: Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
 171
 172     :param 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.
 173
 174 These extended variants of :ocv:func:`DescriptorMatcher::match` methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See :ocv:func:`DescriptorMatcher::match` for the details about query and train descriptors.
 175
 176
 177
 178 DescriptorMatcher::radiusMatch
 179 ----------------------------------
 180 For each query descriptor, finds the training descriptors not farther than the specified distance.
 181
 182 .. ocv:function:: void DescriptorMatcher::radiusMatch( InputArray queryDescriptors,           InputArray trainDescriptors,           vector<vector<DMatch> >& matches,           float maxDistance, InputArray mask=noArray(),           bool compactResult=false ) const
 183
 184 .. ocv:function:: void DescriptorMatcher::radiusMatch( InputArray queryDescriptors,           vector<vector<DMatch> >& matches,           float maxDistance,      InputArrayOfArrays masks=noArray(),       bool compactResult=false )
 185
 186     :param queryDescriptors: Query set of descriptors.
 187
 188     :param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
 189
 190     :param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
 191
 192     :param 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]``.
 193
 194     :param matches: Found matches.
 195
 196     :param 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.
 197
 198     :param 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)!
 199
 200 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.
 201
 202
 203
 204 DescriptorMatcher::clone
 205 ----------------------------
 206 Clones the matcher.
 207
 208 .. ocv:function:: Ptr<DescriptorMatcher> DescriptorMatcher::clone( bool emptyTrainData=false )
 209
 210     :param 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.
 211
 212
 213
 214 DescriptorMatcher::create
 215 -----------------------------
 216 Creates a descriptor matcher of a given type with the default parameters (using default constructor).
 217
 218 .. ocv:function:: Ptr<DescriptorMatcher> DescriptorMatcher::create( const String& descriptorMatcherType )
 219
 220     :param descriptorMatcherType: Descriptor matcher type. Now the following matcher types are supported:
 221
 222         *
 223             ``BruteForce`` (it uses ``L2`` )
 224         *
 225             ``BruteForce-L1``
 226         *
 227             ``BruteForce-Hamming``
 228         *
 229             ``BruteForce-Hamming(2)``
 230         *
 231             ``FlannBased``
 232
 233
 234
 235
 236
 237 BFMatcher
 238 -----------------
 239 .. ocv:class:: BFMatcher : public DescriptorMatcher
 240
 241 Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches of descriptor sets.
 242
 243
 244 BFMatcher::BFMatcher
 245 --------------------
 246 Brute-force matcher constructor.
 247
 248 .. ocv:function:: BFMatcher::BFMatcher( int normType=NORM_L2, bool crossCheck=false )
 249
 250     :param normType: One of ``NORM_L1``, ``NORM_L2``, ``NORM_HAMMING``, ``NORM_HAMMING2``. ``L1`` and ``L2`` norms are preferable choices for SIFT and SURF descriptors, ``NORM_HAMMING`` should be used with ORB, BRISK and BRIEF, ``NORM_HAMMING2`` should be used with ORB when ``WTA_K==3`` or ``4`` (see ORB::ORB constructor description).
 251
 252     :param crossCheck: If it is false, this is will be default BFMatcher behaviour when it finds the k nearest neighbors for each query descriptor. If ``crossCheck==true``, then the ``knnMatch()`` method with ``k=1`` will only return pairs ``(i,j)`` such that for ``i-th`` query descriptor the ``j-th`` descriptor in the matcher's collection is the nearest and vice versa, i.e. the ``BFMathcher`` will only return consistent pairs. Such technique usually produces best results with minimal number of outliers when there are enough matches. This is alternative to the ratio test, used by D. Lowe in SIFT paper.
 253
 254
 255 FlannBasedMatcher
 256 -----------------
 257 .. ocv:class:: FlannBasedMatcher : public DescriptorMatcher
 258
 259 Flann-based descriptor matcher. This matcher trains :ocv:class:`flann::Index_` on a train descriptor collection and calls its nearest search methods to find the best matches. So, this matcher may be faster when matching a large train collection than the brute force matcher. ``FlannBasedMatcher`` does not support masking permissible matches of descriptor sets because ``flann::Index`` does not support this. ::
 260
 261     class FlannBasedMatcher : public DescriptorMatcher
 262     {
 263     public:
 264         FlannBasedMatcher(
 265           const Ptr<flann::IndexParams>& indexParams=new flann::KDTreeIndexParams(),
 266           const Ptr<flann::SearchParams>& searchParams=new flann::SearchParams() );
 267
 268         virtual void add( InputArrayOfArrays descriptors );
 269         virtual void clear();
 270
 271         virtual void train();
 272         virtual bool isMaskSupported() const;
 273
 274         virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
 275     protected:
 276         ...
 277     };
 278
 279 ..