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_XFEATURES2D_FEATURES_2D_HPP__
44 #define __OPENCV_XFEATURES2D_FEATURES_2D_HPP__
45 
46 #include "opencv2/features2d.hpp"
47 
48 namespace cv
49 {
50 namespace xfeatures2d
51 {
52 
53 /** @brief Class for extracting Speeded Up Robust Features from an image @cite Bay06 .
54 
55 The algorithm parameters:
56 -   member int extended
57     -   0 means that the basic descriptors (64 elements each) shall be computed
58     -   1 means that the extended descriptors (128 elements each) shall be computed
59 -   member int upright
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,
62 if you match images from a stereo pair, or do image stitching, the matched features
63 likely have very similar angles, and you can speed up feature extraction by setting
64 upright=1.
65 -   member double hessianThreshold
66 Threshold for the keypoint detector. Only features, whose hessian is larger than
67 hessianThreshold are retained by the detector. Therefore, the larger the value, the less
68 keypoints you will get. A good default value could be from 300 to 500, depending from the
69 image contrast.
70 -   member int nOctaves
71 The number of a gaussian pyramid octaves that the detector uses. It is set to 4 by default.
72 If you want to get very large features, use the larger value. If you want just small
73 features, decrease it.
74 -   member int nOctaveLayers
75 The number of images within each octave of a gaussian pyramid. It is set to 2 by default.
76 @note
77    -   An example using the SURF feature detector can be found at
78         opencv_source_code/samples/cpp/generic_descriptor_match.cpp
79     -   Another example using the SURF feature detector, extractor and matcher can be found at
80         opencv_source_code/samples/cpp/matcher_simple.cpp
81  */
82 class CV_EXPORTS_W SURF : public Feature2D
83 {
84 public:
85     /**
86     @param hessianThreshold Threshold for hessian keypoint detector used in SURF.
87     @param nOctaves Number of pyramid octaves the keypoint detector will use.
88     @param nOctaveLayers Number of octave layers within each octave.
89     @param extended Extended descriptor flag (true - use extended 128-element descriptors; false - use
90     64-element descriptors).
91     @param upright Up-right or rotated features flag (true - do not compute orientation of features;
92     false - compute orientation).
93      */
94     CV_WRAP static Ptr<SURF> create(double hessianThreshold=100,
95                   int nOctaves = 4, int nOctaveLayers = 3,
96                   bool extended = false, bool upright = false);
97 
98     CV_WRAP virtual void setHessianThreshold(double hessianThreshold) = 0;
99     CV_WRAP virtual double getHessianThreshold() const = 0;
100 
101     CV_WRAP virtual void setNOctaves(int nOctaves) = 0;
102     CV_WRAP virtual int getNOctaves() const = 0;
103 
104     CV_WRAP virtual void setNOctaveLayers(int nOctaveLayers) = 0;
105     CV_WRAP virtual int getNOctaveLayers() const = 0;
106 
107     CV_WRAP virtual void setExtended(bool extended) = 0;
108     CV_WRAP virtual bool getExtended() const = 0;
109 
110     CV_WRAP virtual void setUpright(bool upright) = 0;
111     CV_WRAP virtual bool getUpright() const = 0;
112 };
113 
114 typedef SURF SurfFeatureDetector;
115 typedef SURF SurfDescriptorExtractor;
116 
117 //! @}
118 
119 }
120 } /* namespace cv */
121 
122 #endif
123