opencv/modules/features2d/doc/common_interfaces_of_feature_detectors.rst

619 lines
21 KiB
ReStructuredText
Raw Normal View History

Common Interfaces of Feature Detectors
======================================
.. 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
:ocv:class:`FeatureDetector` interface.
KeyPoint
--------
2011-06-16 14:48:23 +02:00
.. ocv:class:: KeyPoint
Data structure for salient point detectors.
.. ocv:member:: Point2f pt
coordinates of the keypoint
.. ocv:member:: float size
diameter of the meaningful keypoint neighborhood
.. ocv:member:: float angle
computed orientation of the keypoint (-1 if not applicable)
.. ocv:member:: float response
the response by which the most strong keypoints have been selected. Can be used for further sorting or subsampling
.. ocv:member:: int octave
octave (pyramid layer) from which the keypoint has been extracted
.. ocv:member:: int class_id
object id that can be used to clustered keypoints by an object they belong to
KeyPoint::KeyPoint
------------------
The keypoint constructors
.. ocv:function:: KeyPoint::KeyPoint()
.. ocv:function:: KeyPoint::KeyPoint(Point2f _pt, float _size, float _angle=-1, float _response=0, int _octave=0, int _class_id=-1)
.. ocv:function:: KeyPoint::KeyPoint(float x, float y, float _size, float _angle=-1, float _response=0, int _octave=0, int _class_id=-1)
.. ocv:pyfunction:: cv2.KeyPoint(x, y, _size[, _angle[, _response[, _octave[, _class_id]]]]) -> <KeyPoint object>
:param x: x-coordinate of the keypoint
:param y: y-coordinate of the keypoint
:param _pt: x & y coordinates of the keypoint
:param _size: keypoint diameter
:param _angle: keypoint orientation
:param _response: keypoint detector response on the keypoint (that is, strength of the keypoint)
:param _octave: pyramid octave in which the keypoint has been detected
:param _class_id: object id
FeatureDetector
---------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: FeatureDetector
Abstract base class for 2D image feature detectors. ::
class CV_EXPORTS FeatureDetector
{
public:
virtual ~FeatureDetector();
2011-02-26 12:05:10 +01:00
void detect( const Mat& image, vector<KeyPoint>& keypoints,
const Mat& mask=Mat() ) const;
2011-02-26 12:05:10 +01:00
void detect( const vector<Mat>& images,
vector<vector<KeyPoint> >& keypoints,
const vector<Mat>& masks=vector<Mat>() ) const;
2011-02-26 12:05:10 +01:00
virtual void read(const FileNode&);
virtual void write(FileStorage&) const;
2011-02-26 12:05:10 +01:00
static Ptr<FeatureDetector> create( const string& detectorType );
2011-02-26 12:05:10 +01:00
protected:
...
};
2011-03-03 08:29:55 +01:00
FeatureDetector::detect
---------------------------
Detects keypoints in an image (first variant) or image set (second variant).
.. ocv:function:: void FeatureDetector::detect( const Mat& image, vector<KeyPoint>& keypoints, const Mat& mask=Mat() ) const
.. ocv:function:: void FeatureDetector::detect( const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints, const vector<Mat>& masks=vector<Mat>() ) const
:param image: Image.
2011-05-04 21:22:51 +02:00
:param images: Image set.
:param keypoints: The detected keypoints. In the second variant of the method ``keypoints[i]`` is a set of keypoints detected in ``images[i]`` .
: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.
:param masks: Masks for each input image specifying where to look for keypoints (optional). ``masks[i]`` is a mask for ``images[i]``.
FeatureDetector::read
-------------------------
Reads a feature detector object from a file node.
.. ocv:function:: void FeatureDetector::read( const FileNode& fn )
2011-05-04 21:22:51 +02:00
:param fn: File node from which the detector is read.
FeatureDetector::write
--------------------------
Writes a feature detector object to a file storage.
.. ocv:function:: void FeatureDetector::write( FileStorage& fs ) const
2011-05-04 21:22:51 +02:00
:param fs: File storage where the detector is written.
FeatureDetector::create
---------------------------
Creates a feature detector by its name.
.. ocv:function:: Ptr<FeatureDetector> FeatureDetector::create( const string& detectorType )
2011-02-26 12:05:10 +01:00
:param detectorType: Feature detector type.
2011-05-04 21:22:51 +02:00
The following detector types are supported:
* ``"FAST"`` -- :ocv:class:`FastFeatureDetector`
* ``"STAR"`` -- :ocv:class:`StarFeatureDetector`
* ``"SIFT"`` -- :ocv:class:`SiftFeatureDetector`
* ``"SURF"`` -- :ocv:class:`SurfFeatureDetector`
* ``"ORB"`` -- :ocv:class:`OrbFeatureDetector`
* ``"MSER"`` -- :ocv:class:`MserFeatureDetector`
* ``"GFTT"`` -- :ocv:class:`GoodFeaturesToTrackDetector`
* ``"HARRIS"`` -- :ocv:class:`GoodFeaturesToTrackDetector` with Harris detector enabled
* ``"Dense"`` -- :ocv:class:`DenseFeatureDetector`
* ``"SimpleBlob"`` -- :ocv:class:`SimpleBlobDetector`
2011-05-04 21:22:51 +02:00
Also a combined format is supported: feature detector adapter name ( ``"Grid"`` --
:ocv:class:`GridAdaptedFeatureDetector`, ``"Pyramid"`` --
:ocv:class:`PyramidAdaptedFeatureDetector` ) + feature detector name (see above),
for example: ``"GridFAST"``, ``"PyramidSTAR"`` .
FastFeatureDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: FastFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:ocv:func:`FAST` method. ::
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
GoodFeaturesToTrackDetector
---------------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: GoodFeaturesToTrackDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:ocv:func:`goodFeaturesToTrack` function. ::
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,
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
int maxCorners;
double qualityLevel;
double minDistance;
int blockSize;
bool useHarrisDetector;
double k;
};
2011-02-26 12:05:10 +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,
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
MserFeatureDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: MserFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:ocv:class:`MSER` class. ::
class MserFeatureDetector : public FeatureDetector
{
public:
MserFeatureDetector( CvMSERParams params=cvMSERParams() );
2011-02-26 12:05:10 +01:00
MserFeatureDetector( int delta, int minArea, int maxArea,
double maxVariation, double minDiversity,
2011-02-26 12:05:10 +01:00
int maxEvolution, double areaThreshold,
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
StarFeatureDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: StarFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:ocv:class:`StarDetector` class. ::
class StarFeatureDetector : public FeatureDetector
{
public:
2011-02-26 12:05:10 +01:00
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:
...
};
2011-03-03 08:29:55 +01:00
SiftFeatureDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: SiftFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:ocv:class:`SIFT` class. ::
class SiftFeatureDetector : public FeatureDetector
{
public:
2011-02-26 12:05:10 +01:00
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:
...
};
2011-03-03 08:29:55 +01:00
SurfFeatureDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: SurfFeatureDetector
2011-05-04 21:22:51 +02:00
Wrapping class for feature detection using the
:ocv:class:`SURF` class. ::
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-05-21 00:25:53 +02:00
OrbFeatureDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: OrbFeatureDetector
2011-05-21 00:25:53 +02:00
Wrapping class for feature detection using the
:ocv:class:`ORB` class. ::
2011-05-21 00:25:53 +02:00
class OrbFeatureDetector : public FeatureDetector
{
public:
OrbFeatureDetector( size_t n_features );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
SimpleBlobDetector
-------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: SimpleBlobDetector
Class for extracting blobs from an image. ::
class SimpleBlobDetector : public FeatureDetector
{
public:
struct Params
{
Params();
float thresholdStep;
float minThreshold;
float maxThreshold;
size_t minRepeatability;
float minDistBetweenBlobs;
bool filterByColor;
uchar blobColor;
bool filterByArea;
float minArea, maxArea;
bool filterByCircularity;
float minCircularity, maxCircularity;
bool filterByInertia;
float minInertiaRatio, maxInertiaRatio;
bool filterByConvexity;
float minConvexity, maxConvexity;
};
SimpleBlobDetector(const SimpleBlobDetector::Params &parameters = SimpleBlobDetector::Params());
protected:
...
};
The class implements a simple algorithm for extracting blobs from an image:
#. 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.
#. Extract connected components from every binary image by :ocv:func:`findContours` and calculate their centers.
#. 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.
#. From the groups, estimate final centers of blobs and their radiuses and return as locations and sizes of keypoints.
This class performs several filtrations of returned blobs. You should set ``filterBy*`` to true/false to turn on/off corresponding filtration. Available filtrations:
* **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.
* **By area**. Extracted blobs have an area between ``minArea`` (inclusive) and ``maxArea`` (exclusive).
* **By circularity**. Extracted blobs have circularity (:math:`\frac{4*\pi*Area}{perimeter * perimeter}`) between ``minCircularity`` (inclusive) and ``maxCircularity`` (exclusive).
* **By ratio of the minimum inertia to maximum inertia**. Extracted blobs have this ratio between ``minInertiaRatio`` (inclusive) and ``maxInertiaRatio`` (exclusive).
* **By convexity**. Extracted blobs have convexity (area / area of blob convex hull) between ``minConvexity`` (inclusive) and ``maxConvexity`` (exclusive).
Default values of parameters are tuned to extract dark circular blobs.
GridAdaptedFeatureDetector
--------------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: GridAdaptedFeatureDetector
Class adapting a detector to partition the source image into a grid and detect points in each cell. ::
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.
* gridCols Grid column count.
*/
2011-02-26 12:05:10 +01:00
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:
...
};
2011-03-03 08:29:55 +01:00
PyramidAdaptedFeatureDetector
-----------------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: 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. ::
class PyramidAdaptedFeatureDetector : public FeatureDetector
{
public:
2011-02-26 12:05:10 +01:00
PyramidAdaptedFeatureDetector( const Ptr<FeatureDetector>& detector,
int levels=2 );
virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const;
protected:
...
};
DynamicAdaptedFeatureDetector
-----------------------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: DynamicAdaptedFeatureDetector
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:
2011-05-12 01:31:50 +02:00
DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster,
2011-03-03 08:29:55 +01:00
int min_features=400, int max_features=500, int max_iters=5 );
...
};
If the detector is persisted, it "remembers" 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
panorama series.
``DynamicAdaptedFeatureDetector`` uses another detector, such as FAST or SURF, to do the dirty work,
2011-05-04 21:22:51 +02:00
with the help of ``AdjusterAdapter`` .
2011-05-12 01:31:50 +02:00
If the detected number of features is not large enough,
2011-05-04 21:22:51 +02:00
``AdjusterAdapter`` adjusts the detection parameters so that the next detection
2011-05-15 22:56:53 +02:00
results in a bigger or smaller number of features. This is repeated until either the number of desired features are found
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-05-12 01:31:50 +02:00
Beware that this is not thread-safe since the adjustment of parameters requires modification of the feature detector class instance.
Example of creating ``DynamicAdaptedFeatureDetector`` : ::
//sample usage:
2011-02-26 12:05:10 +01:00
//will create a detector that attempts to find
//100 - 110 FAST Keypoints, and will at most run
2011-02-26 12:05:10 +01:00
//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-03-03 08:29:55 +01:00
2011-03-03 08:29:55 +01:00
DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector
----------------------------------------------------------------
The constructor
2011-03-03 08:29:55 +01:00
.. ocv:function:: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster, int min_features, int max_features, int max_iters )
2011-03-03 08:29:55 +01:00
:param adjuster: :ocv:class:`AdjusterAdapter` that detects features and adjusts parameters.
2011-03-03 08:29:55 +01:00
:param min_features: Minimum desired number of 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
: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-comsuming. At each iteration the detector is rerun.
2011-03-03 08:29:55 +01:00
AdjusterAdapter
---------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: AdjusterAdapter
2011-03-03 08:29:55 +01:00
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. ::
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;
virtual Ptr<AdjusterAdapter> clone() const = 0;
static Ptr<AdjusterAdapter> create( const string& detectorType );
2011-03-03 08:29:55 +01:00
};
See
:ocv:class:`FastAdjuster`,
:ocv:class:`StarAdjuster`, and
:ocv:class:`SurfAdjuster` for concrete implementations.
2011-03-03 08:29:55 +01:00
AdjusterAdapter::tooFew
---------------------------
Adjusts the detector parameters to detect more features.
2011-03-03 08:29:55 +01:00
.. ocv:function:: void AdjusterAdapter::tooFew(int min, int n_detected)
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_--;
}
AdjusterAdapter::tooMany
----------------------------
Adjusts the detector parameters to detect less features.
2011-03-03 08:29:55 +01:00
.. ocv:function:: void AdjusterAdapter::tooMany(int max, int n_detected)
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_++;
}
AdjusterAdapter::good
-------------------------
Returns false if the detector parameters cannot be adjusted any more.
2011-03-03 08:29:55 +01:00
.. ocv:function:: bool AdjusterAdapter::good() const
2011-05-04 21:22:51 +02:00
Example: ::
2011-03-03 08:29:55 +01:00
bool FastAdjuster::good() const
{
return (thresh_ > 1) && (thresh_ < 200);
}
AdjusterAdapter::create
-------------------------
Creates an adjuster adapter by name
.. ocv:function:: Ptr<AdjusterAdapter> AdjusterAdapter::create( const string& detectorType )
2011-03-03 08:29:55 +01:00
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.
2011-03-03 08:29:55 +01:00
FastAdjuster
------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: FastAdjuster
2011-03-03 08:29:55 +01:00
:ocv:class:`AdjusterAdapter` for :ocv:class:`FastFeatureDetector`. This class decreases or increases the threshold value by 1. ::
2011-03-03 08:29:55 +01:00
class FastAdjuster FastAdjuster: public AdjusterAdapter
{
public:
FastAdjuster(int init_thresh = 20, bool nonmax = true);
...
};
StarAdjuster
------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: StarAdjuster
2011-03-03 08:29:55 +01:00
:ocv:class:`AdjusterAdapter` for :ocv:class:`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);
...
};
SurfAdjuster
------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: SurfAdjuster
2011-03-03 08:29:55 +01:00
:ocv:class:`AdjusterAdapter` for :ocv:class:`SurfFeatureDetector`. This class adjusts the ``hessianThreshold`` of ``SurfFeatureDetector``. ::
2011-03-03 08:29:55 +01:00
class SurfAdjuster: public SurfAdjuster
{
SurfAdjuster();
...
};
FeatureDetector
---------------
2011-06-16 14:48:23 +02:00
.. ocv:class:: FeatureDetector
2011-03-03 08:29:55 +01: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:
...
};