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