1 /*M///////////////////////////////////////////////////////////////////////////////////////
3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
5 // By downloading, copying, installing or using the software you agree to this license.
6 // If you do not agree to this license, do not download, install,
7 // copy or use the software.
11 // For Open Source Computer Vision Library
13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
15 // Third party copyrights are property of their respective owners.
17 // Redistribution and use in source and binary forms, with or without modification,
18 // are permitted provided that the following conditions are met:
20 // * Redistribution's of source code must retain the above copyright notice,
21 // this list of conditions and the following disclaimer.
23 // * Redistribution's in binary form must reproduce the above copyright notice,
24 // this list of conditions and the following disclaimer in the documentation
25 // and/or other materials provided with the distribution.
27 // * The name of the copyright holders may not be used to endorse or promote products
28 // derived from this software without specific prior written permission.
30 // This software is provided by the copyright holders and contributors "as is" and
31 // any express or implied warranties, including, but not limited to, the implied
32 // warranties of merchantability and fitness for a particular purpose are disclaimed.
33 // In no event shall the Intel Corporation or contributors be liable for any direct,
34 // indirect, incidental, special, exemplary, or consequential damages
35 // (including, but not limited to, procurement of substitute goods or services;
36 // loss of use, data, or profits; or business interruption) however caused
37 // and on any theory of liability, whether in contract, strict liability,
38 // or tort (including negligence or otherwise) arising in any way out of
39 // the use of this software, even if advised of the possibility of such damage.
43 #ifndef OPENCV_FEATURES_2D_HPP
44 #define OPENCV_FEATURES_2D_HPP
46 #include "opencv2/opencv_modules.hpp"
47 #include "opencv2/core.hpp"
49 #ifdef HAVE_OPENCV_FLANN
50 #include "opencv2/flann/miniflann.hpp"
54 @defgroup features2d 2D Features Framework
56 @defgroup features2d_main Feature Detection and Description
57 @defgroup features2d_match Descriptor Matchers
59 Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to
60 easily switch between different algorithms solving the same problem. This section is devoted to
61 matching descriptors that are represented as vectors in a multidimensional space. All objects that
62 implement vector descriptor matchers inherit the DescriptorMatcher interface.
64 @defgroup features2d_draw Drawing Function of Keypoints and Matches
65 @defgroup features2d_category Object Categorization
67 This section describes approaches based on local 2D features and used to categorize objects.
69 @defgroup feature2d_hal Hardware Acceleration Layer
71 @defgroup features2d_hal_interface Interface
79 //! @addtogroup features2d_main
82 // //! writes vector of keypoints to the file storage
83 // CV_EXPORTS void write(FileStorage& fs, const String& name, const std::vector<KeyPoint>& keypoints);
84 // //! reads vector of keypoints from the specified file storage node
85 // CV_EXPORTS void read(const FileNode& node, CV_OUT std::vector<KeyPoint>& keypoints);
87 /** @brief A class filters a vector of keypoints.
89 Because now it is difficult to provide a convenient interface for all usage scenarios of the
90 keypoints filter class, it has only several needed by now static methods.
92 class CV_EXPORTS KeyPointsFilter
98 * Remove keypoints within borderPixels of an image edge.
100 static void runByImageBorder( std::vector<KeyPoint>& keypoints, Size imageSize, int borderSize );
102 * Remove keypoints of sizes out of range.
104 static void runByKeypointSize( std::vector<KeyPoint>& keypoints, float minSize,
105 float maxSize=FLT_MAX );
107 * Remove keypoints from some image by mask for pixels of this image.
109 static void runByPixelsMask( std::vector<KeyPoint>& keypoints, const Mat& mask );
111 * Remove duplicated keypoints.
113 static void removeDuplicated( std::vector<KeyPoint>& keypoints );
115 * Remove duplicated keypoints and sort the remaining keypoints
117 static void removeDuplicatedSorted( std::vector<KeyPoint>& keypoints );
120 * Retain the specified number of the best keypoints (according to the response)
122 static void retainBest( std::vector<KeyPoint>& keypoints, int npoints );
126 /************************************ Base Classes ************************************/
128 /** @brief Abstract base class for 2D image feature detectors and descriptor extractors
130 #ifdef __EMSCRIPTEN__
131 class CV_EXPORTS_W Feature2D : public Algorithm
133 class CV_EXPORTS_W Feature2D : public virtual Algorithm
137 virtual ~Feature2D();
139 /** @brief Detects keypoints in an image (first variant) or image set (second variant).
142 @param keypoints The detected keypoints. In the second variant of the method keypoints[i] is a set
143 of keypoints detected in images[i] .
144 @param mask Mask specifying where to look for keypoints (optional). It must be a 8-bit integer
145 matrix with non-zero values in the region of interest.
147 CV_WRAP virtual void detect( InputArray image,
148 CV_OUT std::vector<KeyPoint>& keypoints,
149 InputArray mask=noArray() );
152 @param images Image set.
153 @param keypoints The detected keypoints. In the second variant of the method keypoints[i] is a set
154 of keypoints detected in images[i] .
155 @param masks Masks for each input image specifying where to look for keypoints (optional).
156 masks[i] is a mask for images[i].
158 CV_WRAP virtual void detect( InputArrayOfArrays images,
159 CV_OUT std::vector<std::vector<KeyPoint> >& keypoints,
160 InputArrayOfArrays masks=noArray() );
162 /** @brief Computes the descriptors for a set of keypoints detected in an image (first variant) or image set
166 @param keypoints Input collection of keypoints. Keypoints for which a descriptor cannot be
167 computed are removed. Sometimes new keypoints can be added, for example: SIFT duplicates keypoint
168 with several dominant orientations (for each orientation).
169 @param descriptors Computed descriptors. In the second variant of the method descriptors[i] are
170 descriptors computed for a keypoints[i]. Row j is the keypoints (or keypoints[i]) is the
171 descriptor for keypoint j-th keypoint.
173 CV_WRAP virtual void compute( InputArray image,
174 CV_OUT CV_IN_OUT std::vector<KeyPoint>& keypoints,
175 OutputArray descriptors );
179 @param images Image set.
180 @param keypoints Input collection of keypoints. Keypoints for which a descriptor cannot be
181 computed are removed. Sometimes new keypoints can be added, for example: SIFT duplicates keypoint
182 with several dominant orientations (for each orientation).
183 @param descriptors Computed descriptors. In the second variant of the method descriptors[i] are
184 descriptors computed for a keypoints[i]. Row j is the keypoints (or keypoints[i]) is the
185 descriptor for keypoint j-th keypoint.
187 CV_WRAP virtual void compute( InputArrayOfArrays images,
188 CV_OUT CV_IN_OUT std::vector<std::vector<KeyPoint> >& keypoints,
189 OutputArrayOfArrays descriptors );
191 /** Detects keypoints and computes the descriptors */
192 CV_WRAP virtual void detectAndCompute( InputArray image, InputArray mask,
193 CV_OUT std::vector<KeyPoint>& keypoints,
194 OutputArray descriptors,
195 bool useProvidedKeypoints=false );
197 CV_WRAP virtual int descriptorSize() const;
198 CV_WRAP virtual int descriptorType() const;
199 CV_WRAP virtual int defaultNorm() const;
201 CV_WRAP void write( const String& fileName ) const;
203 CV_WRAP void read( const String& fileName );
205 virtual void write( FileStorage&) const CV_OVERRIDE;
207 // see corresponding cv::Algorithm method
208 CV_WRAP virtual void read( const FileNode&) CV_OVERRIDE;
210 //! Return true if detector object is empty
211 CV_WRAP virtual bool empty() const CV_OVERRIDE;
212 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
214 // see corresponding cv::Algorithm method
215 CV_WRAP inline void write(FileStorage& fs, const String& name) const { Algorithm::write(fs, name); }
216 #if CV_VERSION_MAJOR < 5
217 inline void write(const Ptr<FileStorage>& fs, const String& name) const { CV_Assert(fs); Algorithm::write(*fs, name); }
221 /** Feature detectors in OpenCV have wrappers with a common interface that enables you to easily switch
222 between different algorithms solving the same problem. All objects that implement keypoint detectors
223 inherit the FeatureDetector interface. */
224 typedef Feature2D FeatureDetector;
226 /** Extractors of keypoint descriptors in OpenCV have wrappers with a common interface that enables you
227 to easily switch between different algorithms solving the same problem. This section is devoted to
228 computing descriptors represented as vectors in a multidimensional space. All objects that implement
229 the vector descriptor extractors inherit the DescriptorExtractor interface.
231 typedef Feature2D DescriptorExtractor;
234 /** @brief Class for implementing the wrapper which makes detectors and extractors to be affine invariant,
235 described as ASIFT in @cite YM11 .
237 class CV_EXPORTS_W AffineFeature : public Feature2D
241 @param backend The detector/extractor you want to use as backend.
242 @param maxTilt The highest power index of tilt factor. 5 is used in the paper as tilt sampling range n.
243 @param minTilt The lowest power index of tilt factor. 0 is used in the paper.
244 @param tiltStep Tilt sampling step \f$\delta_t\f$ in Algorithm 1 in the paper.
245 @param rotateStepBase Rotation sampling step factor b in Algorithm 1 in the paper.
247 CV_WRAP static Ptr<AffineFeature> create(const Ptr<Feature2D>& backend,
248 int maxTilt = 5, int minTilt = 0, float tiltStep = 1.4142135623730951f, float rotateStepBase = 72);
250 CV_WRAP virtual void setViewParams(const std::vector<float>& tilts, const std::vector<float>& rolls) = 0;
251 CV_WRAP virtual void getViewParams(std::vector<float>& tilts, std::vector<float>& rolls) const = 0;
252 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
255 typedef AffineFeature AffineFeatureDetector;
256 typedef AffineFeature AffineDescriptorExtractor;
259 /** @brief Class for extracting keypoints and computing descriptors using the Scale Invariant Feature Transform
260 (SIFT) algorithm by D. Lowe @cite Lowe04 .
262 class CV_EXPORTS_W SIFT : public Feature2D
266 @param nfeatures The number of best features to retain. The features are ranked by their scores
267 (measured in SIFT algorithm as the local contrast)
269 @param nOctaveLayers The number of layers in each octave. 3 is the value used in D. Lowe paper. The
270 number of octaves is computed automatically from the image resolution.
272 @param contrastThreshold The contrast threshold used to filter out weak features in semi-uniform
273 (low-contrast) regions. The larger the threshold, the less features are produced by the detector.
275 @note The contrast threshold will be divided by nOctaveLayers when the filtering is applied. When
276 nOctaveLayers is set to default and if you want to use the value used in D. Lowe paper, 0.03, set
277 this argument to 0.09.
279 @param edgeThreshold The threshold used to filter out edge-like features. Note that the its meaning
280 is different from the contrastThreshold, i.e. the larger the edgeThreshold, the less features are
281 filtered out (more features are retained).
283 @param sigma The sigma of the Gaussian applied to the input image at the octave \#0. If your image
284 is captured with a weak camera with soft lenses, you might want to reduce the number.
286 CV_WRAP static Ptr<SIFT> create(int nfeatures = 0, int nOctaveLayers = 3,
287 double contrastThreshold = 0.04, double edgeThreshold = 10,
290 /** @brief Create SIFT with specified descriptorType.
291 @param nfeatures The number of best features to retain. The features are ranked by their scores
292 (measured in SIFT algorithm as the local contrast)
294 @param nOctaveLayers The number of layers in each octave. 3 is the value used in D. Lowe paper. The
295 number of octaves is computed automatically from the image resolution.
297 @param contrastThreshold The contrast threshold used to filter out weak features in semi-uniform
298 (low-contrast) regions. The larger the threshold, the less features are produced by the detector.
300 @note The contrast threshold will be divided by nOctaveLayers when the filtering is applied. When
301 nOctaveLayers is set to default and if you want to use the value used in D. Lowe paper, 0.03, set
302 this argument to 0.09.
304 @param edgeThreshold The threshold used to filter out edge-like features. Note that the its meaning
305 is different from the contrastThreshold, i.e. the larger the edgeThreshold, the less features are
306 filtered out (more features are retained).
308 @param sigma The sigma of the Gaussian applied to the input image at the octave \#0. If your image
309 is captured with a weak camera with soft lenses, you might want to reduce the number.
311 @param descriptorType The type of descriptors. Only CV_32F and CV_8U are supported.
313 CV_WRAP static Ptr<SIFT> create(int nfeatures, int nOctaveLayers,
314 double contrastThreshold, double edgeThreshold,
315 double sigma, int descriptorType);
317 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
320 typedef SIFT SiftFeatureDetector;
321 typedef SIFT SiftDescriptorExtractor;
324 /** @brief Class implementing the BRISK keypoint detector and descriptor extractor, described in @cite LCS11 .
326 class CV_EXPORTS_W BRISK : public Feature2D
329 /** @brief The BRISK constructor
331 @param thresh AGAST detection threshold score.
332 @param octaves detection octaves. Use 0 to do single scale.
333 @param patternScale apply this scale to the pattern used for sampling the neighbourhood of a
336 CV_WRAP static Ptr<BRISK> create(int thresh=30, int octaves=3, float patternScale=1.0f);
338 /** @brief The BRISK constructor for a custom pattern
340 @param radiusList defines the radii (in pixels) where the samples around a keypoint are taken (for
342 @param numberList defines the number of sampling points on the sampling circle. Must be the same
344 @param dMax threshold for the short pairings used for descriptor formation (in pixels for keypoint
346 @param dMin threshold for the long pairings used for orientation determination (in pixels for
348 @param indexChange index remapping of the bits. */
349 CV_WRAP static Ptr<BRISK> create(const std::vector<float> &radiusList, const std::vector<int> &numberList,
350 float dMax=5.85f, float dMin=8.2f, const std::vector<int>& indexChange=std::vector<int>());
352 /** @brief The BRISK constructor for a custom pattern, detection threshold and octaves
354 @param thresh AGAST detection threshold score.
355 @param octaves detection octaves. Use 0 to do single scale.
356 @param radiusList defines the radii (in pixels) where the samples around a keypoint are taken (for
358 @param numberList defines the number of sampling points on the sampling circle. Must be the same
360 @param dMax threshold for the short pairings used for descriptor formation (in pixels for keypoint
362 @param dMin threshold for the long pairings used for orientation determination (in pixels for
364 @param indexChange index remapping of the bits. */
365 CV_WRAP static Ptr<BRISK> create(int thresh, int octaves, const std::vector<float> &radiusList,
366 const std::vector<int> &numberList, float dMax=5.85f, float dMin=8.2f,
367 const std::vector<int>& indexChange=std::vector<int>());
368 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
371 /** @brief Class implementing the ORB (*oriented BRIEF*) keypoint detector and descriptor extractor
373 described in @cite RRKB11 . The algorithm uses FAST in pyramids to detect stable keypoints, selects
374 the strongest features using FAST or Harris response, finds their orientation using first-order
375 moments and computes the descriptors using BRIEF (where the coordinates of random point pairs (or
376 k-tuples) are rotated according to the measured orientation).
378 class CV_EXPORTS_W ORB : public Feature2D
381 enum { kBytes = 32, HARRIS_SCORE=0, FAST_SCORE=1 };
383 /** @brief The ORB constructor
385 @param nfeatures The maximum number of features to retain.
386 @param scaleFactor Pyramid decimation ratio, greater than 1. scaleFactor==2 means the classical
387 pyramid, where each next level has 4x less pixels than the previous, but such a big scale factor
388 will degrade feature matching scores dramatically. On the other hand, too close to 1 scale factor
389 will mean that to cover certain scale range you will need more pyramid levels and so the speed
391 @param nlevels The number of pyramid levels. The smallest level will have linear size equal to
392 input_image_linear_size/pow(scaleFactor, nlevels - firstLevel).
393 @param edgeThreshold This is size of the border where the features are not detected. It should
394 roughly match the patchSize parameter.
395 @param firstLevel The level of pyramid to put source image to. Previous layers are filled
396 with upscaled source image.
397 @param WTA_K The number of points that produce each element of the oriented BRIEF descriptor. The
398 default value 2 means the BRIEF where we take a random point pair and compare their brightnesses,
399 so we get 0/1 response. Other possible values are 3 and 4. For example, 3 means that we take 3
400 random points (of course, those point coordinates are random, but they are generated from the
401 pre-defined seed, so each element of BRIEF descriptor is computed deterministically from the pixel
402 rectangle), find point of maximum brightness and output index of the winner (0, 1 or 2). Such
403 output will occupy 2 bits, and therefore it will need a special variant of Hamming distance,
404 denoted as NORM_HAMMING2 (2 bits per bin). When WTA_K=4, we take 4 random points to compute each
405 bin (that will also occupy 2 bits with possible values 0, 1, 2 or 3).
406 @param scoreType The default HARRIS_SCORE means that Harris algorithm is used to rank features
407 (the score is written to KeyPoint::score and is used to retain best nfeatures features);
408 FAST_SCORE is alternative value of the parameter that produces slightly less stable keypoints,
409 but it is a little faster to compute.
410 @param patchSize size of the patch used by the oriented BRIEF descriptor. Of course, on smaller
411 pyramid layers the perceived image area covered by a feature will be larger.
412 @param fastThreshold the fast threshold
414 CV_WRAP static Ptr<ORB> create(int nfeatures=500, float scaleFactor=1.2f, int nlevels=8, int edgeThreshold=31,
415 int firstLevel=0, int WTA_K=2, int scoreType=ORB::HARRIS_SCORE, int patchSize=31, int fastThreshold=20);
417 CV_WRAP virtual void setMaxFeatures(int maxFeatures) = 0;
418 CV_WRAP virtual int getMaxFeatures() const = 0;
420 CV_WRAP virtual void setScaleFactor(double scaleFactor) = 0;
421 CV_WRAP virtual double getScaleFactor() const = 0;
423 CV_WRAP virtual void setNLevels(int nlevels) = 0;
424 CV_WRAP virtual int getNLevels() const = 0;
426 CV_WRAP virtual void setEdgeThreshold(int edgeThreshold) = 0;
427 CV_WRAP virtual int getEdgeThreshold() const = 0;
429 CV_WRAP virtual void setFirstLevel(int firstLevel) = 0;
430 CV_WRAP virtual int getFirstLevel() const = 0;
432 CV_WRAP virtual void setWTA_K(int wta_k) = 0;
433 CV_WRAP virtual int getWTA_K() const = 0;
435 CV_WRAP virtual void setScoreType(int scoreType) = 0;
436 CV_WRAP virtual int getScoreType() const = 0;
438 CV_WRAP virtual void setPatchSize(int patchSize) = 0;
439 CV_WRAP virtual int getPatchSize() const = 0;
441 CV_WRAP virtual void setFastThreshold(int fastThreshold) = 0;
442 CV_WRAP virtual int getFastThreshold() const = 0;
443 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
446 /** @brief Maximally stable extremal region extractor
448 The class encapsulates all the parameters of the %MSER extraction algorithm (see [wiki
449 article](http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions)).
451 - there are two different implementation of %MSER: one for grey image, one for color image
453 - the grey image algorithm is taken from: @cite nister2008linear ; the paper claims to be faster
454 than union-find method; it actually get 1.5~2m/s on my centrino L7200 1.2GHz laptop.
456 - the color image algorithm is taken from: @cite forssen2007maximally ; it should be much slower
457 than grey image method ( 3~4 times )
459 - (Python) A complete example showing the use of the %MSER detector can be found at samples/python/mser.py
461 class CV_EXPORTS_W MSER : public Feature2D
464 /** @brief Full constructor for %MSER detector
466 @param delta it compares \f$(size_{i}-size_{i-delta})/size_{i-delta}\f$
467 @param min_area prune the area which smaller than minArea
468 @param max_area prune the area which bigger than maxArea
469 @param max_variation prune the area have similar size to its children
470 @param min_diversity for color image, trace back to cut off mser with diversity less than min_diversity
471 @param max_evolution for color image, the evolution steps
472 @param area_threshold for color image, the area threshold to cause re-initialize
473 @param min_margin for color image, ignore too small margin
474 @param edge_blur_size for color image, the aperture size for edge blur
476 CV_WRAP static Ptr<MSER> create( int delta=5, int min_area=60, int max_area=14400,
477 double max_variation=0.25, double min_diversity=.2,
478 int max_evolution=200, double area_threshold=1.01,
479 double min_margin=0.003, int edge_blur_size=5 );
481 /** @brief Detect %MSER regions
483 @param image input image (8UC1, 8UC3 or 8UC4, must be greater or equal than 3x3)
484 @param msers resulting list of point sets
485 @param bboxes resulting bounding boxes
487 CV_WRAP virtual void detectRegions( InputArray image,
488 CV_OUT std::vector<std::vector<Point> >& msers,
489 CV_OUT std::vector<Rect>& bboxes ) = 0;
491 CV_WRAP virtual void setDelta(int delta) = 0;
492 CV_WRAP virtual int getDelta() const = 0;
494 CV_WRAP virtual void setMinArea(int minArea) = 0;
495 CV_WRAP virtual int getMinArea() const = 0;
497 CV_WRAP virtual void setMaxArea(int maxArea) = 0;
498 CV_WRAP virtual int getMaxArea() const = 0;
500 CV_WRAP virtual void setPass2Only(bool f) = 0;
501 CV_WRAP virtual bool getPass2Only() const = 0;
502 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
506 CV_EXPORTS void FAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
507 int threshold, bool nonmaxSuppression=true );
509 /** @brief Detects corners using the FAST algorithm
511 @param image grayscale image where keypoints (corners) are detected.
512 @param keypoints keypoints detected on the image.
513 @param threshold threshold on difference between intensity of the central pixel and pixels of a
514 circle around this pixel.
515 @param nonmaxSuppression if true, non-maximum suppression is applied to detected corners
517 @param type one of the three neighborhoods as defined in the paper:
518 FastFeatureDetector::TYPE_9_16, FastFeatureDetector::TYPE_7_12,
519 FastFeatureDetector::TYPE_5_8
521 Detects corners using the FAST algorithm by @cite Rosten06 .
523 @note In Python API, types are given as cv2.FAST_FEATURE_DETECTOR_TYPE_5_8,
524 cv2.FAST_FEATURE_DETECTOR_TYPE_7_12 and cv2.FAST_FEATURE_DETECTOR_TYPE_9_16. For corner
525 detection, use cv2.FAST.detect() method.
527 CV_EXPORTS void FAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
528 int threshold, bool nonmaxSuppression, int type );
530 //! @} features2d_main
532 //! @addtogroup features2d_main
535 /** @brief Wrapping class for feature detection using the FAST method. :
537 class CV_EXPORTS_W FastFeatureDetector : public Feature2D
542 TYPE_5_8 = 0, TYPE_7_12 = 1, TYPE_9_16 = 2,
543 THRESHOLD = 10000, NONMAX_SUPPRESSION=10001, FAST_N=10002,
546 CV_WRAP static Ptr<FastFeatureDetector> create( int threshold=10,
547 bool nonmaxSuppression=true,
548 int type=FastFeatureDetector::TYPE_9_16 );
550 CV_WRAP virtual void setThreshold(int threshold) = 0;
551 CV_WRAP virtual int getThreshold() const = 0;
553 CV_WRAP virtual void setNonmaxSuppression(bool f) = 0;
554 CV_WRAP virtual bool getNonmaxSuppression() const = 0;
556 CV_WRAP virtual void setType(int type) = 0;
557 CV_WRAP virtual int getType() const = 0;
558 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
562 CV_EXPORTS void AGAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
563 int threshold, bool nonmaxSuppression=true );
565 /** @brief Detects corners using the AGAST algorithm
567 @param image grayscale image where keypoints (corners) are detected.
568 @param keypoints keypoints detected on the image.
569 @param threshold threshold on difference between intensity of the central pixel and pixels of a
570 circle around this pixel.
571 @param nonmaxSuppression if true, non-maximum suppression is applied to detected corners
573 @param type one of the four neighborhoods as defined in the paper:
574 AgastFeatureDetector::AGAST_5_8, AgastFeatureDetector::AGAST_7_12d,
575 AgastFeatureDetector::AGAST_7_12s, AgastFeatureDetector::OAST_9_16
577 For non-Intel platforms, there is a tree optimised variant of AGAST with same numerical results.
578 The 32-bit binary tree tables were generated automatically from original code using perl script.
579 The perl script and examples of tree generation are placed in features2d/doc folder.
580 Detects corners using the AGAST algorithm by @cite mair2010_agast .
583 CV_EXPORTS void AGAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
584 int threshold, bool nonmaxSuppression, int type );
585 //! @} features2d_main
587 //! @addtogroup features2d_main
590 /** @brief Wrapping class for feature detection using the AGAST method. :
592 class CV_EXPORTS_W AgastFeatureDetector : public Feature2D
597 AGAST_5_8 = 0, AGAST_7_12d = 1, AGAST_7_12s = 2, OAST_9_16 = 3,
598 THRESHOLD = 10000, NONMAX_SUPPRESSION = 10001,
601 CV_WRAP static Ptr<AgastFeatureDetector> create( int threshold=10,
602 bool nonmaxSuppression=true,
603 int type=AgastFeatureDetector::OAST_9_16 );
605 CV_WRAP virtual void setThreshold(int threshold) = 0;
606 CV_WRAP virtual int getThreshold() const = 0;
608 CV_WRAP virtual void setNonmaxSuppression(bool f) = 0;
609 CV_WRAP virtual bool getNonmaxSuppression() const = 0;
611 CV_WRAP virtual void setType(int type) = 0;
612 CV_WRAP virtual int getType() const = 0;
613 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
616 /** @brief Wrapping class for feature detection using the goodFeaturesToTrack function. :
618 class CV_EXPORTS_W GFTTDetector : public Feature2D
621 CV_WRAP static Ptr<GFTTDetector> create( int maxCorners=1000, double qualityLevel=0.01, double minDistance=1,
622 int blockSize=3, bool useHarrisDetector=false, double k=0.04 );
623 CV_WRAP static Ptr<GFTTDetector> create( int maxCorners, double qualityLevel, double minDistance,
624 int blockSize, int gradiantSize, bool useHarrisDetector=false, double k=0.04 );
625 CV_WRAP virtual void setMaxFeatures(int maxFeatures) = 0;
626 CV_WRAP virtual int getMaxFeatures() const = 0;
628 CV_WRAP virtual void setQualityLevel(double qlevel) = 0;
629 CV_WRAP virtual double getQualityLevel() const = 0;
631 CV_WRAP virtual void setMinDistance(double minDistance) = 0;
632 CV_WRAP virtual double getMinDistance() const = 0;
634 CV_WRAP virtual void setBlockSize(int blockSize) = 0;
635 CV_WRAP virtual int getBlockSize() const = 0;
637 CV_WRAP virtual void setHarrisDetector(bool val) = 0;
638 CV_WRAP virtual bool getHarrisDetector() const = 0;
640 CV_WRAP virtual void setK(double k) = 0;
641 CV_WRAP virtual double getK() const = 0;
642 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
645 /** @brief Class for extracting blobs from an image. :
647 The class implements a simple algorithm for extracting blobs from an image:
649 1. Convert the source image to binary images by applying thresholding with several thresholds from
650 minThreshold (inclusive) to maxThreshold (exclusive) with distance thresholdStep between
651 neighboring thresholds.
652 2. Extract connected components from every binary image by findContours and calculate their
654 3. Group centers from several binary images by their coordinates. Close centers form one group that
655 corresponds to one blob, which is controlled by the minDistBetweenBlobs parameter.
656 4. From the groups, estimate final centers of blobs and their radiuses and return as locations and
659 This class performs several filtrations of returned blobs. You should set filterBy\* to true/false
660 to turn on/off corresponding filtration. Available filtrations:
662 - **By color**. This filter compares the intensity of a binary image at the center of a blob to
663 blobColor. If they differ, the blob is filtered out. Use blobColor = 0 to extract dark blobs
664 and blobColor = 255 to extract light blobs.
665 - **By area**. Extracted blobs have an area between minArea (inclusive) and maxArea (exclusive).
666 - **By circularity**. Extracted blobs have circularity
667 (\f$\frac{4*\pi*Area}{perimeter * perimeter}\f$) between minCircularity (inclusive) and
668 maxCircularity (exclusive).
669 - **By ratio of the minimum inertia to maximum inertia**. Extracted blobs have this ratio
670 between minInertiaRatio (inclusive) and maxInertiaRatio (exclusive).
671 - **By convexity**. Extracted blobs have convexity (area / area of blob convex hull) between
672 minConvexity (inclusive) and maxConvexity (exclusive).
674 Default values of parameters are tuned to extract dark circular blobs.
676 class CV_EXPORTS_W SimpleBlobDetector : public Feature2D
679 struct CV_EXPORTS_W_SIMPLE Params
682 CV_PROP_RW float thresholdStep;
683 CV_PROP_RW float minThreshold;
684 CV_PROP_RW float maxThreshold;
685 CV_PROP_RW size_t minRepeatability;
686 CV_PROP_RW float minDistBetweenBlobs;
688 CV_PROP_RW bool filterByColor;
689 CV_PROP_RW uchar blobColor;
691 CV_PROP_RW bool filterByArea;
692 CV_PROP_RW float minArea, maxArea;
694 CV_PROP_RW bool filterByCircularity;
695 CV_PROP_RW float minCircularity, maxCircularity;
697 CV_PROP_RW bool filterByInertia;
698 CV_PROP_RW float minInertiaRatio, maxInertiaRatio;
700 CV_PROP_RW bool filterByConvexity;
701 CV_PROP_RW float minConvexity, maxConvexity;
703 void read( const FileNode& fn );
704 void write( FileStorage& fs ) const;
707 CV_WRAP static Ptr<SimpleBlobDetector>
708 create(const SimpleBlobDetector::Params ¶meters = SimpleBlobDetector::Params());
709 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
712 //! @} features2d_main
714 //! @addtogroup features2d_main
717 /** @brief Class implementing the KAZE keypoint detector and descriptor extractor, described in @cite ABD12 .
719 @note AKAZE descriptor can only be used with KAZE or AKAZE keypoints .. [ABD12] KAZE Features. Pablo
720 F. Alcantarilla, Adrien Bartoli and Andrew J. Davison. In European Conference on Computer Vision
721 (ECCV), Fiorenze, Italy, October 2012.
723 class CV_EXPORTS_W KAZE : public Feature2D
734 /** @brief The KAZE constructor
736 @param extended Set to enable extraction of extended (128-byte) descriptor.
737 @param upright Set to enable use of upright descriptors (non rotation-invariant).
738 @param threshold Detector response threshold to accept point
739 @param nOctaves Maximum octave evolution of the image
740 @param nOctaveLayers Default number of sublevels per scale level
741 @param diffusivity Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or
744 CV_WRAP static Ptr<KAZE> create(bool extended=false, bool upright=false,
745 float threshold = 0.001f,
746 int nOctaves = 4, int nOctaveLayers = 4,
747 int diffusivity = KAZE::DIFF_PM_G2);
749 CV_WRAP virtual void setExtended(bool extended) = 0;
750 CV_WRAP virtual bool getExtended() const = 0;
752 CV_WRAP virtual void setUpright(bool upright) = 0;
753 CV_WRAP virtual bool getUpright() const = 0;
755 CV_WRAP virtual void setThreshold(double threshold) = 0;
756 CV_WRAP virtual double getThreshold() const = 0;
758 CV_WRAP virtual void setNOctaves(int octaves) = 0;
759 CV_WRAP virtual int getNOctaves() const = 0;
761 CV_WRAP virtual void setNOctaveLayers(int octaveLayers) = 0;
762 CV_WRAP virtual int getNOctaveLayers() const = 0;
764 CV_WRAP virtual void setDiffusivity(int diff) = 0;
765 CV_WRAP virtual int getDiffusivity() const = 0;
766 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
769 /** @brief Class implementing the AKAZE keypoint detector and descriptor extractor, described in @cite ANB13.
771 @details AKAZE descriptors can only be used with KAZE or AKAZE keypoints. This class is thread-safe.
773 @note When you need descriptors use Feature2D::detectAndCompute, which
774 provides better performance. When using Feature2D::detect followed by
775 Feature2D::compute scale space pyramid is computed twice.
777 @note AKAZE implements T-API. When image is passed as UMat some parts of the algorithm
780 @note [ANB13] Fast Explicit Diffusion for Accelerated Features in Nonlinear
781 Scale Spaces. Pablo F. Alcantarilla, Jesús Nuevo and Adrien Bartoli. In
782 British Machine Vision Conference (BMVC), Bristol, UK, September 2013.
785 class CV_EXPORTS_W AKAZE : public Feature2D
788 // AKAZE descriptor type
791 DESCRIPTOR_KAZE_UPRIGHT = 2, ///< Upright descriptors, not invariant to rotation
793 DESCRIPTOR_MLDB_UPRIGHT = 4, ///< Upright descriptors, not invariant to rotation
797 /** @brief The AKAZE constructor
799 @param descriptor_type Type of the extracted descriptor: DESCRIPTOR_KAZE,
800 DESCRIPTOR_KAZE_UPRIGHT, DESCRIPTOR_MLDB or DESCRIPTOR_MLDB_UPRIGHT.
801 @param descriptor_size Size of the descriptor in bits. 0 -\> Full size
802 @param descriptor_channels Number of channels in the descriptor (1, 2, 3)
803 @param threshold Detector response threshold to accept point
804 @param nOctaves Maximum octave evolution of the image
805 @param nOctaveLayers Default number of sublevels per scale level
806 @param diffusivity Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or
809 CV_WRAP static Ptr<AKAZE> create(int descriptor_type=AKAZE::DESCRIPTOR_MLDB,
810 int descriptor_size = 0, int descriptor_channels = 3,
811 float threshold = 0.001f, int nOctaves = 4,
812 int nOctaveLayers = 4, int diffusivity = KAZE::DIFF_PM_G2);
814 CV_WRAP virtual void setDescriptorType(int dtype) = 0;
815 CV_WRAP virtual int getDescriptorType() const = 0;
817 CV_WRAP virtual void setDescriptorSize(int dsize) = 0;
818 CV_WRAP virtual int getDescriptorSize() const = 0;
820 CV_WRAP virtual void setDescriptorChannels(int dch) = 0;
821 CV_WRAP virtual int getDescriptorChannels() const = 0;
823 CV_WRAP virtual void setThreshold(double threshold) = 0;
824 CV_WRAP virtual double getThreshold() const = 0;
826 CV_WRAP virtual void setNOctaves(int octaves) = 0;
827 CV_WRAP virtual int getNOctaves() const = 0;
829 CV_WRAP virtual void setNOctaveLayers(int octaveLayers) = 0;
830 CV_WRAP virtual int getNOctaveLayers() const = 0;
832 CV_WRAP virtual void setDiffusivity(int diff) = 0;
833 CV_WRAP virtual int getDiffusivity() const = 0;
834 CV_WRAP virtual String getDefaultName() const CV_OVERRIDE;
837 //! @} features2d_main
839 /****************************************************************************************\
841 \****************************************************************************************/
844 struct CV_EXPORTS Accumulator
849 template<> struct Accumulator<unsigned char> { typedef float Type; };
850 template<> struct Accumulator<unsigned short> { typedef float Type; };
851 template<> struct Accumulator<char> { typedef float Type; };
852 template<> struct Accumulator<short> { typedef float Type; };
855 * Squared Euclidean distance functor
858 struct CV_EXPORTS SL2
860 enum { normType = NORM_L2SQR };
862 typedef typename Accumulator<T>::Type ResultType;
864 ResultType operator()( const T* a, const T* b, int size ) const
866 return normL2Sqr<ValueType, ResultType>(a, b, size);
871 * Euclidean distance functor
876 enum { normType = NORM_L2 };
878 typedef typename Accumulator<T>::Type ResultType;
880 ResultType operator()( const T* a, const T* b, int size ) const
882 return (ResultType)std::sqrt((double)normL2Sqr<ValueType, ResultType>(a, b, size));
887 * Manhattan distance (city block distance) functor
892 enum { normType = NORM_L1 };
894 typedef typename Accumulator<T>::Type ResultType;
896 ResultType operator()( const T* a, const T* b, int size ) const
898 return normL1<ValueType, ResultType>(a, b, size);
902 /****************************************************************************************\
903 * DescriptorMatcher *
904 \****************************************************************************************/
906 //! @addtogroup features2d_match
909 /** @brief Abstract base class for matching keypoint descriptors.
911 It has two groups of match methods: for matching descriptors of an image with another image or with
914 class CV_EXPORTS_W DescriptorMatcher : public Algorithm
922 BRUTEFORCE_HAMMING = 4,
923 BRUTEFORCE_HAMMINGLUT = 5,
926 virtual ~DescriptorMatcher();
928 /** @brief Adds descriptors to train a CPU(trainDescCollectionis) or GPU(utrainDescCollectionis) descriptor
931 If the collection is not empty, the new descriptors are added to existing train descriptors.
933 @param descriptors Descriptors to add. Each descriptors[i] is a set of descriptors from the same
936 CV_WRAP virtual void add( InputArrayOfArrays descriptors );
938 /** @brief Returns a constant link to the train descriptor collection trainDescCollection .
940 CV_WRAP const std::vector<Mat>& getTrainDescriptors() const;
942 /** @brief Clears the train descriptor collections.
944 CV_WRAP virtual void clear() CV_OVERRIDE;
946 /** @brief Returns true if there are no train descriptors in the both collections.
948 CV_WRAP virtual bool empty() const CV_OVERRIDE;
950 /** @brief Returns true if the descriptor matcher supports masking permissible matches.
952 CV_WRAP virtual bool isMaskSupported() const = 0;
954 /** @brief Trains a descriptor matcher
956 Trains a descriptor matcher (for example, the flann index). In all methods to match, the method
957 train() is run every time before matching. Some descriptor matchers (for example, BruteForceMatcher)
958 have an empty implementation of this method. Other matchers really train their inner structures (for
959 example, FlannBasedMatcher trains flann::Index ).
961 CV_WRAP virtual void train();
963 /** @brief Finds the best match for each descriptor from a query set.
965 @param queryDescriptors Query set of descriptors.
966 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors
967 collection stored in the class object.
968 @param matches Matches. If a query descriptor is masked out in mask , no match is added for this
969 descriptor. So, matches size may be smaller than the query descriptors count.
970 @param mask Mask specifying permissible matches between an input query and train matrices of
973 In the first variant of this method, the train descriptors are passed as an input argument. In the
974 second variant of the method, train descriptors collection that was set by DescriptorMatcher::add is
975 used. Optional mask (or masks) can be passed to specify which query and training descriptors can be
976 matched. Namely, queryDescriptors[i] can be matched with trainDescriptors[j] only if
977 mask.at\<uchar\>(i,j) is non-zero.
979 CV_WRAP void match( InputArray queryDescriptors, InputArray trainDescriptors,
980 CV_OUT std::vector<DMatch>& matches, InputArray mask=noArray() ) const;
982 /** @brief Finds the k best matches for each descriptor from a query set.
984 @param queryDescriptors Query set of descriptors.
985 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors
986 collection stored in the class object.
987 @param mask Mask specifying permissible matches between an input query and train matrices of
989 @param matches Matches. Each matches[i] is k or less matches for the same query descriptor.
990 @param k Count of best matches found per each query descriptor or less if a query descriptor has
991 less than k possible matches in total.
992 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
993 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
994 the matches vector does not contain matches for fully masked-out query descriptors.
996 These extended variants of DescriptorMatcher::match methods find several best matches for each query
997 descriptor. The matches are returned in the distance increasing order. See DescriptorMatcher::match
998 for the details about query and train descriptors.
1000 CV_WRAP void knnMatch( InputArray queryDescriptors, InputArray trainDescriptors,
1001 CV_OUT std::vector<std::vector<DMatch> >& matches, int k,
1002 InputArray mask=noArray(), bool compactResult=false ) const;
1004 /** @brief For each query descriptor, finds the training descriptors not farther than the specified distance.
1006 @param queryDescriptors Query set of descriptors.
1007 @param trainDescriptors Train set of descriptors. This set is not added to the train descriptors
1008 collection stored in the class object.
1009 @param matches Found matches.
1010 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
1011 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
1012 the matches vector does not contain matches for fully masked-out query descriptors.
1013 @param maxDistance Threshold for the distance between matched descriptors. Distance means here
1014 metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured
1016 @param mask Mask specifying permissible matches between an input query and train matrices of
1019 For each query descriptor, the methods find such training descriptors that the distance between the
1020 query descriptor and the training descriptor is equal or smaller than maxDistance. Found matches are
1021 returned in the distance increasing order.
1023 CV_WRAP void radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors,
1024 CV_OUT std::vector<std::vector<DMatch> >& matches, float maxDistance,
1025 InputArray mask=noArray(), bool compactResult=false ) const;
1028 @param queryDescriptors Query set of descriptors.
1029 @param matches Matches. If a query descriptor is masked out in mask , no match is added for this
1030 descriptor. So, matches size may be smaller than the query descriptors count.
1031 @param masks Set of masks. Each masks[i] specifies permissible matches between the input query
1032 descriptors and stored train descriptors from the i-th image trainDescCollection[i].
1034 CV_WRAP void match( InputArray queryDescriptors, CV_OUT std::vector<DMatch>& matches,
1035 InputArrayOfArrays masks=noArray() );
1037 @param queryDescriptors Query set of descriptors.
1038 @param matches Matches. Each matches[i] is k or less matches for the same query descriptor.
1039 @param k Count of best matches found per each query descriptor or less if a query descriptor has
1040 less than k possible matches in total.
1041 @param masks Set of masks. Each masks[i] specifies permissible matches between the input query
1042 descriptors and stored train descriptors from the i-th image trainDescCollection[i].
1043 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
1044 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
1045 the matches vector does not contain matches for fully masked-out query descriptors.
1047 CV_WRAP void knnMatch( InputArray queryDescriptors, CV_OUT std::vector<std::vector<DMatch> >& matches, int k,
1048 InputArrayOfArrays masks=noArray(), bool compactResult=false );
1050 @param queryDescriptors Query set of descriptors.
1051 @param matches Found matches.
1052 @param maxDistance Threshold for the distance between matched descriptors. Distance means here
1053 metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured
1055 @param masks Set of masks. Each masks[i] specifies permissible matches between the input query
1056 descriptors and stored train descriptors from the i-th image trainDescCollection[i].
1057 @param compactResult Parameter used when the mask (or masks) is not empty. If compactResult is
1058 false, the matches vector has the same size as queryDescriptors rows. If compactResult is true,
1059 the matches vector does not contain matches for fully masked-out query descriptors.
1061 CV_WRAP void radiusMatch( InputArray queryDescriptors, CV_OUT std::vector<std::vector<DMatch> >& matches, float maxDistance,
1062 InputArrayOfArrays masks=noArray(), bool compactResult=false );
1065 CV_WRAP void write( const String& fileName ) const
1067 FileStorage fs(fileName, FileStorage::WRITE);
1071 CV_WRAP void read( const String& fileName )
1073 FileStorage fs(fileName, FileStorage::READ);
1076 // Reads matcher object from a file node
1077 // see corresponding cv::Algorithm method
1078 CV_WRAP virtual void read( const FileNode& ) CV_OVERRIDE;
1079 // Writes matcher object to a file storage
1080 virtual void write( FileStorage& ) const CV_OVERRIDE;
1082 /** @brief Clones the matcher.
1084 @param emptyTrainData If emptyTrainData is false, the method creates a deep copy of the object,
1085 that is, copies both parameters and train data. If emptyTrainData is true, the method creates an
1086 object copy with the current parameters but with empty train data.
1088 CV_WRAP CV_NODISCARD_STD virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
1090 /** @brief Creates a descriptor matcher of a given type with the default parameters (using default
1093 @param descriptorMatcherType Descriptor matcher type. Now the following matcher types are
1095 - `BruteForce` (it uses L2 )
1097 - `BruteForce-Hamming`
1098 - `BruteForce-Hamming(2)`
1101 CV_WRAP static Ptr<DescriptorMatcher> create( const String& descriptorMatcherType );
1103 CV_WRAP static Ptr<DescriptorMatcher> create( int matcherType );
1106 // see corresponding cv::Algorithm method
1107 CV_WRAP inline void write(FileStorage& fs, const String& name) const { Algorithm::write(fs, name); }
1108 #if CV_VERSION_MAJOR < 5
1109 inline void write(const Ptr<FileStorage>& fs, const String& name) const { CV_Assert(fs); Algorithm::write(*fs, name); }
1114 * Class to work with descriptors from several images as with one merged matrix.
1115 * It is used e.g. in FlannBasedMatcher.
1117 class CV_EXPORTS DescriptorCollection
1120 DescriptorCollection();
1121 DescriptorCollection( const DescriptorCollection& collection );
1122 virtual ~DescriptorCollection();
1124 // Vector of matrices "descriptors" will be merged to one matrix "mergedDescriptors" here.
1125 void set( const std::vector<Mat>& descriptors );
1126 virtual void clear();
1128 const Mat& getDescriptors() const;
1129 const Mat getDescriptor( int imgIdx, int localDescIdx ) const;
1130 const Mat getDescriptor( int globalDescIdx ) const;
1131 void getLocalIdx( int globalDescIdx, int& imgIdx, int& localDescIdx ) const;
1136 Mat mergedDescriptors;
1137 std::vector<int> startIdxs;
1140 //! In fact the matching is implemented only by the following two methods. These methods suppose
1141 //! that the class object has been trained already. Public match methods call these methods
1142 //! after calling train().
1143 virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
1144 InputArrayOfArrays masks=noArray(), bool compactResult=false ) = 0;
1145 virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1146 InputArrayOfArrays masks=noArray(), bool compactResult=false ) = 0;
1148 static bool isPossibleMatch( InputArray mask, int queryIdx, int trainIdx );
1149 static bool isMaskedOut( InputArrayOfArrays masks, int queryIdx );
1151 CV_NODISCARD_STD static Mat clone_op( Mat m ) { return m.clone(); }
1152 void checkMasks( InputArrayOfArrays masks, int queryDescriptorsCount ) const;
1154 //! Collection of descriptors from train images.
1155 std::vector<Mat> trainDescCollection;
1156 std::vector<UMat> utrainDescCollection;
1159 /** @brief Brute-force descriptor matcher.
1161 For each descriptor in the first set, this matcher finds the closest descriptor in the second set
1162 by trying each one. This descriptor matcher supports masking permissible matches of descriptor
1165 class CV_EXPORTS_W BFMatcher : public DescriptorMatcher
1168 /** @brief Brute-force matcher constructor (obsolete). Please use BFMatcher.create()
1172 CV_WRAP BFMatcher( int normType=NORM_L2, bool crossCheck=false );
1174 virtual ~BFMatcher() {}
1176 virtual bool isMaskSupported() const CV_OVERRIDE { return true; }
1178 /** @brief Brute-force matcher create method.
1179 @param normType One of NORM_L1, NORM_L2, NORM_HAMMING, NORM_HAMMING2. L1 and L2 norms are
1180 preferable choices for SIFT and SURF descriptors, NORM_HAMMING should be used with ORB, BRISK and
1181 BRIEF, NORM_HAMMING2 should be used with ORB when WTA_K==3 or 4 (see ORB::ORB constructor
1183 @param crossCheck If it is false, this is will be default BFMatcher behaviour when it finds the k
1184 nearest neighbors for each query descriptor. If crossCheck==true, then the knnMatch() method with
1185 k=1 will only return pairs (i,j) such that for i-th query descriptor the j-th descriptor in the
1186 matcher's collection is the nearest and vice versa, i.e. the BFMatcher will only return consistent
1187 pairs. Such technique usually produces best results with minimal number of outliers when there are
1188 enough matches. This is alternative to the ratio test, used by D. Lowe in SIFT paper.
1190 CV_WRAP static Ptr<BFMatcher> create( int normType=NORM_L2, bool crossCheck=false ) ;
1192 CV_NODISCARD_STD virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const CV_OVERRIDE;
1194 virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
1195 InputArrayOfArrays masks=noArray(), bool compactResult=false ) CV_OVERRIDE;
1196 virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1197 InputArrayOfArrays masks=noArray(), bool compactResult=false ) CV_OVERRIDE;
1203 #if defined(HAVE_OPENCV_FLANN) || defined(CV_DOXYGEN)
1205 /** @brief Flann-based descriptor matcher.
1207 This matcher trains cv::flann::Index on a train descriptor collection and calls its nearest search
1208 methods to find the best matches. So, this matcher may be faster when matching a large train
1209 collection than the brute force matcher. FlannBasedMatcher does not support masking permissible
1210 matches of descriptor sets because flann::Index does not support this. :
1212 class CV_EXPORTS_W FlannBasedMatcher : public DescriptorMatcher
1215 CV_WRAP FlannBasedMatcher( const Ptr<flann::IndexParams>& indexParams=makePtr<flann::KDTreeIndexParams>(),
1216 const Ptr<flann::SearchParams>& searchParams=makePtr<flann::SearchParams>() );
1218 virtual void add( InputArrayOfArrays descriptors ) CV_OVERRIDE;
1219 virtual void clear() CV_OVERRIDE;
1221 // Reads matcher object from a file node
1222 virtual void read( const FileNode& ) CV_OVERRIDE;
1223 // Writes matcher object to a file storage
1224 virtual void write( FileStorage& ) const CV_OVERRIDE;
1226 virtual void train() CV_OVERRIDE;
1227 virtual bool isMaskSupported() const CV_OVERRIDE;
1229 CV_WRAP static Ptr<FlannBasedMatcher> create();
1231 CV_NODISCARD_STD virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const CV_OVERRIDE;
1233 static void convertToDMatches( const DescriptorCollection& descriptors,
1234 const Mat& indices, const Mat& distances,
1235 std::vector<std::vector<DMatch> >& matches );
1237 virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
1238 InputArrayOfArrays masks=noArray(), bool compactResult=false ) CV_OVERRIDE;
1239 virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1240 InputArrayOfArrays masks=noArray(), bool compactResult=false ) CV_OVERRIDE;
1242 Ptr<flann::IndexParams> indexParams;
1243 Ptr<flann::SearchParams> searchParams;
1244 Ptr<flann::Index> flannIndex;
1246 DescriptorCollection mergedDescriptors;
1252 //! @} features2d_match
1254 /****************************************************************************************\
1255 * Drawing functions *
1256 \****************************************************************************************/
1258 //! @addtogroup features2d_draw
1261 struct CV_EXPORTS DrawMatchesFlags
1263 enum{ DEFAULT = 0, //!< Output image matrix will be created (Mat::create),
1264 //!< i.e. existing memory of output image may be reused.
1265 //!< Two source image, matches and single keypoints will be drawn.
1266 //!< For each keypoint only the center point will be drawn (without
1267 //!< the circle around keypoint with keypoint size and orientation).
1268 DRAW_OVER_OUTIMG = 1, //!< Output image matrix will not be created (Mat::create).
1269 //!< Matches will be drawn on existing content of output image.
1270 NOT_DRAW_SINGLE_POINTS = 2, //!< Single keypoints will not be drawn.
1271 DRAW_RICH_KEYPOINTS = 4 //!< For each keypoint the circle around keypoint with keypoint size and
1272 //!< orientation will be drawn.
1276 /** @brief Draws keypoints.
1278 @param image Source image.
1279 @param keypoints Keypoints from the source image.
1280 @param outImage Output image. Its content depends on the flags value defining what is drawn in the
1281 output image. See possible flags bit values below.
1282 @param color Color of keypoints.
1283 @param flags Flags setting drawing features. Possible flags bit values are defined by
1284 DrawMatchesFlags. See details above in drawMatches .
1287 For Python API, flags are modified as cv2.DRAW_MATCHES_FLAGS_DEFAULT,
1288 cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS, cv2.DRAW_MATCHES_FLAGS_DRAW_OVER_OUTIMG,
1289 cv2.DRAW_MATCHES_FLAGS_NOT_DRAW_SINGLE_POINTS
1291 CV_EXPORTS_W void drawKeypoints( InputArray image, const std::vector<KeyPoint>& keypoints, InputOutputArray outImage,
1292 const Scalar& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT );
1294 /** @brief Draws the found matches of keypoints from two images.
1296 @param img1 First source image.
1297 @param keypoints1 Keypoints from the first source image.
1298 @param img2 Second source image.
1299 @param keypoints2 Keypoints from the second source image.
1300 @param matches1to2 Matches from the first image to the second one, which means that keypoints1[i]
1301 has a corresponding point in keypoints2[matches[i]] .
1302 @param outImg Output image. Its content depends on the flags value defining what is drawn in the
1303 output image. See possible flags bit values below.
1304 @param matchColor Color of matches (lines and connected keypoints). If matchColor==Scalar::all(-1)
1305 , the color is generated randomly.
1306 @param singlePointColor Color of single keypoints (circles), which means that keypoints do not
1307 have the matches. If singlePointColor==Scalar::all(-1) , the color is generated randomly.
1308 @param matchesMask Mask determining which matches are drawn. If the mask is empty, all matches are
1310 @param flags Flags setting drawing features. Possible flags bit values are defined by
1313 This function draws matches of keypoints from two images in the output image. Match is a line
1314 connecting two keypoints (circles). See cv::DrawMatchesFlags.
1316 CV_EXPORTS_W void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
1317 InputArray img2, const std::vector<KeyPoint>& keypoints2,
1318 const std::vector<DMatch>& matches1to2, InputOutputArray outImg,
1319 const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1),
1320 const std::vector<char>& matchesMask=std::vector<char>(), int flags=DrawMatchesFlags::DEFAULT );
1323 CV_EXPORTS_W void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
1324 InputArray img2, const std::vector<KeyPoint>& keypoints2,
1325 const std::vector<DMatch>& matches1to2, InputOutputArray outImg,
1326 const int matchesThickness, const Scalar& matchColor=Scalar::all(-1),
1327 const Scalar& singlePointColor=Scalar::all(-1), const std::vector<char>& matchesMask=std::vector<char>(),
1328 int flags=DrawMatchesFlags::DEFAULT );
1330 CV_EXPORTS_AS(drawMatchesKnn) void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
1331 InputArray img2, const std::vector<KeyPoint>& keypoints2,
1332 const std::vector<std::vector<DMatch> >& matches1to2, InputOutputArray outImg,
1333 const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1),
1334 const std::vector<std::vector<char> >& matchesMask=std::vector<std::vector<char> >(), int flags=DrawMatchesFlags::DEFAULT );
1336 //! @} features2d_draw
1338 /****************************************************************************************\
1339 * Functions to evaluate the feature detectors and [generic] descriptor extractors *
1340 \****************************************************************************************/
1342 CV_EXPORTS void evaluateFeatureDetector( const Mat& img1, const Mat& img2, const Mat& H1to2,
1343 std::vector<KeyPoint>* keypoints1, std::vector<KeyPoint>* keypoints2,
1344 float& repeatability, int& correspCount,
1345 const Ptr<FeatureDetector>& fdetector=Ptr<FeatureDetector>() );
1347 CV_EXPORTS void computeRecallPrecisionCurve( const std::vector<std::vector<DMatch> >& matches1to2,
1348 const std::vector<std::vector<uchar> >& correctMatches1to2Mask,
1349 std::vector<Point2f>& recallPrecisionCurve );
1351 CV_EXPORTS float getRecall( const std::vector<Point2f>& recallPrecisionCurve, float l_precision );
1352 CV_EXPORTS int getNearestPoint( const std::vector<Point2f>& recallPrecisionCurve, float l_precision );
1354 /****************************************************************************************\
1355 * Bag of visual words *
1356 \****************************************************************************************/
1358 //! @addtogroup features2d_category
1361 /** @brief Abstract base class for training the *bag of visual words* vocabulary from a set of descriptors.
1363 For details, see, for example, *Visual Categorization with Bags of Keypoints* by Gabriella Csurka,
1364 Christopher R. Dance, Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. :
1366 class CV_EXPORTS_W BOWTrainer
1370 virtual ~BOWTrainer();
1372 /** @brief Adds descriptors to a training set.
1374 @param descriptors Descriptors to add to a training set. Each row of the descriptors matrix is a
1377 The training set is clustered using clustermethod to construct the vocabulary.
1379 CV_WRAP void add( const Mat& descriptors );
1381 /** @brief Returns a training set of descriptors.
1383 CV_WRAP const std::vector<Mat>& getDescriptors() const;
1385 /** @brief Returns the count of all descriptors stored in the training set.
1387 CV_WRAP int descriptorsCount() const;
1389 CV_WRAP virtual void clear();
1392 CV_WRAP virtual Mat cluster() const = 0;
1394 /** @brief Clusters train descriptors.
1396 @param descriptors Descriptors to cluster. Each row of the descriptors matrix is a descriptor.
1397 Descriptors are not added to the inner train descriptor set.
1399 The vocabulary consists of cluster centers. So, this method returns the vocabulary. In the first
1400 variant of the method, train descriptors stored in the object are clustered. In the second variant,
1401 input descriptors are clustered.
1403 CV_WRAP virtual Mat cluster( const Mat& descriptors ) const = 0;
1406 std::vector<Mat> descriptors;
1410 /** @brief kmeans -based class to train visual vocabulary using the *bag of visual words* approach. :
1412 class CV_EXPORTS_W BOWKMeansTrainer : public BOWTrainer
1415 /** @brief The constructor.
1419 CV_WRAP BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
1420 int attempts=3, int flags=KMEANS_PP_CENTERS );
1421 virtual ~BOWKMeansTrainer();
1423 // Returns trained vocabulary (i.e. cluster centers).
1424 CV_WRAP virtual Mat cluster() const CV_OVERRIDE;
1425 CV_WRAP virtual Mat cluster( const Mat& descriptors ) const CV_OVERRIDE;
1430 TermCriteria termcrit;
1435 /** @brief Class to compute an image descriptor using the *bag of visual words*.
1437 Such a computation consists of the following steps:
1439 1. Compute descriptors for a given image and its keypoints set.
1440 2. Find the nearest visual words from the vocabulary for each keypoint descriptor.
1441 3. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words
1442 encountered in the image. The i-th bin of the histogram is a frequency of i-th word of the
1443 vocabulary in the given image.
1445 class CV_EXPORTS_W BOWImgDescriptorExtractor
1448 /** @brief The constructor.
1450 @param dextractor Descriptor extractor that is used to compute descriptors for an input image and
1452 @param dmatcher Descriptor matcher that is used to find the nearest word of the trained vocabulary
1453 for each keypoint descriptor of the image.
1455 CV_WRAP BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
1456 const Ptr<DescriptorMatcher>& dmatcher );
1458 BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher );
1459 virtual ~BOWImgDescriptorExtractor();
1461 /** @brief Sets a visual vocabulary.
1463 @param vocabulary Vocabulary (can be trained using the inheritor of BOWTrainer ). Each row of the
1464 vocabulary is a visual word (cluster center).
1466 CV_WRAP void setVocabulary( const Mat& vocabulary );
1468 /** @brief Returns the set vocabulary.
1470 CV_WRAP const Mat& getVocabulary() const;
1472 /** @brief Computes an image descriptor using the set visual vocabulary.
1474 @param image Image, for which the descriptor is computed.
1475 @param keypoints Keypoints detected in the input image.
1476 @param imgDescriptor Computed output image descriptor.
1477 @param pointIdxsOfClusters Indices of keypoints that belong to the cluster. This means that
1478 pointIdxsOfClusters[i] are keypoint indices that belong to the i -th cluster (word of vocabulary)
1479 returned if it is non-zero.
1480 @param descriptors Descriptors of the image keypoints that are returned if they are non-zero.
1482 void compute( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray imgDescriptor,
1483 std::vector<std::vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 );
1485 @param keypointDescriptors Computed descriptors to match with vocabulary.
1486 @param imgDescriptor Computed output image descriptor.
1487 @param pointIdxsOfClusters Indices of keypoints that belong to the cluster. This means that
1488 pointIdxsOfClusters[i] are keypoint indices that belong to the i -th cluster (word of vocabulary)
1489 returned if it is non-zero.
1491 void compute( InputArray keypointDescriptors, OutputArray imgDescriptor,
1492 std::vector<std::vector<int> >* pointIdxsOfClusters=0 );
1493 // compute() is not constant because DescriptorMatcher::match is not constant
1495 CV_WRAP_AS(compute) void compute2( const Mat& image, std::vector<KeyPoint>& keypoints, CV_OUT Mat& imgDescriptor )
1496 { compute(image,keypoints,imgDescriptor); }
1498 /** @brief Returns an image descriptor size if the vocabulary is set. Otherwise, it returns 0.
1500 CV_WRAP int descriptorSize() const;
1502 /** @brief Returns an image descriptor type.
1504 CV_WRAP int descriptorType() const;
1508 Ptr<DescriptorExtractor> dextractor;
1509 Ptr<DescriptorMatcher> dmatcher;
1512 //! @} features2d_category
1516 } /* namespace cv */