2011-02-22 21:43:26 +01:00
Common Interfaces of Feature Detectors
======================================
2011-04-19 13:41:12 +02:00
.. highlight :: cpp
2011-05-04 21:22:51 +02:00
Feature detectors in OpenCV have wrappers with a common interface that enables you to easily switch
2011-02-26 12:05:10 +01:00
between different algorithms solving the same problem. All objects that implement keypoint detectors
2011-05-04 21:22:51 +02:00
inherit the
:ref: `FeatureDetector` interface.
2011-02-22 21:43:26 +01:00
.. index :: KeyPoint
2011-03-03 08:29:55 +01:00
.. KeyPoint:
2011-02-22 21:43:26 +01:00
KeyPoint
--------
2011-02-28 22:26:43 +01:00
.. c:type :: KeyPoint
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Data structure for salient point detectors ::
2011-02-22 21:43:26 +01:00
class KeyPoint
{
public:
// the default constructor
2011-02-26 12:05:10 +01:00
KeyPoint() : pt(0,0), size(0), angle(-1), response(0), octave(0),
2011-02-22 21:43:26 +01:00
class_id(-1) {}
// the full constructor
KeyPoint(Point2f _pt, float _size, float _angle=-1,
float _response=0, int _octave=0, int _class_id=-1)
2011-02-26 12:05:10 +01:00
: pt(_pt), size(_size), angle(_angle), response(_response),
2011-02-22 21:43:26 +01:00
octave(_octave), class_id(_class_id) {}
// another form of the full constructor
KeyPoint(float x, float y, float _size, float _angle=-1,
float _response=0, int _octave=0, int _class_id=-1)
2011-02-26 12:05:10 +01:00
: pt(x, y), size(_size), angle(_angle), response(_response),
2011-02-22 21:43:26 +01:00
octave(_octave), class_id(_class_id) {}
// converts vector of keypoints to vector of points
static void convert(const std::vector<KeyPoint>& keypoints,
std::vector<Point2f>& points2f,
const std::vector<int>& keypointIndexes=std::vector<int>());
2011-02-26 12:05:10 +01:00
// converts vector of points to the vector of keypoints, where each
2011-05-04 21:22:51 +02:00
// keypoint is assigned to the same size and the same orientation
2011-02-22 21:43:26 +01:00
static void convert(const std::vector<Point2f>& points2f,
std::vector<KeyPoint>& keypoints,
2011-02-26 12:05:10 +01:00
float size=1, float response=1, int octave=0,
2011-02-22 21:43:26 +01:00
int class_id=-1);
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
// computes overlap for pair of keypoints;
// overlap is a ratio between area of keypoint regions intersection and
2011-05-04 21:22:51 +02:00
// area of keypoint regions union (now keypoint region is a circle)
2011-02-22 21:43:26 +01:00
static float overlap(const KeyPoint& kp1, const KeyPoint& kp2);
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
Point2f pt; // coordinates of the keypoints
2011-05-04 21:22:51 +02:00
float size; // diameter of the meaningful keypoint neighborhood
2011-02-22 21:43:26 +01:00
float angle; // computed orientation of the keypoint (-1 if not applicable)
2011-02-26 12:05:10 +01:00
float response; // the response by which the most strong keypoints
2011-05-04 21:22:51 +02:00
// have been selected. Can be used for further sorting
2011-02-22 21:43:26 +01:00
// or subsampling
int octave; // octave (pyramid layer) from which the keypoint has been extracted
2011-02-26 12:05:10 +01:00
int class_id; // object class (if the keypoints need to be clustered by
// an object they belong to)
2011-02-22 21:43:26 +01:00
};
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
// writes vector of keypoints to the file storage
void write(FileStorage& fs, const string& name, const vector<KeyPoint>& keypoints);
// reads vector of keypoints from the specified file storage node
2011-02-26 12:05:10 +01:00
void read(const FileNode& node, CV_OUT vector<KeyPoint>& keypoints);
2011-03-03 08:29:55 +01:00
2011-04-19 13:41:12 +02:00
..
2011-02-22 21:43:26 +01:00
.. index :: FeatureDetector
.. _FeatureDetector:
FeatureDetector
---------------
2011-02-28 22:26:43 +01:00
.. c:type :: FeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Abstract base class for 2D image feature detectors ::
2011-02-22 21:43:26 +01:00
class CV_EXPORTS FeatureDetector
{
public:
virtual ~FeatureDetector();
2011-02-26 12:05:10 +01:00
void detect( const Mat& image, vector<KeyPoint>& keypoints,
2011-02-22 21:43:26 +01:00
const Mat& mask=Mat() ) const;
2011-02-26 12:05:10 +01:00
void detect( const vector<Mat>& images,
vector<vector<KeyPoint> >& keypoints,
2011-02-22 21:43:26 +01:00
const vector<Mat>& masks=vector<Mat>() ) const;
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
virtual void read(const FileNode&);
virtual void write(FileStorage&) const;
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
static Ptr<FeatureDetector> create( const string& detectorType );
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: FeatureDetector::detect
2011-02-28 22:26:43 +01:00
FeatureDetector::detect
2011-02-22 21:43:26 +01:00
---------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: void FeatureDetector::detect( const Mat\& image, vector<KeyPoint>\& keypoints, const Mat\& mask=Mat() ) const
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Detects keypoints in an image (first variant) or image set (second variant).
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param image: Image.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param keypoints: Detected keypoints.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param mask: Mask specifying where to look for keypoints (optional). It must be a char matrix with non-zero values in the region of interest.
2011-02-22 21:43:26 +01:00
2011-02-28 22:26:43 +01:00
.. c:function :: void FeatureDetector::detect( const vector<Mat>\& images, vector<vector<KeyPoint> >\& keypoints, const vector<Mat>\& masks=vector<Mat>() ) const
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param images: Image set.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param keypoints: Collection of keypoints detected in input images. ``keypoints[i]`` is a set of keypoints detected in ``images[i]`` .
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param masks: Masks for each input image specifying where to look for keypoints (optional). ``masks[i]`` is a mask for ``images[i]`` . Each element of the ``masks`` vector must be a char matrix with non-zero values in the region of interest.
2011-02-22 21:43:26 +01:00
.. index :: FeatureDetector::read
2011-02-28 22:26:43 +01:00
FeatureDetector::read
2011-02-22 21:43:26 +01:00
-------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: void FeatureDetector::read( const FileNode\& fn )
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Reads a feature detector object from a file node.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param fn: File node from which the detector is read.
2011-02-22 21:43:26 +01:00
.. index :: FeatureDetector::write
2011-02-28 22:26:43 +01:00
FeatureDetector::write
2011-02-22 21:43:26 +01:00
--------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: void FeatureDetector::write( FileStorage\& fs ) const
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Writes a feature detector object to a file storage.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param fs: File storage where the detector is written.
2011-02-22 21:43:26 +01:00
.. index :: FeatureDetector::create
2011-02-28 22:26:43 +01:00
FeatureDetector::create
2011-02-22 21:43:26 +01:00
---------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: Ptr<FeatureDetector> FeatureDetector::create( const string\& detectorType )
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Creates a feature detector of a given type with the default parameters (or using the default constructor).??
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
:param detectorType: Feature detector type.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
The following detector types are supported:
* `` "FAST" `` -- :func: `FastFeatureDetector`
* `` "STAR" `` -- :func: `StarFeatureDetector`
* `` "SIFT" `` -- :func: `SiftFeatureDetector`
* `` "SURF" `` -- :func: `SurfFeatureDetector`
* `` "MSER" `` -- :func: `MserFeatureDetector`
* `` "GFTT" `` -- :func: `GfttFeatureDetector`
* `` "HARRIS" `` -- :func: `HarrisFeatureDetector`
Also a combined format is supported: feature detector adapter name ( `` "Grid" `` --
:func: `GridAdaptedFeatureDetector` , `` "Pyramid" `` --
2011-02-26 12:05:10 +01:00
:func: `PyramidAdaptedFeatureDetector` ) + feature detector name (see above),
2011-05-04 21:22:51 +02:00
for example, `` "GridFAST" `` , `` "PyramidSTAR" `` .
2011-02-22 21:43:26 +01:00
.. index :: FastFeatureDetector
.. _FastFeatureDetector:
FastFeatureDetector
-------------------
2011-02-28 22:26:43 +01:00
.. c:type :: FastFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `FAST` method ::
2011-02-22 21:43:26 +01:00
class FastFeatureDetector : public FeatureDetector
{
public:
FastFeatureDetector( int threshold=1, bool nonmaxSuppression=true );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: GoodFeaturesToTrackDetector
.. _GoodFeaturesToTrackDetector:
GoodFeaturesToTrackDetector
---------------------------
2011-02-28 22:26:43 +01:00
.. c:type :: GoodFeaturesToTrackDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `goodFeaturesToTrack` function ::
2011-02-22 21:43:26 +01:00
class GoodFeaturesToTrackDetector : public FeatureDetector
{
public:
class Params
{
public:
2011-02-26 12:05:10 +01:00
Params( int maxCorners=1000, double qualityLevel=0.01,
double minDistance=1., int blockSize=3,
2011-02-22 21:43:26 +01:00
bool useHarrisDetector=false, double k=0.04 );
void read( const FileNode& fn );
void write( FileStorage& fs ) const;
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
int maxCorners;
double qualityLevel;
double minDistance;
int blockSize;
bool useHarrisDetector;
double k;
};
2011-02-26 12:05:10 +01:00
2011-02-22 21:43:26 +01:00
GoodFeaturesToTrackDetector( const GoodFeaturesToTrackDetector::Params& params=
GoodFeaturesToTrackDetector::Params() );
2011-02-26 12:05:10 +01:00
GoodFeaturesToTrackDetector( int maxCorners, double qualityLevel,
double minDistance, int blockSize=3,
2011-02-22 21:43:26 +01:00
bool useHarrisDetector=false, double k=0.04 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: MserFeatureDetector
.. _MserFeatureDetector:
MserFeatureDetector
-------------------
2011-02-28 22:26:43 +01:00
.. c:type :: MserFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `MSER` class ::
2011-02-22 21:43:26 +01:00
class MserFeatureDetector : public FeatureDetector
{
public:
MserFeatureDetector( CvMSERParams params=cvMSERParams() );
2011-02-26 12:05:10 +01:00
MserFeatureDetector( int delta, int minArea, int maxArea,
2011-02-22 21:43:26 +01:00
double maxVariation, double minDiversity,
2011-02-26 12:05:10 +01:00
int maxEvolution, double areaThreshold,
2011-02-22 21:43:26 +01:00
double minMargin, int edgeBlurSize );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: StarFeatureDetector
.. _StarFeatureDetector:
StarFeatureDetector
-------------------
2011-02-28 22:26:43 +01:00
.. c:type :: StarFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `StarDetector` class ::
2011-02-22 21:43:26 +01:00
class StarFeatureDetector : public FeatureDetector
{
public:
2011-02-26 12:05:10 +01:00
StarFeatureDetector( int maxSize=16, int responseThreshold=30,
2011-02-22 21:43:26 +01:00
int lineThresholdProjected = 10,
int lineThresholdBinarized=8, int suppressNonmaxSize=5 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: SiftFeatureDetector
.. _SiftFeatureDetector:
SiftFeatureDetector
-------------------
2011-02-28 22:26:43 +01:00
.. c:type :: SiftFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `SIFT` class ::
2011-02-22 21:43:26 +01:00
class SiftFeatureDetector : public FeatureDetector
{
public:
2011-02-26 12:05:10 +01:00
SiftFeatureDetector(
2011-02-22 21:43:26 +01:00
const SIFT::DetectorParams& detectorParams=SIFT::DetectorParams(),
const SIFT::CommonParams& commonParams=SIFT::CommonParams() );
SiftFeatureDetector( double threshold, double edgeThreshold,
int nOctaves=SIFT::CommonParams::DEFAULT_NOCTAVES,
int nOctaveLayers=SIFT::CommonParams::DEFAULT_NOCTAVE_LAYERS,
int firstOctave=SIFT::CommonParams::DEFAULT_FIRST_OCTAVE,
int angleMode=SIFT::CommonParams::FIRST_ANGLE );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: SurfFeatureDetector
.. _SurfFeatureDetector:
SurfFeatureDetector
-------------------
2011-02-28 22:26:43 +01:00
.. c:type :: SurfFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `SURF` class ::
2011-02-22 21:43:26 +01:00
class SurfFeatureDetector : public FeatureDetector
{
public:
SurfFeatureDetector( double hessianThreshold = 400., int octaves = 3,
int octaveLayers = 4 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: GridAdaptedFeatureDetector
.. _GridAdaptedFeatureDetector:
GridAdaptedFeatureDetector
--------------------------
2011-02-28 22:26:43 +01:00
.. c:type :: GridAdaptedFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Class adapting a detector to partition the source image into a grid and detect points in each cell ::
2011-02-22 21:43:26 +01:00
class GridAdaptedFeatureDetector : public FeatureDetector
{
public:
/*
* detector Detector that will be adapted.
2011-02-26 12:05:10 +01:00
* maxTotalKeypoints Maximum count of keypoints detected on the image.
2011-05-04 21:22:51 +02:00
* Only the strongest keypoints will be kept.
* gridRows Grid row count.
2011-02-22 21:43:26 +01:00
* gridCols Grid column count.
*/
2011-02-26 12:05:10 +01:00
GridAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
int maxTotalKeypoints, int gridRows=4,
2011-02-22 21:43:26 +01:00
int gridCols=4 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: PyramidAdaptedFeatureDetector
.. _PyramidAdaptedFeatureDetector:
PyramidAdaptedFeatureDetector
-----------------------------
2011-02-28 22:26:43 +01:00
.. c:type :: PyramidAdaptedFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
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. ::
2011-02-22 21:43:26 +01:00
class PyramidAdaptedFeatureDetector : public FeatureDetector
{
public:
2011-02-26 12:05:10 +01:00
PyramidAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
2011-02-22 21:43:26 +01:00
int levels=2 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
2011-03-03 08:29:55 +01:00
.. index :: DynamicAdaptedFeatureDetector
2011-02-22 21:43:26 +01:00
DynamicAdaptedFeatureDetector
-----------------------------
2011-03-03 08:29:55 +01:00
2011-02-28 22:26:43 +01:00
.. c:type :: DynamicAdaptedFeatureDetector
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Adaptively adjusting detector that iteratively detects features until the desired number is found ::
2011-03-03 08:29:55 +01:00
class DynamicAdaptedFeatureDetector: public FeatureDetector
{
public:
DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjaster,
int min_features=400, int max_features=500, int max_iters=5 );
...
};
2011-02-22 21:43:26 +01:00
If the detector is persisted, it will "remember" the parameters
2011-05-04 21:22:51 +02:00
used for the last detection. In this case, the detector may be used for consistent numbers
of keypoints in a set of temporally related images, such as video streams or
2011-02-22 21:43:26 +01:00
panorama series.
2011-05-04 21:22:51 +02:00
`` DynamicAdaptedFeatureDetector `` uses another detector such as FAST or SURF to do the dirty work,
with the help of `` AdjusterAdapter `` .
If the detected number of features is not enough,??
`` AdjusterAdapter `` adjusts the detection parameters so that the next detection
results in more or less features. This is repeated until either the number of desired features are found
2011-02-22 21:43:26 +01:00
or the parameters are maxed out.
2011-05-04 21:22:51 +02:00
Adapters can be easily implemented for any detector via the
`` AdjusterAdapter `` interface.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Beware that this is not thread-safe since the adjustment of parameters breaks the const??
of the detection routine.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Here is a sample of how to create `` DynamicAdaptedFeatureDetector `` : ::
2011-02-22 21:43:26 +01:00
//sample usage:
2011-02-26 12:05:10 +01:00
//will create a detector that attempts to find
2011-02-22 21:43:26 +01:00
//100 - 110 FAST Keypoints, and will at most run
2011-02-26 12:05:10 +01:00
//FAST feature detection 10 times until that
2011-02-22 21:43:26 +01:00
//number of keypoints are found
Ptr<FeatureDetector> detector(new DynamicAdaptedFeatureDetector (100, 110, 10,
new FastAdjuster(20,true)));
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
2011-03-03 08:29:55 +01:00
.. index :: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector
DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector
----------------------------------------------------------------
.. c:function :: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>\& adjaster, int min_features, int max_features, int max_iters )
2011-05-04 21:22:51 +02:00
`` DynamicAdaptedFeatureDetector `` constructor
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param adjaster: :func:`AdjusterAdapter` that detects features and adjusts parameters.??parameter formatting is broken here
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param min_features: Minimum desired number features.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param max_features: Maximum desired number of features.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param max_iters: Maximum number of times to try adjusting the feature detector parameters. For :func:`FastAdjuster` , this number can be high, but with ``Star`` or ``Surf`` , many iterations can be time-comsuming. At each iteration the detector is rerun.
2011-03-03 08:29:55 +01:00
.. index :: AdjusterAdapter
AdjusterAdapter
---------------
.. c:type :: AdjusterAdapter
2011-05-04 21:22:51 +02:00
Class providing an interface for adjusting parameters of a feature detector. This interface is used by :func: `DynamicAdaptedFeatureDetector` . It is a wrapper for :func: `FeatureDetector` that enables adjusting parameters after detection.?? ::
2011-03-03 08:29:55 +01:00
class AdjusterAdapter: public FeatureDetector
{
public:
virtual ~AdjusterAdapter() {}
virtual void tooFew(int min, int n_detected) = 0;
virtual void tooMany(int max, int n_detected) = 0;
virtual bool good() const = 0;
};
See
2011-05-04 21:22:51 +02:00
:func: `FastAdjuster` ,
:func: `StarAdjuster` ,
:func: `SurfAdjuster` for concrete implementations.
2011-03-03 08:29:55 +01:00
.. index :: AdjusterAdapter::tooFew
AdjusterAdapter::tooFew
---------------------------
.. c:function :: virtual void tooFew(int min, int n_detected) = 0
2011-05-04 21:22:51 +02:00
Adjusts the detector parameters to detect more features.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param min: Minimum desired number of features.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param n_detected: Number of features detected during the latest run.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
Example: ::
2011-03-03 08:29:55 +01:00
void FastAdjuster::tooFew(int min, int n_detected)
{
thresh_--;
}
.. index :: AdjusterAdapter::tooMany
AdjusterAdapter::tooMany
----------------------------
.. c:function :: virtual void tooMany(int max, int n_detected) = 0
2011-05-04 21:22:51 +02:00
Adjusts the detector parameters detect less features.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param max: Maximum desired number of features.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param n_detected: Number of features detected during the latest run.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
Example: ::
2011-03-03 08:29:55 +01:00
void FastAdjuster::tooMany(int min, int n_detected)
{
thresh_++;
}
.. index :: AdjusterAdapter::good
AdjusterAdapter::good
-------------------------
.. c:function :: virtual bool good() const = 0
2011-05-04 21:22:51 +02:00
Returns false if the detector parameters cannot be adjusted any more.
Example: ::
2011-03-03 08:29:55 +01:00
bool FastAdjuster::good() const
{
return (thresh_ > 1) && (thresh_ < 200);
}
.. index :: FastAdjuster
FastAdjuster
------------
.. c:type :: FastAdjuster
2011-05-04 21:22:51 +02:00
:func: `AdjusterAdapter` for :func: `FastFeatureDetector` . This class decrements or increments the threshhold by 1.?? ::
2011-03-03 08:29:55 +01:00
class FastAdjuster FastAdjuster: public AdjusterAdapter
{
public:
FastAdjuster(int init_thresh = 20, bool nonmax = true);
...
};
.. index :: StarAdjuster
StarAdjuster
------------
.. c:type :: StarAdjuster
2011-05-04 21:22:51 +02:00
:func: `AdjusterAdapter` for :func: `StarFeatureDetector` . This class adjusts the `` responseThreshhold `` of `` StarFeatureDetector `` . ::
2011-03-03 08:29:55 +01:00
class StarAdjuster: public AdjusterAdapter
{
StarAdjuster(double initial_thresh = 30.0);
...
};
.. index :: SurfAdjuster
SurfAdjuster
------------
.. c:type :: SurfAdjuster
2011-05-04 21:22:51 +02:00
:func: `AdjusterAdapter` for :func: `SurfFeatureDetector` . This class adjusts the `` hessianThreshold `` of `` SurfFeatureDetector `` . ::
2011-03-03 08:29:55 +01:00
class SurfAdjuster: public SurfAdjuster
{
SurfAdjuster();
...
};
.. index :: FeatureDetector
FeatureDetector
---------------
.. c:type :: FeatureDetector
2011-05-04 21:22:51 +02:00
Abstract base class for 2D image feature detectors ::
2011-03-03 08:29:55 +01:00
class CV_EXPORTS FeatureDetector
{
public:
virtual ~FeatureDetector();
void detect( const Mat& image, vector<KeyPoint>& keypoints,
const Mat& mask=Mat() ) const;
void detect( const vector<Mat>& images,
vector<vector<KeyPoint> >& keypoints,
const vector<Mat>& masks=vector<Mat>() ) const;
virtual void read(const FileNode&);
virtual void write(FileStorage&) const;
static Ptr<FeatureDetector> create( const string& detectorType );
protected:
...
};
.. index :: FeatureDetector::detect
FeatureDetector::detect
---------------------------
.. c:function :: void FeatureDetector::detect( const Mat\& image, vector<KeyPoint>\& keypoints, const Mat\& mask=Mat() ) const
2011-05-04 21:22:51 +02:00
Detects keypoints in an image (first variant) or image set (second variant).
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param image: Image.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param keypoints: Detected keypoints.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param mask: Mask specifying where to look for keypoints (optional). It must be a char matrix
2011-03-03 08:29:55 +01:00
with non-zero values in the region of interest.
.. c:function :: void FeatureDetector::detect( const vector<Mat>\& images, vector<vector<KeyPoint> >\& keypoints, const vector<Mat>\& masks=vector<Mat>() ) const
2011-05-04 21:22:51 +02:00
:param images: Image set.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param keypoints: Collection of keypoints detected in an input image. ``keypoints[i]`` is a set of keypoints detected in ``images[i]`` .
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param masks: Masks for each input image specifying where to look for keypoints (optional). ``masks[i]`` is a mask for ``images[i]`` .
2011-03-03 08:29:55 +01:00
Each element of `` masks `` vector must be a char matrix with non-zero values in the region of interest.
.. index :: FeatureDetector::read
FeatureDetector::read
-------------------------
.. c:function :: void FeatureDetector::read( const FileNode\& fn )
2011-05-04 21:22:51 +02:00
Reads a feature detector object from a file node.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param fn: File node from which the detector is read.
2011-03-03 08:29:55 +01:00
.. index :: FeatureDetector::write
FeatureDetector::write
--------------------------
.. c:function :: void FeatureDetector::write( FileStorage\& fs ) const
2011-05-04 21:22:51 +02:00
Writes a feature detector object to a file storage.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
:param fs: File storage where the detector is written.
2011-03-03 08:29:55 +01:00
.. index :: FeatureDetector::create
FeatureDetector::create
---------------------------
2011-05-04 21:22:51 +02:00
.. c:function :: Ptr<FeatureDetector> FeatureDetector::create( const string\& detectorType )??
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
Creates a feature detector of a given type with the default parameters (or using the default constructor).??
2011-03-03 08:29:55 +01:00
:param detectorType: Feature detector type.
Now the following detector types are supported:
2011-05-04 21:22:51 +02:00
* `` "FAST" `` -- :func: `FastFeatureDetector`
* `` "STAR" `` -- :func: `StarFeatureDetector`
* `` "SIFT" `` -- :func: `SiftFeatureDetector`
* `` "SURF" `` -- :func: `SurfFeatureDetector`
* `` "MSER" `` -- :func: `MserFeatureDetector`
* `` "GFTT" `` -- :func: `GfttFeatureDetector`
* `` "HARRIS" `` -- :func: `HarrisFeatureDetector`
A combined format is also supported: feature detector adapter name ( `` "Grid" `` --
:func: `GridAdaptedFeatureDetector` , `` "Pyramid" `` --
2011-03-03 08:29:55 +01:00
:func: `PyramidAdaptedFeatureDetector` ) + feature detector name (see above),
2011-05-04 21:22:51 +02:00
for example, `` "GridFAST" `` , `` "PyramidSTAR" `` .
2011-03-03 08:29:55 +01:00
.. index :: FastFeatureDetector
FastFeatureDetector
-------------------
.. c:type :: FastFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:func: `FAST` method ::
2011-03-03 08:29:55 +01:00
class FastFeatureDetector : public FeatureDetector
{
public:
FastFeatureDetector( int threshold=1, bool nonmaxSuppression=true );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: GoodFeaturesToTrackDetector
GoodFeaturesToTrackDetector
---------------------------
.. c:type :: GoodFeaturesToTrackDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the :func: `goodFeaturesToTrack` function ::
2011-03-03 08:29:55 +01:00
class GoodFeaturesToTrackDetector : public FeatureDetector
{
public:
class Params
{
public:
Params( int maxCorners=1000, double qualityLevel=0.01,
double minDistance=1., int blockSize=3,
bool useHarrisDetector=false, double k=0.04 );
void read( const FileNode& fn );
void write( FileStorage& fs ) const;
int maxCorners;
double qualityLevel;
double minDistance;
int blockSize;
bool useHarrisDetector;
double k;
};
GoodFeaturesToTrackDetector( const GoodFeaturesToTrackDetector::Params& params=
GoodFeaturesToTrackDetector::Params() );
GoodFeaturesToTrackDetector( int maxCorners, double qualityLevel,
double minDistance, int blockSize=3,
bool useHarrisDetector=false, double k=0.04 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: MserFeatureDetector
MserFeatureDetector
-------------------
.. c:type :: MserFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the :func: `MSER` class ::
2011-03-03 08:29:55 +01:00
class MserFeatureDetector : public FeatureDetector
{
public:
MserFeatureDetector( CvMSERParams params=cvMSERParams() );
MserFeatureDetector( int delta, int minArea, int maxArea,
double maxVariation, double minDiversity,
int maxEvolution, double areaThreshold,
double minMargin, int edgeBlurSize );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: StarFeatureDetector
StarFeatureDetector
-------------------
.. c:type :: StarFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the :func: `StarDetector` class ::
2011-03-03 08:29:55 +01:00
class StarFeatureDetector : public FeatureDetector
{
public:
StarFeatureDetector( int maxSize=16, int responseThreshold=30,
int lineThresholdProjected = 10,
int lineThresholdBinarized=8, int suppressNonmaxSize=5 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: SiftFeatureDetector
SiftFeatureDetector
-------------------
.. c:type :: SiftFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the :func: `SIFT` class ::
2011-03-03 08:29:55 +01:00
class SiftFeatureDetector : public FeatureDetector
{
public:
SiftFeatureDetector(
const SIFT::DetectorParams& detectorParams=SIFT::DetectorParams(),
const SIFT::CommonParams& commonParams=SIFT::CommonParams() );
SiftFeatureDetector( double threshold, double edgeThreshold,
int nOctaves=SIFT::CommonParams::DEFAULT_NOCTAVES,
int nOctaveLayers=SIFT::CommonParams::DEFAULT_NOCTAVE_LAYERS,
int firstOctave=SIFT::CommonParams::DEFAULT_FIRST_OCTAVE,
int angleMode=SIFT::CommonParams::FIRST_ANGLE );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: SurfFeatureDetector
SurfFeatureDetector
-------------------
.. c:type :: SurfFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the :func: `SURF` class ::
2011-03-03 08:29:55 +01:00
class SurfFeatureDetector : public FeatureDetector
{
public:
SurfFeatureDetector( double hessianThreshold = 400., int octaves = 3,
int octaveLayers = 4 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: GridAdaptedFeatureDetector
GridAdaptedFeatureDetector
--------------------------
.. c:type :: GridAdaptedFeatureDetector
2011-05-04 21:22:51 +02:00
Class adapting a detector to partition the source image into a grid and detect points in each cell ::
2011-03-03 08:29:55 +01:00
class GridAdaptedFeatureDetector : public FeatureDetector
{
public:
/*
* detector Detector that will be adapted.
* maxTotalKeypoints Maximum count of keypoints detected on the image.
2011-05-04 21:22:51 +02:00
* Only the strongest keypoints are kept.
* gridRows Grid row count.
2011-03-03 08:29:55 +01:00
* gridCols Grid column count.
*/
GridAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
int maxTotalKeypoints, int gridRows=4,
int gridCols=4 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: PyramidAdaptedFeatureDetector
PyramidAdaptedFeatureDetector
-----------------------------
.. c:type :: PyramidAdaptedFeatureDetector
2011-05-04 21:22:51 +02:00
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. ::
2011-03-03 08:29:55 +01:00
class PyramidAdaptedFeatureDetector : public FeatureDetector
{
public:
PyramidAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
int levels=2 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
.. index :: DynamicAdaptedFeatureDetector
DynamicAdaptedFeatureDetector
-----------------------------
.. c:type :: DynamicAdaptedFeatureDetector
2011-05-04 21:22:51 +02:00
Adaptively adjusting detector that iteratively detects features until the desired number is found. ::
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
class DynamicAdaptedFeatureDetector: public FeatureDetector
2011-02-22 21:43:26 +01:00
{
public:
2011-02-26 12:05:10 +01:00
DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjaster,
2011-02-22 21:43:26 +01:00
int min_features=400, int max_features=500, int max_iters=5 );
...
};
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
If the detector is persisted, it "remembers" the parameters
used on the last detection. In this case, the detector may be used for consistent numbers
of keypoints in a set of images that are temporally related, such as video streams or
2011-03-03 08:29:55 +01:00
panorama series.
2011-05-04 21:22:51 +02:00
`` DynamicAdaptedFeatureDetector `` uses another detector such as FAST or SURF to do the dirty work,
with the help of `` AdjusterAdapter `` .
If the number of detected features is not enough,
`` AdjusterAdapter `` adjusts the detection parameters so that the next detection
results in a bigger or smaller number of features. This is repeated until either the number of desired features are found
2011-03-03 08:29:55 +01:00
or the parameters are maxed out.
Adapters can easily be implemented for any detector via the
2011-05-04 21:22:51 +02:00
`` AdjusterAdapter `` interface.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
Beware that this is not thread safe as the adjustment of parameters breaks the const??
of the detection routine.
2011-03-03 08:29:55 +01:00
2011-05-04 21:22:51 +02:00
Example of creating `` DynamicAdaptedFeatureDetector `` : ::
2011-03-03 08:29:55 +01:00
//sample usage:
//will create a detector that attempts to find
//100 - 110 FAST Keypoints, and will at most run
//FAST feature detection 10 times until that
//number of keypoints are found
Ptr<FeatureDetector> detector(new DynamicAdaptedFeatureDetector (100, 110, 10,
new FastAdjuster(20,true)));
2011-02-22 21:43:26 +01:00
.. index :: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector
2011-02-28 22:26:43 +01:00
DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector
2011-02-22 21:43:26 +01:00
----------------------------------------------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>\& adjaster, int min_features, int max_features, int max_iters )
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Provides the `` DynamicAdaptedFeatureDetector `` constructor.??
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param adjaster: :func:`AdjusterAdapter` that detects features and adjusts parameters.??formatting issue again
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param min_features: Minimum desired number features.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param max_features: Maximum desired number of features.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param max_iters: Maximum number of times to try adjusting the feature detector parameters. For :func:`FastAdjuster` , this number can be high, but with ``Star`` or ``Surf`` , many iterations can be time-consuming. At each iteration the detector is rerun.
2011-02-22 21:43:26 +01:00
.. index :: AdjusterAdapter
AdjusterAdapter
---------------
2011-03-03 08:29:55 +01:00
2011-02-28 22:26:43 +01:00
.. c:type :: AdjusterAdapter
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Class providing an interface for adjusting parameters of a feature detector. This interface is used by :func: `DynamicAdaptedFeatureDetector` . It is a wrapper for :func: `FeatureDetector` that enables adjusting parameters after detection. ::
2011-03-03 08:29:55 +01:00
class AdjusterAdapter: public FeatureDetector
{
public:
virtual ~AdjusterAdapter() {}
virtual void tooFew(int min, int n_detected) = 0;
virtual void tooMany(int max, int n_detected) = 0;
virtual bool good() const = 0;
};
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
See
2011-05-04 21:22:51 +02:00
:func: `FastAdjuster` ,
:func: `StarAdjuster` ,
:func: `SurfAdjuster` for concrete implementations.
2011-02-22 21:43:26 +01:00
.. index :: AdjusterAdapter::tooFew
2011-02-28 22:26:43 +01:00
AdjusterAdapter::tooFew
2011-02-22 21:43:26 +01:00
---------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: virtual void tooFew(int min, int n_detected) = 0
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Adjusts the detector parameters to detect more features.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param min: Minimum desired number of features.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
:param n_detected: Number of features detected during the latest run.
2011-02-22 21:43:26 +01:00
2011-05-04 21:22:51 +02:00
Example: ::
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
void FastAdjuster::tooFew(int min, int n_detected)
2011-02-22 21:43:26 +01:00
{
thresh_--;
}
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: AdjusterAdapter::tooMany
2011-02-28 22:26:43 +01:00
AdjusterAdapter::tooMany
2011-02-22 21:43:26 +01:00
----------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: virtual void tooMany(int max, int n_detected) = 0
2011-02-22 21:43:26 +01:00
2011-03-03 08:29:55 +01:00
Too many features were detected so, adjust the detector parameters accordingly - so that the next detection detects less features.
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
:param max: This maximum desired number features.
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
:param n_detected: The actual number detected last run.
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
An example implementation of this is ::
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
void FastAdjuster::tooMany(int min, int n_detected)
2011-02-22 21:43:26 +01:00
{
thresh_++;
}
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
.. index :: AdjusterAdapter::good
2011-02-28 22:26:43 +01:00
AdjusterAdapter::good
2011-02-22 21:43:26 +01:00
-------------------------
2011-02-28 22:26:43 +01:00
.. c:function :: virtual bool good() const = 0
2011-02-22 21:43:26 +01:00
2011-03-03 08:29:55 +01:00
Are params maxed out or still valid? Returns false if the parameters can't be adjusted any more. An example implementation of this is ::
2011-02-22 21:43:26 +01:00
2011-03-05 22:26:13 +01:00
bool FastAdjuster::good() const
{
return (thresh > 1) && (thresh < 200);
}
2011-02-22 21:43:26 +01:00
2011-03-03 08:29:55 +01:00
.. index :: FastAdjuster
2011-02-22 21:43:26 +01:00
FastAdjuster
------------
2011-03-03 08:29:55 +01:00
2011-02-28 22:26:43 +01:00
.. c:type :: FastAdjuster
2011-02-22 21:43:26 +01:00
2011-03-03 08:29:55 +01:00
:func: `AdjusterAdapter` for the :func: `FastFeatureDetector` . This will basically decrement or increment the threshhold by 1 ::
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
class FastAdjuster FastAdjuster: public AdjusterAdapter
2011-02-22 21:43:26 +01:00
{
public:
FastAdjuster(int init_thresh = 20, bool nonmax = true);
...
};
2011-03-03 08:29:55 +01:00
.. index :: StarAdjuster
2011-02-22 21:43:26 +01:00
StarAdjuster
------------
2011-03-03 08:29:55 +01:00
2011-02-28 22:26:43 +01:00
.. c:type :: StarAdjuster
2011-02-22 21:43:26 +01:00
2011-03-03 08:29:55 +01:00
:func: `AdjusterAdapter` for the :func: `StarFeatureDetector` . This adjusts the responseThreshhold of StarFeatureDetector. ::
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
class StarAdjuster: public AdjusterAdapter
2011-02-22 21:43:26 +01:00
{
StarAdjuster(double initial_thresh = 30.0);
...
};
2011-03-03 08:29:55 +01:00
.. index :: SurfAdjuster
2011-02-22 21:43:26 +01:00
SurfAdjuster
------------
2011-03-03 08:29:55 +01:00
2011-02-28 22:26:43 +01:00
.. c:type :: SurfAdjuster
2011-02-22 21:43:26 +01:00
2011-03-03 08:29:55 +01:00
:func: `AdjusterAdapter` for the :func: `SurfFeatureDetector` . This adjusts the hessianThreshold of SurfFeatureDetector. ::
2011-02-22 21:43:26 +01:00
2011-02-26 12:05:10 +01:00
class SurfAdjuster: public SurfAdjuster
2011-02-22 21:43:26 +01:00
{
SurfAdjuster();
...
};
2011-03-03 08:29:55 +01:00
2011-02-22 21:43:26 +01:00
..