modules/features2d/doc/common_interfaces_of_feature_detectors.rst

   1 Common Interfaces of Feature Detectors
   2 ======================================
   3
   4 .. highlight:: cpp
   5
   6 Feature detectors in OpenCV have wrappers with a common interface that enables you to easily switch
   7 between different algorithms solving the same problem. All objects that implement keypoint detectors
   8 inherit the
   9 :ocv:class:`FeatureDetector` interface.
  10
  11 KeyPoint
  12 --------
  13 .. ocv:class:: KeyPoint
  14
  15   Data structure for salient point detectors.
  16
  17   .. ocv:member:: Point2f pt
  18
  19      coordinates of the keypoint
  20
  21   .. ocv:member:: float size
  22
  23      diameter of the meaningful keypoint neighborhood
  24
  25   .. ocv:member:: float angle
  26
  27      computed orientation of the keypoint (-1 if not applicable). Its possible values are in a range [0,360) degrees. It is measured relative to image coordinate system (y-axis is directed downward), ie in clockwise.
  28
  29   .. ocv:member:: float response
  30
  31      the response by which the most strong keypoints have been selected. Can be used for further sorting or subsampling
  32
  33   .. ocv:member:: int octave
  34
  35      octave (pyramid layer) from which the keypoint has been extracted
  36
  37   .. ocv:member:: int class_id
  38
  39      object id that can be used to clustered keypoints by an object they belong to
  40
  41 KeyPoint::KeyPoint
  42 ------------------
  43 The keypoint constructors
  44
  45 .. ocv:function:: KeyPoint::KeyPoint()
  46
  47 .. ocv:function:: KeyPoint::KeyPoint(Point2f _pt, float _size, float _angle=-1, float _response=0, int _octave=0, int _class_id=-1)
  48
  49 .. ocv:function:: KeyPoint::KeyPoint(float x, float y, float _size, float _angle=-1, float _response=0, int _octave=0, int _class_id=-1)
  50
  51 .. ocv:pyfunction:: cv2.KeyPoint([x, y, _size[, _angle[, _response[, _octave[, _class_id]]]]]) -> <KeyPoint object>
  52
  53     :param x: x-coordinate of the keypoint
  54
  55     :param y: y-coordinate of the keypoint
  56
  57     :param _pt: x & y coordinates of the keypoint
  58
  59     :param _size: keypoint diameter
  60
  61     :param _angle: keypoint orientation
  62
  63     :param _response: keypoint detector response on the keypoint (that is, strength of the keypoint)
  64
  65     :param _octave: pyramid octave in which the keypoint has been detected
  66
  67     :param _class_id: object id
  68
  69
  70 FeatureDetector
  71 ---------------
  72 .. ocv:class:: FeatureDetector : public Algorithm
  73
  74 Abstract base class for 2D image feature detectors. ::
  75
  76     class CV_EXPORTS FeatureDetector
  77     {
  78     public:
  79         virtual ~FeatureDetector();
  80
  81         void detect( const Mat& image, vector<KeyPoint>& keypoints,
  82                      const Mat& mask=Mat() ) const;
  83
  84         void detect( const vector<Mat>& images,
  85                      vector<vector<KeyPoint> >& keypoints,
  86                      const vector<Mat>& masks=vector<Mat>() ) const;
  87
  88         virtual void read(const FileNode&);
  89         virtual void write(FileStorage&) const;
  90
  91         static Ptr<FeatureDetector> create( const string& detectorType );
  92
  93     protected:
  94     ...
  95     };
  96
  97 FeatureDetector::detect
  98 ---------------------------
  99 Detects keypoints in an image (first variant) or image set (second variant).
 100
 101 .. ocv:function:: void FeatureDetector::detect( const Mat& image, vector<KeyPoint>& keypoints, const Mat& mask=Mat() ) const
 102
 103 .. ocv:function:: void FeatureDetector::detect( const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints, const vector<Mat>& masks=vector<Mat>() ) const
 104
 105     :param image: Image.
 106
 107     :param images: Image set.
 108
 109     :param keypoints: The detected keypoints. In the second variant of the method ``keypoints[i]`` is a set of keypoints detected in ``images[i]`` .
 110
 111     :param mask: Mask specifying where to look for keypoints (optional). It must be a 8-bit integer matrix with non-zero values in the region of interest.
 112
 113     :param masks: Masks for each input image specifying where to look for keypoints (optional). ``masks[i]`` is a mask for ``images[i]``.
 114
 115 FeatureDetector::create
 116 -----------------------
 117 Creates a feature detector by its name.
 118
 119 .. ocv:function:: Ptr<FeatureDetector> FeatureDetector::create( const string& detectorType )
 120
 121     :param detectorType: Feature detector type.
 122
 123 The following detector types are supported:
 124
 125 * ``"FAST"`` -- :ocv:class:`FastFeatureDetector`
 126 * ``"STAR"`` -- :ocv:class:`StarFeatureDetector`
 127 * ``"SIFT"`` -- :ocv:class:`SIFT` (nonfree module)
 128 * ``"SURF"`` -- :ocv:class:`SURF` (nonfree module)
 129 * ``"ORB"`` -- :ocv:class:`ORB`
 130 * ``"BRISK"`` -- :ocv:class:`BRISK`
 131 * ``"MSER"`` -- :ocv:class:`MSER`
 132 * ``"GFTT"`` -- :ocv:class:`GoodFeaturesToTrackDetector`
 133 * ``"HARRIS"`` -- :ocv:class:`GoodFeaturesToTrackDetector` with Harris detector enabled
 134 * ``"Dense"`` -- :ocv:class:`DenseFeatureDetector`
 135 * ``"SimpleBlob"`` -- :ocv:class:`SimpleBlobDetector`
 136
 137 Also a combined format is supported: feature detector adapter name ( ``"Grid"`` --
 138 :ocv:class:`GridAdaptedFeatureDetector`, ``"Pyramid"`` --
 139 :ocv:class:`PyramidAdaptedFeatureDetector` ) + feature detector name (see above),
 140 for example: ``"GridFAST"``, ``"PyramidSTAR"`` .
 141
 142 FastFeatureDetector
 143 -------------------
 144 .. ocv:class:: FastFeatureDetector : public FeatureDetector
 145
 146 Wrapping class for feature detection using the
 147 :ocv:func:`FAST` method. ::
 148
 149     class FastFeatureDetector : public FeatureDetector
 150     {
 151     public:
 152         FastFeatureDetector( int threshold=1, bool nonmaxSuppression=true, type=FastFeatureDetector::TYPE_9_16 );
 153         virtual void read( const FileNode& fn );
 154         virtual void write( FileStorage& fs ) const;
 155     protected:
 156         ...
 157     };
 158
 159 GoodFeaturesToTrackDetector
 160 ---------------------------
 161 .. ocv:class:: GoodFeaturesToTrackDetector : public FeatureDetector
 162
 163 Wrapping class for feature detection using the
 164 :ocv:func:`goodFeaturesToTrack` function. ::
 165
 166     class GoodFeaturesToTrackDetector : public FeatureDetector
 167     {
 168     public:
 169         class Params
 170         {
 171         public:
 172             Params( int maxCorners=1000, double qualityLevel=0.01,
 173                     double minDistance=1., int blockSize=3,
 174                     bool useHarrisDetector=false, double k=0.04 );
 175             void read( const FileNode& fn );
 176             void write( FileStorage& fs ) const;
 177
 178             int maxCorners;
 179             double qualityLevel;
 180             double minDistance;
 181             int blockSize;
 182             bool useHarrisDetector;
 183             double k;
 184         };
 185
 186         GoodFeaturesToTrackDetector( const GoodFeaturesToTrackDetector::Params& params=
 187                                                 GoodFeaturesToTrackDetector::Params() );
 188         GoodFeaturesToTrackDetector( int maxCorners, double qualityLevel,
 189                                      double minDistance, int blockSize=3,
 190                                      bool useHarrisDetector=false, double k=0.04 );
 191         virtual void read( const FileNode& fn );
 192         virtual void write( FileStorage& fs ) const;
 193     protected:
 194         ...
 195     };
 196
 197 MserFeatureDetector
 198 -------------------
 199 .. ocv:class:: MserFeatureDetector : public FeatureDetector
 200
 201 Wrapping class for feature detection using the
 202 :ocv:class:`MSER` class. ::
 203
 204     class MserFeatureDetector : public FeatureDetector
 205     {
 206     public:
 207         MserFeatureDetector( CvMSERParams params=cvMSERParams() );
 208         MserFeatureDetector( int delta, int minArea, int maxArea,
 209                              double maxVariation, double minDiversity,
 210                              int maxEvolution, double areaThreshold,
 211                              double minMargin, int edgeBlurSize );
 212         virtual void read( const FileNode& fn );
 213         virtual void write( FileStorage& fs ) const;
 214     protected:
 215         ...
 216     };
 217
 218
 219 StarFeatureDetector
 220 -------------------
 221 .. ocv:class:: StarFeatureDetector : public FeatureDetector
 222
 223 The class implements the keypoint detector introduced by K. Konolige, synonym of ``StarDetector``.  ::
 224
 225     class StarFeatureDetector : public FeatureDetector
 226     {
 227     public:
 228         StarFeatureDetector( int maxSize=16, int responseThreshold=30,
 229                              int lineThresholdProjected = 10,
 230                              int lineThresholdBinarized=8, int suppressNonmaxSize=5 );
 231         virtual void read( const FileNode& fn );
 232         virtual void write( FileStorage& fs ) const;
 233     protected:
 234         ...
 235     };
 236
 237 DenseFeatureDetector
 238 --------------------
 239 .. ocv:class:: DenseFeatureDetector : public FeatureDetector
 240
 241 Class for generation of image features which are distributed densely and regularly over the image. ::
 242
 243         class DenseFeatureDetector : public FeatureDetector
 244         {
 245         public:
 246                 DenseFeatureDetector( float initFeatureScale=1.f, int featureScaleLevels=1,
 247                               float featureScaleMul=0.1f,
 248                               int initXyStep=6, int initImgBound=0,
 249                               bool varyXyStepWithScale=true,
 250                               bool varyImgBoundWithScale=false );
 251         protected:
 252         ...
 253     };
 254
 255 The detector generates several levels (in the amount of ``featureScaleLevels``) of features. Features of each level are located in the nodes of a regular grid over the image (excluding the image boundary of given size). The level parameters (a feature scale, a node size, a size of boundary) are multiplied by ``featureScaleMul`` with level index growing depending on input flags, viz.:
 256
 257 * Feature scale is multiplied always.
 258
 259 * The grid node size is multiplied if ``varyXyStepWithScale`` is ``true``.
 260
 261 * Size of image boundary is multiplied if ``varyImgBoundWithScale`` is ``true``.
 262
 263
 264 SimpleBlobDetector
 265 -------------------
 266 .. ocv:class:: SimpleBlobDetector : public FeatureDetector
 267
 268 Class for extracting blobs from an image. ::
 269
 270     class SimpleBlobDetector : public FeatureDetector
 271     {
 272     public:
 273     struct Params
 274     {
 275         Params();
 276         float thresholdStep;
 277         float minThreshold;
 278         float maxThreshold;
 279         size_t minRepeatability;
 280         float minDistBetweenBlobs;
 281
 282         bool filterByColor;
 283         uchar blobColor;
 284
 285         bool filterByArea;
 286         float minArea, maxArea;
 287
 288         bool filterByCircularity;
 289         float minCircularity, maxCircularity;
 290
 291         bool filterByInertia;
 292         float minInertiaRatio, maxInertiaRatio;
 293
 294         bool filterByConvexity;
 295         float minConvexity, maxConvexity;
 296     };
 297
 298     SimpleBlobDetector(const SimpleBlobDetector::Params &parameters = SimpleBlobDetector::Params());
 299
 300     protected:
 301         ...
 302     };
 303
 304 The class implements a simple algorithm for extracting blobs from an image:
 305
 306 #. Convert the source image to binary images by applying thresholding with several thresholds from ``minThreshold`` (inclusive) to ``maxThreshold`` (exclusive) with distance ``thresholdStep`` between neighboring thresholds.
 307
 308 #. Extract connected components from every binary image by  :ocv:func:`findContours`  and calculate their centers.
 309
 310 #. Group centers from several binary images by their coordinates. Close centers form one group that corresponds to one blob, which is controlled by the ``minDistBetweenBlobs`` parameter.
 311
 312 #. From the groups, estimate final centers of blobs and their radiuses and return as locations and sizes of keypoints.
 313
 314 This class performs several filtrations of returned blobs. You should set ``filterBy*`` to true/false to turn on/off corresponding filtration. Available filtrations:
 315
 316  * **By color**. This filter compares the intensity of a binary image at the center of a blob to ``blobColor``. If they differ, the blob is filtered out. Use ``blobColor = 0`` to extract dark blobs and ``blobColor = 255`` to extract light blobs.
 317
 318  * **By area**. Extracted blobs have an area between ``minArea`` (inclusive) and ``maxArea`` (exclusive).
 319
 320  * **By circularity**. Extracted blobs have circularity (:math:`\frac{4*\pi*Area}{perimeter * perimeter}`) between ``minCircularity`` (inclusive) and ``maxCircularity`` (exclusive).
 321
 322  * **By ratio of the minimum inertia to maximum inertia**. Extracted blobs have this ratio between ``minInertiaRatio`` (inclusive) and ``maxInertiaRatio`` (exclusive).
 323
 324  * **By convexity**. Extracted blobs have convexity (area / area of blob convex hull) between ``minConvexity`` (inclusive) and ``maxConvexity`` (exclusive).
 325
 326
 327 Default values of parameters are tuned to extract dark circular blobs.
 328
 329 GridAdaptedFeatureDetector
 330 --------------------------
 331 .. ocv:class:: GridAdaptedFeatureDetector : public FeatureDetector
 332
 333 Class adapting a detector to partition the source image into a grid and detect points in each cell. ::
 334
 335     class GridAdaptedFeatureDetector : public FeatureDetector
 336     {
 337     public:
 338         /*
 339          * detector            Detector that will be adapted.
 340          * maxTotalKeypoints   Maximum count of keypoints detected on the image.
 341          *                     Only the strongest keypoints will be kept.
 342          * gridRows            Grid row count.
 343          * gridCols            Grid column count.
 344          */
 345         GridAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
 346                                     int maxTotalKeypoints, int gridRows=4,
 347                                     int gridCols=4 );
 348         virtual void read( const FileNode& fn );
 349         virtual void write( FileStorage& fs ) const;
 350     protected:
 351         ...
 352     };
 353
 354 PyramidAdaptedFeatureDetector
 355 -----------------------------
 356 .. ocv:class:: PyramidAdaptedFeatureDetector : public FeatureDetector
 357
 358 Class adapting a detector to detect points over multiple levels of a Gaussian pyramid. Consider using this class for detectors that are not inherently scaled. ::
 359
 360     class PyramidAdaptedFeatureDetector : public FeatureDetector
 361     {
 362     public:
 363         PyramidAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
 364                                        int levels=2 );
 365         virtual void read( const FileNode& fn );
 366         virtual void write( FileStorage& fs ) const;
 367     protected:
 368         ...
 369     };
 370
 371
 372 DynamicAdaptedFeatureDetector
 373 -----------------------------
 374 .. ocv:class:: DynamicAdaptedFeatureDetector : public FeatureDetector
 375
 376 Adaptively adjusting detector that iteratively detects features until the desired number is found. ::
 377
 378        class DynamicAdaptedFeatureDetector: public FeatureDetector
 379        {
 380        public:
 381            DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster,
 382                int min_features=400, int max_features=500, int max_iters=5 );
 383            ...
 384        };
 385
 386 If the detector is persisted, it "remembers" the parameters
 387 used for the last detection. In this case, the detector may be used for consistent numbers
 388 of keypoints in a set of temporally related images, such as video streams or
 389 panorama series.
 390
 391 ``DynamicAdaptedFeatureDetector``  uses another detector, such as FAST or SURF, to do the dirty work,
 392 with the help of ``AdjusterAdapter`` .
 393 If the detected number of features is not large enough,
 394 ``AdjusterAdapter`` adjusts the detection parameters so that the next detection
 395 results in a bigger or smaller number of features.  This is repeated until either the number of desired features are found
 396 or the parameters are maxed out.
 397
 398 Adapters can be easily implemented for any detector via the
 399 ``AdjusterAdapter`` interface.
 400
 401 Beware that this is not thread-safe since the adjustment of parameters requires modification of the feature detector class instance.
 402
 403 Example of creating ``DynamicAdaptedFeatureDetector`` : ::
 404
 405     //sample usage:
 406     //will create a detector that attempts to find
 407     //100 - 110 FAST Keypoints, and will at most run
 408     //FAST feature detection 10 times until that
 409     //number of keypoints are found
 410     Ptr<FeatureDetector> detector(new DynamicAdaptedFeatureDetector (100, 110, 10,
 411                                   new FastAdjuster(20,true)));
 412
 413
 414 DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector
 415 ------------------------------------------------------------
 416 The constructor
 417
 418 .. ocv:function:: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster, int min_features=400, int max_features=500, int max_iters=5 )
 419
 420     :param adjuster:  :ocv:class:`AdjusterAdapter`  that detects features and adjusts parameters.
 421
 422     :param min_features: Minimum desired number of features.
 423
 424     :param max_features: Maximum desired number of features.
 425
 426     :param max_iters: Maximum number of times to try adjusting the feature detector parameters. For :ocv:class:`FastAdjuster` , this number can be high, but with ``Star`` or ``Surf``  many iterations can be time-consuming.  At each iteration the detector is rerun.
 427
 428 AdjusterAdapter
 429 ---------------
 430 .. ocv:class:: AdjusterAdapter : public FeatureDetector
 431
 432 Class providing an interface for adjusting parameters of a feature detector. This interface is used by :ocv:class:`DynamicAdaptedFeatureDetector` . It is a wrapper for :ocv:class:`FeatureDetector` that enables adjusting parameters after feature detection. ::
 433
 434      class AdjusterAdapter: public FeatureDetector
 435      {
 436      public:
 437         virtual ~AdjusterAdapter() {}
 438         virtual void tooFew(int min, int n_detected) = 0;
 439         virtual void tooMany(int max, int n_detected) = 0;
 440         virtual bool good() const = 0;
 441         virtual Ptr<AdjusterAdapter> clone() const = 0;
 442         static Ptr<AdjusterAdapter> create( const string& detectorType );
 443      };
 444
 445
 446 See
 447 :ocv:class:`FastAdjuster`,
 448 :ocv:class:`StarAdjuster`, and
 449 :ocv:class:`SurfAdjuster` for concrete implementations.
 450
 451 AdjusterAdapter::tooFew
 452 ---------------------------
 453 Adjusts the detector parameters to detect more features.
 454
 455 .. ocv:function:: void AdjusterAdapter::tooFew(int min, int n_detected)
 456
 457     :param min: Minimum desired number of features.
 458
 459     :param n_detected: Number of features detected during the latest run.
 460
 461 Example: ::
 462
 463     void FastAdjuster::tooFew(int min, int n_detected)
 464     {
 465             thresh_--;
 466     }
 467
 468 AdjusterAdapter::tooMany
 469 ----------------------------
 470 Adjusts the detector parameters to detect less features.
 471
 472 .. ocv:function:: void AdjusterAdapter::tooMany(int max, int n_detected)
 473
 474     :param max: Maximum desired number of features.
 475
 476     :param n_detected: Number of features detected during the latest run.
 477
 478 Example: ::
 479
 480     void FastAdjuster::tooMany(int min, int n_detected)
 481     {
 482             thresh_++;
 483     }
 484
 485
 486 AdjusterAdapter::good
 487 ---------------------
 488 Returns false if the detector parameters cannot be adjusted any more.
 489
 490 .. ocv:function:: bool AdjusterAdapter::good() const
 491
 492 Example: ::
 493
 494         bool FastAdjuster::good() const
 495         {
 496                 return (thresh_ > 1) && (thresh_ < 200);
 497         }
 498
 499 AdjusterAdapter::create
 500 -----------------------
 501 Creates an adjuster adapter by name
 502
 503 .. ocv:function:: Ptr<AdjusterAdapter> AdjusterAdapter::create( const string& detectorType )
 504
 505     Creates an adjuster adapter by name ``detectorType``. The detector name is the same as in :ocv:func:`FeatureDetector::create`, but now supports ``"FAST"``, ``"STAR"``, and ``"SURF"`` only.
 506
 507 FastAdjuster
 508 ------------
 509 .. ocv:class:: FastAdjuster : public AdjusterAdapter
 510
 511 :ocv:class:`AdjusterAdapter` for :ocv:class:`FastFeatureDetector`. This class decreases or increases the threshold value by 1. ::
 512
 513         class FastAdjuster FastAdjuster: public AdjusterAdapter
 514         {
 515         public:
 516                 FastAdjuster(int init_thresh = 20, bool nonmax = true);
 517                 ...
 518         };
 519
 520 StarAdjuster
 521 ------------
 522 .. ocv:class:: StarAdjuster : public AdjusterAdapter
 523
 524 :ocv:class:`AdjusterAdapter` for :ocv:class:`StarFeatureDetector`. This class adjusts the ``responseThreshhold`` of ``StarFeatureDetector``.  ::
 525
 526         class StarAdjuster: public AdjusterAdapter
 527         {
 528                 StarAdjuster(double initial_thresh = 30.0);
 529                 ...
 530         };
 531
 532 SurfAdjuster
 533 ------------
 534 .. ocv:class:: SurfAdjuster : public AdjusterAdapter
 535
 536 :ocv:class:`AdjusterAdapter` for ``SurfFeatureDetector``.  ::
 537
 538     class CV_EXPORTS SurfAdjuster: public AdjusterAdapter
 539     {
 540     public:
 541         SurfAdjuster( double initial_thresh=400.f, double min_thresh=2, double max_thresh=1000 );
 542
 543         virtual void tooFew(int minv, int n_detected);
 544         virtual void tooMany(int maxv, int n_detected);
 545         virtual bool good() const;
 546
 547         virtual Ptr<AdjusterAdapter> clone() const;
 548
 549         ...
 550     };