modules/features2d/include/opencv2/features2d.hpp

   1 /*M///////////////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
   4 //
   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.
   8 //
   9 //
  10 //                           License Agreement
  11 //                For Open Source Computer Vision Library
  12 //
  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.
  16 //
  17 // Redistribution and use in source and binary forms, with or without modification,
  18 // are permitted provided that the following conditions are met:
  19 //
  20 //   * Redistribution's of source code must retain the above copyright notice,
  21 //     this list of conditions and the following disclaimer.
  22 //
  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.
  26 //
  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.
  29 //
  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.
  40 //
  41 //M*/
  42
  43 #ifndef __OPENCV_FEATURES_2D_HPP__
  44 #define __OPENCV_FEATURES_2D_HPP__
  45
  46 #include "opencv2/core.hpp"
  47 #include "opencv2/flann/miniflann.hpp"
  48
  49 namespace cv
  50 {
  51
  52 CV_EXPORTS bool initModule_features2d();
  53
  54 // //! writes vector of keypoints to the file storage
  55 // CV_EXPORTS void write(FileStorage& fs, const String& name, const std::vector<KeyPoint>& keypoints);
  56 // //! reads vector of keypoints from the specified file storage node
  57 // CV_EXPORTS void read(const FileNode& node, CV_OUT std::vector<KeyPoint>& keypoints);
  58
  59 /*
  60  * A class filters a vector of keypoints.
  61  * Because now it is difficult to provide a convenient interface for all usage scenarios of the keypoints filter class,
  62  * it has only several needed by now static methods.
  63  */
  64 class CV_EXPORTS KeyPointsFilter
  65 {
  66 public:
  67     KeyPointsFilter(){}
  68
  69     /*
  70      * Remove keypoints within borderPixels of an image edge.
  71      */
  72     static void runByImageBorder( std::vector<KeyPoint>& keypoints, Size imageSize, int borderSize );
  73     /*
  74      * Remove keypoints of sizes out of range.
  75      */
  76     static void runByKeypointSize( std::vector<KeyPoint>& keypoints, float minSize,
  77                                    float maxSize=FLT_MAX );
  78     /*
  79      * Remove keypoints from some image by mask for pixels of this image.
  80      */
  81     static void runByPixelsMask( std::vector<KeyPoint>& keypoints, const Mat& mask );
  82     /*
  83      * Remove duplicated keypoints.
  84      */
  85     static void removeDuplicated( std::vector<KeyPoint>& keypoints );
  86
  87     /*
  88      * Retain the specified number of the best keypoints (according to the response)
  89      */
  90     static void retainBest( std::vector<KeyPoint>& keypoints, int npoints );
  91 };
  92
  93
  94 /************************************ Base Classes ************************************/
  95
  96 /*
  97  * Abstract base class for 2D image feature detectors.
  98  */
  99 class CV_EXPORTS_W FeatureDetector : public virtual Algorithm
 100 {
 101 public:
 102     virtual ~FeatureDetector();
 103
 104     /*
 105      * Detect keypoints in an image.
 106      * image        The image.
 107      * keypoints    The detected keypoints.
 108      * mask         Mask specifying where to look for keypoints (optional). Must be a char
 109      *              matrix with non-zero values in the region of interest.
 110      */
 111     CV_WRAP void detect( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 112
 113     /*
 114      * Detect keypoints in an image set.
 115      * images       Image collection.
 116      * keypoints    Collection of keypoints detected in an input images. keypoints[i] is a set of keypoints detected in an images[i].
 117      * masks        Masks for image set. masks[i] is a mask for images[i].
 118      */
 119     void detect( InputArrayOfArrays images, std::vector<std::vector<KeyPoint> >& keypoints, InputArrayOfArrays masks=noArray() ) const;
 120
 121     // Return true if detector object is empty
 122     CV_WRAP virtual bool empty() const;
 123
 124     // Create feature detector by detector name.
 125     CV_WRAP static Ptr<FeatureDetector> create( const String& detectorType );
 126
 127 protected:
 128     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const = 0;
 129
 130     /*
 131      * Remove keypoints that are not in the mask.
 132      * Helper function, useful when wrapping a library call for keypoint detection that
 133      * does not support a mask argument.
 134      */
 135     static void removeInvalidPoints( const Mat & mask, std::vector<KeyPoint>& keypoints );
 136 };
 137
 138
 139 /*
 140  * Abstract base class for computing descriptors for image keypoints.
 141  *
 142  * In this interface we assume a keypoint descriptor can be represented as a
 143  * dense, fixed-dimensional vector of some basic type. Most descriptors used
 144  * in practice follow this pattern, as it makes it very easy to compute
 145  * distances between descriptors. Therefore we represent a collection of
 146  * descriptors as a Mat, where each row is one keypoint descriptor.
 147  */
 148 class CV_EXPORTS_W DescriptorExtractor : public virtual Algorithm
 149 {
 150 public:
 151     virtual ~DescriptorExtractor();
 152
 153     /*
 154      * Compute the descriptors for a set of keypoints in an image.
 155      * image        The image.
 156      * keypoints    The input keypoints. Keypoints for which a descriptor cannot be computed are removed.
 157      * descriptors  Copmputed descriptors. Row i is the descriptor for keypoint i.
 158      */
 159     CV_WRAP void compute( InputArray image, CV_OUT CV_IN_OUT std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 160
 161     /*
 162      * Compute the descriptors for a keypoints collection detected in image collection.
 163      * images       Image collection.
 164      * keypoints    Input keypoints collection. keypoints[i] is keypoints detected in images[i].
 165      *              Keypoints for which a descriptor cannot be computed are removed.
 166      * descriptors  Descriptor collection. descriptors[i] are descriptors computed for set keypoints[i].
 167      */
 168     void compute( InputArrayOfArrays images, std::vector<std::vector<KeyPoint> >& keypoints, OutputArrayOfArrays descriptors ) const;
 169
 170     CV_WRAP virtual int descriptorSize() const = 0;
 171     CV_WRAP virtual int descriptorType() const = 0;
 172     CV_WRAP virtual int defaultNorm() const = 0;
 173
 174     CV_WRAP virtual bool empty() const;
 175
 176     CV_WRAP static Ptr<DescriptorExtractor> create( const String& descriptorExtractorType );
 177
 178 protected:
 179     virtual void computeImpl( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const = 0;
 180
 181     /*
 182      * Remove keypoints within borderPixels of an image edge.
 183      */
 184     static void removeBorderKeypoints( std::vector<KeyPoint>& keypoints,
 185                                       Size imageSize, int borderSize );
 186 };
 187
 188
 189
 190 /*
 191  * Abstract base class for simultaneous 2D feature detection descriptor extraction.
 192  */
 193 class CV_EXPORTS_W Feature2D : public FeatureDetector, public DescriptorExtractor
 194 {
 195 public:
 196     /*
 197      * Detect keypoints in an image.
 198      * image        The image.
 199      * keypoints    The detected keypoints.
 200      * mask         Mask specifying where to look for keypoints (optional). Must be a char
 201      *              matrix with non-zero values in the region of interest.
 202      * useProvidedKeypoints If true, the method will skip the detection phase and will compute
 203      *                      descriptors for the provided keypoints
 204      */
 205     CV_WRAP_AS(detectAndCompute) virtual void operator()( InputArray image, InputArray mask,
 206                                      CV_OUT std::vector<KeyPoint>& keypoints,
 207                                      OutputArray descriptors,
 208                                      bool useProvidedKeypoints=false ) const = 0;
 209
 210     CV_WRAP void compute( InputArray image, CV_OUT CV_IN_OUT std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 211
 212     // Create feature detector and descriptor extractor by name.
 213     CV_WRAP static Ptr<Feature2D> create( const String& name );
 214 };
 215
 216 /*!
 217   BRISK implementation
 218 */
 219 class CV_EXPORTS_W BRISK : public Feature2D
 220 {
 221 public:
 222     CV_WRAP explicit BRISK(int thresh=30, int octaves=3, float patternScale=1.0f);
 223
 224     virtual ~BRISK();
 225
 226     // returns the descriptor size in bytes
 227     int descriptorSize() const;
 228     // returns the descriptor type
 229     int descriptorType() const;
 230     // returns the default norm type
 231     int defaultNorm() const;
 232
 233     // Compute the BRISK features on an image
 234     void operator()(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints) const;
 235
 236     // Compute the BRISK features and descriptors on an image
 237     void operator()( InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints,
 238                      OutputArray descriptors, bool useProvidedKeypoints=false ) const;
 239
 240     AlgorithmInfo* info() const;
 241
 242     // custom setup
 243     CV_WRAP explicit BRISK(std::vector<float> &radiusList, std::vector<int> &numberList,
 244         float dMax=5.85f, float dMin=8.2f, std::vector<int> indexChange=std::vector<int>());
 245
 246     // call this to generate the kernel:
 247     // circle of radius r (pixels), with n points;
 248     // short pairings with dMax, long pairings with dMin
 249     CV_WRAP void generateKernel(std::vector<float> &radiusList,
 250         std::vector<int> &numberList, float dMax=5.85f, float dMin=8.2f,
 251         std::vector<int> indexChange=std::vector<int>());
 252
 253 protected:
 254
 255     void computeImpl( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 256     void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 257
 258     void computeKeypointsNoOrientation(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints) const;
 259     void computeDescriptorsAndOrOrientation(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints,
 260                                        OutputArray descriptors, bool doDescriptors, bool doOrientation,
 261                                        bool useProvidedKeypoints) const;
 262
 263     // Feature parameters
 264     CV_PROP_RW int threshold;
 265     CV_PROP_RW int octaves;
 266
 267     // some helper structures for the Brisk pattern representation
 268     struct BriskPatternPoint{
 269         float x;         // x coordinate relative to center
 270         float y;         // x coordinate relative to center
 271         float sigma;     // Gaussian smoothing sigma
 272     };
 273     struct BriskShortPair{
 274         unsigned int i;  // index of the first pattern point
 275         unsigned int j;  // index of other pattern point
 276     };
 277     struct BriskLongPair{
 278         unsigned int i;  // index of the first pattern point
 279         unsigned int j;  // index of other pattern point
 280         int weighted_dx; // 1024.0/dx
 281         int weighted_dy; // 1024.0/dy
 282     };
 283     inline int smoothedIntensity(const cv::Mat& image,
 284                 const cv::Mat& integral,const float key_x,
 285                 const float key_y, const unsigned int scale,
 286                 const unsigned int rot, const unsigned int point) const;
 287     // pattern properties
 288     BriskPatternPoint* patternPoints_;     //[i][rotation][scale]
 289     unsigned int points_;                 // total number of collocation points
 290     float* scaleList_;                     // lists the scaling per scale index [scale]
 291     unsigned int* sizeList_;             // lists the total pattern size per scale index [scale]
 292     static const unsigned int scales_;    // scales discretization
 293     static const float scalerange_;     // span of sizes 40->4 Octaves - else, this needs to be adjusted...
 294     static const unsigned int n_rot_;    // discretization of the rotation look-up
 295
 296     // pairs
 297     int strings_;                        // number of uchars the descriptor consists of
 298     float dMax_;                         // short pair maximum distance
 299     float dMin_;                         // long pair maximum distance
 300     BriskShortPair* shortPairs_;         // d<_dMax
 301     BriskLongPair* longPairs_;             // d>_dMin
 302     unsigned int noShortPairs_;         // number of shortParis
 303     unsigned int noLongPairs_;             // number of longParis
 304
 305     // general
 306     static const float basicSize_;
 307 };
 308
 309
 310 /*!
 311  ORB implementation.
 312 */
 313 class CV_EXPORTS_W ORB : public Feature2D
 314 {
 315 public:
 316     // the size of the signature in bytes
 317     enum { kBytes = 32, HARRIS_SCORE=0, FAST_SCORE=1 };
 318
 319     CV_WRAP explicit ORB(int nfeatures = 500, float scaleFactor = 1.2f, int nlevels = 8, int edgeThreshold = 31,
 320         int firstLevel = 0, int WTA_K=2, int scoreType=ORB::HARRIS_SCORE, int patchSize=31 );
 321
 322     // returns the descriptor size in bytes
 323     int descriptorSize() const;
 324     // returns the descriptor type
 325     int descriptorType() const;
 326     // returns the default norm type
 327     int defaultNorm() const;
 328
 329     // Compute the ORB features and descriptors on an image
 330     void operator()(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints) const;
 331
 332     // Compute the ORB features and descriptors on an image
 333     void operator()( InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints,
 334                      OutputArray descriptors, bool useProvidedKeypoints=false ) const;
 335
 336     AlgorithmInfo* info() const;
 337
 338 protected:
 339
 340     void computeImpl( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 341     void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 342
 343     CV_PROP_RW int nfeatures;
 344     CV_PROP_RW double scaleFactor;
 345     CV_PROP_RW int nlevels;
 346     CV_PROP_RW int edgeThreshold;
 347     CV_PROP_RW int firstLevel;
 348     CV_PROP_RW int WTA_K;
 349     CV_PROP_RW int scoreType;
 350     CV_PROP_RW int patchSize;
 351 };
 352
 353 typedef ORB OrbFeatureDetector;
 354 typedef ORB OrbDescriptorExtractor;
 355
 356 /*!
 357   FREAK implementation
 358 */
 359 class CV_EXPORTS FREAK : public DescriptorExtractor
 360 {
 361 public:
 362     /** Constructor
 363          * @param orientationNormalized enable orientation normalization
 364          * @param scaleNormalized enable scale normalization
 365          * @param patternScale scaling of the description pattern
 366          * @param nbOctave number of octaves covered by the detected keypoints
 367          * @param selectedPairs (optional) user defined selected pairs
 368     */
 369     explicit FREAK( bool orientationNormalized = true,
 370            bool scaleNormalized = true,
 371            float patternScale = 22.0f,
 372            int nOctaves = 4,
 373            const std::vector<int>& selectedPairs = std::vector<int>());
 374     FREAK( const FREAK& rhs );
 375     FREAK& operator=( const FREAK& );
 376
 377     virtual ~FREAK();
 378
 379     /** returns the descriptor length in bytes */
 380     virtual int descriptorSize() const;
 381
 382     /** returns the descriptor type */
 383     virtual int descriptorType() const;
 384
 385     /** returns the default norm type */
 386     virtual int defaultNorm() const;
 387
 388     /** select the 512 "best description pairs"
 389          * @param images grayscale images set
 390          * @param keypoints set of detected keypoints
 391          * @param corrThresh correlation threshold
 392          * @param verbose print construction information
 393          * @return list of best pair indexes
 394     */
 395     std::vector<int> selectPairs( const std::vector<Mat>& images, std::vector<std::vector<KeyPoint> >& keypoints,
 396                       const double corrThresh = 0.7, bool verbose = true );
 397
 398     AlgorithmInfo* info() const;
 399
 400     enum
 401     {
 402         NB_SCALES = 64, NB_PAIRS = 512, NB_ORIENPAIRS = 45
 403     };
 404
 405 protected:
 406     virtual void computeImpl( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 407     void buildPattern();
 408
 409     template <typename imgType, typename iiType>
 410     imgType meanIntensity( InputArray image, InputArray integral, const float kp_x, const float kp_y,
 411                            const unsigned int scale, const unsigned int rot, const unsigned int point ) const;
 412
 413     template <typename srcMatType, typename iiMatType>
 414     void computeDescriptors( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 415
 416     template <typename srcMatType>
 417     void extractDescriptor(srcMatType *pointsValue, void ** ptr) const;
 418
 419     bool orientationNormalized; //true if the orientation is normalized, false otherwise
 420     bool scaleNormalized; //true if the scale is normalized, false otherwise
 421     double patternScale; //scaling of the pattern
 422     int nOctaves; //number of octaves
 423     bool extAll; // true if all pairs need to be extracted for pairs selection
 424
 425     double patternScale0;
 426     int nOctaves0;
 427     std::vector<int> selectedPairs0;
 428
 429     struct PatternPoint
 430     {
 431         float x; // x coordinate relative to center
 432         float y; // x coordinate relative to center
 433         float sigma; // Gaussian smoothing sigma
 434     };
 435
 436     struct DescriptionPair
 437     {
 438         uchar i; // index of the first point
 439         uchar j; // index of the second point
 440     };
 441
 442     struct OrientationPair
 443     {
 444         uchar i; // index of the first point
 445         uchar j; // index of the second point
 446         int weight_dx; // dx/(norm_sq))*4096
 447         int weight_dy; // dy/(norm_sq))*4096
 448     };
 449
 450     std::vector<PatternPoint> patternLookup; // look-up table for the pattern points (position+sigma of all points at all scales and orientation)
 451     int patternSizes[NB_SCALES]; // size of the pattern at a specific scale (used to check if a point is within image boundaries)
 452     DescriptionPair descriptionPairs[NB_PAIRS];
 453     OrientationPair orientationPairs[NB_ORIENPAIRS];
 454 };
 455
 456
 457 /*!
 458  Maximal Stable Extremal Regions class.
 459
 460  The class implements MSER algorithm introduced by J. Matas.
 461  Unlike SIFT, SURF and many other detectors in OpenCV, this is salient region detector,
 462  not the salient point detector.
 463
 464  It returns the regions, each of those is encoded as a contour.
 465 */
 466 class CV_EXPORTS_W MSER : public FeatureDetector
 467 {
 468 public:
 469     //! the full constructor
 470     CV_WRAP explicit MSER( int _delta=5, int _min_area=60, int _max_area=14400,
 471           double _max_variation=0.25, double _min_diversity=.2,
 472           int _max_evolution=200, double _area_threshold=1.01,
 473           double _min_margin=0.003, int _edge_blur_size=5 );
 474
 475     //! the operator that extracts the MSERs from the image or the specific part of it
 476     CV_WRAP_AS(detect) void operator()( InputArray image, CV_OUT std::vector<std::vector<Point> >& msers,
 477                                         InputArray mask=noArray() ) const;
 478     AlgorithmInfo* info() const;
 479
 480 protected:
 481     void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 482
 483     int delta;
 484     int minArea;
 485     int maxArea;
 486     double maxVariation;
 487     double minDiversity;
 488     int maxEvolution;
 489     double areaThreshold;
 490     double minMargin;
 491     int edgeBlurSize;
 492 };
 493
 494 typedef MSER MserFeatureDetector;
 495
 496 /*!
 497  The "Star" Detector.
 498
 499  The class implements the keypoint detector introduced by K. Konolige.
 500 */
 501 class CV_EXPORTS_W StarDetector : public FeatureDetector
 502 {
 503 public:
 504     //! the full constructor
 505     CV_WRAP StarDetector(int _maxSize=45, int _responseThreshold=30,
 506                  int _lineThresholdProjected=10,
 507                  int _lineThresholdBinarized=8,
 508                  int _suppressNonmaxSize=5);
 509
 510     //! finds the keypoints in the image
 511     CV_WRAP_AS(detect) void operator()(const Mat& image,
 512                 CV_OUT std::vector<KeyPoint>& keypoints) const;
 513
 514     AlgorithmInfo* info() const;
 515
 516 protected:
 517     void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 518
 519     int maxSize;
 520     int responseThreshold;
 521     int lineThresholdProjected;
 522     int lineThresholdBinarized;
 523     int suppressNonmaxSize;
 524 };
 525
 526 //! detects corners using FAST algorithm by E. Rosten
 527 CV_EXPORTS void FAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
 528                       int threshold, bool nonmaxSuppression=true );
 529
 530 CV_EXPORTS void FAST( InputArray image, CV_OUT std::vector<KeyPoint>& keypoints,
 531                       int threshold, bool nonmaxSuppression, int type );
 532
 533 class CV_EXPORTS_W FastFeatureDetector : public FeatureDetector
 534 {
 535 public:
 536     enum Type
 537     {
 538       TYPE_5_8 = 0, TYPE_7_12 = 1, TYPE_9_16 = 2
 539     };
 540
 541     CV_WRAP FastFeatureDetector( int threshold=10, bool nonmaxSuppression=true);
 542     CV_WRAP FastFeatureDetector( int threshold, bool nonmaxSuppression, int type);
 543     AlgorithmInfo* info() const;
 544
 545 protected:
 546     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 547
 548     int threshold;
 549     bool nonmaxSuppression;
 550     int type;
 551 };
 552
 553
 554 class CV_EXPORTS_W GFTTDetector : public FeatureDetector
 555 {
 556 public:
 557     CV_WRAP GFTTDetector( int maxCorners=1000, double qualityLevel=0.01, double minDistance=1,
 558                           int blockSize=3, bool useHarrisDetector=false, double k=0.04 );
 559     AlgorithmInfo* info() const;
 560
 561 protected:
 562     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 563
 564     int nfeatures;
 565     double qualityLevel;
 566     double minDistance;
 567     int blockSize;
 568     bool useHarrisDetector;
 569     double k;
 570 };
 571
 572 typedef GFTTDetector GoodFeaturesToTrackDetector;
 573 typedef StarDetector StarFeatureDetector;
 574
 575 class CV_EXPORTS_W SimpleBlobDetector : public FeatureDetector
 576 {
 577 public:
 578   struct CV_EXPORTS_W_SIMPLE Params
 579   {
 580       CV_WRAP Params();
 581       CV_PROP_RW float thresholdStep;
 582       CV_PROP_RW float minThreshold;
 583       CV_PROP_RW float maxThreshold;
 584       CV_PROP_RW size_t minRepeatability;
 585       CV_PROP_RW float minDistBetweenBlobs;
 586
 587       CV_PROP_RW bool filterByColor;
 588       CV_PROP_RW uchar blobColor;
 589
 590       CV_PROP_RW bool filterByArea;
 591       CV_PROP_RW float minArea, maxArea;
 592
 593       CV_PROP_RW bool filterByCircularity;
 594       CV_PROP_RW float minCircularity, maxCircularity;
 595
 596       CV_PROP_RW bool filterByInertia;
 597       CV_PROP_RW float minInertiaRatio, maxInertiaRatio;
 598
 599       CV_PROP_RW bool filterByConvexity;
 600       CV_PROP_RW float minConvexity, maxConvexity;
 601
 602       void read( const FileNode& fn );
 603       void write( FileStorage& fs ) const;
 604   };
 605
 606   CV_WRAP SimpleBlobDetector(const SimpleBlobDetector::Params &parameters = SimpleBlobDetector::Params());
 607
 608   virtual void read( const FileNode& fn );
 609   virtual void write( FileStorage& fs ) const;
 610
 611 protected:
 612   struct CV_EXPORTS Center
 613   {
 614       Point2d location;
 615       double radius;
 616       double confidence;
 617   };
 618
 619   virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 620   virtual void findBlobs(InputArray image, InputArray binaryImage, std::vector<Center> &centers) const;
 621
 622   Params params;
 623   AlgorithmInfo* info() const;
 624 };
 625
 626
 627 class CV_EXPORTS_W DenseFeatureDetector : public FeatureDetector
 628 {
 629 public:
 630     CV_WRAP explicit DenseFeatureDetector( float initFeatureScale=1.f, int featureScaleLevels=1,
 631                                            float featureScaleMul=0.1f,
 632                                            int initXyStep=6, int initImgBound=0,
 633                                            bool varyXyStepWithScale=true,
 634                                            bool varyImgBoundWithScale=false );
 635     AlgorithmInfo* info() const;
 636
 637 protected:
 638     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 639
 640     double initFeatureScale;
 641     int featureScaleLevels;
 642     double featureScaleMul;
 643
 644     int initXyStep;
 645     int initImgBound;
 646
 647     bool varyXyStepWithScale;
 648     bool varyImgBoundWithScale;
 649 };
 650
 651 /*
 652  * Adapts a detector to partition the source image into a grid and detect
 653  * points in each cell.
 654  */
 655 class CV_EXPORTS_W GridAdaptedFeatureDetector : public FeatureDetector
 656 {
 657 public:
 658     /*
 659      * detector            Detector that will be adapted.
 660      * maxTotalKeypoints   Maximum count of keypoints detected on the image. Only the strongest keypoints
 661      *                      will be keeped.
 662      * gridRows            Grid rows count.
 663      * gridCols            Grid column count.
 664      */
 665     CV_WRAP GridAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector=Ptr<FeatureDetector>(),
 666                                         int maxTotalKeypoints=1000,
 667                                         int gridRows=4, int gridCols=4 );
 668
 669     // TODO implement read/write
 670     virtual bool empty() const;
 671
 672     AlgorithmInfo* info() const;
 673
 674 protected:
 675     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 676
 677     Ptr<FeatureDetector> detector;
 678     int maxTotalKeypoints;
 679     int gridRows;
 680     int gridCols;
 681 };
 682
 683 /*
 684  * Adapts a detector to detect points over multiple levels of a Gaussian
 685  * pyramid. Useful for detectors that are not inherently scaled.
 686  */
 687 class CV_EXPORTS_W PyramidAdaptedFeatureDetector : public FeatureDetector
 688 {
 689 public:
 690     // maxLevel - The 0-based index of the last pyramid layer
 691     CV_WRAP PyramidAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector, int maxLevel=2 );
 692
 693     // TODO implement read/write
 694     virtual bool empty() const;
 695
 696 protected:
 697     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 698
 699     Ptr<FeatureDetector> detector;
 700     int maxLevel;
 701 };
 702
 703 /** \brief A feature detector parameter adjuster, this is used by the DynamicAdaptedFeatureDetector
 704  *  and is a wrapper for FeatureDetector that allow them to be adjusted after a detection
 705  */
 706 class CV_EXPORTS AdjusterAdapter: public FeatureDetector
 707 {
 708 public:
 709     /** pure virtual interface
 710      */
 711     virtual ~AdjusterAdapter() {}
 712     /** too few features were detected so, adjust the detector params accordingly
 713      * \param min the minimum number of desired features
 714      * \param n_detected the number previously detected
 715      */
 716     virtual void tooFew(int min, int n_detected) = 0;
 717     /** too many features were detected so, adjust the detector params accordingly
 718      * \param max the maximum number of desired features
 719      * \param n_detected the number previously detected
 720      */
 721     virtual void tooMany(int max, int n_detected) = 0;
 722     /** are params maxed out or still valid?
 723      * \return false if the parameters can't be adjusted any more
 724      */
 725     virtual bool good() const = 0;
 726
 727     virtual Ptr<AdjusterAdapter> clone() const = 0;
 728
 729     static Ptr<AdjusterAdapter> create( const String& detectorType );
 730 };
 731 /** \brief an adaptively adjusting detector that iteratively detects until the desired number
 732  * of features are detected.
 733  *  Beware that this is not thread safe - as the adjustment of parameters breaks the const
 734  *  of the detection routine...
 735  *  /TODO Make this const correct and thread safe
 736  *
 737  *  sample usage:
 738  //will create a detector that attempts to find 100 - 110 FAST Keypoints, and will at most run
 739  //FAST feature detection 10 times until that number of keypoints are found
 740  Ptr<FeatureDetector> detector(new DynamicAdaptedFeatureDetector(new FastAdjuster(20,true),100, 110, 10));
 741
 742  */
 743 class CV_EXPORTS DynamicAdaptedFeatureDetector: public FeatureDetector
 744 {
 745 public:
 746
 747     /** \param adjuster an AdjusterAdapter that will do the detection and parameter adjustment
 748      *  \param max_features the maximum desired number of features
 749      *  \param max_iters the maximum number of times to try to adjust the feature detector params
 750      *          for the FastAdjuster this can be high, but with Star or Surf this can get time consuming
 751      *  \param min_features the minimum desired features
 752      */
 753     DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster, int min_features=400, int max_features=500, int max_iters=5 );
 754
 755     virtual bool empty() const;
 756
 757 protected:
 758     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 759
 760 private:
 761     DynamicAdaptedFeatureDetector& operator=(const DynamicAdaptedFeatureDetector&);
 762     DynamicAdaptedFeatureDetector(const DynamicAdaptedFeatureDetector&);
 763
 764     int escape_iters_;
 765     int min_features_, max_features_;
 766     const Ptr<AdjusterAdapter> adjuster_;
 767 };
 768
 769 /**\brief an adjust for the FAST detector. This will basically decrement or increment the
 770  * threshold by 1
 771  */
 772 class CV_EXPORTS FastAdjuster: public AdjusterAdapter
 773 {
 774 public:
 775     /**\param init_thresh the initial threshold to start with, default = 20
 776      * \param nonmax whether to use non max or not for fast feature detection
 777      */
 778     FastAdjuster(int init_thresh=20, bool nonmax=true, int min_thresh=1, int max_thresh=200);
 779
 780     virtual void tooFew(int minv, int n_detected);
 781     virtual void tooMany(int maxv, int n_detected);
 782     virtual bool good() const;
 783
 784     virtual Ptr<AdjusterAdapter> clone() const;
 785
 786 protected:
 787     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 788
 789     int thresh_;
 790     bool nonmax_;
 791     int init_thresh_, min_thresh_, max_thresh_;
 792 };
 793
 794
 795 /** An adjuster for StarFeatureDetector, this one adjusts the responseThreshold for now
 796  * TODO find a faster way to converge the parameters for Star - use CvStarDetectorParams
 797  */
 798 class CV_EXPORTS StarAdjuster: public AdjusterAdapter
 799 {
 800 public:
 801     StarAdjuster(double initial_thresh=30.0, double min_thresh=2., double max_thresh=200.);
 802
 803     virtual void tooFew(int minv, int n_detected);
 804     virtual void tooMany(int maxv, int n_detected);
 805     virtual bool good() const;
 806
 807     virtual Ptr<AdjusterAdapter> clone() const;
 808
 809 protected:
 810     virtual void detectImpl(InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 811
 812     double thresh_, init_thresh_, min_thresh_, max_thresh_;
 813 };
 814
 815 class CV_EXPORTS SurfAdjuster: public AdjusterAdapter
 816 {
 817 public:
 818     SurfAdjuster( double initial_thresh=400.f, double min_thresh=2, double max_thresh=1000 );
 819
 820     virtual void tooFew(int minv, int n_detected);
 821     virtual void tooMany(int maxv, int n_detected);
 822     virtual bool good() const;
 823
 824     virtual Ptr<AdjusterAdapter> clone() const;
 825
 826 protected:
 827     virtual void detectImpl( InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const;
 828
 829     double thresh_, init_thresh_, min_thresh_, max_thresh_;
 830 };
 831
 832 CV_EXPORTS Mat windowedMatchingMask( const std::vector<KeyPoint>& keypoints1, const std::vector<KeyPoint>& keypoints2,
 833                                      float maxDeltaX, float maxDeltaY );
 834
 835
 836
 837 /*
 838  * OpponentColorDescriptorExtractor
 839  *
 840  * Adapts a descriptor extractor to compute descriptors in Opponent Color Space
 841  * (refer to van de Sande et al., CGIV 2008 "Color Descriptors for Object Category Recognition").
 842  * Input RGB image is transformed in Opponent Color Space. Then unadapted descriptor extractor
 843  * (set in constructor) computes descriptors on each of the three channel and concatenate
 844  * them into a single color descriptor.
 845  */
 846 class CV_EXPORTS OpponentColorDescriptorExtractor : public DescriptorExtractor
 847 {
 848 public:
 849     OpponentColorDescriptorExtractor( const Ptr<DescriptorExtractor>& descriptorExtractor );
 850
 851     virtual void read( const FileNode& );
 852     virtual void write( FileStorage& ) const;
 853
 854     virtual int descriptorSize() const;
 855     virtual int descriptorType() const;
 856     virtual int defaultNorm() const;
 857
 858     virtual bool empty() const;
 859
 860 protected:
 861     virtual void computeImpl( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors ) const;
 862
 863     Ptr<DescriptorExtractor> descriptorExtractor;
 864 };
 865
 866 /*
 867  * BRIEF Descriptor
 868  */
 869 class CV_EXPORTS BriefDescriptorExtractor : public DescriptorExtractor
 870 {
 871 public:
 872     static const int PATCH_SIZE = 48;
 873     static const int KERNEL_SIZE = 9;
 874
 875     // bytes is a length of descriptor in bytes. It can be equal 16, 32 or 64 bytes.
 876     BriefDescriptorExtractor( int bytes = 32 );
 877
 878     virtual void read( const FileNode& );
 879     virtual void write( FileStorage& ) const;
 880
 881     virtual int descriptorSize() const;
 882     virtual int descriptorType() const;
 883     virtual int defaultNorm() const;
 884
 885     /// @todo read and write for brief
 886
 887     AlgorithmInfo* info() const;
 888
 889 protected:
 890     virtual void computeImpl(InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors) const;
 891
 892     typedef void(*PixelTestFn)(InputArray, const std::vector<KeyPoint>&, OutputArray);
 893
 894     int bytes_;
 895     PixelTestFn test_fn_;
 896 };
 897
 898 // KAZE/AKAZE diffusivity
 899 enum {
 900     DIFF_PM_G1 = 0,
 901     DIFF_PM_G2 = 1,
 902     DIFF_WEICKERT = 2,
 903     DIFF_CHARBONNIER = 3
 904 };
 905
 906 // AKAZE descriptor type
 907 enum {
 908     DESCRIPTOR_KAZE_UPRIGHT = 2, ///< Upright descriptors, not invariant to rotation
 909     DESCRIPTOR_KAZE = 3,
 910     DESCRIPTOR_MLDB_UPRIGHT = 4, ///< Upright descriptors, not invariant to rotation
 911     DESCRIPTOR_MLDB = 5
 912 };
 913
 914 /*!
 915 KAZE implementation
 916 */
 917 class CV_EXPORTS_W KAZE : public Feature2D
 918 {
 919 public:
 920     CV_WRAP KAZE();
 921     CV_WRAP explicit KAZE(bool extended, bool upright, float threshold = 0.001f,
 922                           int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
 923
 924     virtual ~KAZE();
 925
 926     // returns the descriptor size in bytes
 927     int descriptorSize() const;
 928     // returns the descriptor type
 929     int descriptorType() const;
 930     // returns the default norm type
 931     int defaultNorm() const;
 932
 933     AlgorithmInfo* info() const;
 934
 935     // Compute the KAZE features on an image
 936     void operator()(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints) const;
 937
 938     // Compute the KAZE features and descriptors on an image
 939     void operator()(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints,
 940         OutputArray descriptors, bool useProvidedKeypoints = false) const;
 941
 942 protected:
 943     void detectImpl(InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask) const;
 944     void computeImpl(InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors) const;
 945
 946     CV_PROP bool extended;
 947     CV_PROP bool upright;
 948     CV_PROP float threshold;
 949     CV_PROP int octaves;
 950     CV_PROP int sublevels;
 951     CV_PROP int diffusivity;
 952 };
 953
 954 /*!
 955 AKAZE implementation
 956 */
 957 class CV_EXPORTS_W AKAZE : public Feature2D
 958 {
 959 public:
 960     CV_WRAP AKAZE();
 961     CV_WRAP explicit AKAZE(int descriptor_type, int descriptor_size = 0, int descriptor_channels = 3,
 962                    float threshold = 0.001f, int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
 963
 964     virtual ~AKAZE();
 965
 966     // returns the descriptor size in bytes
 967     int descriptorSize() const;
 968     // returns the descriptor type
 969     int descriptorType() const;
 970     // returns the default norm type
 971     int defaultNorm() const;
 972
 973     // Compute the AKAZE features on an image
 974     void operator()(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints) const;
 975
 976     // Compute the AKAZE features and descriptors on an image
 977     void operator()(InputArray image, InputArray mask, std::vector<KeyPoint>& keypoints,
 978         OutputArray descriptors, bool useProvidedKeypoints = false) const;
 979
 980     AlgorithmInfo* info() const;
 981
 982 protected:
 983
 984     void computeImpl(InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors) const;
 985     void detectImpl(InputArray image, std::vector<KeyPoint>& keypoints, InputArray mask = noArray()) const;
 986
 987     CV_PROP int descriptor;
 988     CV_PROP int descriptor_channels;
 989     CV_PROP int descriptor_size;
 990     CV_PROP float threshold;
 991     CV_PROP int octaves;
 992     CV_PROP int sublevels;
 993     CV_PROP int diffusivity;
 994 };
 995 /****************************************************************************************\
 996 *                                      Distance                                          *
 997 \****************************************************************************************/
 998
 999 template<typename T>
1000 struct CV_EXPORTS Accumulator
1001 {
1002     typedef T Type;
1003 };
1004
1005 template<> struct Accumulator<unsigned char>  { typedef float Type; };
1006 template<> struct Accumulator<unsigned short> { typedef float Type; };
1007 template<> struct Accumulator<char>   { typedef float Type; };
1008 template<> struct Accumulator<short>  { typedef float Type; };
1009
1010 /*
1011  * Squared Euclidean distance functor
1012  */
1013 template<class T>
1014 struct CV_EXPORTS SL2
1015 {
1016     enum { normType = NORM_L2SQR };
1017     typedef T ValueType;
1018     typedef typename Accumulator<T>::Type ResultType;
1019
1020     ResultType operator()( const T* a, const T* b, int size ) const
1021     {
1022         return normL2Sqr<ValueType, ResultType>(a, b, size);
1023     }
1024 };
1025
1026 /*
1027  * Euclidean distance functor
1028  */
1029 template<class T>
1030 struct CV_EXPORTS L2
1031 {
1032     enum { normType = NORM_L2 };
1033     typedef T ValueType;
1034     typedef typename Accumulator<T>::Type ResultType;
1035
1036     ResultType operator()( const T* a, const T* b, int size ) const
1037     {
1038         return (ResultType)std::sqrt((double)normL2Sqr<ValueType, ResultType>(a, b, size));
1039     }
1040 };
1041
1042 /*
1043  * Manhattan distance (city block distance) functor
1044  */
1045 template<class T>
1046 struct CV_EXPORTS L1
1047 {
1048     enum { normType = NORM_L1 };
1049     typedef T ValueType;
1050     typedef typename Accumulator<T>::Type ResultType;
1051
1052     ResultType operator()( const T* a, const T* b, int size ) const
1053     {
1054         return normL1<ValueType, ResultType>(a, b, size);
1055     }
1056 };
1057
1058 /*
1059  * Hamming distance functor - counts the bit differences between two strings - useful for the Brief descriptor
1060  * bit count of A exclusive XOR'ed with B
1061  */
1062 struct CV_EXPORTS Hamming
1063 {
1064     enum { normType = NORM_HAMMING };
1065     typedef unsigned char ValueType;
1066     typedef int ResultType;
1067
1068     /** this will count the bits in a ^ b
1069      */
1070     ResultType operator()( const unsigned char* a, const unsigned char* b, int size ) const
1071     {
1072         return normHamming(a, b, size);
1073     }
1074 };
1075
1076 typedef Hamming HammingLUT;
1077
1078 template<int cellsize> struct HammingMultilevel
1079 {
1080     enum { normType = NORM_HAMMING + (cellsize>1) };
1081     typedef unsigned char ValueType;
1082     typedef int ResultType;
1083
1084     ResultType operator()( const unsigned char* a, const unsigned char* b, int size ) const
1085     {
1086         return normHamming(a, b, size, cellsize);
1087     }
1088 };
1089
1090 /****************************************************************************************\
1091 *                                  DescriptorMatcher                                     *
1092 \****************************************************************************************/
1093 /*
1094  * Abstract base class for matching two sets of descriptors.
1095  */
1096 class CV_EXPORTS_W DescriptorMatcher : public Algorithm
1097 {
1098 public:
1099     virtual ~DescriptorMatcher();
1100
1101     /*
1102      * Add descriptors to train descriptor collection.
1103      * descriptors      Descriptors to add. Each descriptors[i] is a descriptors set from one image.
1104      */
1105     CV_WRAP virtual void add( InputArrayOfArrays descriptors );
1106     /*
1107      * Get train descriptors collection.
1108      */
1109     CV_WRAP const std::vector<Mat>& getTrainDescriptors() const;
1110     /*
1111      * Clear train descriptors collection.
1112      */
1113     CV_WRAP virtual void clear();
1114
1115     /*
1116      * Return true if there are not train descriptors in collection.
1117      */
1118     CV_WRAP virtual bool empty() const;
1119     /*
1120      * Return true if the matcher supports mask in match methods.
1121      */
1122     CV_WRAP virtual bool isMaskSupported() const = 0;
1123
1124     /*
1125      * Train matcher (e.g. train flann index).
1126      * In all methods to match the method train() is run every time before matching.
1127      * Some descriptor matchers (e.g. BruteForceMatcher) have empty implementation
1128      * of this method, other matchers really train their inner structures
1129      * (e.g. FlannBasedMatcher trains flann::Index). So nonempty implementation
1130      * of train() should check the class object state and do traing/retraining
1131      * only if the state requires that (e.g. FlannBasedMatcher trains flann::Index
1132      * if it has not trained yet or if new descriptors have been added to the train
1133      * collection).
1134      */
1135     CV_WRAP virtual void train();
1136     /*
1137      * Group of methods to match descriptors from image pair.
1138      * Method train() is run in this methods.
1139      */
1140     // Find one best match for each query descriptor (if mask is empty).
1141     CV_WRAP void match( InputArray queryDescriptors, InputArray trainDescriptors,
1142                 CV_OUT std::vector<DMatch>& matches, InputArray mask=noArray() ) const;
1143     // Find k best matches for each query descriptor (in increasing order of distances).
1144     // compactResult is used when mask is not empty. If compactResult is false matches
1145     // vector will have the same size as queryDescriptors rows. If compactResult is true
1146     // matches vector will not contain matches for fully masked out query descriptors.
1147     CV_WRAP void knnMatch( InputArray queryDescriptors, InputArray trainDescriptors,
1148                    CV_OUT std::vector<std::vector<DMatch> >& matches, int k,
1149                    InputArray mask=noArray(), bool compactResult=false ) const;
1150     // Find best matches for each query descriptor which have distance less than
1151     // maxDistance (in increasing order of distances).
1152     void radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors,
1153                       std::vector<std::vector<DMatch> >& matches, float maxDistance,
1154                       InputArray mask=noArray(), bool compactResult=false ) const;
1155     /*
1156      * Group of methods to match descriptors from one image to image set.
1157      * See description of similar methods for matching image pair above.
1158      */
1159     CV_WRAP void match( InputArray queryDescriptors, CV_OUT std::vector<DMatch>& matches,
1160                         InputArrayOfArrays masks=noArray() );
1161     CV_WRAP void knnMatch( InputArray queryDescriptors, CV_OUT std::vector<std::vector<DMatch> >& matches, int k,
1162                            InputArrayOfArrays masks=noArray(), bool compactResult=false );
1163     void radiusMatch( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1164                       InputArrayOfArrays masks=noArray(), bool compactResult=false );
1165
1166     // Reads matcher object from a file node
1167     virtual void read( const FileNode& );
1168     // Writes matcher object to a file storage
1169     virtual void write( FileStorage& ) const;
1170
1171     // Clone the matcher. If emptyTrainData is false the method create deep copy of the object, i.e. copies
1172     // both parameters and train data. If emptyTrainData is true the method create object copy with current parameters
1173     // but with empty train data.
1174     virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
1175
1176     CV_WRAP static Ptr<DescriptorMatcher> create( const String& descriptorMatcherType );
1177 protected:
1178     /*
1179      * Class to work with descriptors from several images as with one merged matrix.
1180      * It is used e.g. in FlannBasedMatcher.
1181      */
1182     class CV_EXPORTS DescriptorCollection
1183     {
1184     public:
1185         DescriptorCollection();
1186         DescriptorCollection( const DescriptorCollection& collection );
1187         virtual ~DescriptorCollection();
1188
1189         // Vector of matrices "descriptors" will be merged to one matrix "mergedDescriptors" here.
1190         void set( const std::vector<Mat>& descriptors );
1191         virtual void clear();
1192
1193         const Mat& getDescriptors() const;
1194         const Mat getDescriptor( int imgIdx, int localDescIdx ) const;
1195         const Mat getDescriptor( int globalDescIdx ) const;
1196         void getLocalIdx( int globalDescIdx, int& imgIdx, int& localDescIdx ) const;
1197
1198         int size() const;
1199
1200     protected:
1201         Mat mergedDescriptors;
1202         std::vector<int> startIdxs;
1203     };
1204
1205     // In fact the matching is implemented only by the following two methods. These methods suppose
1206     // that the class object has been trained already. Public match methods call these methods
1207     // after calling train().
1208     virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
1209         InputArrayOfArrays masks=noArray(), bool compactResult=false ) = 0;
1210     virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1211         InputArrayOfArrays masks=noArray(), bool compactResult=false ) = 0;
1212
1213     static bool isPossibleMatch( InputArray mask, int queryIdx, int trainIdx );
1214     static bool isMaskedOut( InputArrayOfArrays masks, int queryIdx );
1215
1216     static Mat clone_op( Mat m ) { return m.clone(); }
1217     void checkMasks( InputArrayOfArrays masks, int queryDescriptorsCount ) const;
1218
1219     // Collection of descriptors from train images.
1220     std::vector<Mat> trainDescCollection;
1221     std::vector<UMat> utrainDescCollection;
1222 };
1223
1224 /*
1225  * Brute-force descriptor matcher.
1226  *
1227  * For each descriptor in the first set, this matcher finds the closest
1228  * descriptor in the second set by trying each one.
1229  *
1230  * For efficiency, BruteForceMatcher is templated on the distance metric.
1231  * For float descriptors, a common choice would be cv::L2<float>.
1232  */
1233 class CV_EXPORTS_W BFMatcher : public DescriptorMatcher
1234 {
1235 public:
1236     CV_WRAP BFMatcher( int normType=NORM_L2, bool crossCheck=false );
1237     virtual ~BFMatcher() {}
1238
1239     virtual bool isMaskSupported() const { return true; }
1240
1241     virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
1242
1243     AlgorithmInfo* info() const;
1244 protected:
1245     virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
1246         InputArrayOfArrays masks=noArray(), bool compactResult=false );
1247     virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1248         InputArrayOfArrays masks=noArray(), bool compactResult=false );
1249
1250     int normType;
1251     bool crossCheck;
1252 };
1253
1254
1255 /*
1256  * Flann based matcher
1257  */
1258 class CV_EXPORTS_W FlannBasedMatcher : public DescriptorMatcher
1259 {
1260 public:
1261     CV_WRAP FlannBasedMatcher( const Ptr<flann::IndexParams>& indexParams=makePtr<flann::KDTreeIndexParams>(),
1262                        const Ptr<flann::SearchParams>& searchParams=makePtr<flann::SearchParams>() );
1263
1264     virtual void add( InputArrayOfArrays descriptors );
1265     virtual void clear();
1266
1267     // Reads matcher object from a file node
1268     virtual void read( const FileNode& );
1269     // Writes matcher object to a file storage
1270     virtual void write( FileStorage& ) const;
1271
1272     virtual void train();
1273     virtual bool isMaskSupported() const;
1274
1275     virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
1276
1277     AlgorithmInfo* info() const;
1278 protected:
1279     static void convertToDMatches( const DescriptorCollection& descriptors,
1280                                    const Mat& indices, const Mat& distances,
1281                                    std::vector<std::vector<DMatch> >& matches );
1282
1283     virtual void knnMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, int k,
1284         InputArrayOfArrays masks=noArray(), bool compactResult=false );
1285     virtual void radiusMatchImpl( InputArray queryDescriptors, std::vector<std::vector<DMatch> >& matches, float maxDistance,
1286         InputArrayOfArrays masks=noArray(), bool compactResult=false );
1287
1288     Ptr<flann::IndexParams> indexParams;
1289     Ptr<flann::SearchParams> searchParams;
1290     Ptr<flann::Index> flannIndex;
1291
1292     DescriptorCollection mergedDescriptors;
1293     int addedDescCount;
1294 };
1295
1296 /****************************************************************************************\
1297 *                                GenericDescriptorMatcher                                *
1298 \****************************************************************************************/
1299 /*
1300  *   Abstract interface for a keypoint descriptor and matcher
1301  */
1302 class GenericDescriptorMatcher;
1303 typedef GenericDescriptorMatcher GenericDescriptorMatch;
1304
1305 class CV_EXPORTS GenericDescriptorMatcher
1306 {
1307 public:
1308     GenericDescriptorMatcher();
1309     virtual ~GenericDescriptorMatcher();
1310
1311     /*
1312      * Add train collection: images and keypoints from them.
1313      * images       A set of train images.
1314      * ketpoints    Keypoint collection that have been detected on train images.
1315      *
1316      * Keypoints for which a descriptor cannot be computed are removed. Such keypoints
1317      * must be filtered in this method befor adding keypoints to train collection "trainPointCollection".
1318      * If inheritor class need perform such prefiltering the method add() must be overloaded.
1319      * In the other class methods programmer has access to the train keypoints by a constant link.
1320      */
1321     virtual void add( InputArrayOfArrays images,
1322                       std::vector<std::vector<KeyPoint> >& keypoints );
1323
1324     const std::vector<Mat>& getTrainImages() const;
1325     const std::vector<std::vector<KeyPoint> >& getTrainKeypoints() const;
1326
1327     /*
1328      * Clear images and keypoints storing in train collection.
1329      */
1330     virtual void clear();
1331     /*
1332      * Returns true if matcher supports mask to match descriptors.
1333      */
1334     virtual bool isMaskSupported() = 0;
1335     /*
1336      * Train some inner structures (e.g. flann index or decision trees).
1337      * train() methods is run every time in matching methods. So the method implementation
1338      * should has a check whether these inner structures need be trained/retrained or not.
1339      */
1340     virtual void train();
1341
1342     /*
1343      * Classifies query keypoints.
1344      * queryImage    The query image
1345      * queryKeypoints   Keypoints from the query image
1346      * trainImage    The train image
1347      * trainKeypoints   Keypoints from the train image
1348      */
1349     // Classify keypoints from query image under one train image.
1350     void classify( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1351                            InputArray trainImage, std::vector<KeyPoint>& trainKeypoints ) const;
1352     // Classify keypoints from query image under train image collection.
1353     void classify( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints );
1354
1355     /*
1356      * Group of methods to match keypoints from image pair.
1357      * Keypoints for which a descriptor cannot be computed are removed.
1358      * train() method is called here.
1359      */
1360     // Find one best match for each query descriptor (if mask is empty).
1361     void match( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1362                 InputArray trainImage, std::vector<KeyPoint>& trainKeypoints,
1363                 std::vector<DMatch>& matches, InputArray mask=noArray() ) const;
1364     // Find k best matches for each query keypoint (in increasing order of distances).
1365     // compactResult is used when mask is not empty. If compactResult is false matches
1366     // vector will have the same size as queryDescriptors rows.
1367     // If compactResult is true matches vector will not contain matches for fully masked out query descriptors.
1368     void knnMatch( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1369                    InputArray trainImage, std::vector<KeyPoint>& trainKeypoints,
1370                    std::vector<std::vector<DMatch> >& matches, int k,
1371                    InputArray mask=noArray(), bool compactResult=false ) const;
1372     // Find best matches for each query descriptor which have distance less than maxDistance (in increasing order of distances).
1373     void radiusMatch( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1374                       InputArray trainImage, std::vector<KeyPoint>& trainKeypoints,
1375                       std::vector<std::vector<DMatch> >& matches, float maxDistance,
1376                       InputArray mask=noArray(), bool compactResult=false ) const;
1377     /*
1378      * Group of methods to match keypoints from one image to image set.
1379      * See description of similar methods for matching image pair above.
1380      */
1381     void match( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1382                 std::vector<DMatch>& matches, InputArrayOfArrays masks=noArray() );
1383     void knnMatch( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1384                    std::vector<std::vector<DMatch> >& matches, int k,
1385                    InputArrayOfArrays masks=noArray(), bool compactResult=false );
1386     void radiusMatch(InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1387                       std::vector<std::vector<DMatch> >& matches, float maxDistance,
1388                       InputArrayOfArrays masks=noArray(), bool compactResult=false );
1389
1390     // Reads matcher object from a file node
1391     virtual void read( const FileNode& fn );
1392     // Writes matcher object to a file storage
1393     virtual void write( FileStorage& fs ) const;
1394
1395     // Return true if matching object is empty (e.g. feature detector or descriptor matcher are empty)
1396     virtual bool empty() const;
1397
1398     // Clone the matcher. If emptyTrainData is false the method create deep copy of the object, i.e. copies
1399     // both parameters and train data. If emptyTrainData is true the method create object copy with current parameters
1400     // but with empty train data.
1401     virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
1402
1403     static Ptr<GenericDescriptorMatcher> create( const String& genericDescritptorMatcherType,
1404                                                  const String &paramsFilename=String() );
1405
1406 protected:
1407     // In fact the matching is implemented only by the following two methods. These methods suppose
1408     // that the class object has been trained already. Public match methods call these methods
1409     // after calling train().
1410     virtual void knnMatchImpl( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1411                                std::vector<std::vector<DMatch> >& matches, int k,
1412                                InputArrayOfArrays masks, bool compactResult ) = 0;
1413     virtual void radiusMatchImpl( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1414                                   std::vector<std::vector<DMatch> >& matches, float maxDistance,
1415                                   InputArrayOfArrays masks, bool compactResult ) = 0;
1416     /*
1417      * A storage for sets of keypoints together with corresponding images and class IDs
1418      */
1419     class CV_EXPORTS KeyPointCollection
1420     {
1421     public:
1422         KeyPointCollection();
1423         KeyPointCollection( const KeyPointCollection& collection );
1424         void add( const std::vector<Mat>& images, const std::vector<std::vector<KeyPoint> >& keypoints );
1425         void clear();
1426
1427         // Returns the total number of keypoints in the collection
1428         size_t keypointCount() const;
1429         size_t imageCount() const;
1430
1431         const std::vector<std::vector<KeyPoint> >& getKeypoints() const;
1432         const std::vector<KeyPoint>& getKeypoints( int imgIdx ) const;
1433         const KeyPoint& getKeyPoint( int imgIdx, int localPointIdx ) const;
1434         const KeyPoint& getKeyPoint( int globalPointIdx ) const;
1435         void getLocalIdx( int globalPointIdx, int& imgIdx, int& localPointIdx ) const;
1436
1437         const std::vector<Mat>& getImages() const;
1438         const Mat& getImage( int imgIdx ) const;
1439
1440     protected:
1441         int pointCount;
1442
1443         std::vector<Mat> images;
1444         std::vector<std::vector<KeyPoint> > keypoints;
1445         // global indices of the first points in each image, startIndices.size() = keypoints.size()
1446         std::vector<int> startIndices;
1447
1448     private:
1449         static Mat clone_op( Mat m ) { return m.clone(); }
1450     };
1451
1452     KeyPointCollection trainPointCollection;
1453 };
1454
1455
1456 /****************************************************************************************\
1457 *                                VectorDescriptorMatcher                                 *
1458 \****************************************************************************************/
1459
1460 /*
1461  *  A class used for matching descriptors that can be described as vectors in a finite-dimensional space
1462  */
1463 class VectorDescriptorMatcher;
1464 typedef VectorDescriptorMatcher VectorDescriptorMatch;
1465
1466 class CV_EXPORTS VectorDescriptorMatcher : public GenericDescriptorMatcher
1467 {
1468 public:
1469     VectorDescriptorMatcher( const Ptr<DescriptorExtractor>& extractor, const Ptr<DescriptorMatcher>& matcher );
1470     virtual ~VectorDescriptorMatcher();
1471
1472     virtual void add( InputArrayOfArrays imgCollection,
1473                       std::vector<std::vector<KeyPoint> >& pointCollection );
1474
1475     virtual void clear();
1476
1477     virtual void train();
1478
1479     virtual bool isMaskSupported();
1480
1481     virtual void read( const FileNode& fn );
1482     virtual void write( FileStorage& fs ) const;
1483     virtual bool empty() const;
1484
1485     virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
1486
1487 protected:
1488     virtual void knnMatchImpl( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1489                                std::vector<std::vector<DMatch> >& matches, int k,
1490                                InputArrayOfArrays masks, bool compactResult );
1491     virtual void radiusMatchImpl( InputArray queryImage, std::vector<KeyPoint>& queryKeypoints,
1492                                   std::vector<std::vector<DMatch> >& matches, float maxDistance,
1493                                   InputArrayOfArrays masks, bool compactResult );
1494
1495     Ptr<DescriptorExtractor> extractor;
1496     Ptr<DescriptorMatcher> matcher;
1497 };
1498
1499 /****************************************************************************************\
1500 *                                   Drawing functions                                    *
1501 \****************************************************************************************/
1502 struct CV_EXPORTS DrawMatchesFlags
1503 {
1504     enum{ DEFAULT = 0, // Output image matrix will be created (Mat::create),
1505                        // i.e. existing memory of output image may be reused.
1506                        // Two source image, matches and single keypoints will be drawn.
1507                        // For each keypoint only the center point will be drawn (without
1508                        // the circle around keypoint with keypoint size and orientation).
1509           DRAW_OVER_OUTIMG = 1, // Output image matrix will not be created (Mat::create).
1510                                 // Matches will be drawn on existing content of output image.
1511           NOT_DRAW_SINGLE_POINTS = 2, // Single keypoints will not be drawn.
1512           DRAW_RICH_KEYPOINTS = 4 // For each keypoint the circle around keypoint with keypoint size and
1513                                   // orientation will be drawn.
1514         };
1515 };
1516
1517 // Draw keypoints.
1518 CV_EXPORTS_W void drawKeypoints( InputArray image, const std::vector<KeyPoint>& keypoints, InputOutputArray outImage,
1519                                const Scalar& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT );
1520
1521 // Draws matches of keypints from two images on output image.
1522 CV_EXPORTS_W void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
1523                              InputArray img2, const std::vector<KeyPoint>& keypoints2,
1524                              const std::vector<DMatch>& matches1to2, InputOutputArray outImg,
1525                              const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1),
1526                              const std::vector<char>& matchesMask=std::vector<char>(), int flags=DrawMatchesFlags::DEFAULT );
1527
1528 CV_EXPORTS_AS(drawMatchesKnn) void drawMatches( InputArray img1, const std::vector<KeyPoint>& keypoints1,
1529                              InputArray img2, const std::vector<KeyPoint>& keypoints2,
1530                              const std::vector<std::vector<DMatch> >& matches1to2, InputOutputArray outImg,
1531                              const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1),
1532                              const std::vector<std::vector<char> >& matchesMask=std::vector<std::vector<char> >(), int flags=DrawMatchesFlags::DEFAULT );
1533
1534 /****************************************************************************************\
1535 *   Functions to evaluate the feature detectors and [generic] descriptor extractors      *
1536 \****************************************************************************************/
1537
1538 CV_EXPORTS void evaluateFeatureDetector( const Mat& img1, const Mat& img2, const Mat& H1to2,
1539                                          std::vector<KeyPoint>* keypoints1, std::vector<KeyPoint>* keypoints2,
1540                                          float& repeatability, int& correspCount,
1541                                          const Ptr<FeatureDetector>& fdetector=Ptr<FeatureDetector>() );
1542
1543 CV_EXPORTS void computeRecallPrecisionCurve( const std::vector<std::vector<DMatch> >& matches1to2,
1544                                              const std::vector<std::vector<uchar> >& correctMatches1to2Mask,
1545                                              std::vector<Point2f>& recallPrecisionCurve );
1546
1547 CV_EXPORTS float getRecall( const std::vector<Point2f>& recallPrecisionCurve, float l_precision );
1548 CV_EXPORTS int getNearestPoint( const std::vector<Point2f>& recallPrecisionCurve, float l_precision );
1549
1550 CV_EXPORTS void evaluateGenericDescriptorMatcher( const Mat& img1, const Mat& img2, const Mat& H1to2,
1551                                                   std::vector<KeyPoint>& keypoints1, std::vector<KeyPoint>& keypoints2,
1552                                                   std::vector<std::vector<DMatch> >* matches1to2, std::vector<std::vector<uchar> >* correctMatches1to2Mask,
1553                                                   std::vector<Point2f>& recallPrecisionCurve,
1554                                                   const Ptr<GenericDescriptorMatcher>& dmatch=Ptr<GenericDescriptorMatcher>() );
1555
1556
1557 /****************************************************************************************\
1558 *                                     Bag of visual words                                *
1559 \****************************************************************************************/
1560 /*
1561  * Abstract base class for training of a 'bag of visual words' vocabulary from a set of descriptors
1562  */
1563 class CV_EXPORTS_W BOWTrainer
1564 {
1565 public:
1566     BOWTrainer();
1567     virtual ~BOWTrainer();
1568
1569     CV_WRAP void add( const Mat& descriptors );
1570     CV_WRAP const std::vector<Mat>& getDescriptors() const;
1571     CV_WRAP int descriptorsCount() const;
1572
1573     CV_WRAP virtual void clear();
1574
1575     /*
1576      * Train visual words vocabulary, that is cluster training descriptors and
1577      * compute cluster centers.
1578      * Returns cluster centers.
1579      *
1580      * descriptors      Training descriptors computed on images keypoints.
1581      */
1582     CV_WRAP virtual Mat cluster() const = 0;
1583     CV_WRAP virtual Mat cluster( const Mat& descriptors ) const = 0;
1584
1585 protected:
1586     std::vector<Mat> descriptors;
1587     int size;
1588 };
1589
1590 /*
1591  * This is BOWTrainer using cv::kmeans to get vocabulary.
1592  */
1593 class CV_EXPORTS_W BOWKMeansTrainer : public BOWTrainer
1594 {
1595 public:
1596     CV_WRAP BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
1597                       int attempts=3, int flags=KMEANS_PP_CENTERS );
1598     virtual ~BOWKMeansTrainer();
1599
1600     // Returns trained vocabulary (i.e. cluster centers).
1601     CV_WRAP virtual Mat cluster() const;
1602     CV_WRAP virtual Mat cluster( const Mat& descriptors ) const;
1603
1604 protected:
1605
1606     int clusterCount;
1607     TermCriteria termcrit;
1608     int attempts;
1609     int flags;
1610 };
1611
1612 /*
1613  * Class to compute image descriptor using bag of visual words.
1614  */
1615 class CV_EXPORTS_W BOWImgDescriptorExtractor
1616 {
1617 public:
1618     CV_WRAP BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
1619                                const Ptr<DescriptorMatcher>& dmatcher );
1620     BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher );
1621     virtual ~BOWImgDescriptorExtractor();
1622
1623     CV_WRAP void setVocabulary( const Mat& vocabulary );
1624     CV_WRAP const Mat& getVocabulary() const;
1625     void compute( InputArray image, std::vector<KeyPoint>& keypoints, OutputArray imgDescriptor,
1626                   std::vector<std::vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 );
1627     void compute( InputArray keypointDescriptors, OutputArray imgDescriptor,
1628                   std::vector<std::vector<int> >* pointIdxsOfClusters=0 );
1629     // compute() is not constant because DescriptorMatcher::match is not constant
1630
1631     CV_WRAP_AS(compute) void compute2( const Mat& image, std::vector<KeyPoint>& keypoints, CV_OUT Mat& imgDescriptor )
1632     { compute(image,keypoints,imgDescriptor); }
1633
1634     CV_WRAP int descriptorSize() const;
1635     CV_WRAP int descriptorType() const;
1636
1637 protected:
1638     Mat vocabulary;
1639     Ptr<DescriptorExtractor> dextractor;
1640     Ptr<DescriptorMatcher> dmatcher;
1641 };
1642
1643 } /* namespace cv */
1644
1645 #endif