modules/features2d/doc/feature_detection_and_description.rst

   1 Feature Detection and Description
   2 =================================
   3
   4 .. highlight:: cpp
   5
   6 .. note::
   7
   8    * An example explaining keypoint detection and description can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
   9
  10 FAST
  11 ----
  12 Detects corners using the FAST algorithm
  13
  14 .. ocv:function:: void FAST( InputArray image, vector<KeyPoint>& keypoints, int threshold, bool nonmaxSuppression=true )
  15 .. ocv:function:: void FAST( InputArray image, vector<KeyPoint>& keypoints, int threshold, bool nonmaxSuppression, int type )
  16
  17     :param image: grayscale image where keypoints (corners) are detected.
  18
  19     :param keypoints: keypoints detected on the image.
  20
  21     :param threshold: threshold on difference between intensity of the central pixel and pixels of a circle around this pixel.
  22
  23     :param nonmaxSuppression: if true, non-maximum suppression is applied to detected corners (keypoints).
  24
  25     :param type: one of the three neighborhoods as defined in the paper: ``FastFeatureDetector::TYPE_9_16``, ``FastFeatureDetector::TYPE_7_12``, ``FastFeatureDetector::TYPE_5_8``
  26
  27 Detects corners using the FAST algorithm by [Rosten06]_.
  28
  29 .. note:: In Python API, types are given as ``cv2.FAST_FEATURE_DETECTOR_TYPE_5_8``, ``cv2.FAST_FEATURE_DETECTOR_TYPE_7_12`` and  ``cv2.FAST_FEATURE_DETECTOR_TYPE_9_16``. For corner detection, use ``cv2.FAST.detect()`` method.
  30
  31
  32 .. [Rosten06] E. Rosten. Machine Learning for High-speed Corner Detection, 2006.
  33
  34 MSER
  35 ----
  36 .. ocv:class:: MSER : public FeatureDetector
  37
  38 Maximally stable extremal region extractor. ::
  39
  40     class MSER : public CvMSERParams
  41     {
  42     public:
  43         // default constructor
  44         MSER();
  45         // constructor that initializes all the algorithm parameters
  46         MSER( int _delta, int _min_area, int _max_area,
  47               float _max_variation, float _min_diversity,
  48               int _max_evolution, double _area_threshold,
  49               double _min_margin, int _edge_blur_size );
  50         // runs the extractor on the specified image; returns the MSERs,
  51         // each encoded as a contour (vector<Point>, see findContours)
  52         // the optional mask marks the area where MSERs are searched for
  53         void detectRegions( InputArray image, vector<vector<Point> >& msers, vector<Rect>& bboxes ) const;
  54     };
  55
  56 The class encapsulates all the parameters of the MSER extraction algorithm (see
  57 http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions). Also see http://code.opencv.org/projects/opencv/wiki/MSER for useful comments and parameters description.
  58
  59 .. note::
  60
  61    * (Python) A complete example showing the use of the MSER detector can be found at opencv_source_code/samples/python2/mser.py
  62
  63
  64 ORB
  65 ---
  66 .. ocv:class:: ORB : public Feature2D
  67
  68 Class implementing the ORB (*oriented BRIEF*) keypoint detector and descriptor extractor, described in [RRKB11]_. The algorithm uses FAST in pyramids to detect stable keypoints, selects the strongest features using FAST or Harris response, finds their orientation using first-order moments and computes the descriptors using BRIEF (where the coordinates of random point pairs (or k-tuples) are rotated according to the measured orientation).
  69
  70 .. [RRKB11] Ethan Rublee, Vincent Rabaud, Kurt Konolige, Gary R. Bradski: ORB: An efficient alternative to SIFT or SURF. ICCV 2011: 2564-2571.
  71
  72 ORB::ORB
  73 --------
  74 The ORB constructor
  75
  76 .. ocv:function:: ORB::ORB(int nfeatures = 500, float scaleFactor = 1.2f, int nlevels = 8, int edgeThreshold = 31, int firstLevel = 0, int WTA_K=2, int scoreType=ORB::HARRIS_SCORE, int patchSize=31)
  77
  78 .. ocv:pyfunction:: cv2.ORB([, nfeatures[, scaleFactor[, nlevels[, edgeThreshold[, firstLevel[, WTA_K[, scoreType[, patchSize]]]]]]]]) -> <ORB object>
  79
  80
  81     :param nfeatures: The maximum number of features to retain.
  82
  83     :param scaleFactor: Pyramid decimation ratio, greater than 1. ``scaleFactor==2`` means the classical pyramid, where each next level has 4x less pixels than the previous, but such a big scale factor will degrade feature matching scores dramatically. On the other hand, too close to 1 scale factor will mean that to cover certain scale range you will need more pyramid levels and so the speed will suffer.
  84
  85     :param nlevels: The number of pyramid levels. The smallest level will have linear size equal to ``input_image_linear_size/pow(scaleFactor, nlevels)``.
  86
  87     :param edgeThreshold: This is size of the border where the features are not detected. It should roughly match the ``patchSize`` parameter.
  88
  89     :param firstLevel: It should be 0 in the current implementation.
  90
  91     :param WTA_K: The number of points that produce each element of the oriented BRIEF descriptor. The default value 2 means the BRIEF where we take a random point pair and compare their brightnesses, so we get 0/1 response. Other possible values are 3 and 4. For example, 3 means that we take 3 random points (of course, those point coordinates are random, but they are generated from the pre-defined seed, so each element of BRIEF descriptor is computed deterministically from the pixel rectangle), find point of maximum brightness and output index of the winner (0, 1 or 2). Such output will occupy 2 bits, and therefore it will need a special variant of Hamming distance, denoted as ``NORM_HAMMING2`` (2 bits per bin).  When ``WTA_K=4``, we take 4 random points to compute each bin (that will also occupy 2 bits with possible values 0, 1, 2 or 3).
  92
  93     :param scoreType: The default HARRIS_SCORE means that Harris algorithm is used to rank features (the score is written to ``KeyPoint::score`` and is used to retain best ``nfeatures`` features); FAST_SCORE is alternative value of the parameter that produces slightly less stable keypoints, but it is a little faster to compute.
  94
  95     :param patchSize: size of the patch used by the oriented BRIEF descriptor. Of course, on smaller pyramid layers the perceived image area covered by a feature will be larger.
  96
  97 ORB::operator()
  98 ---------------
  99 Finds keypoints in an image and computes their descriptors
 100
 101 .. ocv:function:: void ORB::operator()(InputArray image, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false ) const
 102
 103 .. ocv:pyfunction:: cv2.ORB.detect(image[, mask]) -> keypoints
 104 .. ocv:pyfunction:: cv2.ORB.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
 105 .. ocv:pyfunction:: cv2.ORB.detectAndCompute(image, mask[, descriptors[, useProvidedKeypoints]]) -> keypoints, descriptors
 106
 107
 108     :param image: The input 8-bit grayscale image.
 109
 110     :param mask: The operation mask.
 111
 112     :param keypoints: The output vector of keypoints.
 113
 114     :param descriptors: The output descriptors. Pass ``cv::noArray()`` if you do not need it.
 115
 116     :param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
 117
 118
 119 BRISK
 120 -----
 121 .. ocv:class:: BRISK : public Feature2D
 122
 123 Class implementing the BRISK keypoint detector and descriptor extractor, described in [LCS11]_.
 124
 125 .. [LCS11] Stefan Leutenegger, Margarita Chli and Roland Siegwart: BRISK: Binary Robust Invariant Scalable Keypoints. ICCV 2011: 2548-2555.
 126
 127 BRISK::BRISK
 128 ------------
 129 The BRISK constructor
 130
 131 .. ocv:function:: BRISK::BRISK(int thresh=30, int octaves=3, float patternScale=1.0f)
 132
 133 .. ocv:pyfunction:: cv2.BRISK([, thresh[, octaves[, patternScale]]]) -> <BRISK object>
 134
 135     :param thresh: FAST/AGAST detection threshold score.
 136
 137     :param octaves: detection octaves. Use 0 to do single scale.
 138
 139     :param patternScale: apply this scale to the pattern used for sampling the neighbourhood of a keypoint.
 140
 141 BRISK::BRISK
 142 ------------
 143 The BRISK constructor for a custom pattern
 144
 145 .. ocv:function:: BRISK::BRISK(std::vector<float> &radiusList, std::vector<int> &numberList, float dMax=5.85f, float dMin=8.2f, std::vector<int> indexChange=std::vector<int>())
 146
 147 .. ocv:pyfunction:: cv2.BRISK(radiusList, numberList[, dMax[, dMin[, indexChange]]]) -> <BRISK object>
 148
 149     :param radiusList: defines the radii (in pixels) where the samples around a keypoint are taken (for keypoint scale 1).
 150
 151     :param numberList: defines the number of sampling points on the sampling circle. Must be the same size as radiusList..
 152
 153     :param dMax: threshold for the short pairings used for descriptor formation (in pixels for keypoint scale 1).
 154
 155     :param dMin: threshold for the long pairings used for orientation determination (in pixels for keypoint scale 1).
 156
 157     :param indexChanges: index remapping of the bits.
 158
 159 BRISK::operator()
 160 -----------------
 161 Finds keypoints in an image and computes their descriptors
 162
 163 .. ocv:function:: void BRISK::operator()(InputArray image, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false ) const
 164
 165 .. ocv:pyfunction:: cv2.BRISK.detect(image[, mask]) -> keypoints
 166 .. ocv:pyfunction:: cv2.BRISK.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
 167 .. ocv:pyfunction:: cv2.BRISK.detectAndCompute(image, mask[, descriptors[, useProvidedKeypoints]]) -> keypoints, descriptors
 168
 169     :param image: The input 8-bit grayscale image.
 170
 171     :param mask: The operation mask.
 172
 173     :param keypoints: The output vector of keypoints.
 174
 175     :param descriptors: The output descriptors. Pass ``cv::noArray()`` if you do not need it.
 176
 177     :param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
 178
 179 KAZE
 180 ----
 181 .. ocv:class:: KAZE : public Feature2D
 182
 183 Class implementing the KAZE keypoint detector and descriptor extractor, described in [ABD12]_. ::
 184
 185     class CV_EXPORTS_W KAZE : public Feature2D
 186     {
 187     public:
 188         CV_WRAP KAZE();
 189         CV_WRAP explicit KAZE(bool extended, bool upright, float threshold = 0.001f,
 190                               int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
 191     };
 192
 193 .. note:: AKAZE descriptor can only be used with KAZE or AKAZE keypoints
 194
 195 .. [ABD12] KAZE Features. Pablo F. Alcantarilla, Adrien Bartoli and Andrew J. Davison. In European Conference on Computer Vision (ECCV), Fiorenze, Italy, October 2012.
 196
 197 KAZE::KAZE
 198 ----------
 199 The KAZE constructor
 200
 201 .. ocv:function:: KAZE::KAZE(bool extended, bool upright, float threshold, int octaves, int sublevels, int diffusivity)
 202
 203     :param extended: Set to enable extraction of extended (128-byte) descriptor.
 204     :param upright: Set to enable use of upright descriptors (non rotation-invariant).
 205     :param threshold: Detector response threshold to accept point
 206     :param octaves: Maximum octave evolution of the image
 207     :param sublevels: Default number of sublevels per scale level
 208     :param diffusivity: Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or DIFF_CHARBONNIER
 209
 210 AKAZE
 211 -----
 212 .. ocv:class:: AKAZE : public Feature2D
 213
 214 Class implementing the AKAZE keypoint detector and descriptor extractor, described in [ANB13]_. ::
 215
 216     class CV_EXPORTS_W AKAZE : public Feature2D
 217     {
 218     public:
 219         CV_WRAP AKAZE();
 220         CV_WRAP explicit AKAZE(int descriptor_type, int descriptor_size = 0, int descriptor_channels = 3,
 221                                float threshold = 0.001f, int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
 222     };
 223
 224 .. note:: AKAZE descriptors can only be used with KAZE or AKAZE keypoints. Try to avoid using *extract* and *detect* instead of *operator()* due to performance reasons.
 225
 226 .. [ANB13] Fast Explicit Diffusion for Accelerated Features in Nonlinear Scale Spaces. Pablo F. Alcantarilla, Jesús Nuevo and Adrien Bartoli. In British Machine Vision Conference (BMVC), Bristol, UK, September 2013.
 227
 228 AKAZE::AKAZE
 229 ------------
 230 The AKAZE constructor
 231
 232 .. ocv:function:: AKAZE::AKAZE(int descriptor_type, int descriptor_size, int descriptor_channels, float threshold, int octaves, int sublevels, int diffusivity)
 233
 234     :param descriptor_type: Type of the extracted descriptor: DESCRIPTOR_KAZE, DESCRIPTOR_KAZE_UPRIGHT, DESCRIPTOR_MLDB or DESCRIPTOR_MLDB_UPRIGHT.
 235     :param descriptor_size: Size of the descriptor in bits. 0 -> Full size
 236     :param descriptor_channels: Number of channels in the descriptor (1, 2, 3)
 237     :param threshold: Detector response threshold to accept point
 238     :param octaves: Maximum octave evolution of the image
 239     :param sublevels: Default number of sublevels per scale level
 240     :param diffusivity: Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or DIFF_CHARBONNIER
 241
 242 SIFT
 243 ----
 244
 245 .. ocv:class:: SIFT : public Feature2D
 246
 247 The SIFT algorithm has been moved to opencv_contrib/xfeatures2d module.