@ -413,10 +413,8 @@ value if all of the corners are found and they are placed
in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder
in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder
them, it returns 0. For example, a regular chessboard has 8 x 8
them, it returns 0. For example, a regular chessboard has 8 x 8
squares and 7 x 7 internal corners, that is, points where the black
squares and 7 x 7 internal corners, that is, points where the black
squares touch each other. The detected coordinates are approximate,
squares touch each other. The detected coordinates are approximate so the function calls :ref:`cornerSubPix` internally to determine their position more accurately.
and to determine their position more accurately, you may use
You also may use the function :ref:`cornerSubPix` with different parameters if returned coordinates are not accurate enough.
the function
:ref:`cornerSubPix`.
Sample usage of detecting and drawing chessboard corners: ::
Sample usage of detecting and drawing chessboard corners: ::
then the point :math:`i` is considered an outlier. If ``srcPoints`` and ``dstPoints`` are measured in pixels, it usually makes sense to set this parameter somewhere in the range of 1 to 10.
then the point :math:`i` is considered an outlier. If ``srcPoints`` and ``dstPoints`` are measured in pixels, it usually makes sense to set this parameter somewhere in the range of 1 to 10.
You can store and then restore various OpenCV data structures to/from XML (http://www.w3c.org/XML) or YAML
(http://www.yaml.org) formats. Also, it is possible store and load arbitrarily complex data structures, which include OpenCV data structures, as well as primitive data types (integer and floating-point numbers and text strings) as their elements.
Use the following procedure to write something to XML or YAML:
#. Create new :ocv:class:`FileStorage` and open it for writing. It can be done with a single call to :ocv:func:`FileStorage::FileStorage` constructor that takes a filename, or you can use the default constructor and then call :ocv:class:`FileStorage::open`. Format of the file (XML or YAML) is determined from the filename extension (".xml" and ".yml"/".yaml", respectively)
#. Write all the data you want using the streaming operator ``>>``, just like in the case of STL streams.
#. Close the file using :ocv:func:`FileStorage::release`. ``FileStorage`` destructor also closes the file.
fs << "{:" << "x" << x << "y" << y << "lbp" << "[:";
for( int j = 0; j < 8; j++ )
fs << ((lbp >> j) & 1);
fs << "]" << "}";
}
fs << "]";
fs.release();
return 0;
}
The sample above stores to XML and integer, text string (calibration date), 2 matrices, and a custom structure "feature", which includes feature coordinates and LBP (local binary pattern) value. Here is output of the sample:
As an exercise, you can replace ".yml" with ".xml" in the sample above and see, how the corresponding XML file will look like.
Several things can be noted by looking at the sample code and the output:
*
The produced YAML (and XML) consists of heterogeneous collections that can be nested. There are 2 types of collections: named collections (mappings) and unnamed collections (sequences). In mappings each element has a name and is accessed by name. This is similar to structures and ``std::map`` in C/C++ and dictionaries in Python. In sequences elements do not have names, they are accessed by indices. This is similar to arrays and ``std::vector`` in C/C++ and lists, tuples in Python. "Heterogeneous" means that elements of each single collection can have different types.
Top-level collection in YAML/XML is a mapping. Each matrix is stored as a mapping, and the matrix elements are stored as a sequence. Then, there is a sequence of features, where each feature is represented a mapping, and lbp value in a nested sequence.
*
When you write to a mapping (a structure), you write element name followed by its value. When you write to a sequence, you simply write the elements one by one. OpenCV data structures (such as cv::Mat) are written in absolutely the same way as simple C data structures - using **``<<``** operator.
*
To write a mapping, you first write the special string **"{"** to the storage, then write the elements as pairs (``fs << <element_name> << <element_value>``) and then write the closing **"}"**.
*
To write a sequence, you first write the special string **"["**, then write the elements, then write the closing **"]"**.
*
In YAML (but not XML), mappings and sequences can be written in a compact Python-like inline form. In the sample above matrix elements, as well as each feature, including its lbp value, is stored in such inline form. To store a mapping/sequence in a compact form, put ":" after the opening character, e.g. use **"{:"** instead of **"{"** and **"[:"** instead of **"["**. When the data is written to XML, those extra ":" are ignored.
Reading data from a file storage.
---------------------------------
To read the previously written XML or YAML file, do the following:
#.
Open the file storage using :ocv:func:`FileStorage::FileStorage` constructor or :ocv:func:`FileStorage::open` method. In the current implementation the whole file is parsed and the whole representation of file storage is built in memory as a hierarchy of file nodes (see :ocv:class:`FileNode`)
#.
Read the data you are interested in. Use :ocv:func:`FileStorage::operator []`, :ocv:func:`FileNode::operator []` and/or :ocv:class:`FileNodeIterator`.
#.
Close the storage using :ocv:func:`FileStorage::release`.
Here is how to read the file created by the code sample above: ::
FileStorage fs2("test.yml", FileStorage::READ);
// first method: use (type) operator on FileNode.
int frameCount = (int)fs2["frameCount"];
std::string date;
// second method: use FileNode::operator >>
fs2["calibrationDate"] >> date;
Mat cameraMatrix2, distCoeffs2;
fs2["cameraMatrix"] >> cameraMatrix2;
fs2["distCoeffs"] >> distCoeffs2;
cout << "frameCount: " << frameCount << endl
<< "calibration date: " << date << endl
<< "camera matrix: " << cameraMatrix2 << endl
<< "distortion coeffs: " << distCoeffs2 << endl;
FileNode features = fs2["features"];
FileNodeIterator it = features.begin(), it_end = features.end();
int idx = 0;
std::vector<uchar> lbpval;
// iterate through a sequence using FileNodeIterator
The class ``FileNode`` represents each element of the file storage, be it a matrix, a matrix element or a top-level node, containing all the file content. That is, a file node may contain either a singe value (integer, floating-point value or a text string), or it can be a sequence of other file nodes, or it can be a mapping. Type of the file node can be determined using :ocv:func:`FileNode::type` method.
// do not use wrapper pointer classes for better efficiency
const CvFileStorage* fs;
const CvFileNode* node;
};
..index:: FileNodeIterator
FileNodeIterator
FileNodeIterator
----------------
----------------
..ocv:class:: FileNodeIterator
..ocv:class:: FileNodeIterator
XML/YAML file node iterator class. ::
The class ``FileNodeIterator`` is used to iterate through sequences and mappings. A standard STL notation, with ``node.begin()``, ``node.end()`` denoting the beginning and the end of a sequence, stored in ``node``. See the data reading sample in the beginning of the section.
@ -5,9 +5,9 @@ Common Interfaces of Descriptor Extractors
Extractors of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
Extractors of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
between different algorithms solving the same problem. This section is devoted to computing descriptors
between different algorithms solving the same problem. This section is devoted to computing descriptors
that are represented as vectors in a multidimensional space. All objects that implement the ``vector``
represented as vectors in a multidimensional space. All objects that implement the ``vector``
descriptor extractors inherit the
descriptor extractors inherit the
:ref:`DescriptorExtractor` interface.
:ocv:class:`DescriptorExtractor` interface.
..index:: DescriptorExtractor
..index:: DescriptorExtractor
@ -15,7 +15,7 @@ DescriptorExtractor
-------------------
-------------------
..ocv:class:: DescriptorExtractor
..ocv:class:: DescriptorExtractor
Abstract base class for computing descriptors for image keypoints ::
Abstract base class for computing descriptors for image keypoints. ::
class CV_EXPORTS DescriptorExtractor
class CV_EXPORTS DescriptorExtractor
{
{
@ -45,7 +45,7 @@ dense, fixed-dimension vector of a basic type. Most descriptors
follow this pattern as it simplifies computing
follow this pattern as it simplifies computing
distances between descriptors. Therefore, a collection of
distances between descriptors. Therefore, a collection of
descriptors is represented as
descriptors is represented as
:ref:`Mat` , where each row is a keypoint descriptor.
:ocv:class:`Mat` , where each row is a keypoint descriptor.
..index:: DescriptorExtractor::compute
..index:: DescriptorExtractor::compute
@ -57,9 +57,9 @@ DescriptorExtractor::compute
:param image:Image.
:param image:Image.
:param keypoints:Keypoints. Keypoints for which a descriptor cannot be computed are removed. Somtimes new keypoints can be added, eg SIFT duplicates keypoint with several dominant orientations (for each orientation).
:param keypoints:Keypoints. Keypoints for which a descriptor cannot be computed are removed. Sometimes new keypoints can be added, for example: ``SIFT`` duplicates keypoint with several dominant orientations (for each orientation).
:param descriptors:Descriptors. Row i is the descriptor for keypoint i.
:param descriptors:Descriptors. Row ``i`` is the descriptor for keypoint ``i``.
@ -6,8 +6,8 @@ Common Interfaces of Descriptor Matchers
Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
between different algorithms solving the same problem. This section is devoted to matching descriptors
between different algorithms solving the same problem. This section is devoted to matching descriptors
that are represented as vectors in a multidimensional space. All objects that implement ``vector``
that are represented as vectors in a multidimensional space. All objects that implement ``vector``
descriptor matchers inherit
descriptor matchers inherit the
:ref:`DescriptorMatcher` interface.
:ocv:class:`DescriptorMatcher` interface.
..index:: DMatch
..index:: DMatch
@ -18,7 +18,7 @@ DMatch
..ocv:class:: DMatch
..ocv:class:: DMatch
Class for matching keypoint descriptors: query descriptor index,
Class for matching keypoint descriptors: query descriptor index,
train descriptor index, train image index, and distance between descriptors ::
train descriptor index, train image index, and distance between descriptors. ::
struct DMatch
struct DMatch
{
{
@ -48,7 +48,7 @@ train descriptor index, train image index, and distance between descriptors ::
DescriptorMatcher
DescriptorMatcher
-----------------
-----------------
..c:type:: DescriptorMatcher
..ocv:class:: DescriptorMatcher
Abstract base class for matching keypoint descriptors. It has two groups
Abstract base class for matching keypoint descriptors. It has two groups
of match methods: for matching descriptors of an image with another image or
of match methods: for matching descriptors of an image with another image or
@ -198,7 +198,7 @@ DescriptorMatcher::knnMatch
:param k:Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
:param k:Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
:param compactResult:Parameter that is used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
:param compactResult:Parameter used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
These extended variants of :ocv:func:`DescriptorMatcher::match` methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See :ocv:func:`DescriptorMatcher::match` for the details about query and train descriptors.
These extended variants of :ocv:func:`DescriptorMatcher::match` methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See :ocv:func:`DescriptorMatcher::match` for the details about query and train descriptors.
@ -220,9 +220,9 @@ DescriptorMatcher::radiusMatch
:param masks:Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
:param masks:Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
:param matches:The found matches.
:param matches:Found matches.
:param compactResult:Parameter that is used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
:param compactResult:Parameter used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
:param maxDistance:Threshold for the distance between matched descriptors.
:param maxDistance:Threshold for the distance between matched descriptors.
@ -265,7 +265,7 @@ DescriptorMatcher::create
BruteForceMatcher
BruteForceMatcher
-----------------
-----------------
..c:type:: BruteForceMatcher
..ocv:class:: BruteForceMatcher
Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches of descriptor sets. ::
Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches of descriptor sets. ::
@ -351,9 +351,9 @@ For efficiency, ``BruteForceMatcher`` is used as a template parameterized with t
FlannBasedMatcher
FlannBasedMatcher
-----------------
-----------------
..c:type:: FlannBasedMatcher
..ocv:class:: FlannBasedMatcher
Flann-based descriptor matcher. This matcher trains :ref:`flann::Index` on a train descriptor collection and calls its nearest search methods to find the best matches. So, this matcher may be faster when matching a large train collection than the brute force matcher. ``FlannBasedMatcher`` does not support masking permissible matches of descriptor sets because :ocv:func:`flann::Index` does not support this. ::
Flann-based descriptor matcher. This matcher trains :ocv:func:`flann::Index` on a train descriptor collection and calls its nearest search methods to find the best matches. So, this matcher may be faster when matching a large train collection than the brute force matcher. ``FlannBasedMatcher`` does not support masking permissible matches of descriptor sets because ``flann::Index`` does not support this. ::
class FlannBasedMatcher : public DescriptorMatcher
class FlannBasedMatcher : public DescriptorMatcher
:ref:`PyramidAdaptedFeatureDetector` ) + feature detector name (see above),
:ocv:class:`PyramidAdaptedFeatureDetector` ) + feature detector name (see above),
for example: ``"GridFAST"``, ``"PyramidSTAR"`` .
for example: ``"GridFAST"``, ``"PyramidSTAR"`` .
FastFeatureDetector
FastFeatureDetector
@ -156,7 +156,7 @@ FastFeatureDetector
..ocv:class:: FastFeatureDetector
..ocv:class:: FastFeatureDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`FAST` method ::
:ocv:func:`FAST` method. ::
class FastFeatureDetector : public FeatureDetector
class FastFeatureDetector : public FeatureDetector
{
{
@ -173,7 +173,7 @@ GoodFeaturesToTrackDetector
..ocv:class:: GoodFeaturesToTrackDetector
..ocv:class:: GoodFeaturesToTrackDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`goodFeaturesToTrack` function ::
:ocv:func:`goodFeaturesToTrack` function. ::
class GoodFeaturesToTrackDetector : public FeatureDetector
class GoodFeaturesToTrackDetector : public FeatureDetector
{
{
@ -211,7 +211,7 @@ MserFeatureDetector
..ocv:class:: MserFeatureDetector
..ocv:class:: MserFeatureDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`MSER` class ::
:ocv:class:`MSER` class. ::
class MserFeatureDetector : public FeatureDetector
class MserFeatureDetector : public FeatureDetector
{
{
@ -233,7 +233,7 @@ StarFeatureDetector
..ocv:class:: StarFeatureDetector
..ocv:class:: StarFeatureDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`StarDetector` class ::
:ocv:class:`StarDetector` class. ::
class StarFeatureDetector : public FeatureDetector
class StarFeatureDetector : public FeatureDetector
{
{
@ -252,7 +252,7 @@ SiftFeatureDetector
..ocv:class:: SiftFeatureDetector
..ocv:class:: SiftFeatureDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`SIFT` class ::
:ocv:class:`SIFT` class. ::
class SiftFeatureDetector : public FeatureDetector
class SiftFeatureDetector : public FeatureDetector
{
{
@ -276,7 +276,7 @@ SurfFeatureDetector
..ocv:class:: SurfFeatureDetector
..ocv:class:: SurfFeatureDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`SURF` class ::
:ocv:class:`SURF` class. ::
class SurfFeatureDetector : public FeatureDetector
class SurfFeatureDetector : public FeatureDetector
{
{
@ -295,7 +295,7 @@ OrbFeatureDetector
..ocv:class:: OrbFeatureDetector
..ocv:class:: OrbFeatureDetector
Wrapping class for feature detection using the
Wrapping class for feature detection using the
:ref:`ORB` class ::
:ocv:class:`ORB` class. ::
class OrbFeatureDetector : public FeatureDetector
class OrbFeatureDetector : public FeatureDetector
{
{
@ -311,7 +311,7 @@ SimpleBlobDetector
-------------------
-------------------
..ocv:class:: SimpleBlobDetector
..ocv:class:: SimpleBlobDetector
Class for extracting blobs from an image ::
Class for extracting blobs from an image. ::
class SimpleBlobDetector : public FeatureDetector
class SimpleBlobDetector : public FeatureDetector
{
{
@ -347,19 +347,27 @@ Class for extracting blobs from an image ::
...
...
};
};
The class implements a simple algorithm for extracting blobs from an image. It converts the source image to binary images by applying thresholding with several thresholds from ``minThreshold`` (inclusive) to ``maxThreshold`` (exclusive) with distance ``thresholdStep`` between neighboring thresholds. Then connected components are extracted from every binary image by :ocv:func:`findContours` and their centers are calculated. Centers from several binary images are grouped by their coordinates. Close centers form one group that corresponds to one blob and this is controled by the ``minDistBetweenBlobs`` parameter. Then final centers of blobs and their radiuses are estimated from these groups and returned as locations and sizes of keypoints.
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:
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 then the blob is filtered out. Use ``blobColor = 0`` to extract dark blobs and ``blobColor = 255`` to extract light blobs.
* **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 will have area between ``minArea`` (inclusive) and ``maxArea`` (exclusive).
* **By area**. Extracted blobs have an area between ``minArea`` (inclusive) and ``maxArea`` (exclusive).
* By circularity. Extracted blobs will have circularity (:math:`\frac{4*\pi*Area}{perimeter * perimeter}`) between ``minCircularity`` (inclusive) and ``maxCircularity`` (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 will have this ratio between ``minInertiaRatio`` (inclusive) and ``maxInertiaRatio`` (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 will have convexity (area / area of blob convex hull) between ``minConvexity`` (inclusive) and ``maxConvexity`` (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.
Default values of parameters are tuned to extract dark circular blobs.
@ -368,7 +376,7 @@ GridAdaptedFeatureDetector
--------------------------
--------------------------
..ocv:class:: GridAdaptedFeatureDetector
..ocv:class:: GridAdaptedFeatureDetector
Class adapting a detector to partition the source image into a grid and detect points in each cell ::
Class adapting a detector to partition the source image into a grid and detect points in each cell. ::
class GridAdaptedFeatureDetector : public FeatureDetector
class GridAdaptedFeatureDetector : public FeatureDetector
{
{
@ -411,7 +419,7 @@ DynamicAdaptedFeatureDetector
-----------------------------
-----------------------------
..ocv:class:: DynamicAdaptedFeatureDetector
..ocv:class:: DynamicAdaptedFeatureDetector
Adaptively adjusting detector that iteratively detects features until the desired number is found ::
Adaptively adjusting detector that iteratively detects features until the desired number is found. ::
class DynamicAdaptedFeatureDetector: public FeatureDetector
class DynamicAdaptedFeatureDetector: public FeatureDetector
{
{
@ -426,7 +434,7 @@ used for the last detection. In this case, the detector may be used for consiste
of keypoints in a set of temporally related images, such as video streams or
of keypoints in a set of temporally related images, such as video streams or
panorama series.
panorama series.
``DynamicAdaptedFeatureDetector`` uses another detector such as FAST or SURF to do the dirty work,
``DynamicAdaptedFeatureDetector`` uses another detector, such as FAST or SURF, to do the dirty work,
with the help of ``AdjusterAdapter`` .
with the help of ``AdjusterAdapter`` .
If the detected number of features is not large enough,
If the detected number of features is not large enough,
``AdjusterAdapter`` adjusts the detection parameters so that the next detection
``AdjusterAdapter`` adjusts the detection parameters so that the next detection
@ -448,25 +456,27 @@ Example of creating ``DynamicAdaptedFeatureDetector`` : ::
..ocv:function:: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster, int min_features, int max_features, int max_iters )
..ocv:function:: DynamicAdaptedFeatureDetector::DynamicAdaptedFeatureDetector( const Ptr<AdjusterAdapter>& adjuster, int min_features, int max_features, int max_iters )
Constructs the class.
Constructs the class.
:param adjuster::ref:`AdjusterAdapter` that detects features and adjusts parameters.
:param adjuster::ocv:class:`AdjusterAdapter` that detects features and adjusts parameters.
:param min_features:Minimum desired number of features.
:param min_features:Minimum desired number of features.
:param max_features:Maximum desired number of features.
:param max_features:Maximum desired number of features.
:param max_iters:Maximum number of times to try adjusting the feature detector parameters. For :ref:`FastAdjuster` , this number can be high, but with ``Star`` or ``Surf`` many iterations can be time-comsuming. At each iteration the detector is rerun.
: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.
AdjusterAdapter
AdjusterAdapter
---------------
---------------
..ocv:class:: AdjusterAdapter
..ocv:class:: AdjusterAdapter
Class providing an interface for adjusting parameters of a feature detector. This interface is used by :ref:`DynamicAdaptedFeatureDetector` . It is a wrapper for :ref:`FeatureDetector` that enables adjusting parameters after feature detection. ::
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. ::
class AdjusterAdapter: public FeatureDetector
class AdjusterAdapter: public FeatureDetector
{
{
@ -481,9 +491,9 @@ Class providing an interface for adjusting parameters of a feature detector. Thi
See
See
:ref:`FastAdjuster`,
:ocv:class:`FastAdjuster`,
:ref:`StarAdjuster`,
:ocv:class:`StarAdjuster`, and
:ref:`SurfAdjuster` for concrete implementations.
:ocv:class:`SurfAdjuster` for concrete implementations.
Creates adjuster adapter by name ``detectorType``. The detector name is the same as in :ocv:func:`FeatureDetector::create`, but now supported``"FAST"``, ``"STAR"`` and ``"SURF"`` only.
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.
FastAdjuster
FastAdjuster
------------
------------
..ocv:class:: FastAdjuster
..ocv:class:: FastAdjuster
:ref:`AdjusterAdapter` for :ref:`FastFeatureDetector`. This class decreases or increases the threshold value by 1. ::
:ocv:class:`AdjusterAdapter` for :ocv:class:`FastFeatureDetector`. This class decreases or increases the threshold value by 1. ::
class FastAdjuster FastAdjuster: public AdjusterAdapter
class FastAdjuster FastAdjuster: public AdjusterAdapter
{
{
@ -556,7 +566,7 @@ StarAdjuster
------------
------------
..ocv:class:: StarAdjuster
..ocv:class:: StarAdjuster
:ref:`AdjusterAdapter` for :ref:`StarFeatureDetector`. This class adjusts the ``responseThreshhold`` of ``StarFeatureDetector``. ::
:ocv:class:`AdjusterAdapter` for :ocv:class:`StarFeatureDetector`. This class adjusts the ``responseThreshhold`` of ``StarFeatureDetector``. ::
class StarAdjuster: public AdjusterAdapter
class StarAdjuster: public AdjusterAdapter
{
{
@ -568,7 +578,7 @@ SurfAdjuster
------------
------------
..ocv:class:: SurfAdjuster
..ocv:class:: SurfAdjuster
:ref:`AdjusterAdapter` for :ref:`SurfFeatureDetector`. This class adjusts the ``hessianThreshold`` of ``SurfFeatureDetector``. ::
:ocv:class:`AdjusterAdapter` for :ocv:class:`SurfFeatureDetector`. This class adjusts the ``hessianThreshold`` of ``SurfFeatureDetector``. ::
class SurfAdjuster: public SurfAdjuster
class SurfAdjuster: public SurfAdjuster
{
{
@ -580,7 +590,7 @@ FeatureDetector
---------------
---------------
..ocv:class:: FeatureDetector
..ocv:class:: FeatureDetector
Abstract base class for 2D image feature detectors ::
Abstract base class for 2D image feature detectors. ::
Abstract interface for extracting and matching a keypoint descriptor. There are also :ref:`DescriptorExtractor` and :ref:`DescriptorMatcher` for these purposes but their interfaces are intended for descriptors represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors. :ref:`DescriptorMatcher` and ``GenericDescriptorMatcher`` have two groups of match methods: for matching keypoints of an image with another image or with an image set. ::
Abstract interface for extracting and matching a keypoint descriptor. There are also :ocv:class:`DescriptorExtractor` and :ocv:class:`DescriptorMatcher` for these purposes but their interfaces are intended for descriptors represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors. ``DescriptorMatcher`` and ``GenericDescriptorMatcher`` have two groups of match methods: for matching keypoints of an image with another image or with an image set. ::
:param trainKeypoints:Keypoints from a train image.
:param trainKeypoints:Keypoints from a train image.
The method classifies each keypoint from a query set. The first variant of the method takes a train image and its keypoints as an input argument. The second variant uses the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method.
The method classifies each keypoint from a query set. The first variant of the method takes a train image and its keypoints as an input argument. The second variant uses the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method.
The methods do the following:
The methods do the following:
#.
#.
Call the ``GenericDescriptorMatcher::match`` method to find correspondence between the query set and the training set.
Call the ``GenericDescriptorMatcher::match`` method to find correspondence between the query set and the training set.
#.
#.
Sey the ``class_id`` field of each keypoint from the query set to ``class_id`` of the corresponding keypoint from the training set.
Set the ``class_id`` field of each keypoint from the query set to ``class_id`` of the corresponding keypoint from the training set.
:param matches:Matches. If a query descriptor (keypoint) is masked out in ``mask`` , match is added for this descriptor. So, ``matches`` size may be smaller than the query keypoints count.
:param matches:Matches. If a query descriptor (keypoint) is masked out in ``mask`` , match is added for this descriptor. So, ``matches`` size may be smaller than the query keypoints count.
:param mask:Mask specifying permissible matches between input query and train keypoints.
:param mask:Mask specifying permissible matches between an input query and train keypoints.
:param masks:Set of masks. Each ``masks[i]`` specifies permissible matches between input query keypoints and stored train keypoints from the i-th image.
:param masks:Set of masks. Each ``masks[i]`` specifies permissible matches between input query keypoints and stored train keypoints from the i-th image.
The methods find the best match for each query keypoint. In the first variant of the method, a train image and its keypoints are the input arguments. In the second variant, query keypoints are matched to the internally stored training collection that can be built using ``GenericDescriptorMatcher::add`` method. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, ``queryKeypoints[i]`` can be matched with ``trainKeypoints[j]`` only if ``mask.at<uchar>(i,j)`` is non-zero.
The methods find the best match for each query keypoint. In the first variant of the method, a train image and its keypoints are the input arguments. In the second variant, query keypoints are matched to the internally stored training collection that can be built using the ``GenericDescriptorMatcher::add`` method. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, ``queryKeypoints[i]`` can be matched with ``trainKeypoints[j]`` only if ``mask.at<uchar>(i,j)`` is non-zero.
Find the ``k`` best matches for each query keypoint.
Finds the ``k`` best matches for each query keypoint.
The methods are extended variants of ``GenericDescriptorMatch::match``. The parameters are similar, and the the semantics is similar to ``DescriptorMatcher::knnMatch``. But this class does not require explicitly computed keypoint descriptors.
The methods are extended variants of ``GenericDescriptorMatch::match``. The parameters are similar, and the the semantics is similar to ``DescriptorMatcher::knnMatch``. But this class does not require explicitly computed keypoint descriptors.
Draw the found matches of keypoints from two images
Draws the found matches of keypoints from two images.
:param img1:The first source image.
:param img1:First source image.
:param keypoints1:Keypoints from the first source image.
:param keypoints1:Keypoints from the first source image.
:param img2:The second source image.
:param img2:Second source image.
:param keypoints2:Keypoints from the second source image.
:param keypoints2:Keypoints from the second source image.
@ -75,5 +75,5 @@ drawKeypoints
:param color:Color of keypoints.
:param color:Color of keypoints.
:param flags:Flags setting drawing features. Possible ``flags`` bit values are defined by ``DrawMatchesFlags``. See details above in :ref:`drawMatches` .
:param flags:Flags setting drawing features. Possible ``flags`` bit values are defined by ``DrawMatchesFlags``. See details above in :ocv:func:`drawMatches` .
http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions). Also see http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/MSER for usefull comments and parameters description.
..index:: StarDetector
..index:: StarDetector
@ -56,7 +56,7 @@ StarDetector
------------
------------
..ocv:class:: StarDetector
..ocv:class:: StarDetector
Class implementing the Star keypoint detector ::
Class implementing the ``Star`` keypoint detector. ::
class StarDetector : CvStarDetectorParams
class StarDetector : CvStarDetectorParams
{
{
@ -89,13 +89,11 @@ The class implements a modified version of the ``CenSurE`` keypoint detector des
..index:: SIFT
..index:: SIFT
.._SIFT:
SIFT
SIFT
----
----
..ocv:class:: SIFT
..ocv:class:: SIFT
Class for extracting keypoints and computing descriptors using the Scale Invariant Feature Transform (SIFT) approach ::
Class for extracting keypoints and computing descriptors using the Scale Invariant Feature Transform (SIFT) approach. ::
class CV_EXPORTS SIFT
class CV_EXPORTS SIFT
{
{
@ -179,13 +177,11 @@ Class for extracting keypoints and computing descriptors using the Scale Invaria
..index:: SURF
..index:: SURF
.._SURF:
SURF
SURF
----
----
..ocv:class:: SURF
..ocv:class:: SURF
Class for extracting Speeded Up Robust Features from an image ::
Class for extracting Speeded Up Robust Features from an image. ::
class SURF : public CvSURFParams
class SURF : public CvSURFParams
{
{
@ -214,18 +210,16 @@ The class implements the Speeded Up Robust Features descriptor
[Bay06].
[Bay06].
There is a fast multi-scale Hessian keypoint detector that can be used to find keypoints
There is a fast multi-scale Hessian keypoint detector that can be used to find keypoints
(default option). But the descriptors can be also computed for the user-specified keypoints.
(default option). But the descriptors can be also computed for the user-specified keypoints.
The algorithm can be used for object tracking and localization, image stitching, and so on. See the ``find_obj.cpp`` demo in OpenCV samples directory.
The algorithm can be used for object tracking and localization, image stitching, and so on. See the ``find_obj.cpp`` demo in the OpenCV samples directory.
..index:: ORB
..index:: ORB
.._ORB:
ORB
ORB
----
----
..ocv:class:: ORB
..ocv:class:: ORB
Class for extracting ORB features and descriptors from an image ::
Class for extracting ORB features and descriptors from an image. ::
class ORB
class ORB
{
{
@ -272,18 +266,17 @@ Class for extracting ORB features and descriptors from an image ::
bool useProvidedKeypoints=false) const;
bool useProvidedKeypoints=false) const;
};
};
The class implements ORB
The class implements ORB.
..index:: RandomizedTree
..index:: RandomizedTree
.._RandomizedTree:
RandomizedTree
RandomizedTree
--------------
--------------
..ocv:class:: RandomizedTree
..ocv:class:: RandomizedTree
Class containing a base structure for ``RTreeClassifier`` ::
Class containing a base structure for ``RTreeClassifier``. ::
class CV_EXPORTS RandomizedTree
class CV_EXPORTS RandomizedTree
{
{
@ -423,7 +416,7 @@ RTreeNode
---------
---------
..ocv:class:: RTreeNode
..ocv:class:: RTreeNode
Class containing a base structure for ``RandomizedTree`` ::
Class containing a base structure for ``RandomizedTree``. ::
struct RTreeNode
struct RTreeNode
{
{
@ -451,7 +444,7 @@ RTreeClassifier
---------------
---------------
..ocv:class:: RTreeClassifier
..ocv:class:: RTreeClassifier
Class containing ``RTreeClassifier``. It represents the Calonder descriptor that was originally introduced by Michael Calonder. ::
Class containing ``RTreeClassifier``. It represents the Calonder descriptor originally introduced by Michael Calonder. ::
..ocv:function:: BOWKMeansTrainer::BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(), int attempts=3, int flags=KMEANS_PP_CENTERS );
..ocv:function:: BOWKMeansTrainer::BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(), int attempts=3, int flags=KMEANS_PP_CENTERS );
To understand constructor parameters, see :ref:`kmeans` function arguments.
See :ocv:func:`kmeans` function parameters.
BOWImgDescriptorExtractor
BOWImgDescriptorExtractor
-------------------------
-------------------------
..ocv:class:: BOWImgDescriptorExtractor
..ocv:class:: BOWImgDescriptorExtractor
Class to compute an image descriptor using the ''bag of visual words''. Such a computation consists of the following steps:
Class to compute an image descriptor using the *bag of visual words*. Such a computation consists of the following steps:
#. Compute descriptors for a given image and its keypoints set.
#. Compute descriptors for a given image and its keypoints set.
#. Find the nearest visual words from the vocabulary for each keypoint descriptor.
#. Find the nearest visual words from the vocabulary for each keypoint descriptor.
#. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words encountered in the image. The ``i``-th bin of the histogram is a frequency of ``i``-th word of the vocabulary in the given image.
#. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words encountered in the image. The ``i``-th bin of the histogram is a frequency of ``i``-th word of the vocabulary in the given image.
:param vocabulary:Vocabulary (can be trained using the inheritor of :ref:`BOWTrainer` ). Each row of the vocabulary is a visual word (cluster center).
:param vocabulary:Vocabulary (can be trained using the inheritor of :ocv:class:`BOWTrainer` ). Each row of the vocabulary is a visual word (cluster center).
:param delay:Delay in milliseconds. 0 is the special value that means "forever".
:param delay:Delay in milliseconds. 0 is the special value that means "forever".
The function ``waitKey`` waits for a key event infinitely (when
The function ``waitKey`` waits for a key event infinitely (when
:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it is positive. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the function will not wait exactly ``delay`` ms, it will wait at least ``delay`` ms, depending on what else is running on your computer at that time. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
``bilateralFilter`` can do a very good job of reducing unwanted noise while keep edges fairly sharp. However it is very slow compared to most filters.
*Sigma values*: For simplicity, you can set the 2 sigma values to be the same. If they are small (< 10) then the filter will not have much effect, whereas if they are large (> 150) then they will have a very strong effect, making the image look "cartoonish".
*Filter size*: Large filters (d > 5) are very slow, so it is recommended to use d=5 for real-time applications, and perhaps d=9 for offline applications that need heavy noise filtering.
To shrink an image, it will generally look best with CV_INTER_AREA interpolation, whereas to enlarge an image, it will generally look best with CV_INTER_CUBIC (slow) or CV_INTER_LINEAR (faster but still looks OK).
The function converts an input image from one color
The function converts an input image from one color
space to another. In case of transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR).
space to another. In case of transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR).
Note that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue component, the second byte will be Green and the third byte will be Red. The fourth, fifth and sixth bytes would then be the 2nd pixel (Blue then Green then Red) and so on.
The conventional ranges for R, G, and B channel values are:
The conventional ranges for R, G, and B channel values are:
@ -103,6 +104,8 @@ But in case of a non-linear transformation, an input RGB image should be normali
img *= 1./255;
img *= 1./255;
cvtColor(img, img, CV_BGR2Luv);
cvtColor(img, img, CV_BGR2Luv);
If you use ``cvtColor`` with 8-bit images then conversion will have lost some information. For many applications this will not be noticeable but it is recommended to use 32-bit images in applications that need the full range of colors or that convert an image before an operation and then convert back.
The function can do the following transformations:
The function can do the following transformations:
The structure contains all the decision tree training parameters. You can initialize it by default constructor and then override any parameters directly before training, or the structure may be fully initialized using the advanced variant of the constructor.
{
int max_categories;
..index:: CvDTreeParams::CvDTreeParams
int max_depth;
int min_sample_count;
.._CvDTreeParams::CvDTreeParams
int cv_folds;
bool use_surrogates;
CvDTreeParams::CvDTreeParams
bool use_1se_rule;
----------------------------
bool truncate_pruned_tree;
..ocv:function:: CvDTreeParams::CvDTreeParams()
float regression_accuracy;
const float* priors;
..ocv:function:: CvDTreeParams( int max_depth, int min_sample_count, float regression_accuracy, bool use_surrogates, int max_categories, int cv_folds, bool use_1se_rule, bool truncate_pruned_tree, const float* priors )
:param max_depth:The maximum number of levels in a tree. The depth of a constructed tree may be smaller due to other termination criterias or pruning of the tree.
:param min_sample_count:If the number of samples in a node is less than this parameter then the node will not be splitted.
{}
:param regression_accuracy:Termination criteria for regression trees. If all absolute differences between an estimated value in a node and values of train samples in this node are less than this parameter then the node will not be splitted.
CvDTreeParams( int _max_depth, int _min_sample_count,
float _regression_accuracy, bool _use_surrogates,
:param use_surrogates:If true then surrogate splits will be built. These splits allow to work with missing data.
int _max_categories, int _cv_folds,
bool _use_1se_rule, bool _truncate_pruned_tree,
:param max_categories:Cluster possible values of a categorical variable into ``K`` :math:`\leq` ``max_categories`` clusters to find a suboptimal split. The clustering is applied only in n>2-class classification problems for categorical variables with ``N > max_categories`` possible values. See the Learning OpenCV book (page 489) for more detailed explanation.
const float* _priors );
};
:param cv_folds:If ``cv_folds > 1`` then prune a tree with ``K``-fold cross-validation where ``K`` is equal to ``cv_folds``.
:param use_1se_rule:If true then a pruning will be harsher. This will make a tree more compact but a bit less accurate.
:param truncate_pruned_tree:If true then pruned branches are removed completely from the tree. Otherwise they are retained and it is possible to get the unpruned tree or prune the tree differently by changing ``CvDTree::pruned_tree_idx`` parameter.
:param priors:Weights of prediction categories which determine relative weights that you give to misclassification. That is, if the weight of the first category is 1 and the weight of the second category is 10, then each mistake in predicting the second category is equivalent to making 10 mistakes in predicting the first category.
The default constructor initializes all the parameters with the default values tuned for the standalone classification tree:
::
The structure contains all the decision tree training parameters. There is a default constructor that initializes all the parameters with the default values tuned for the standalone classification tree. Any parameters can be overridden then, or the structure may be fully initialized using the advanced variant of the constructor.
Vadim Pisarevsky
14 years ago