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