modules/features2d/doc/common_interfaces_of_generic_descriptor_matchers.rst

   1 Common Interfaces of Generic 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 cannot be represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors. It does not make any assumptions about descriptor representation.
   9 Every descriptor with the
  10 :ocv:class:`DescriptorExtractor` interface has a wrapper with the ``GenericDescriptorMatcher`` interface (see
  11 :ocv:class:`VectorDescriptorMatcher` ).
  12 There are descriptors such as the One-way descriptor and Ferns that have the ``GenericDescriptorMatcher`` interface implemented but do not support ``DescriptorExtractor``.
  13
  14 .. note::
  15
  16    * An example explaining keypoint description can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
  17    * An example on descriptor matching evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_matcher_evaluation.cpp
  18    * An example on one to many image matching can be found at opencv_source_code/samples/cpp/matching_to_many_images.cpp
  19
  20 GenericDescriptorMatcher
  21 ------------------------
  22 .. ocv:class:: GenericDescriptorMatcher
  23
  24 Abstract interface for extracting and matching a keypoint descriptor. There are also :ocv:class:`DescriptorExtractor` and :ocv:class:`DescriptorMatcher` for these purposes but their interfaces are intended for descriptors represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors. ``DescriptorMatcher`` and ``GenericDescriptorMatcher`` have two groups of match methods: for matching keypoints of an image with another image or with an image set. ::
  25
  26     class GenericDescriptorMatcher
  27     {
  28     public:
  29         GenericDescriptorMatcher();
  30         virtual ~GenericDescriptorMatcher();
  31
  32         virtual void add( InputArrayOfArrays images,
  33                           vector<vector<KeyPoint> >& keypoints );
  34
  35         const vector<Mat>& getTrainImages() const;
  36         const vector<vector<KeyPoint> >& getTrainKeypoints() const;
  37         virtual void clear();
  38
  39         virtual void train() = 0;
  40
  41         virtual bool isMaskSupported() = 0;
  42
  43         void classify( InputArray queryImage,
  44                        vector<KeyPoint>& queryKeypoints,
  45                        InputArray trainImage,
  46                        vector<KeyPoint>& trainKeypoints ) const;
  47         void classify( InputArray queryImage,
  48                        vector<KeyPoint>& queryKeypoints );
  49
  50         /*
  51          * Group of methods to match keypoints from an image pair.
  52          */
  53         void match( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
  54                     InputArray trainImage, vector<KeyPoint>& trainKeypoints,
  55                     vector<DMatch>& matches, const Mat& mask=Mat() ) const;
  56         void knnMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
  57                        InputArray trainImage, vector<KeyPoint>& trainKeypoints,
  58                        vector<vector<DMatch> >& matches, int k,
  59                        const Mat& mask=Mat(), bool compactResult=false ) const;
  60         void radiusMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
  61                           InputArray trainImage, vector<KeyPoint>& trainKeypoints,
  62                           vector<vector<DMatch> >& matches, float maxDistance,
  63                           const Mat& mask=Mat(), bool compactResult=false ) const;
  64         /*
  65          * Group of methods to match keypoints from one image to an image set.
  66          */
  67         void match( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
  68                     vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>() );
  69         void knnMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
  70                        vector<vector<DMatch> >& matches, int k,
  71                        const vector<Mat>& masks=vector<Mat>(), bool compactResult=false );
  72         void radiusMatch( InputArray queryImage, vector<KeyPoint>& queryKeypoints,
  73                           vector<vector<DMatch> >& matches, float maxDistance,
  74                           const vector<Mat>& masks=vector<Mat>(), bool compactResult=false );
  75
  76         virtual void read( const FileNode& );
  77         virtual void write( FileStorage& ) const;
  78
  79         virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
  80
  81     protected:
  82         ...
  83     };
  84
  85
  86
  87
  88 GenericDescriptorMatcher::add
  89 ---------------------------------
  90 Adds images and their keypoints to the training collection stored in the class instance.
  91
  92 .. ocv:function:: void GenericDescriptorMatcher::add( InputArrayOfArrays images,                        vector<vector<KeyPoint> >& keypoints )
  93
  94     :param images: Image collection.
  95
  96     :param keypoints: Point collection. It is assumed that ``keypoints[i]``  are keypoints detected in the image  ``images[i]`` .
  97
  98
  99
 100 GenericDescriptorMatcher::getTrainImages
 101 --------------------------------------------
 102 Returns a train image collection.
 103
 104 .. ocv:function:: const vector<Mat>& GenericDescriptorMatcher::getTrainImages() const
 105
 106
 107
 108 GenericDescriptorMatcher::getTrainKeypoints
 109 -----------------------------------------------
 110 Returns a train keypoints collection.
 111
 112 .. ocv:function:: const vector<vector<KeyPoint> >&  GenericDescriptorMatcher::getTrainKeypoints() const
 113
 114
 115
 116 GenericDescriptorMatcher::clear
 117 -----------------------------------
 118 Clears a train collection (images and keypoints).
 119
 120 .. ocv:function:: void GenericDescriptorMatcher::clear()
 121
 122
 123
 124 GenericDescriptorMatcher::train
 125 -----------------------------------
 126 Trains descriptor matcher
 127
 128 .. ocv:function:: void GenericDescriptorMatcher::train()
 129
 130 Prepares descriptor matcher, for example, creates a tree-based structure, to extract descriptors or to optimize descriptors matching.
 131
 132
 133 GenericDescriptorMatcher::isMaskSupported
 134 ---------------------------------------------
 135 Returns ``true`` if a generic descriptor matcher supports masking permissible matches.
 136
 137 .. ocv:function:: bool GenericDescriptorMatcher::isMaskSupported()
 138
 139
 140
 141 GenericDescriptorMatcher::classify
 142 --------------------------------------
 143 Classifies keypoints from a query set.
 144
 145 .. ocv:function:: void GenericDescriptorMatcher::classify(  InputArray queryImage,           vector<KeyPoint>& queryKeypoints,           InputArray trainImage,           vector<KeyPoint>& trainKeypoints ) const
 146
 147 .. ocv:function:: void GenericDescriptorMatcher::classify( InputArray queryImage,           vector<KeyPoint>& queryKeypoints )
 148
 149     :param queryImage: Query image.
 150
 151     :param queryKeypoints: Keypoints from a query image.
 152
 153     :param trainImage: Train image.
 154
 155     :param trainKeypoints: Keypoints from a train image.
 156
 157 The method classifies each keypoint from a query set. The first variant of the method takes a train image and its keypoints as an input argument. The second variant uses the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method.
 158
 159 The methods do the following:
 160
 161 #.
 162     Call the ``GenericDescriptorMatcher::match`` method to find correspondence between the query set and the training set.
 163
 164 #.
 165     Set the ``class_id`` field of each keypoint from the query set to ``class_id`` of the corresponding keypoint from the training set.
 166
 167
 168
 169 GenericDescriptorMatcher::match
 170 -----------------------------------
 171 Finds the best match in the training set for each keypoint from the query set.
 172
 173 .. ocv:function:: void GenericDescriptorMatcher::match(InputArray queryImage, vector<KeyPoint>& queryKeypoints, InputArray trainImage, vector<KeyPoint>& trainKeypoints, vector<DMatch>& matches, const Mat& mask=Mat() ) const
 174
 175 .. ocv:function:: void GenericDescriptorMatcher::match( InputArray queryImage, vector<KeyPoint>& queryKeypoints, vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>() )
 176
 177     :param queryImage: Query image.
 178
 179     :param queryKeypoints: Keypoints detected in  ``queryImage`` .
 180
 181     :param trainImage: Train image. It is not added to a train image collection  stored in the class object.
 182
 183     :param trainKeypoints: Keypoints detected in  ``trainImage`` . They are not added to a train points collection stored in the class object.
 184
 185     :param matches: Matches. If a query descriptor (keypoint) is masked out in  ``mask`` ,  match is added for this descriptor. So,  ``matches``  size may be smaller than the query keypoints count.
 186
 187     :param mask: Mask specifying permissible matches between an input query and train keypoints.
 188
 189     :param masks: Set of masks. Each  ``masks[i]``  specifies permissible matches between input query keypoints and stored train keypoints from the i-th image.
 190
 191 The methods find the best match for each query keypoint. In the first variant of the method, a train image and its keypoints are the input arguments. In the second variant, query keypoints are matched to the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method.     Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, ``queryKeypoints[i]`` can be matched with ``trainKeypoints[j]`` only if ``mask.at<uchar>(i,j)`` is non-zero.
 192
 193
 194
 195 GenericDescriptorMatcher::knnMatch
 196 --------------------------------------
 197 Finds the ``k`` best matches for each query keypoint.
 198
 199 .. ocv:function:: void GenericDescriptorMatcher::knnMatch(           InputArray queryImage, vector<KeyPoint>& queryKeypoints,      InputArray trainImage, vector<KeyPoint>& trainKeypoints,      vector<vector<DMatch> >& matches, int k,       const Mat& mask=Mat(), bool compactResult=false ) const
 200
 201 .. ocv:function:: void GenericDescriptorMatcher::knnMatch(           InputArray queryImage, vector<KeyPoint>& queryKeypoints,      vector<vector<DMatch> >& matches, int k,       const vector<Mat>& masks=vector<Mat>(),       bool compactResult=false )
 202
 203 The methods are extended variants of ``GenericDescriptorMatch::match``. The parameters are similar, and the semantics is similar to ``DescriptorMatcher::knnMatch``. But this class does not require explicitly computed keypoint descriptors.
 204
 205
 206
 207 GenericDescriptorMatcher::radiusMatch
 208 -----------------------------------------
 209 For each query keypoint, finds the training keypoints not farther than the specified distance.
 210
 211 .. ocv:function:: void GenericDescriptorMatcher::radiusMatch(           InputArray queryImage, vector<KeyPoint>& queryKeypoints,      InputArray trainImage, vector<KeyPoint>& trainKeypoints,      vector<vector<DMatch> >& matches, float maxDistance,       const Mat& mask=Mat(), bool compactResult=false ) const
 212
 213 .. ocv:function:: void GenericDescriptorMatcher::radiusMatch(           InputArray queryImage, vector<KeyPoint>& queryKeypoints,      vector<vector<DMatch> >& matches, float maxDistance,       const vector<Mat>& masks=vector<Mat>(),       bool compactResult=false )
 214
 215 The methods are similar to ``DescriptorMatcher::radius``. But this class does not require explicitly computed keypoint descriptors.
 216
 217
 218
 219 GenericDescriptorMatcher::read
 220 ----------------------------------
 221 Reads a matcher object from a file node.
 222
 223 .. ocv:function:: void GenericDescriptorMatcher::read( const FileNode& fn )
 224
 225
 226
 227 GenericDescriptorMatcher::write
 228 -----------------------------------
 229 Writes a match object to a file storage.
 230
 231 .. ocv:function:: void GenericDescriptorMatcher::write( FileStorage& fs ) const
 232
 233
 234 GenericDescriptorMatcher::clone
 235 -----------------------------------
 236 Clones the matcher.
 237
 238 .. ocv:function:: Ptr<GenericDescriptorMatcher> GenericDescriptorMatcher::clone( bool emptyTrainData=false ) const
 239
 240     :param emptyTrainData: If ``emptyTrainData`` is false, the method creates a deep copy of the object, that is, copies
 241             both parameters and train data. If ``emptyTrainData`` is true, the method creates an object copy with the current parameters
 242             but with empty train data.
 243
 244
 245 VectorDescriptorMatcher
 246 -----------------------
 247 .. ocv:class:: VectorDescriptorMatcher : public GenericDescriptorMatcher
 248
 249 Class used for matching descriptors that can be described as vectors in a finite-dimensional space. ::
 250
 251     class CV_EXPORTS VectorDescriptorMatcher : public GenericDescriptorMatcher
 252     {
 253     public:
 254         VectorDescriptorMatcher( const Ptr<DescriptorExtractor>& extractor, const Ptr<DescriptorMatcher>& matcher );
 255         virtual ~VectorDescriptorMatcher();
 256
 257         virtual void add( InputArrayOfArrays imgCollection,
 258                           vector<vector<KeyPoint> >& pointCollection );
 259         virtual void clear();
 260         virtual void train();
 261         virtual bool isMaskSupported();
 262
 263         virtual void read( const FileNode& fn );
 264         virtual void write( FileStorage& fs ) const;
 265
 266         virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
 267
 268     protected:
 269         ...
 270     };
 271
 272
 273 Example: ::
 274
 275     VectorDescriptorMatcher matcher( new SurfDescriptorExtractor,
 276                                      new BruteForceMatcher<L2<float> > );