modules/nonfree/doc/feature_detection.rst

   1 Feature Detection and Description
   2 =================================
   3
   4 SIFT
   5 ----
   6 .. ocv:class:: SIFT : public Feature2D
   7
   8 Class for extracting keypoints and computing descriptors using the Scale Invariant Feature Transform (SIFT) algorithm by D. Lowe [Lowe04]_.
   9
  10 .. [Lowe04] Lowe, D. G., “Distinctive Image Features from Scale-Invariant Keypoints”, International Journal of Computer Vision, 60, 2, pp. 91-110, 2004.
  11
  12
  13 SIFT::SIFT
  14 ----------
  15 The SIFT constructors.
  16
  17 .. ocv:function:: SIFT::SIFT( int nfeatures=0, int nOctaveLayers=3, double contrastThreshold=0.04, double edgeThreshold=10, double sigma=1.6)
  18
  19     :param nfeatures: The number of best features to retain. The features are ranked by their scores (measured in SIFT algorithm as the local contrast)
  20
  21     :param nOctaveLayers: The number of layers in each octave. 3 is the value used in D. Lowe paper. The number of octaves is computed automatically from the image resolution.
  22
  23     :param contrastThreshold: The contrast threshold used to filter out weak features in semi-uniform (low-contrast) regions. The larger the threshold, the less features are produced by the detector.
  24
  25     :param edgeThreshold: The threshold used to filter out edge-like features. Note that the its meaning is different from the contrastThreshold, i.e. the larger the ``edgeThreshold``, the less features are filtered out (more features are retained).
  26
  27     :param sigma: The sigma of the Gaussian applied to the input image at the octave #0. If your image is captured with a weak camera with soft lenses, you might want to reduce the number.
  28
  29
  30 SIFT::operator ()
  31 -----------------
  32 Extract features and computes their descriptors using SIFT algorithm
  33
  34 .. ocv:function:: void SIFT::operator()(InputArray img, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false)
  35
  36     :param img: Input 8-bit grayscale image
  37
  38     :param mask: Optional input mask that marks the regions where we should detect features.
  39
  40     :param keypoints: The input/output vector of keypoints
  41
  42     :param descriptors: The output matrix of descriptors. Pass ``cv::noArray()`` if you do not need them.
  43
  44     :param useProvidedKeypoints: Boolean flag. If it is true, the keypoint detector is not run. Instead, the provided vector of keypoints is used and the algorithm just computes their descriptors.
  45
  46
  47 SURF
  48 ----
  49 .. ocv:class:: SURF : public Feature2D
  50
  51   Class for extracting Speeded Up Robust Features from an image [Bay06]_. The class is derived from ``CvSURFParams`` structure, which specifies the algorithm parameters:
  52
  53   .. ocv:member:: int extended
  54
  55      * 0 means that the basic descriptors (64 elements each) shall be computed
  56      * 1 means that the extended descriptors (128 elements each) shall be computed
  57
  58   .. ocv:member:: int upright
  59
  60      * 0 means that detector computes orientation of each feature.
  61      * 1 means that the orientation is not computed (which is much, much faster). For example, if you match images from a stereo pair, or do image stitching, the matched features likely have very similar angles, and you can speed up feature extraction by setting ``upright=1``.
  62
  63   .. ocv:member:: double hessianThreshold
  64
  65      Threshold for the keypoint detector. Only features, whose hessian is larger than ``hessianThreshold`` are retained by the detector. Therefore, the larger the value, the less keypoints you will get. A good default value could be from 300 to 500, depending from the image contrast.
  66
  67   .. ocv:member:: int nOctaves
  68
  69      The number of a gaussian pyramid octaves that the detector uses. It is set to 4 by default. If you want to get very large features, use the larger value. If you want just small features, decrease it.
  70
  71   .. ocv:member:: int nOctaveLayers
  72
  73      The number of images within each octave of a gaussian pyramid. It is set to 2 by default.
  74
  75
  76 .. [Bay06] Bay, H. and Tuytelaars, T. and Van Gool, L. "SURF: Speeded Up Robust Features", 9th European Conference on Computer Vision, 2006
  77
  78 .. note::
  79
  80    * An example using the SURF feature detector can be found at opencv_source_code/samples/cpp/generic_descriptor_match.cpp
  81    * Another example using the SURF feature detector, extractor and matcher can be found at opencv_source_code/samples/cpp/matcher_simple.cpp
  82
  83 SURF::SURF
  84 ----------
  85 The SURF extractor constructors.
  86
  87 .. ocv:function:: SURF::SURF()
  88
  89 .. ocv:function:: SURF::SURF( double hessianThreshold, int nOctaves=4, int nOctaveLayers=2, bool extended=true, bool upright=false )
  90
  91 .. ocv:pyfunction:: cv2.SURF([hessianThreshold[, nOctaves[, nOctaveLayers[, extended[, upright]]]]]) -> <SURF object>
  92
  93     :param hessianThreshold: Threshold for hessian keypoint detector used in SURF.
  94
  95     :param nOctaves: Number of pyramid octaves the keypoint detector will use.
  96
  97     :param nOctaveLayers: Number of octave layers within each octave.
  98
  99     :param extended: Extended descriptor flag (true - use extended 128-element descriptors; false - use 64-element descriptors).
 100
 101     :param upright: Up-right or rotated features flag (true - do not compute orientation of features; false - compute orientation).
 102
 103
 104 SURF::operator()
 105 ----------------
 106 Detects keypoints and computes SURF descriptors for them.
 107
 108 .. ocv:function:: void SURF::operator()(InputArray img, InputArray mask, vector<KeyPoint>& keypoints) const
 109 .. ocv:function:: void SURF::operator()(InputArray img, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false)
 110
 111 .. ocv:pyfunction:: cv2.SURF.detect(image[, mask]) -> keypoints
 112
 113 .. ocv:cfunction:: void cvExtractSURF( const CvArr* image, const CvArr* mask, CvSeq** keypoints, CvSeq** descriptors, CvMemStorage* storage, CvSURFParams params )
 114
 115 .. ocv:pyoldfunction:: cv.ExtractSURF(image, mask, storage, params)-> (keypoints, descriptors)
 116
 117     :param image: Input 8-bit grayscale image
 118
 119     :param mask: Optional input mask that marks the regions where we should detect features.
 120
 121     :param keypoints: The input/output vector of keypoints
 122
 123     :param descriptors: The output matrix of descriptors. Pass ``cv::noArray()`` if you do not need them.
 124
 125     :param useProvidedKeypoints: Boolean flag. If it is true, the keypoint detector is not run. Instead, the provided vector of keypoints is used and the algorithm just computes their descriptors.
 126
 127     :param storage: Memory storage for the output keypoints and descriptors in OpenCV 1.x API.
 128
 129     :param params: SURF algorithm parameters in OpenCV 1.x API.
 130
 131 The function is parallelized with the TBB library.
 132
 133 If you are using the C version, make sure you call ``cv::initModule_nonfree()`` from ``nonfree/nonfree.hpp``.
 134
 135
 136 gpu::SURF_GPU
 137 -------------
 138 .. ocv:class:: gpu::SURF_GPU
 139
 140 Class used for extracting Speeded Up Robust Features (SURF) from an image. ::
 141
 142     class SURF_GPU
 143     {
 144     public:
 145         enum KeypointLayout
 146         {
 147             X_ROW = 0,
 148             Y_ROW,
 149             LAPLACIAN_ROW,
 150             OCTAVE_ROW,
 151             SIZE_ROW,
 152             ANGLE_ROW,
 153             HESSIAN_ROW,
 154             ROWS_COUNT
 155         };
 156
 157         //! the default constructor
 158         SURF_GPU();
 159         //! the full constructor taking all the necessary parameters
 160         explicit SURF_GPU(double _hessianThreshold, int _nOctaves=4,
 161              int _nOctaveLayers=2, bool _extended=false, float _keypointsRatio=0.01f);
 162
 163         //! returns the descriptor size in float's (64 or 128)
 164         int descriptorSize() const;
 165
 166         //! upload host keypoints to device memory
 167         void uploadKeypoints(const vector<KeyPoint>& keypoints,
 168             GpuMat& keypointsGPU);
 169         //! download keypoints from device to host memory
 170         void downloadKeypoints(const GpuMat& keypointsGPU,
 171             vector<KeyPoint>& keypoints);
 172
 173         //! download descriptors from device to host memory
 174         void downloadDescriptors(const GpuMat& descriptorsGPU,
 175             vector<float>& descriptors);
 176
 177         void operator()(const GpuMat& img, const GpuMat& mask,
 178             GpuMat& keypoints);
 179
 180         void operator()(const GpuMat& img, const GpuMat& mask,
 181             GpuMat& keypoints, GpuMat& descriptors,
 182             bool useProvidedKeypoints = false,
 183             bool calcOrientation = true);
 184
 185         void operator()(const GpuMat& img, const GpuMat& mask,
 186             std::vector<KeyPoint>& keypoints);
 187
 188         void operator()(const GpuMat& img, const GpuMat& mask,
 189             std::vector<KeyPoint>& keypoints, GpuMat& descriptors,
 190             bool useProvidedKeypoints = false,
 191             bool calcOrientation = true);
 192
 193         void operator()(const GpuMat& img, const GpuMat& mask,
 194             std::vector<KeyPoint>& keypoints,
 195             std::vector<float>& descriptors,
 196             bool useProvidedKeypoints = false,
 197             bool calcOrientation = true);
 198
 199         void releaseMemory();
 200
 201         // SURF parameters
 202         double hessianThreshold;
 203         int nOctaves;
 204         int nOctaveLayers;
 205         bool extended;
 206         bool upright;
 207
 208         //! max keypoints = keypointsRatio * img.size().area()
 209         float keypointsRatio;
 210
 211         GpuMat sum, mask1, maskSum, intBuffer;
 212
 213         GpuMat det, trace;
 214
 215         GpuMat maxPosBuffer;
 216     };
 217
 218
 219 The class ``SURF_GPU`` implements Speeded Up Robust Features descriptor. There is a fast multi-scale Hessian keypoint detector that can be used to find the keypoints (which is the default option). But the descriptors can also be computed for the user-specified keypoints. Only 8-bit grayscale images are supported.
 220
 221 The class ``SURF_GPU`` can store results in the GPU and CPU memory. It provides functions to convert results between CPU and GPU version ( ``uploadKeypoints``, ``downloadKeypoints``, ``downloadDescriptors`` ). The format of CPU results is the same as ``SURF`` results. GPU results are stored in ``GpuMat``. The ``keypoints`` matrix is :math:`\texttt{nFeatures} \times 7` matrix with the ``CV_32FC1`` type.
 222
 223 * ``keypoints.ptr<float>(X_ROW)[i]`` contains x coordinate of the i-th feature.
 224 * ``keypoints.ptr<float>(Y_ROW)[i]`` contains y coordinate of the i-th feature.
 225 * ``keypoints.ptr<float>(LAPLACIAN_ROW)[i]``  contains the laplacian sign of the i-th feature.
 226 * ``keypoints.ptr<float>(OCTAVE_ROW)[i]`` contains the octave of the i-th feature.
 227 * ``keypoints.ptr<float>(SIZE_ROW)[i]`` contains the size of the i-th feature.
 228 * ``keypoints.ptr<float>(ANGLE_ROW)[i]`` contain orientation of the i-th feature.
 229 * ``keypoints.ptr<float>(HESSIAN_ROW)[i]`` contains the response of the i-th feature.
 230
 231 The ``descriptors`` matrix is :math:`\texttt{nFeatures} \times \texttt{descriptorSize}` matrix with the ``CV_32FC1`` type.
 232
 233 The class ``SURF_GPU`` uses some buffers and provides access to it. All buffers can be safely released between function calls.
 234
 235 .. seealso:: :ocv:class:`SURF`
 236
 237 .. note::
 238
 239    * An example for using the SURF keypoint matcher on GPU can be found at opencv_source_code/samples/gpu/surf_keypoint_matcher.cpp
 240
 241 ocl::SURF_OCL
 242 -------------
 243 .. ocv:class:: ocl::SURF_OCL
 244
 245 Class used for extracting Speeded Up Robust Features (SURF) from an image. ::
 246
 247     class SURF_OCL
 248     {
 249     public:
 250         enum KeypointLayout
 251         {
 252             X_ROW = 0,
 253             Y_ROW,
 254             LAPLACIAN_ROW,
 255             OCTAVE_ROW,
 256             SIZE_ROW,
 257             ANGLE_ROW,
 258             HESSIAN_ROW,
 259             ROWS_COUNT
 260         };
 261
 262         //! the default constructor
 263         SURF_OCL();
 264         //! the full constructor taking all the necessary parameters
 265         explicit SURF_OCL(double _hessianThreshold, int _nOctaves=4,
 266              int _nOctaveLayers=2, bool _extended=false, float _keypointsRatio=0.01f, bool _upright = false);
 267
 268         //! returns the descriptor size in float's (64 or 128)
 269         int descriptorSize() const;
 270
 271         //! upload host keypoints to device memory
 272         void uploadKeypoints(const vector<KeyPoint>& keypoints,
 273             oclMat& keypointsocl);
 274         //! download keypoints from device to host memory
 275         void downloadKeypoints(const oclMat& keypointsocl,
 276             vector<KeyPoint>& keypoints);
 277
 278         //! download descriptors from device to host memory
 279         void downloadDescriptors(const oclMat& descriptorsocl,
 280             vector<float>& descriptors);
 281
 282         void operator()(const oclMat& img, const oclMat& mask,
 283             oclMat& keypoints);
 284
 285         void operator()(const oclMat& img, const oclMat& mask,
 286             oclMat& keypoints, oclMat& descriptors,
 287             bool useProvidedKeypoints = false);
 288
 289         void operator()(const oclMat& img, const oclMat& mask,
 290             std::vector<KeyPoint>& keypoints);
 291
 292         void operator()(const oclMat& img, const oclMat& mask,
 293             std::vector<KeyPoint>& keypoints, oclMat& descriptors,
 294             bool useProvidedKeypoints = false);
 295
 296         void operator()(const oclMat& img, const oclMat& mask,
 297             std::vector<KeyPoint>& keypoints,
 298             std::vector<float>& descriptors,
 299             bool useProvidedKeypoints = false);
 300
 301         void releaseMemory();
 302
 303         // SURF parameters
 304         double hessianThreshold;
 305         int nOctaves;
 306         int nOctaveLayers;
 307         bool extended;
 308         bool upright;
 309
 310         //! max keypoints = min(keypointsRatio * img.size().area(), 65535)
 311         float keypointsRatio;
 312
 313         oclMat sum, mask1, maskSum, intBuffer;
 314
 315         oclMat det, trace;
 316
 317         oclMat maxPosBuffer;
 318     };
 319
 320
 321 The class ``SURF_OCL`` implements Speeded Up Robust Features descriptor. There is a fast multi-scale Hessian keypoint detector that can be used to find the keypoints (which is the default option). But the descriptors can also be computed for the user-specified keypoints. Only 8-bit grayscale images are supported.
 322
 323 The class ``SURF_OCL`` can store results in the GPU and CPU memory. It provides functions to convert results between CPU and GPU version ( ``uploadKeypoints``, ``downloadKeypoints``, ``downloadDescriptors`` ). The format of CPU results is the same as ``SURF`` results. GPU results are stored in ``oclMat``. The ``keypoints`` matrix is :math:`\texttt{nFeatures} \times 7` matrix with the ``CV_32FC1`` type.
 324
 325 * ``keypoints.ptr<float>(X_ROW)[i]`` contains x coordinate of the i-th feature.
 326 * ``keypoints.ptr<float>(Y_ROW)[i]`` contains y coordinate of the i-th feature.
 327 * ``keypoints.ptr<float>(LAPLACIAN_ROW)[i]``  contains the laplacian sign of the i-th feature.
 328 * ``keypoints.ptr<float>(OCTAVE_ROW)[i]`` contains the octave of the i-th feature.
 329 * ``keypoints.ptr<float>(SIZE_ROW)[i]`` contains the size of the i-th feature.
 330 * ``keypoints.ptr<float>(ANGLE_ROW)[i]`` contain orientation of the i-th feature.
 331 * ``keypoints.ptr<float>(HESSIAN_ROW)[i]`` contains the response of the i-th feature.
 332
 333 The ``descriptors`` matrix is :math:`\texttt{nFeatures} \times \texttt{descriptorSize}` matrix with the ``CV_32FC1`` type.
 334
 335 The class ``SURF_OCL`` uses some buffers and provides access to it. All buffers can be safely released between function calls.
 336
 337 .. seealso:: :ocv:class:`SURF`
 338
 339 .. note::
 340
 341    * OCL : An example of the SURF detector can be found at opencv_source_code/samples/ocl/surf_matcher.cpp