mirror/opencv
1
0
Fork 0
mirror of https://github.com/opencv/opencv.git synced 2025-06-07 17:44:04 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

cleaned RST formatting a bit

Browse Source
This commit is contained in:
Vadim Pisarevsky 2011-02-26 11:05:10 +00:00
parent d7b3e254dd
commit 24ccbccf63
61 changed files with 6843 additions and 25874 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
modules/calib3d/doc/calib3d.rst
View File

@ -1,6 +1,6 @@
**************************************** *************************************************
Camera Calibration and 3D Reconstruction calib3d. Camera Calibration and 3D Reconstruction
**************************************** *************************************************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

2181
modules/calib3d/doc/camera_calibration_and_3d_reconstruction.rst
View File

File diff suppressed because it is too large Load Diff

3162
modules/core/doc/basic_structures.rst
View File

File diff suppressed because it is too large Load Diff

125
modules/core/doc/clustering.rst
View File

@ -3,136 +3,73 @@ Clustering
.. highlight:: cpp .. highlight:: cpp
.. index:: kmeans .. index:: kmeans
cv::kmeans cv::kmeans
---------- ----------
`id=0.0672046481842 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/kmeans>`__
.. cfunction:: double kmeans( const Mat\& samples, int clusterCount, Mat\& labels, TermCriteria termcrit, int attempts, int flags, Mat* centers ) .. cfunction:: double kmeans( const Mat\& samples, int clusterCount, Mat\& labels, TermCriteria termcrit, int attempts, int flags, Mat* centers )
Finds the centers of clusters and groups the input samples around the clusters. Finds the centers of clusters and groups the input samples around the clusters.
:param samples: Floating-point matrix of input samples, one row per sample
:param clusterCount: The number of clusters to split the set by
:param labels: The input/output integer array that will store the cluster indices for every sample
:param termcrit: Specifies maximum number of iterations and/or accuracy (distance the centers can move by between subsequent iterations)
:param attempts: How many times the algorithm is executed using different initial labelings. The algorithm returns the labels that yield the best compactness (see the last function parameter)
:param flags: It can take the following values:
* **KMEANS_RANDOM_CENTERS** Random initial centers are selected in each attempt
* **KMEANS_PP_CENTERS** Use kmeans++ center initialization by Arthur and Vassilvitskii
:param samples: Floating-point matrix of input samples, one row per sample
:param clusterCount: The number of clusters to split the set by
:param labels: The input/output integer array that will store the cluster indices for every sample
:param termcrit: Specifies maximum number of iterations and/or accuracy (distance the centers can move by between subsequent iterations)
:param attempts: How many times the algorithm is executed using different initial labelings. The algorithm returns the labels that yield the best compactness (see the last function parameter)
:param flags: It can take the following values:
* **KMEANS_RANDOM_CENTERS** Random initial centers are selected in each attempt
* **KMEANS_PP_CENTERS** Use kmeans++ center initialization by Arthur and Vassilvitskii
* **KMEANS_USE_INITIAL_LABELS** During the first (and possibly the only) attempt, the * **KMEANS_USE_INITIAL_LABELS** During the first (and possibly the only) attempt, the
function uses the user-supplied labels instaed of computing them from the initial centers. For the second and further attempts, the function will use the random or semi-random centers (use one of ``KMEANS_*_CENTERS`` flag to specify the exact method) function uses the user-supplied labels instaed of computing them from the initial centers. For the second and further attempts, the function will use the random or semi-random centers (use one of ``KMEANS_*_CENTERS`` flag to specify the exact method)
:param centers: The output matrix of the cluster centers, one row per each cluster center
The function ``kmeans`` implements a k-means algorithm that finds the
:param centers: The output matrix of the cluster centers, one row per each cluster center centers of ``clusterCount`` clusters and groups the input samples
around the clusters. On output,
:math:`\texttt{labels}_i` contains a 0-based cluster index for
the sample stored in the
The function :math:`i^{th}` row of the ``samples`` matrix.
``kmeans``
implements a k-means algorithm that finds the
centers of
``clusterCount``
clusters and groups the input samples
around the clusters. On output,
:math:`\texttt{labels}_i`
contains a 0-based cluster index for
the sample stored in the
:math:`i^{th}`
row of the
``samples``
matrix.
The function returns the compactness measure, which is computed as The function returns the compactness measure, which is computed as
.. math:: .. math::
\sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2 \sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2
after every attempt; the best (minimum) value is chosen and the after every attempt; the best (minimum) value is chosen and the
corresponding labels and the compactness value are returned by the function. corresponding labels and the compactness value are returned by the function.
Basically, the user can use only the core of the function, set the number of Basically, the user can use only the core of the function, set the number of
attempts to 1, initialize labels each time using some custom algorithm and pass them with attempts to 1, initialize labels each time using some custom algorithm and pass them with
( ( ``flags`` = ``KMEANS_USE_INITIAL_LABELS`` ) flag, and then choose the best (most-compact) clustering.
``flags``
=
``KMEANS_USE_INITIAL_LABELS``
) flag, and then choose the best (most-compact) clustering.
.. index:: partition .. index:: partition
cv::partition cv::partition
------------- -------------
`id=0.0923567235062 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/partition>`__
.. cfunction:: template<typename _Tp, class _EqPredicate> int .. cfunction:: template<typename _Tp, class _EqPredicate> int
.. cfunction:: partition( const vector<_Tp>\& vec, vector<int>\& labels, _EqPredicate predicate=_EqPredicate()) .. cfunction:: partition( const vector<_Tp>\& vec, vector<int>\& labels, _EqPredicate predicate=_EqPredicate())
Splits an element set into equivalency classes. Splits an element set into equivalency classes.
:param vec: The set of elements stored as a vector
:param labels: The output vector of labels; will contain as many elements as ``vec`` . Each label ``labels[i]`` is 0-based cluster index of ``vec[i]`` :param predicate: The equivalence predicate (i.e. pointer to a boolean function of two arguments or an instance of the class that has the method ``bool operator()(const _Tp& a, const _Tp& b)`` . The predicate returns true when the elements are certainly if the same class, and false if they may or may not be in the same class
The generic function ``partition`` implements an
:math:`O(N^2)` algorithm for
splitting a set of
:param vec: The set of elements stored as a vector :math:`N` elements into one or more equivalency classes, as described in
:param labels: The output vector of labels; will contain as many elements as ``vec`` . Each label ``labels[i]`` is 0-based cluster index of ``vec[i]``
:param predicate: The equivalence predicate (i.e. pointer to a boolean function of two arguments or an instance of the class that has the method ``bool operator()(const _Tp& a, const _Tp& b)`` . The predicate returns true when the elements are certainly if the same class, and false if they may or may not be in the same class
The generic function
``partition``
implements an
:math:`O(N^2)`
algorithm for
splitting a set of
:math:`N`
elements into one or more equivalency classes, as described in
http://en.wikipedia.org/wiki/Disjoint-set_data_structure http://en.wikipedia.org/wiki/Disjoint-set_data_structure
. The function . The function
returns the number of equivalency classes. returns the number of equivalency classes.

6
modules/core/doc/core.rst
View File

@ -1,6 +1,6 @@
****************** ****************************
Core Functionality core. The Core Functionality
****************** ****************************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

673
modules/core/doc/drawing_functions.rst
View File

@ -3,442 +3,225 @@ Drawing Functions
.. highlight:: cpp .. highlight:: cpp
Drawing functions work with matrices/images of arbitrary depth. Drawing functions work with matrices/images of arbitrary depth.
The boundaries of the shapes can be rendered with antialiasing (implemented only for 8-bit images for now). The boundaries of the shapes can be rendered with antialiasing (implemented only for 8-bit images for now).
All the functions include the parameter color that uses a rgb value (that may be constructed All the functions include the parameter color that uses a rgb value (that may be constructed
with with ``CV_RGB`` or the :ref:`Scalar` constructor
``CV_RGB``
or the :ref:`Scalar` constructor
) for color ) for color
images and brightness for grayscale images. For color images the order channel images and brightness for grayscale images. For color images the order channel
is normally is normally
*Blue, Green, Red* *Blue, Green, Red*
, this is what , this is what
:func:`imshow` :func:`imshow`,:func:`imread` and
, :func:`imwrite` expect
:func:`imread` , so if you form a color using
and :ref:`Scalar` constructor, it should look like:
:func:`imwrite`
expect
, so if you form a color using
:ref:`Scalar`
constructor, it should look like:
.. math:: .. math::
\texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component]) \texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component])
If you are using your own image rendering and I/O functions, you can use any channel ordering, the drawing functions process each channel independently and do not depend on the channel order or even on the color space used. The whole image can be converted from BGR to RGB or to a different color space using
:func:`cvtColor` .
If you are using your own image rendering and I/O functions, you can use any channel ordering, the drawing functions process each channel independently and do not depend on the channel order or even on the color space used. The whole image can be converted from BGR to RGB or to a different color space using If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also, many drawing functions can handle pixel coordinates specified with sub-pixel accuracy, that is, the coordinates can be passed as fixed-point numbers, encoded as integers. The number of fractional bits is specified by the ``shift`` parameter and the real point coordinates are calculated as
:func:`cvtColor` :math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})` . This feature is especially effective wehn rendering antialiased shapes.
.
If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also, many drawing functions can handle pixel coordinates specified with sub-pixel accuracy, that is, the coordinates can be passed as fixed-point numbers, encoded as integers. The number of fractional bits is specified by the
``shift``
parameter and the real point coordinates are calculated as
:math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})`
. This feature is especially effective wehn rendering antialiased shapes.
Also, note that the functions do not support alpha-transparency - when the target image is 4-channnel, then the
``color[3]``
is simply copied to the repainted pixels. Thus, if you want to paint semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main image.
Also, note that the functions do not support alpha-transparency - when the target image is 4-channnel, then the ``color[3]`` is simply copied to the repainted pixels. Thus, if you want to paint semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main image.
.. index:: circle .. index:: circle
cv::circle cv::circle
---------- ----------
`id=0.143685141364 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/circle>`__
.. cfunction:: void circle(Mat\& img, Point center, int radius, const Scalar\& color, int thickness=1, int lineType=8, int shift=0) .. cfunction:: void circle(Mat\& img, Point center, int radius, const Scalar\& color, int thickness=1, int lineType=8, int shift=0)
Draws a circle Draws a circle
:param img: Image where the circle is drawn
:param center: Center of the circle
:param radius: Radius of the circle
:param color: Circle color
:param thickness: Thickness of the circle outline if positive; negative thickness means that a filled circle is to be drawn
:param img: Image where the circle is drawn
:param lineType: Type of the circle boundary, see :func:`line` description
:param center: Center of the circle :param shift: Number of fractional bits in the center coordinates and radius value
The function ``circle`` draws a simple or filled circle with a
:param radius: Radius of the circle
:param color: Circle color
:param thickness: Thickness of the circle outline if positive; negative thickness means that a filled circle is to be drawn
:param lineType: Type of the circle boundary, see :func:`line` description
:param shift: Number of fractional bits in the center coordinates and radius value
The function
``circle``
draws a simple or filled circle with a
given center and radius. given center and radius.
.. index:: clipLine .. index:: clipLine
cv::clipLine cv::clipLine
------------ ------------
`id=0.715949286846 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/clipLine>`__
.. cfunction:: bool clipLine(Size imgSize, Point\& pt1, Point\& pt2) .. cfunction:: bool clipLine(Size imgSize, Point\& pt1, Point\& pt2)
.. cfunction:: bool clipLine(Rect imgRect, Point\& pt1, Point\& pt2) .. cfunction:: bool clipLine(Rect imgRect, Point\& pt1, Point\& pt2)
Clips the line against the image rectangle Clips the line against the image rectangle
:param imgSize: The image size; the image rectangle will be ``Rect(0, 0, imgSize.width, imgSize.height)`` :param imgSize: The image rectangle
:param pt1: The first line point
:param pt2: The second line point
The functions ``clipLine`` calculate a part of the line
:param imgSize: The image size; the image rectangle will be ``Rect(0, 0, imgSize.width, imgSize.height)``
:param imgSize: The image rectangle
:param pt1: The first line point
:param pt2: The second line point
The functions
``clipLine``
calculate a part of the line
segment which is entirely within the specified rectangle. segment which is entirely within the specified rectangle.
They return They return ``false`` if the line segment is completely outside the rectangle and ``true`` otherwise.
``false``
if the line segment is completely outside the rectangle and
``true``
otherwise.
.. index:: ellipse .. index:: ellipse
cv::ellipse cv::ellipse
----------- -----------
`id=0.0631091216884 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/ellipse>`__
.. cfunction:: void ellipse(Mat\& img, Point center, Size axes, double angle, double startAngle, double endAngle, const Scalar\& color, int thickness=1, int lineType=8, int shift=0) .. cfunction:: void ellipse(Mat\& img, Point center, Size axes, double angle, double startAngle, double endAngle, const Scalar\& color, int thickness=1, int lineType=8, int shift=0)
.. cfunction:: void ellipse(Mat\& img, const RotatedRect\& box, const Scalar\& color, int thickness=1, int lineType=8) .. cfunction:: void ellipse(Mat\& img, const RotatedRect\& box, const Scalar\& color, int thickness=1, int lineType=8)
Draws a simple or thick elliptic arc or an fills ellipse sector. Draws a simple or thick elliptic arc or an fills ellipse sector.
:param img: The image
:param center: Center of the ellipse
:param axes: Length of the ellipse axes
:param angle: The ellipse rotation angle in degrees
:param startAngle: Starting angle of the elliptic arc in degrees
:param img: The image
:param endAngle: Ending angle of the elliptic arc in degrees
:param center: Center of the ellipse :param box: Alternative ellipse representation via a :ref:`RotatedRect` , i.e. the function draws an ellipse inscribed in the rotated rectangle
:param color: Ellipse color
:param axes: Length of the ellipse axes
:param thickness: Thickness of the ellipse arc outline if positive, otherwise this indicates that a filled ellipse sector is to be drawn
:param angle: The ellipse rotation angle in degrees :param lineType: Type of the ellipse boundary, see :func:`line` description
:param shift: Number of fractional bits in the center coordinates and axes' values
:param startAngle: Starting angle of the elliptic arc in degrees
The functions ``ellipse`` with less parameters draw an ellipse outline, a filled ellipse, an elliptic
arc or a filled ellipse sector.
:param endAngle: Ending angle of the elliptic arc in degrees A piecewise-linear curve is used to approximate the elliptic arc boundary. If you need more control of the ellipse rendering, you can retrieve the curve using
:func:`ellipse2Poly` and then render it with
:func:`polylines` or fill it with
:param box: Alternative ellipse representation via a :ref:`RotatedRect` , i.e. the function draws an ellipse inscribed in the rotated rectangle :func:`fillPoly` . If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass ``startAngle=0`` and ``endAngle=360`` . The picture below
:param color: Ellipse color
:param thickness: Thickness of the ellipse arc outline if positive, otherwise this indicates that a filled ellipse sector is to be drawn
:param lineType: Type of the ellipse boundary, see :func:`line` description
:param shift: Number of fractional bits in the center coordinates and axes' values
The functions
``ellipse``
with less parameters draw an ellipse outline, a filled ellipse, an elliptic
arc or a filled ellipse sector.
A piecewise-linear curve is used to approximate the elliptic arc boundary. If you need more control of the ellipse rendering, you can retrieve the curve using
:func:`ellipse2Poly`
and then render it with
:func:`polylines`
or fill it with
:func:`fillPoly`
. If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass
``startAngle=0``
and
``endAngle=360``
. The picture below
explains the meaning of the parameters. explains the meaning of the parameters.
Parameters of Elliptic Arc Parameters of Elliptic Arc
.. image:: ../../pics/ellipse.png .. image:: ../../pics/ellipse.png
.. index:: ellipse2Poly .. index:: ellipse2Poly
cv::ellipse2Poly cv::ellipse2Poly
---------------- ----------------
`id=0.644340648167 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/ellipse2Poly>`__
.. cfunction:: void ellipse2Poly( Point center, Size axes, int angle, int startAngle, int endAngle, int delta, vector<Point>\& pts ) .. cfunction:: void ellipse2Poly( Point center, Size axes, int angle, int startAngle, int endAngle, int delta, vector<Point>\& pts )
Approximates an elliptic arc with a polyline Approximates an elliptic arc with a polyline
:param center: Center of the arc
:param axes: Half-sizes of the arc. See :func:`ellipse` :param angle: Rotation angle of the ellipse in degrees. See :func:`ellipse` :param startAngle: Starting angle of the elliptic arc in degrees
:param endAngle: Ending angle of the elliptic arc in degrees
:param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy.
:param pts: The output vector of polyline vertices
:param center: Center of the arc
:param axes: Half-sizes of the arc. See :func:`ellipse`
:param angle: Rotation angle of the ellipse in degrees. See :func:`ellipse`
:param startAngle: Starting angle of the elliptic arc in degrees
:param endAngle: Ending angle of the elliptic arc in degrees
:param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy.
:param pts: The output vector of polyline vertices
The function
``ellipse2Poly``
computes the vertices of a polyline that approximates the specified elliptic arc. It is used by
:func:`ellipse`
.
The function ``ellipse2Poly`` computes the vertices of a polyline that approximates the specified elliptic arc. It is used by
:func:`ellipse` .
.. index:: fillConvexPoly .. index:: fillConvexPoly
cv::fillConvexPoly cv::fillConvexPoly
------------------ ------------------
`id=0.345453533071 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fillConvexPoly>`__
.. cfunction:: void fillConvexPoly(Mat\& img, const Point* pts, int npts, const Scalar\& color, int lineType=8, int shift=0) .. cfunction:: void fillConvexPoly(Mat\& img, const Point* pts, int npts, const Scalar\& color, int lineType=8, int shift=0)
Fills a convex polygon. Fills a convex polygon.
:param img: Image
:param pts: The polygon vertices
:param npts: The number of polygon vertices
:param color: Polygon color
:param lineType: Type of the polygon boundaries, see :func:`line` description
:param img: Image
:param shift: The number of fractional bits in the vertex coordinates
:param pts: The polygon vertices The function ``fillConvexPoly`` draws a filled convex polygon.
This function is much faster than the function ``fillPoly`` and can fill not only convex polygons but any monotonic polygon without self-intersections,
:param npts: The number of polygon vertices
:param color: Polygon color
:param lineType: Type of the polygon boundaries, see :func:`line` description
:param shift: The number of fractional bits in the vertex coordinates
The function
``fillConvexPoly``
draws a filled convex polygon.
This function is much faster than the function
``fillPoly``
and can fill not only convex polygons but any monotonic polygon without self-intersections,
i.e., a polygon whose contour intersects every horizontal line (scan i.e., a polygon whose contour intersects every horizontal line (scan
line) twice at the most (though, its top-most and/or the bottom edge could be horizontal). line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).
.. index:: fillPoly .. index:: fillPoly
cv::fillPoly cv::fillPoly
------------ ------------
`id=0.00272984452496 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fillPoly>`__
.. cfunction:: void fillPoly(Mat\& img, const Point** pts, const int* npts, int ncontours, const Scalar\& color, int lineType=8, int shift=0, Point offset=Point() ) .. cfunction:: void fillPoly(Mat\& img, const Point** pts, const int* npts, int ncontours, const Scalar\& color, int lineType=8, int shift=0, Point offset=Point() )
Fills the area bounded by one or more polygons Fills the area bounded by one or more polygons
:param img: Image
:param pts: Array of polygons, each represented as an array of points
:param npts: The array of polygon vertex counters
:param ncontours: The number of contours that bind the filled region
:param color: Polygon color
:param img: Image
:param lineType: Type of the polygon boundaries, see :func:`line` description
:param pts: Array of polygons, each represented as an array of points :param shift: The number of fractional bits in the vertex coordinates
The function ``fillPoly`` fills an area bounded by several
:param npts: The array of polygon vertex counters
:param ncontours: The number of contours that bind the filled region
:param color: Polygon color
:param lineType: Type of the polygon boundaries, see :func:`line` description
:param shift: The number of fractional bits in the vertex coordinates
The function
``fillPoly``
fills an area bounded by several
polygonal contours. The function can fills complex areas, for example, polygonal contours. The function can fills complex areas, for example,
areas with holes, contours with self-intersections (some of thier parts), and so forth. areas with holes, contours with self-intersections (some of thier parts), and so forth.
.. index:: getTextSize .. index:: getTextSize
cv::getTextSize cv::getTextSize
--------------- ---------------
`id=0.364618843078 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getTextSize>`__
.. cfunction:: Size getTextSize(const string\& text, int fontFace, double fontScale, int thickness, int* baseLine) .. cfunction:: Size getTextSize(const string\& text, int fontFace, double fontScale, int thickness, int* baseLine)
Calculates the width and height of a text string. Calculates the width and height of a text string.
:param text: The input text string
:param fontFace: The font to use; see :func:`putText` :param fontScale: The font scale; see :func:`putText` :param thickness: The thickness of lines used to render the text; see :func:`putText` :param baseLine: The output parameter - y-coordinate of the baseline relative to the bottom-most text point
The function ``getTextSize`` calculates and returns size of the box that contain the specified text.
That is, the following code will render some text, the tight box surrounding it and the baseline: ::
:param text: The input text string
:param fontFace: The font to use; see :func:`putText`
:param fontScale: The font scale; see :func:`putText`
:param thickness: The thickness of lines used to render the text; see :func:`putText`
:param baseLine: The output parameter - y-coordinate of the baseline relative to the bottom-most text point
The function
``getTextSize``
calculates and returns size of the box that contain the specified text.
That is, the following code will render some text, the tight box surrounding it and the baseline:
::
// Use "y" to show that the baseLine is about // Use "y" to show that the baseLine is about
string text = "Funny text inside the box"; string text = "Funny text inside the box";
int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX; int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
double fontScale = 2; double fontScale = 2;
int thickness = 3; int thickness = 3;
Mat img(600, 800, CV_8UC3, Scalar::all(0)); Mat img(600, 800, CV_8UC3, Scalar::all(0));
int baseline=0; int baseline=0;
Size textSize = getTextSize(text, fontFace, Size textSize = getTextSize(text, fontFace,
fontScale, thickness, &baseline); fontScale, thickness, &baseline);
baseline += thickness; baseline += thickness;
// center the text // center the text
Point textOrg((img.cols - textSize.width)/2, Point textOrg((img.cols - textSize.width)/2,
(img.rows + textSize.height)/2); (img.rows + textSize.height)/2);
// draw the box // draw the box
rectangle(img, textOrg + Point(0, baseline), rectangle(img, textOrg + Point(0, baseline),
textOrg + Point(textSize.width, -textSize.height), textOrg + Point(textSize.width, -textSize.height),
@ -447,86 +230,46 @@ That is, the following code will render some text, the tight box surrounding it
line(img, textOrg + Point(0, thickness), line(img, textOrg + Point(0, thickness),
textOrg + Point(textSize.width, thickness), textOrg + Point(textSize.width, thickness),
Scalar(0, 0, 255)); Scalar(0, 0, 255));
// then put the text itself // then put the text itself
putText(img, text, textOrg, fontFace, fontScale, putText(img, text, textOrg, fontFace, fontScale,
Scalar::all(255), thickness, 8); Scalar::all(255), thickness, 8);
.. ..
.. index:: line .. index:: line
cv::line cv::line
-------- --------
`id=0.645160739861 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/line>`__
.. cfunction:: void line(Mat\& img, Point pt1, Point pt2, const Scalar\& color, int thickness=1, int lineType=8, int shift=0) .. cfunction:: void line(Mat\& img, Point pt1, Point pt2, const Scalar\& color, int thickness=1, int lineType=8, int shift=0)
Draws a line segment connecting two points Draws a line segment connecting two points
:param img: The image
:param pt1: First point of the line segment
:param pt2: Second point of the line segment
:param color: Line color
:param thickness: Line thickness
:param img: The image
:param pt1: First point of the line segment
:param pt2: Second point of the line segment
:param color: Line color
:param thickness: Line thickness
:param lineType: Type of the line: :param lineType: Type of the line:
* **8** (or omitted) 8-connected line.
* **8** (or omitted) 8-connected line. * **4** 4-connected line.
* **CV_AA** antialiased line.
* **4** 4-connected line.
:param shift: Number of fractional bits in the point coordinates
* **CV_AA** antialiased line. The function ``line`` draws the line segment between ``pt1`` and ``pt2`` points in the image. The line is
:param shift: Number of fractional bits in the point coordinates
The function
``line``
draws the line segment between
``pt1``
and
``pt2``
points in the image. The line is
clipped by the image boundaries. For non-antialiased lines clipped by the image boundaries. For non-antialiased lines
with integer coordinates the 8-connected or 4-connected Bresenham with integer coordinates the 8-connected or 4-connected Bresenham
algorithm is used. Thick lines are drawn with rounding endings. algorithm is used. Thick lines are drawn with rounding endings.
Antialiased lines are drawn using Gaussian filtering. To specify Antialiased lines are drawn using Gaussian filtering. To specify
the line color, the user may use the macro the line color, the user may use the macro ``CV_RGB(r, g, b)`` .
``CV_RGB(r, g, b)``
.
.. index:: LineIterator .. index:: LineIterator
@ -534,22 +277,10 @@ the line color, the user may use the macro
LineIterator LineIterator
------------ ------------
`id=0.913176469223 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/LineIterator>`__
.. ctype:: LineIterator .. ctype:: LineIterator
Class for iterating pixels on a raster line ::
Class for iterating pixels on a raster line
::
class LineIterator class LineIterator
{ {
public: public:
@ -566,205 +297,109 @@ Class for iterating pixels on a raster line
// move the iterator to the next pixel // move the iterator to the next pixel
LineIterator& operator ++(); LineIterator& operator ++();
LineIterator operator ++(int); LineIterator operator ++(int);
// internal state of the iterator // internal state of the iterator
uchar* ptr; uchar* ptr;
int err, count; int err, count;
int minusDelta, plusDelta; int minusDelta, plusDelta;
int minusStep, plusStep; int minusStep, plusStep;
}; };
.. ..
The class The class ``LineIterator`` is used to get each pixel of a raster line. It can be treated as versatile implementation of the Bresenham algorithm, where you can stop at each pixel and do some extra processing, for example, grab pixel values along the line, or draw a line with some effect (e.g. with XOR operation).
``LineIterator``
is used to get each pixel of a raster line. It can be treated as versatile implementation of the Bresenham algorithm, where you can stop at each pixel and do some extra processing, for example, grab pixel values along the line, or draw a line with some effect (e.g. with XOR operation).
The number of pixels along the line is store in The number of pixels along the line is store in ``LineIterator::count`` . ::
``LineIterator::count``
.
::
// grabs pixels along the line (pt1, pt2) // grabs pixels along the line (pt1, pt2)
// from 8-bit 3-channel image to the buffer // from 8-bit 3-channel image to the buffer
LineIterator it(img, pt1, pt2, 8); LineIterator it(img, pt1, pt2, 8);
vector<Vec3b> buf(it.count); vector<Vec3b> buf(it.count);
for(int i = 0; i < it.count; i++, ++it) for(int i = 0; i < it.count; i++, ++it)
buf[i] = *(const Vec3b)*it; buf[i] = *(const Vec3b)*it;
.. ..
.. index:: rectangle .. index:: rectangle
cv::rectangle cv::rectangle
------------- -------------
`id=0.494030339931 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/rectangle>`__
.. cfunction:: void rectangle(Mat\& img, Point pt1, Point pt2, const Scalar\& color, int thickness=1, int lineType=8, int shift=0) .. cfunction:: void rectangle(Mat\& img, Point pt1, Point pt2, const Scalar\& color, int thickness=1, int lineType=8, int shift=0)
Draws a simple, thick, or filled up-right rectangle. Draws a simple, thick, or filled up-right rectangle.
:param img: Image
:param pt1: One of the rectangle's vertices
:param pt2: Opposite to ``pt1`` rectangle vertex
:param color: Rectangle color or brightness (grayscale image)
:param thickness: Thickness of lines that make up the rectangle. Negative values, e.g. ``CV_FILLED`` , mean that the function has to draw a filled rectangle.
:param img: Image
:param pt1: One of the rectangle's vertices
:param pt2: Opposite to ``pt1`` rectangle vertex
:param color: Rectangle color or brightness (grayscale image)
:param thickness: Thickness of lines that make up the rectangle. Negative values, e.g. ``CV_FILLED`` , mean that the function has to draw a filled rectangle.
:param lineType: Type of the line, see :func:`line` description
:param shift: Number of fractional bits in the point coordinates
The function
``rectangle``
draws a rectangle outline or a filled rectangle, which two opposite corners are
``pt1``
and
``pt2``
.
:param lineType: Type of the line, see :func:`line` description
:param shift: Number of fractional bits in the point coordinates
The function ``rectangle`` draws a rectangle outline or a filled rectangle, which two opposite corners are ``pt1`` and ``pt2`` .
.. index:: polylines .. index:: polylines
cv::polylines cv::polylines
------------- -------------
`id=0.550422277453 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/polylines>`__
.. cfunction:: void polylines(Mat\& img, const Point** pts, const int* npts, int ncontours, bool isClosed, const Scalar\& color, int thickness=1, int lineType=8, int shift=0 ) .. cfunction:: void polylines(Mat\& img, const Point** pts, const int* npts, int ncontours, bool isClosed, const Scalar\& color, int thickness=1, int lineType=8, int shift=0 )
Draws several polygonal curves Draws several polygonal curves
:param img: The image
:param pts: Array of polygonal curves
:param npts: Array of polygon vertex counters
:param ncontours: The number of curves
:param isClosed: Indicates whether the drawn polylines are closed or not. If they are closed, the function draws the line from the last vertex of each curve to its first vertex
:param img: The image
:param pts: Array of polygonal curves
:param npts: Array of polygon vertex counters
:param ncontours: The number of curves
:param isClosed: Indicates whether the drawn polylines are closed or not. If they are closed, the function draws the line from the last vertex of each curve to its first vertex
:param color: Polyline color
:param thickness: Thickness of the polyline edges
:param lineType: Type of the line segments, see :func:`line` description
:param shift: The number of fractional bits in the vertex coordinates
The function
``polylines``
draws one or more polygonal curves.
:param color: Polyline color
:param thickness: Thickness of the polyline edges
:param lineType: Type of the line segments, see :func:`line` description
:param shift: The number of fractional bits in the vertex coordinates
The function ``polylines`` draws one or more polygonal curves.
.. index:: putText .. index:: putText
cv::putText cv::putText
----------- -----------
`id=0.164290316532 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/putText>`__
.. cfunction:: void putText( Mat\& img, const string\& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=8, bool bottomLeftOrigin=false ) .. cfunction:: void putText( Mat\& img, const string\& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=8, bool bottomLeftOrigin=false )
Draws a text string Draws a text string
:param img: The image
:param text: The text string to be drawn
:param org: The bottom-left corner of the text string in the image
:param fontFace: The font type, one of ``FONT_HERSHEY_SIMPLEX`` , ``FONT_HERSHEY_PLAIN`` , ``FONT_HERSHEY_DUPLEX`` , ``FONT_HERSHEY_COMPLEX`` , ``FONT_HERSHEY_TRIPLEX`` , ``FONT_HERSHEY_COMPLEX_SMALL`` , ``FONT_HERSHEY_SCRIPT_SIMPLEX`` or ``FONT_HERSHEY_SCRIPT_COMPLEX`` ,
where each of the font id's can be combined with ``FONT_HERSHEY_ITALIC`` to get the slanted letters.
:param fontScale: The font scale factor that is multiplied by the font-specific base size
:param img: The image
:param color: The text color
:param text: The text string to be drawn :param thickness: Thickness of the lines used to draw the text
:param lineType: The line type; see ``line`` for details
:param org: The bottom-left corner of the text string in the image
:param bottomLeftOrigin: When true, the image data origin is at the bottom-left corner, otherwise it's at the top-left corner
:param fontFace: The font type, one of ``FONT_HERSHEY_SIMPLEX`` , ``FONT_HERSHEY_PLAIN`` , The function ``putText`` renders the specified text string in the image.
``FONT_HERSHEY_DUPLEX`` , ``FONT_HERSHEY_COMPLEX`` , ``FONT_HERSHEY_TRIPLEX`` ,
``FONT_HERSHEY_COMPLEX_SMALL`` , ``FONT_HERSHEY_SCRIPT_SIMPLEX`` or ``FONT_HERSHEY_SCRIPT_COMPLEX`` ,
where each of the font id's can be combined with ``FONT_HERSHEY_ITALIC`` to get the slanted letters.
:param fontScale: The font scale factor that is multiplied by the font-specific base size
:param color: The text color
:param thickness: Thickness of the lines used to draw the text
:param lineType: The line type; see ``line`` for details
:param bottomLeftOrigin: When true, the image data origin is at the bottom-left corner, otherwise it's at the top-left corner
The function
``putText``
renders the specified text string in the image.
Symbols that can not be rendered using the specified font are Symbols that can not be rendered using the specified font are
replaced by question marks. See replaced by question marks. See
:func:`getTextSize` :func:`getTextSize` for a text rendering code example.
for a text rendering code example.

1
modules/core/doc/dynamic_structures.rst
View File

@ -3,4 +3,3 @@ Dynamic Structures
.. highlight:: cpp .. highlight:: cpp

56
modules/core/doc/intro.rst
View File

@ -30,20 +30,17 @@ The API Concepts
*"cv"* namespace *"cv"* namespace
---------------- ----------------
All the OpenCV classes and functions are placed into *"cv"* namespace. Therefore, to access this functionality from your code, use All the OpenCV classes and functions are placed into *"cv"* namespace. Therefore, to access this functionality from your code, use ``cv::`` specifier or ``using namespace cv;`` directive:
``cv::`` specifier or ``using namespace cv;`` directive:
.. code-block:: c .. code-block:: c
#include "opencv2/core/core.hpp" #include "opencv2/core/core.hpp"
... ...
cv::Mat H = cv::findHomography(points1, points2, CV_RANSAC, 5); cv::Mat H = cv::findHomography(points1, points2, CV_RANSAC, 5);
... ...
or or ::
::
#include "opencv2/core/core.hpp" #include "opencv2/core/core.hpp"
using namespace cv; using namespace cv;
... ...
@ -51,16 +48,13 @@ or
... ...
It is probable that some of the current or future OpenCV external names conflict with STL It is probable that some of the current or future OpenCV external names conflict with STL
or other libraries, in this case use explicit namespace specifiers to resolve the name conflicts: or other libraries, in this case use explicit namespace specifiers to resolve the name conflicts: ::
::
Mat a(100, 100, CV_32F); Mat a(100, 100, CV_32F);
randu(a, Scalar::all(1), Scalar::all(std::rand())); randu(a, Scalar::all(1), Scalar::all(std::rand()));
cv::log(a, a); cv::log(a, a);
a /= std::log(2.); a /= std::log(2.);
Automatic Memory Management Automatic Memory Management
--------------------------- ---------------------------
@ -68,13 +62,11 @@ OpenCV handles all the memory automatically.
First of all, ``std::vector``, ``Mat`` and other data structures used by the functions and methods have destructors that deallocate the underlying memory buffers when needed. First of all, ``std::vector``, ``Mat`` and other data structures used by the functions and methods have destructors that deallocate the underlying memory buffers when needed.
Secondly, in the case of ``Mat`` this *when needed* means that the destructors do not always deallocate the buffers, they take into account possible data sharing. That is, destructor decrements the reference counter, associated with the matrix data buffer, and the buffer is deallocated if and only if the reference counter reaches zero, that is, when no other structures refer to the same buffer. Similarly, when ``Mat`` instance is copied, not actual data is really copied; instead, the associated with it reference counter is incremented to memorize that there is another owner of the same data. There is also ``Mat::clone`` method that creates a full copy of the matrix data. Here is the example Secondly, in the case of ``Mat`` this *when needed* means that the destructors do not always deallocate the buffers, they take into account possible data sharing. That is, destructor decrements the reference counter, associated with the matrix data buffer, and the buffer is deallocated if and only if the reference counter reaches zero, that is, when no other structures refer to the same buffer. Similarly, when ``Mat`` instance is copied, not actual data is really copied; instead, the associated with it reference counter is incremented to memorize that there is another owner of the same data. There is also ``Mat::clone`` method that creates a full copy of the matrix data. Here is the example ::
::
// create a big 8Mb matrix // create a big 8Mb matrix
Mat A(1000, 1000, CV_64F); Mat A(1000, 1000, CV_64F);
// create another header for the same matrix; // create another header for the same matrix;
// this is instant operation, regardless of the matrix size. // this is instant operation, regardless of the matrix size.
Mat B = A; Mat B = A;
@ -82,7 +74,7 @@ Secondly, in the case of ``Mat`` this *when needed* means that the destructors d
Mat C = B.row(3); Mat C = B.row(3);
// now create a separate copy of the matrix // now create a separate copy of the matrix
Mat D = B.clone(); Mat D = B.clone();
// copy the 5-th row of B to C, that is, copy the 5-th row of A // copy the 5-th row of B to C, that is, copy the 5-th row of A
// to the 3-rd row of A. // to the 3-rd row of A.
B.row(5).copyTo(C); B.row(5).copyTo(C);
// now let A and D share the data; after that the modified version // now let A and D share the data; after that the modified version
@ -91,8 +83,8 @@ Secondly, in the case of ``Mat`` this *when needed* means that the destructors d
// now make B an empty matrix (which references no memory buffers), // now make B an empty matrix (which references no memory buffers),
// but the modified version of A will still be referenced by C, // but the modified version of A will still be referenced by C,
// despite that C is just a single row of the original A // despite that C is just a single row of the original A
B.release(); B.release();
// finally, make a full copy of C. In result, the big modified // finally, make a full copy of C. In result, the big modified
// matrix will be deallocated, since it's not referenced by anyone // matrix will be deallocated, since it's not referenced by anyone
C = C.clone(); C = C.clone();
@ -107,7 +99,6 @@ one can use::
That is, ``Ptr<T> ptr`` incapsulates a pointer to ``T`` instance and a reference counter associated with the pointer. See ``Ptr`` description for details. That is, ``Ptr<T> ptr`` incapsulates a pointer to ``T`` instance and a reference counter associated with the pointer. See ``Ptr`` description for details.
.. todo:: .. todo::
Should we replace Ptr<> with the semi-standard shared_ptr<>? Should we replace Ptr<> with the semi-standard shared_ptr<>?
@ -118,17 +109,17 @@ Automatic Allocation of the Output Data
OpenCV does not only deallocate the memory automatically, it can also allocate memory for the output function parameters automatically most of the time. That is, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays automatically allocated or reallocated. The size and type of the output arrays are determined from the input arrays' size and type. If needed, the functions take extra parameters that help to figure out the output array properties. OpenCV does not only deallocate the memory automatically, it can also allocate memory for the output function parameters automatically most of the time. That is, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays automatically allocated or reallocated. The size and type of the output arrays are determined from the input arrays' size and type. If needed, the functions take extra parameters that help to figure out the output array properties.
Here is the example: :: Here is the example: ::
#include "cv.h" #include "cv.h"
#include "highgui.h" #include "highgui.h"
using namespace cv; using namespace cv;
int main(int, char**) int main(int, char**)
{ {
VideoCapture cap(0); VideoCapture cap(0);
if(!cap.isOpened()) return -1; if(!cap.isOpened()) return -1;
Mat frame, edges; Mat frame, edges;
namedWindow("edges",1); namedWindow("edges",1);
for(;;) for(;;)
@ -150,15 +141,14 @@ The key component of this technology is the method ``Mat::create``. It takes the
Some notable exceptions from this scheme are ``cv::mixChannels``, ``cv::RNG::fill`` and a few others functions and methods. They are not able to allocate the output array, so the user has to do that in advance. Some notable exceptions from this scheme are ``cv::mixChannels``, ``cv::RNG::fill`` and a few others functions and methods. They are not able to allocate the output array, so the user has to do that in advance.
Saturation Arithmetics Saturation Arithmetics
---------------------- ----------------------
As computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact 8- or 16-bit per channel form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If we just store the lowest 8 (16) bit of the result, that will result in some visual artifacts and may affect the further image analysis. To solve this problem, we use so-called *saturation* arithmetics, e.g. to store ``r``, a result of some operation, to 8-bit image, we find the nearest value within 0..255 range: As computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact 8- or 16-bit per channel form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If we just store the lowest 8 (16) bit of the result, that will result in some visual artifacts and may affect the further image analysis. To solve this problem, we use so-called *saturation* arithmetics, e.g. to store ``r``, a result of some operation, to 8-bit image, we find the nearest value within 0..255 range:
.. math:: .. math::
I(x,y)= \min ( \max (\textrm{round}(r), 0), 255) I(x,y)= \min ( \max (\textrm{round}(r), 0), 255)
The similar rules are applied to 8-bit signed and 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code it is done using ``saturate_cast<>`` functions that resembler the standard C++ cast operations. Here is the implementation of the above formula:: The similar rules are applied to 8-bit signed and 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code it is done using ``saturate_cast<>`` functions that resembler the standard C++ cast operations. Here is the implementation of the above formula::
@ -166,7 +156,6 @@ The similar rules are applied to 8-bit signed and 16-bit signed and unsigned typ
where ``cv::uchar`` is OpenCV's 8-bit unsigned integer type. In optimized SIMD code we use specialized instructions, like SSE2' ``paddusb``, ``packuswb`` etc. to achieve exactly the same behavior as in C++ code. where ``cv::uchar`` is OpenCV's 8-bit unsigned integer type. In optimized SIMD code we use specialized instructions, like SSE2' ``paddusb``, ``packuswb`` etc. to achieve exactly the same behavior as in C++ code.
Fixed Pixel Types. Limited Use of Templates Fixed Pixel Types. Limited Use of Templates
------------------------------------------- -------------------------------------------
@ -182,18 +171,17 @@ Because of this, there is a limited fixed set of primitive data types that the l
* 32-bit floating-point number (float) * 32-bit floating-point number (float)
* 64-bit floating-point number (double) * 64-bit floating-point number (double)
* a tuple of several elements, where all elements have the same type (one of the above). Array, which elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, which elements are scalar values. The maximum possible number of channels is defined by ``CV_CN_MAX`` constant (which is not smaller than 32). * a tuple of several elements, where all elements have the same type (one of the above). Array, which elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, which elements are scalar values. The maximum possible number of channels is defined by ``CV_CN_MAX`` constant (which is not smaller than 32).
.. todo:: .. todo::
Need we extend the above list? Shouldn't we throw away 8-bit signed (schar)? Need we extend the above list? Shouldn't we throw away 8-bit signed (schar)?
For these basic types there is enumeration:: For these basic types there is enumeration::
enum { CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6 }; enum { CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6 };
Multi-channel (``n``-channel) types can be specified using ``CV_8UC1`` ... ``CV_64FC4`` constants (for number of channels from 1 to 4), or using ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at compile time. Multi-channel (``n``-channel) types can be specified using ``CV_8UC1`` ... ``CV_64FC4`` constants (for number of channels from 1 to 4), or using ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at compile time.
.. note:: .. note:: ``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)`` and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``, that is, the type constant is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)`` and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``, that is, the type constant is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
Here are some examples:: Here are some examples::
@ -219,7 +207,6 @@ The subset of supported types for each functions has been defined from practical
Should we include such a table into the standard? Should we include such a table into the standard?
Should we specify minimum "must-have" set of supported formats for each functions? Should we specify minimum "must-have" set of supported formats for each functions?
Error handling Error handling
-------------- --------------
@ -227,10 +214,8 @@ OpenCV uses exceptions to signal about the critical errors. When the input data
The exceptions can be instances of ``cv::Exception`` class or its derivatives. In its turn, ``cv::Exception`` is a derivative of std::exception, so it can be gracefully handled in the code using other standard C++ library components. The exceptions can be instances of ``cv::Exception`` class or its derivatives. In its turn, ``cv::Exception`` is a derivative of std::exception, so it can be gracefully handled in the code using other standard C++ library components.
The exception is typically thrown using ``CV_Error(errcode, description)`` macro, or its printf-like ``CV_Error_(errcode, printf-spec, (printf-args))`` variant, or using ``CV_Assert(condition)`` macro that checks the condition and throws exception when it is not satisfied. For performance-critical code there is ``CV_DbgAssert(condition)`` that is only retained in Debug configuration. Thanks to the automatic memory management, all the intermediate buffers are automatically deallocated in the case of sudden error; user only needs to put a try statement to catch the exceptions, if needed: The exception is typically thrown using ``CV_Error(errcode, description)`` macro, or its printf-like ``CV_Error_(errcode, printf-spec, (printf-args))`` variant, or using ``CV_Assert(condition)`` macro that checks the condition and throws exception when it is not satisfied. For performance-critical code there is ``CV_DbgAssert(condition)`` that is only retained in Debug configuration. Thanks to the automatic memory management, all the intermediate buffers are automatically deallocated in the case of sudden error; user only needs to put a try statement to catch the exceptions, if needed: ::
::
try try
{ {
... // call OpenCV ... // call OpenCV
@ -241,7 +226,6 @@ The exception is typically thrown using ``CV_Error(errcode, description)`` macro
std::cout << "exception caught: " << err_msg << std::endl; std::cout << "exception caught: " << err_msg << std::endl;
} }
Multi-threading and reenterability Multi-threading and reenterability
---------------------------------- ----------------------------------

5519
modules/core/doc/operations_on_arrays.rst
View File

File diff suppressed because it is too large Load Diff

399
modules/core/doc/utility_and_system_functions_and_macros.rst
View File

@ -3,149 +3,69 @@ Utility and System Functions and Macros
.. highlight:: cpp .. highlight:: cpp
.. index:: alignPtr .. index:: alignPtr
cv::alignPtr cv::alignPtr
------------ ------------
`id=0.732441674276 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/alignPtr>`__
.. cfunction:: template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp)) .. cfunction:: template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp))
Aligns pointer to the specified number of bytes Aligns pointer to the specified number of bytes
:param ptr: The aligned pointer
:param n: The alignment size; must be a power of two
:param ptr: The aligned pointer
:param n: The alignment size; must be a power of two
The function returns the aligned pointer of the same type as the input pointer: The function returns the aligned pointer of the same type as the input pointer:
.. math:: .. math::
\texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)} \texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)}
.. index:: alignSize .. index:: alignSize
cv::alignSize cv::alignSize
------------- -------------
`id=0.0293178300141 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/alignSize>`__
.. cfunction:: size_t alignSize(size_t sz, int n) .. cfunction:: size_t alignSize(size_t sz, int n)
Aligns a buffer size to the specified number of bytes Aligns a buffer size to the specified number of bytes
:param sz: The buffer size to align
:param n: The alignment size; must be a power of two
The function returns the minimum number that is greater or equal to ``sz`` and is divisble by ``n`` :
:param sz: The buffer size to align
:param n: The alignment size; must be a power of two
The function returns the minimum number that is greater or equal to
``sz``
and is divisble by
``n``
:
.. math:: .. math::
\texttt{(sz + n-1) \& -n} \texttt{(sz + n-1) \& -n}
.. index:: allocate .. index:: allocate
cv::allocate cv::allocate
------------ ------------
`id=0.672857293821 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/allocate>`__
.. cfunction:: template<typename _Tp> _Tp* allocate(size_t n) .. cfunction:: template<typename _Tp> _Tp* allocate(size_t n)
Allocates an array of elements Allocates an array of elements
:param n: The number of elements to allocate
The generic function ``allocate`` allocates buffer for the specified number of elements. For each element the default constructor is called.
:param n: The number of elements to allocate
The generic function
``allocate``
allocates buffer for the specified number of elements. For each element the default constructor is called.
.. index:: deallocate .. index:: deallocate
cv::deallocate cv::deallocate
-------------- --------------
`id=0.907199792708 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/deallocate>`__
.. cfunction:: template<typename _Tp> void deallocate(_Tp* ptr, size_t n) .. cfunction:: template<typename _Tp> void deallocate(_Tp* ptr, size_t n)
Allocates an array of elements Allocates an array of elements
:param ptr: Pointer to the deallocated buffer
:param n: The number of elements in the buffer
The generic function ``deallocate`` deallocates the buffer allocated with
:func:`allocate` . The number of elements must match the number passed to
:func:`allocate` .
:param ptr: Pointer to the deallocated buffer
:param n: The number of elements in the buffer
The generic function
``deallocate``
deallocates the buffer allocated with
:func:`allocate`
. The number of elements must match the number passed to
:func:`allocate`
.
.. index:: CV_Assert .. index:: CV_Assert
@ -153,152 +73,57 @@ deallocates the buffer allocated with
CV_Assert CV_Assert
--------- ---------
`id=0.132247699783 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/CV_Assert>`__
.. cfunction:: CV_Assert(expr) .. cfunction:: CV_Assert(expr)
Checks a condition at runtime. Checks a condition at runtime. ::
::
#define CV_Assert( expr ) ... #define CV_Assert( expr ) ...
#define CV_DbgAssert(expr) ... #define CV_DbgAssert(expr) ...
.. ..
:param expr: The checked expression
The macros ``CV_Assert`` and ``CV_DbgAssert`` evaluate the specified expression and if it is 0, the macros raise an error (see
:func:`error` ). The macro ``CV_Assert`` checks the condition in both Debug and Release configurations, while ``CV_DbgAssert`` is only retained in the Debug configuration.
:param expr: The checked expression
The macros
``CV_Assert``
and
``CV_DbgAssert``
evaluate the specified expression and if it is 0, the macros raise an error (see
:func:`error`
). The macro
``CV_Assert``
checks the condition in both Debug and Release configurations, while
``CV_DbgAssert``
is only retained in the Debug configuration.
.. index:: error .. index:: error
cv::error cv::error
--------- ---------
`id=0.274198769781 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/error>`__
.. cfunction:: void error( const Exception\& exc ) .. cfunction:: void error( const Exception\& exc )
.. cfunction:: \#define CV_Error( code, msg ) <...> .. cfunction:: \#define CV_Error( code, msg ) <...>
.. cfunction:: \#define CV_Error_( code, args ) <...> .. cfunction:: \#define CV_Error_( code, args ) <...>
Signals an error and raises the exception Signals an error and raises the exception
:param exc: The exception to throw
:param code: The error code, normally, a negative value. The list of pre-defined error codes can be found in ``cxerror.h`` :param msg: Text of the error message
:param args: printf-like formatted error message in parantheses
The function and the helper macros ``CV_Error`` and ``CV_Error_`` call the error handler. Currently, the error handler prints the error code ( ``exc.code`` ), the context ( ``exc.file``,``exc.line`` and the error message ``exc.err`` to the standard error stream ``stderr`` . In Debug configuration it then provokes memory access violation, so that the execution stack and all the parameters can be analyzed in debugger. In Release configuration the exception ``exc`` is thrown.
The macro ``CV_Error_`` can be used to construct the error message on-fly to include some dynamic information, for example: ::
:param exc: The exception to throw
:param code: The error code, normally, a negative value. The list of pre-defined error codes can be found in ``cxerror.h``
:param msg: Text of the error message
:param args: printf-like formatted error message in parantheses
The function and the helper macros
``CV_Error``
and
``CV_Error_``
call the error handler. Currently, the error handler prints the error code (
``exc.code``
), the context (
``exc.file``
,
``exc.line``
and the error message
``exc.err``
to the standard error stream
``stderr``
. In Debug configuration it then provokes memory access violation, so that the execution stack and all the parameters can be analyzed in debugger. In Release configuration the exception
``exc``
is thrown.
The macro
``CV_Error_``
can be used to construct the error message on-fly to include some dynamic information, for example:
::
// note the extra parentheses around the formatted text message // note the extra parentheses around the formatted text message
CV_Error_(CV_StsOutOfRange, CV_Error_(CV_StsOutOfRange,
("the matrix element ( ("the matrix element (
i, j, mtx.at<float>(i,j))) i, j, mtx.at<float>(i,j)))
.. ..
.. index:: Exception .. index:: Exception
.. _Exception: .. _Exception:
Exception Exception
--------- ---------
`id=0.792198322059 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/Exception>`__
.. ctype:: Exception .. ctype:: Exception
The exception class passed to error ::
The exception class passed to error
::
class Exception class Exception
{ {
public: public:
@ -308,7 +133,7 @@ The exception class passed to error
const string& _func, const string& _file, int _line); const string& _func, const string& _file, int _line);
Exception(const Exception& exc); Exception(const Exception& exc);
Exception& operator = (const Exception& exc); Exception& operator = (const Exception& exc);
// the error code // the error code
int code; int code;
// the error text message // the error text message
@ -320,249 +145,115 @@ The exception class passed to error
// the source file line where the error happened // the source file line where the error happened
int line; int line;
}; };
.. ..
The class The class ``Exception`` encapsulates all or almost all the necessary information about the error happened in the program. The exception is usually constructed and thrown implicitly, via ``CV_Error`` and ``CV_Error_`` macros, see
``Exception`` :func:`error` .
encapsulates all or almost all the necessary information about the error happened in the program. The exception is usually constructed and thrown implicitly, via
``CV_Error``
and
``CV_Error_``
macros, see
:func:`error`
.
.. index:: fastMalloc .. index:: fastMalloc
cv::fastMalloc cv::fastMalloc
-------------- --------------
`id=0.913748026438 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fastMalloc>`__
.. cfunction:: void* fastMalloc(size_t size) .. cfunction:: void* fastMalloc(size_t size)
Allocates aligned memory buffer Allocates aligned memory buffer
:param size: The allocated buffer size
:param size: The allocated buffer size
The function allocates buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned on 16 bytes. The function allocates buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned on 16 bytes.
.. index:: fastFree .. index:: fastFree
cv::fastFree cv::fastFree
------------ ------------
`id=0.486348253472 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/fastFree>`__
.. cfunction:: void fastFree(void* ptr) .. cfunction:: void fastFree(void* ptr)
Deallocates memory buffer Deallocates memory buffer
:param ptr: Pointer to the allocated buffer
The function deallocates the buffer, allocated with
:func:`fastMalloc` .
:param ptr: Pointer to the allocated buffer
The function deallocates the buffer, allocated with
:func:`fastMalloc`
.
If NULL pointer is passed, the function does nothing. If NULL pointer is passed, the function does nothing.
.. index:: format .. index:: format
cv::format cv::format
---------- ----------
`id=0.359045522761 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/format>`__
.. cfunction:: string format( const char* fmt, ... ) .. cfunction:: string format( const char* fmt, ... )
Returns a text string formatted using printf-like expression Returns a text string formatted using printf-like expression
:param fmt: The printf-compatible formatting specifiers
The function acts like ``sprintf`` , but forms and returns STL string. It can be used for form the error message in
:func:`Exception` constructor.
:param fmt: The printf-compatible formatting specifiers
The function acts like
``sprintf``
, but forms and returns STL string. It can be used for form the error message in
:func:`Exception`
constructor.
.. index:: getNumThreads .. index:: getNumThreads
cv::getNumThreads cv::getNumThreads
----------------- -----------------
`id=0.665594834701 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getNumThreads>`__
.. cfunction:: int getNumThreads() .. cfunction:: int getNumThreads()
Returns the number of threads used by OpenCV Returns the number of threads used by OpenCV
The function returns the number of threads that is used by OpenCV. The function returns the number of threads that is used by OpenCV.
See also: See also:
:func:`setNumThreads` :func:`setNumThreads`,:func:`getThreadNum` .
,
:func:`getThreadNum`
.
.. index:: getThreadNum .. index:: getThreadNum
cv::getThreadNum cv::getThreadNum
---------------- ----------------
`id=0.835208450402 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getThreadNum>`__
.. cfunction:: int getThreadNum() .. cfunction:: int getThreadNum()
Returns index of the currently executed thread Returns index of the currently executed thread
The function returns 0-based index of the currently executed thread. The function is only valid inside a parallel OpenMP region. When OpenCV is built without OpenMP support, the function always returns 0. The function returns 0-based index of the currently executed thread. The function is only valid inside a parallel OpenMP region. When OpenCV is built without OpenMP support, the function always returns 0.
See also: See also:
:func:`setNumThreads` :func:`setNumThreads`,:func:`getNumThreads` .
,
:func:`getNumThreads`
.
.. index:: getTickCount .. index:: getTickCount
cv::getTickCount cv::getTickCount
---------------- ----------------
`id=0.682548115061 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getTickCount>`__
.. cfunction:: int64 getTickCount() .. cfunction:: int64 getTickCount()
Returns the number of ticks Returns the number of ticks
The function returns the number of ticks since the certain event (e.g. when the machine was turned on). The function returns the number of ticks since the certain event (e.g. when the machine was turned on).
It can be used to initialize It can be used to initialize
:func:`RNG` :func:`RNG` or to measure a function execution time by reading the tick count before and after the function call. See also the tick frequency.
or to measure a function execution time by reading the tick count before and after the function call. See also the tick frequency.
.. index:: getTickFrequency .. index:: getTickFrequency
cv::getTickFrequency cv::getTickFrequency
-------------------- --------------------
`id=0.85013360741 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/getTickFrequency>`__
.. cfunction:: double getTickFrequency() .. cfunction:: double getTickFrequency()
Returns the number of ticks per second Returns the number of ticks per second
The function returns the number of ticks per second. The function returns the number of ticks per second.
That is, the following code computes the execution time in seconds. That is, the following code computes the execution time in seconds. ::
::
double t = (double)getTickCount(); double t = (double)getTickCount();
// do something ... // do something ...
t = ((double)getTickCount() - t)/getTickFrequency(); t = ((double)getTickCount() - t)/getTickFrequency();
.. ..
.. index:: setNumThreads .. index:: setNumThreads
cv::setNumThreads cv::setNumThreads
----------------- -----------------
`id=0.215563071229 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/setNumThreads>`__
.. cfunction:: void setNumThreads(int nthreads) .. cfunction:: void setNumThreads(int nthreads)
Sets the number of threads used by OpenCV Sets the number of threads used by OpenCV
:param nthreads: The number of threads used by OpenCV
The function sets the number of threads used by OpenCV in parallel OpenMP regions. If ``nthreads=0`` , the function will use the default number of threads, which is usually equal to the number of the processing cores.
See also:
:func:`getNumThreads`,:func:`getThreadNum`
:param nthreads: The number of threads used by OpenCV
The function sets the number of threads used by OpenCV in parallel OpenMP regions. If
``nthreads=0``
, the function will use the default number of threads, which is usually equal to the number of the processing cores.
See also:
:func:`getNumThreads`
,
:func:`getThreadNum`

78
modules/core/doc/xml_yaml_persistence.rst
View File

@ -3,30 +3,16 @@ XML/YAML Persistence
.. highlight:: cpp .. highlight:: cpp
.. index:: FileStorage .. index:: FileStorage
.. _FileStorage: .. _FileStorage:
FileStorage FileStorage
----------- -----------
`id=0.36488878292 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/FileStorage>`__
.. ctype:: FileStorage .. ctype:: FileStorage
The XML/YAML file storage class ::
The XML/YAML file storage class
::
class FileStorage class FileStorage
{ {
public: public:
@ -41,7 +27,7 @@ The XML/YAML file storage class
FileStorage(CvFileStorage* fs); FileStorage(CvFileStorage* fs);
// the destructor; closes the file if needed // the destructor; closes the file if needed
virtual ~FileStorage(); virtual ~FileStorage();
// opens the specified file for reading (flags=FileStorage::READ) // opens the specified file for reading (flags=FileStorage::READ)
// or writing (flags=FileStorage::WRITE) // or writing (flags=FileStorage::WRITE)
virtual bool open(const string& filename, int flags); virtual bool open(const string& filename, int flags);
@ -49,7 +35,7 @@ The XML/YAML file storage class
virtual bool isOpened() const; virtual bool isOpened() const;
// closes the file // closes the file
virtual void release(); virtual void release();
// returns the first top-level node // returns the first top-level node
FileNode getFirstTopLevelNode() const; FileNode getFirstTopLevelNode() const;
// returns the root file node // returns the root file node
@ -58,54 +44,39 @@ The XML/YAML file storage class
// returns the top-level node by name // returns the top-level node by name
FileNode operator[](const string& nodename) const; FileNode operator[](const string& nodename) const;
FileNode operator[](const char* nodename) const; FileNode operator[](const char* nodename) const;
// returns the underlying CvFileStorage* // returns the underlying CvFileStorage*
CvFileStorage* operator *() { return fs; } CvFileStorage* operator *() { return fs; }
const CvFileStorage* operator *() const { return fs; } const CvFileStorage* operator *() const { return fs; }
// writes the certain number of elements of the specified format // writes the certain number of elements of the specified format
// (see DataType) without any headers // (see DataType) without any headers
void writeRaw( const string& fmt, const uchar* vec, size_t len ); void writeRaw( const string& fmt, const uchar* vec, size_t len );
// writes an old-style object (CvMat, CvMatND etc.) // writes an old-style object (CvMat, CvMatND etc.)
void writeObj( const string& name, const void* obj ); void writeObj( const string& name, const void* obj );
// returns the default object name from the filename // returns the default object name from the filename
// (used by cvSave() with the default object name etc.) // (used by cvSave() with the default object name etc.)
static string getDefaultObjectName(const string& filename); static string getDefaultObjectName(const string& filename);
Ptr<CvFileStorage> fs; Ptr<CvFileStorage> fs;
string elname; string elname;
vector<char> structs; vector<char> structs;
int state; int state;
}; };
.. ..
.. index:: FileNode .. index:: FileNode
.. _FileNode: .. _FileNode:
FileNode FileNode
-------- --------
`id=0.228849909258 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/FileNode>`__
.. ctype:: FileNode .. ctype:: FileNode
The XML/YAML file node class ::
The XML/YAML file node class
::
class CV_EXPORTS FileNode class CV_EXPORTS FileNode
{ {
public: public:
@ -134,44 +105,29 @@ The XML/YAML file node class
operator float() const; operator float() const;
operator double() const; operator double() const;
operator string() const; operator string() const;
FileNodeIterator begin() const; FileNodeIterator begin() const;
FileNodeIterator end() const; FileNodeIterator end() const;
void readRaw( const string& fmt, uchar* vec, size_t len ) const; void readRaw( const string& fmt, uchar* vec, size_t len ) const;
void* readObj() const; void* readObj() const;
// do not use wrapper pointer classes for better efficiency // do not use wrapper pointer classes for better efficiency
const CvFileStorage* fs; const CvFileStorage* fs;
const CvFileNode* node; const CvFileNode* node;
}; };
.. ..
.. index:: FileNodeIterator .. index:: FileNodeIterator
.. _FileNodeIterator: .. _FileNodeIterator:
FileNodeIterator FileNodeIterator
---------------- ----------------
`id=0.575104633905 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/core/FileNodeIterator>`__
.. ctype:: FileNodeIterator .. ctype:: FileNodeIterator
The XML/YAML file node iterator class ::
The XML/YAML file node iterator class
::
class CV_EXPORTS FileNodeIterator class CV_EXPORTS FileNodeIterator
{ {
public: public:
@ -181,23 +137,21 @@ The XML/YAML file node iterator class
FileNodeIterator(const FileNodeIterator& it); FileNodeIterator(const FileNodeIterator& it);
FileNode operator *() const; FileNode operator *() const;
FileNode operator ->() const; FileNode operator ->() const;
FileNodeIterator& operator ++(); FileNodeIterator& operator ++();
FileNodeIterator operator ++(int); FileNodeIterator operator ++(int);
FileNodeIterator& operator --(); FileNodeIterator& operator --();
FileNodeIterator operator --(int); FileNodeIterator operator --(int);
FileNodeIterator& operator += (int); FileNodeIterator& operator += (int);
FileNodeIterator& operator -= (int); FileNodeIterator& operator -= (int);
FileNodeIterator& readRaw( const string& fmt, uchar* vec, FileNodeIterator& readRaw( const string& fmt, uchar* vec,
size_t maxCount=(size_t)INT_MAX ); size_t maxCount=(size_t)INT_MAX );
const CvFileStorage* fs; const CvFileStorage* fs;
const CvFileNode* container; const CvFileNode* container;
CvSeqReader reader; CvSeqReader reader;
size_t remaining; size_t remaining;
}; };
.. ..

293
modules/features2d/doc/common_interfaces_of_descriptor_extractors.rst
View File

@ -3,14 +3,11 @@ Common Interfaces of Descriptor Extractors
.. highlight:: cpp .. highlight:: cpp
Extractors of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily
Extractors of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily 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 ''vector''
that are represented as vectors in a multidimensional space. All objects that implement ''vector'' descriptor extractors inherit
descriptor extractors inherit :func:`DescriptorExtractor` interface.
:func:`DescriptorExtractor`
interface.
.. index:: DescriptorExtractor .. index:: DescriptorExtractor
@ -18,212 +15,107 @@ interface.
DescriptorExtractor DescriptorExtractor
------------------- -------------------
`id=0.00924308242838 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorExtractor>`__
.. ctype:: DescriptorExtractor .. ctype:: 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
{ {
public: public:
virtual ~DescriptorExtractor(); virtual ~DescriptorExtractor();
void compute( const Mat& image, vector<KeyPoint>& keypoints, void compute( const Mat& image, vector<KeyPoint>& keypoints,
Mat& descriptors ) const; Mat& descriptors ) const;
void compute( const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints, void compute( const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints,
vector<Mat>& descriptors ) const; vector<Mat>& descriptors ) const;
virtual void read( const FileNode& ); virtual void read( const FileNode& );
virtual void write( FileStorage& ) const; virtual void write( FileStorage& ) const;
virtual int descriptorSize() const = 0; virtual int descriptorSize() const = 0;
virtual int descriptorType() const = 0; virtual int descriptorType() const = 0;
static Ptr<DescriptorExtractor> create( const string& descriptorExtractorType ); static Ptr<DescriptorExtractor> create( const string& descriptorExtractorType );
protected: protected:
... ...
}; };
.. ..
In this interface we assume a keypoint descriptor can be represented as a In this interface we assume a keypoint descriptor can be represented as a
dense, fixed-dimensional vector of some basic type. Most descriptors used dense, fixed-dimensional vector of some basic type. Most descriptors used
in practice follow this pattern, as it makes it very easy to compute in practice follow this pattern, as it makes it very easy to compute
distances between descriptors. Therefore we represent a collection of distances between descriptors. Therefore we represent a collection of
descriptors as a descriptors as a
:func:`Mat` :func:`Mat` , where each row is one keypoint descriptor.
, where each row is one keypoint descriptor.
.. index:: DescriptorExtractor::compute .. index:: DescriptorExtractor::compute
cv::DescriptorExtractor::compute cv::DescriptorExtractor::compute
-------------------------------- --------------------------------
`id=0.622580160404 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorExtractor%3A%3Acompute>`__
.. cfunction:: void DescriptorExtractor::compute( const Mat\& image, vector<KeyPoint>\& keypoints, Mat\& descriptors ) const .. cfunction:: void DescriptorExtractor::compute( const Mat\& image, vector<KeyPoint>\& keypoints, Mat\& descriptors ) const
Compute the descriptors for a set of keypoints detected in an image (first variant) Compute the descriptors for a set of keypoints detected in an image (first variant)
or image set (second variant). or image set (second variant).
:param image: The image.
:param keypoints: The keypoints. Keypoints for which a descriptor cannot be computed are removed.
:param descriptors: The descriptors. Row i is the descriptor for keypoint i.
:param image: The image.
:param keypoints: The keypoints. Keypoints for which a descriptor cannot be computed are removed.
:param descriptors: The descriptors. Row i is the descriptor for keypoint i.
.. cfunction:: void DescriptorExtractor::compute( const vector<Mat>\& images, vector<vector<KeyPoint> >\& keypoints, vector<Mat>\& descriptors ) const .. cfunction:: void DescriptorExtractor::compute( const vector<Mat>\& images, vector<vector<KeyPoint> >\& keypoints, vector<Mat>\& descriptors ) const
* **images** The image set.
* **keypoints** Input keypoints collection. keypoints[i] is keypoints
detected in images[i]. Keypoints for which a descriptor
can not be computed are removed.
* **descriptors** Descriptor collection. descriptors[i] are descriptors computed for
a set keypoints[i].
* **images** The image set.
* **keypoints** Input keypoints collection. keypoints[i] is keypoints
detected in images[i]. Keypoints for which a descriptor
can not be computed are removed.
* **descriptors** Descriptor collection. descriptors[i] are descriptors computed for
a set keypoints[i].
.. index:: DescriptorExtractor::read .. index:: DescriptorExtractor::read
cv::DescriptorExtractor::read cv::DescriptorExtractor::read
----------------------------- -----------------------------
`id=0.708176779821 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorExtractor%3A%3Aread>`__
.. cfunction:: void DescriptorExtractor::read( const FileNode\& fn ) .. cfunction:: void DescriptorExtractor::read( const FileNode\& fn )
Read descriptor extractor object from file node. Read descriptor extractor object from file node.
:param fn: File node from which detector will be read.
:param fn: File node from which detector will be read.
.. index:: DescriptorExtractor::write .. index:: DescriptorExtractor::write
cv::DescriptorExtractor::write cv::DescriptorExtractor::write
------------------------------ ------------------------------
`id=0.206682397054 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorExtractor%3A%3Awrite>`__
.. cfunction:: void DescriptorExtractor::write( FileStorage\& fs ) const .. cfunction:: void DescriptorExtractor::write( FileStorage\& fs ) const
Write descriptor extractor object to file storage. Write descriptor extractor object to file storage.
:param fs: File storage in which detector will be written.
:param fs: File storage in which detector will be written.
.. index:: DescriptorExtractor::create .. index:: DescriptorExtractor::create
cv::DescriptorExtractor::create cv::DescriptorExtractor::create
------------------------------- -------------------------------
`id=0.923714079643 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorExtractor%3A%3Acreate>`__
:func:`DescriptorExtractor` :func:`DescriptorExtractor`
.. cfunction:: Ptr<DescriptorExtractor> DescriptorExtractor::create( const string\& descriptorExtractorType ) .. cfunction:: Ptr<DescriptorExtractor> DescriptorExtractor::create( const string\& descriptorExtractorType )
Descriptor extractor factory that creates of given type with Descriptor extractor factory that creates of given type with
default parameters (rather using default constructor). default parameters (rather using default constructor).
:param descriptorExtractorType: Descriptor extractor type.
:param descriptorExtractorType: Descriptor extractor type.
Now the following descriptor extractor types are supported: Now the following descriptor extractor types are supported:
\ ``"SIFT"`` --
:func:`SiftFeatureDetector`,\ ``"SURF"`` --
:func:`SurfFeatureDetector`,\ ``"BRIEF"`` --
:func:`BriefFeatureDetector` .
\ \
``"SIFT"`` Also combined format is supported: descriptor extractor adapter name ( ``"Opponent"`` --
-- :func:`OpponentColorDescriptorExtractor` ) + descriptor extractor name (see above),
:func:`SiftFeatureDetector` e.g. ``"OpponentSIFT"`` , etc.
,
\
``"SURF"``
--
:func:`SurfFeatureDetector`
,
\
``"BRIEF"``
--
:func:`BriefFeatureDetector`
.
\
Also combined format is supported: descriptor extractor adapter name (
``"Opponent"``
--
:func:`OpponentColorDescriptorExtractor`
) + descriptor extractor name (see above),
e.g.
``"OpponentSIFT"``
, etc.
.. index:: SiftDescriptorExtractor .. index:: SiftDescriptorExtractor
@ -231,36 +123,23 @@ e.g.
SiftDescriptorExtractor SiftDescriptorExtractor
----------------------- -----------------------
`id=0.676546819501 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/SiftDescriptorExtractor>`__
.. ctype:: SiftDescriptorExtractor .. ctype:: SiftDescriptorExtractor
Wrapping class for descriptors computing using
:func:`SIFT` class. ::
Wrapping class for descriptors computing using
:func:`SIFT`
class.
::
class SiftDescriptorExtractor : public DescriptorExtractor class SiftDescriptorExtractor : public DescriptorExtractor
{ {
public: public:
SiftDescriptorExtractor( SiftDescriptorExtractor(
const SIFT::DescriptorParams& descriptorParams=SIFT::DescriptorParams(), const SIFT::DescriptorParams& descriptorParams=SIFT::DescriptorParams(),
const SIFT::CommonParams& commonParams=SIFT::CommonParams() ); const SIFT::CommonParams& commonParams=SIFT::CommonParams() );
SiftDescriptorExtractor( double magnification, bool isNormalize=true, SiftDescriptorExtractor( double magnification, bool isNormalize=true,
bool recalculateAngles=true, int nOctaves=SIFT::CommonParams::DEFAULT_NOCTAVES, bool recalculateAngles=true, int nOctaves=SIFT::CommonParams::DEFAULT_NOCTAVES,
int nOctaveLayers=SIFT::CommonParams::DEFAULT_NOCTAVE_LAYERS, int nOctaveLayers=SIFT::CommonParams::DEFAULT_NOCTAVE_LAYERS,
int firstOctave=SIFT::CommonParams::DEFAULT_FIRST_OCTAVE, int firstOctave=SIFT::CommonParams::DEFAULT_FIRST_OCTAVE,
int angleMode=SIFT::CommonParams::FIRST_ANGLE ); int angleMode=SIFT::CommonParams::FIRST_ANGLE );
virtual void read (const FileNode &fn); virtual void read (const FileNode &fn);
virtual void write (FileStorage &fs) const; virtual void write (FileStorage &fs) const;
virtual int descriptorSize() const; virtual int descriptorSize() const;
@ -268,41 +147,25 @@ class.
protected: protected:
... ...
} }
.. ..
.. index:: SurfDescriptorExtractor .. index:: SurfDescriptorExtractor
.. _SurfDescriptorExtractor: .. _SurfDescriptorExtractor:
SurfDescriptorExtractor SurfDescriptorExtractor
----------------------- -----------------------
`id=0.638581739296 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/SurfDescriptorExtractor>`__
.. ctype:: SurfDescriptorExtractor .. ctype:: SurfDescriptorExtractor
Wrapping class for descriptors computing using
:func:`SURF` class. ::
Wrapping class for descriptors computing using
:func:`SURF`
class.
::
class SurfDescriptorExtractor : public DescriptorExtractor class SurfDescriptorExtractor : public DescriptorExtractor
{ {
public: public:
SurfDescriptorExtractor( int nOctaves=4, SurfDescriptorExtractor( int nOctaves=4,
int nOctaveLayers=2, bool extended=false ); int nOctaveLayers=2, bool extended=false );
virtual void read (const FileNode &fn); virtual void read (const FileNode &fn);
virtual void write (FileStorage &fs) const; virtual void write (FileStorage &fs) const;
virtual int descriptorSize() const; virtual int descriptorSize() const;
@ -310,41 +173,25 @@ class.
protected: protected:
... ...
} }
.. ..
.. index:: CalonderDescriptorExtractor .. index:: CalonderDescriptorExtractor
.. _CalonderDescriptorExtractor: .. _CalonderDescriptorExtractor:
CalonderDescriptorExtractor CalonderDescriptorExtractor
--------------------------- ---------------------------
`id=0.301561509204 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/CalonderDescriptorExtractor>`__
.. ctype:: CalonderDescriptorExtractor .. ctype:: CalonderDescriptorExtractor
Wrapping class for descriptors computing using
:func:`RTreeClassifier` class. ::
Wrapping class for descriptors computing using
:func:`RTreeClassifier`
class.
::
template<typename T> template<typename T>
class CalonderDescriptorExtractor : public DescriptorExtractor class CalonderDescriptorExtractor : public DescriptorExtractor
{ {
public: public:
CalonderDescriptorExtractor( const string& classifierFile ); CalonderDescriptorExtractor( const string& classifierFile );
virtual void read( const FileNode &fn ); virtual void read( const FileNode &fn );
virtual void write( FileStorage &fs ) const; virtual void write( FileStorage &fs ) const;
virtual int descriptorSize() const; virtual int descriptorSize() const;
@ -352,42 +199,27 @@ class.
protected: protected:
... ...
} }
.. ..
.. index:: OpponentColorDescriptorExtractor .. index:: OpponentColorDescriptorExtractor
.. _OpponentColorDescriptorExtractor: .. _OpponentColorDescriptorExtractor:
OpponentColorDescriptorExtractor OpponentColorDescriptorExtractor
-------------------------------- --------------------------------
`id=0.081563051622 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/OpponentColorDescriptorExtractor>`__
.. ctype:: OpponentColorDescriptorExtractor .. ctype:: OpponentColorDescriptorExtractor
Adapts a descriptor extractor to compute descripors in Opponent Color Space Adapts a descriptor extractor to compute descripors in Opponent Color Space
(refer to van de Sande et al., CGIV 2008 "Color Descriptors for Object Category Recognition"). (refer to van de Sande et al., CGIV 2008 "Color Descriptors for Object Category Recognition").
Input RGB image is transformed in Opponent Color Space. Then unadapted descriptor extractor Input RGB image is transformed in Opponent Color Space. Then unadapted descriptor extractor
(set in constructor) computes descriptors on each of the three channel and concatenate (set in constructor) computes descriptors on each of the three channel and concatenate
them into a single color descriptor. them into a single color descriptor. ::
::
class OpponentColorDescriptorExtractor : public DescriptorExtractor class OpponentColorDescriptorExtractor : public DescriptorExtractor
{ {
public: public:
OpponentColorDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor ); OpponentColorDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor );
virtual void read( const FileNode& ); virtual void read( const FileNode& );
virtual void write( FileStorage& ) const; virtual void write( FileStorage& ) const;
virtual int descriptorSize() const; virtual int descriptorSize() const;
@ -395,44 +227,29 @@ them into a single color descriptor.
protected: protected:
... ...
}; };
.. ..
.. index:: BriefDescriptorExtractor .. index:: BriefDescriptorExtractor
.. _BriefDescriptorExtractor: .. _BriefDescriptorExtractor:
BriefDescriptorExtractor BriefDescriptorExtractor
------------------------ ------------------------
`id=0.207875021385 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BriefDescriptorExtractor>`__
.. ctype:: BriefDescriptorExtractor .. ctype:: BriefDescriptorExtractor
Class for computing BRIEF descriptors described in paper of Calonder M., Lepetit V.,
Strecha C., Fua P.: ''BRIEF: Binary Robust Independent Elementary Features.''
11th European Conference on Computer Vision (ECCV), Heraklion, Crete. LNCS Springer, September 2010. ::
Class for computing BRIEF descriptors described in paper of Calonder M., Lepetit V.,
Strecha C., Fua P.: ''BRIEF: Binary Robust Independent Elementary Features.''
11th European Conference on Computer Vision (ECCV), Heraklion, Crete. LNCS Springer, September 2010.
::
class BriefDescriptorExtractor : public DescriptorExtractor class BriefDescriptorExtractor : public DescriptorExtractor
{ {
public: public:
static const int PATCH_SIZE = 48; static const int PATCH_SIZE = 48;
static const int KERNEL_SIZE = 9; static const int KERNEL_SIZE = 9;
// bytes is a length of descriptor in bytes. It can be equal 16, 32 or 64 bytes. // bytes is a length of descriptor in bytes. It can be equal 16, 32 or 64 bytes.
BriefDescriptorExtractor( int bytes = 32 ); BriefDescriptorExtractor( int bytes = 32 );
virtual void read( const FileNode& ); virtual void read( const FileNode& );
virtual void write( FileStorage& ) const; virtual void write( FileStorage& ) const;
virtual int descriptorSize() const; virtual int descriptorSize() const;
@ -440,7 +257,5 @@ Strecha C., Fua P.: ''BRIEF: Binary Robust Independent Elementary Features.''
protected: protected:
... ...
}; };
.. ..

435
modules/features2d/doc/common_interfaces_of_descriptor_matchers.rst
View File

@ -3,14 +3,11 @@ Common Interfaces of Descriptor Matchers
.. highlight:: cpp .. highlight:: cpp
Matchers of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily
Matchers of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily 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 :func:`DescriptorMatcher` interface.
:func:`DescriptorMatcher`
interface.
.. index:: DMatch .. index:: DMatch
@ -18,86 +15,59 @@ interface.
DMatch DMatch
------ ------
`id=0.193402930617 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DMatch>`__
.. ctype:: DMatch .. ctype:: DMatch
Match between two keypoint descriptors: query descriptor index,
train descriptor index, train image index and distance between descriptors. ::
Match between two keypoint descriptors: query descriptor index,
train descriptor index, train image index and distance between descriptors.
::
struct DMatch struct DMatch
{ {
DMatch() : queryIdx(-1), trainIdx(-1), imgIdx(-1), DMatch() : queryIdx(-1), trainIdx(-1), imgIdx(-1),
distance(std::numeric_limits<float>::max()) {} distance(std::numeric_limits<float>::max()) {}
DMatch( int _queryIdx, int _trainIdx, float _distance ) : DMatch( int _queryIdx, int _trainIdx, float _distance ) :
queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(-1), queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(-1),
distance(_distance) {} distance(_distance) {}
DMatch( int _queryIdx, int _trainIdx, int _imgIdx, float _distance ) : DMatch( int _queryIdx, int _trainIdx, int _imgIdx, float _distance ) :
queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(_imgIdx), queryIdx(_queryIdx), trainIdx(_trainIdx), imgIdx(_imgIdx),
distance(_distance) {} distance(_distance) {}
int queryIdx; // query descriptor index int queryIdx; // query descriptor index
int trainIdx; // train descriptor index int trainIdx; // train descriptor index
int imgIdx; // train image index int imgIdx; // train image index
float distance; float distance;
// less is better // less is better
bool operator<( const DMatch &m ) const; bool operator<( const DMatch &m ) const;
}; };
.. ..
.. index:: DescriptorMatcher .. index:: DescriptorMatcher
.. _DescriptorMatcher: .. _DescriptorMatcher:
DescriptorMatcher DescriptorMatcher
----------------- -----------------
`id=0.0185035556985 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher>`__
.. ctype:: DescriptorMatcher .. ctype:: 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 one image with other image or of match methods: for matching descriptors of one image with other image or
with image set. with image set. ::
::
class DescriptorMatcher class DescriptorMatcher
{ {
public: public:
virtual ~DescriptorMatcher(); virtual ~DescriptorMatcher();
virtual void add( const vector<Mat>& descriptors ); virtual void add( const vector<Mat>& descriptors );
const vector<Mat>& getTrainDescriptors() const; const vector<Mat>& getTrainDescriptors() const;
virtual void clear(); virtual void clear();
bool empty() const; bool empty() const;
virtual bool isMaskSupported() const = 0; virtual bool isMaskSupported() const = 0;
virtual void train(); virtual void train();
/* /*
* Group of methods to match descriptors from image pair. * Group of methods to match descriptors from image pair.
*/ */
@ -114,357 +84,174 @@ with image set.
*/ */
void match( const Mat& queryDescriptors, vector<DMatch>& matches, void match( const Mat& queryDescriptors, vector<DMatch>& matches,
const vector<Mat>& masks=vector<Mat>() ); const vector<Mat>& masks=vector<Mat>() );
void knnMatch( const Mat& queryDescriptors, vector<vector<DMatch> >& matches, void knnMatch( const Mat& queryDescriptors, vector<vector<DMatch> >& matches,
int k, const vector<Mat>& masks=vector<Mat>(), int k, const vector<Mat>& masks=vector<Mat>(),
bool compactResult=false ); bool compactResult=false );
void radiusMatch( const Mat& queryDescriptors, vector<vector<DMatch> >& matches, void radiusMatch( const Mat& queryDescriptors, vector<vector<DMatch> >& matches,
float maxDistance, const vector<Mat>& masks=vector<Mat>(), float maxDistance, const vector<Mat>& masks=vector<Mat>(),
bool compactResult=false ); bool compactResult=false );
virtual void read( const FileNode& ); virtual void read( const FileNode& );
virtual void write( FileStorage& ) const; virtual void write( FileStorage& ) const;
virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0; virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
static Ptr<DescriptorMatcher> create( const string& descriptorMatcherType ); static Ptr<DescriptorMatcher> create( const string& descriptorMatcherType );
protected: protected:
vector<Mat> trainDescCollection; vector<Mat> trainDescCollection;
... ...
}; };
.. ..
.. index:: DescriptorMatcher::add .. index:: DescriptorMatcher::add
cv::DescriptorMatcher::add cv::DescriptorMatcher::add
-------------------------- -------------------------- ````
`id=0.549221986718 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Aadd>`__
````
.. cfunction:: void add( const vector<Mat>\& descriptors ) .. cfunction:: void add( const vector<Mat>\& descriptors )
Add descriptors to train descriptor collection. If collection trainDescCollectionis not empty Add descriptors to train descriptor collection. If collection trainDescCollectionis not empty
the new descriptors are added to existing train descriptors. the new descriptors are added to existing train descriptors.
:param descriptors: Descriptors to add. Each ``descriptors[i]`` is a set of descriptors
from the same (one) train image.
:param descriptors: Descriptors to add. Each ``descriptors[i]`` is a set of descriptors
from the same (one) train image.
.. index:: DescriptorMatcher::getTrainDescriptors .. index:: DescriptorMatcher::getTrainDescriptors
cv::DescriptorMatcher::getTrainDescriptors cv::DescriptorMatcher::getTrainDescriptors
------------------------------------------ ------------------------------------------ ````
`id=0.354691082433 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3AgetTrainDescriptors>`__
````
.. cfunction:: const vector<Mat>\& getTrainDescriptors() const .. cfunction:: const vector<Mat>\& getTrainDescriptors() const
Returns constant link to the train descriptor collection (i.e. trainDescCollection). Returns constant link to the train descriptor collection (i.e. trainDescCollection).
.. index:: DescriptorMatcher::clear .. index:: DescriptorMatcher::clear
cv::DescriptorMatcher::clear cv::DescriptorMatcher::clear
---------------------------- ----------------------------
`id=0.776403699262 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Aclear>`__
.. cfunction:: void DescriptorMatcher::clear() .. cfunction:: void DescriptorMatcher::clear()
Clear train descriptor collection. Clear train descriptor collection.
.. index:: DescriptorMatcher::empty .. index:: DescriptorMatcher::empty
cv::DescriptorMatcher::empty cv::DescriptorMatcher::empty
---------------------------- ----------------------------
`id=0.186730120991 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Aempty>`__
.. cfunction:: bool DescriptorMatcher::empty() const .. cfunction:: bool DescriptorMatcher::empty() const
Return true if there are not train descriptors in collection. Return true if there are not train descriptors in collection.
.. index:: DescriptorMatcher::isMaskSupported .. index:: DescriptorMatcher::isMaskSupported
cv::DescriptorMatcher::isMaskSupported cv::DescriptorMatcher::isMaskSupported
-------------------------------------- --------------------------------------
`id=0.4880242426 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3AisMaskSupported>`__
.. cfunction:: bool DescriptorMatcher::isMaskSupported() .. cfunction:: bool DescriptorMatcher::isMaskSupported()
Returns true if descriptor matcher supports masking permissible matches. Returns true if descriptor matcher supports masking permissible matches.
.. index:: DescriptorMatcher::train .. index:: DescriptorMatcher::train
cv::DescriptorMatcher::train cv::DescriptorMatcher::train
---------------------------- ----------------------------
`id=0.708209257367 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Atrain>`__
.. cfunction:: void DescriptorMatcher::train() .. cfunction:: void DescriptorMatcher::train()
Train descriptor matcher (e.g. train flann index). In all methods to match the method train() Train descriptor matcher (e.g. train flann index). In all methods to match the method train()
is run every time before matching. Some descriptor matchers (e.g. BruteForceMatcher) have empty is run every time before matching. Some descriptor matchers (e.g. BruteForceMatcher) have empty
implementation of this method, other matchers realy train their inner structures (e.g. FlannBasedMatcher implementation of this method, other matchers realy train their inner structures (e.g. FlannBasedMatcher
trains flann::Index) trains flann::Index)
.. index:: DescriptorMatcher::match .. index:: DescriptorMatcher::match
cv::DescriptorMatcher::match cv::DescriptorMatcher::match
---------------------------- ---------------------------- ```` ```` ```` ````
`id=0.803878673329 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Amatch>`__
````
````
````
````
.. cfunction:: void DescriptorMatcher::match( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector<DMatch>\& matches, const Mat\& mask=Mat() ) const .. cfunction:: void DescriptorMatcher::match( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector<DMatch>\& matches, const Mat\& mask=Mat() ) const
Find the best match for each descriptor from a query set with train descriptors. Find the best match for each descriptor from a query set with train descriptors.
Supposed that the query descriptors are of keypoints detected on the same query image. Supposed that the query descriptors are of keypoints detected on the same query image.
In first variant of this method train descriptors are set as input argument and In first variant of this method train descriptors are set as input argument and
supposed that they are of keypoints detected on the same train image. In second variant supposed that they are of keypoints detected on the same train image. In second variant
of the method train descriptors collection that was set using addmethod is used. of the method train descriptors collection that was set using addmethod is used.
Optional mask (or masks) can be set to describe which descriptors can be matched. queryDescriptors[i]can be matched with trainDescriptors[j]only if mask.at<uchar>(i,j)is non-zero. Optional mask (or masks) can be set to describe which descriptors can be matched. queryDescriptors[i]can be matched with trainDescriptors[j]only if mask.at<uchar>(i,j)is non-zero.
.. cfunction:: void DescriptorMatcher::match( const Mat\& queryDescriptors, vector<DMatch>\& matches, const vector<Mat>\& masks=vector<Mat>() ) .. cfunction:: void DescriptorMatcher::match( const Mat\& queryDescriptors, vector<DMatch>\& matches, const vector<Mat>\& masks=vector<Mat>() )
:param queryDescriptors: Query set of descriptors.
:param trainDescriptors: Train set of descriptors. This will not be added to train descriptors collection
stored in class object.
:param queryDescriptors: Query set of descriptors.
:param trainDescriptors: Train set of descriptors. This will not be added to train descriptors collection
stored in class object.
:param matches: Matches. If some query descriptor masked out in ``mask`` no match will be added for this descriptor. :param matches: Matches. If some query descriptor masked out in ``mask`` no match will be added for this descriptor.
So ``matches`` size may be less query descriptors count. So ``matches`` size may be less query descriptors count.
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
:param masks: The set of masks. Each ``masks[i]`` specifies permissible matches between input query descriptors :param masks: The set of masks. Each ``masks[i]`` specifies permissible matches between input query descriptors
and stored train descriptors from i-th image (i.e. ``trainDescCollection[i])`` . and stored train descriptors from i-th image (i.e. ``trainDescCollection[i])`` .
.. index:: DescriptorMatcher::knnMatch .. index:: DescriptorMatcher::knnMatch
cv::DescriptorMatcher::knnMatch cv::DescriptorMatcher::knnMatch
------------------------------- -------------------------------
`id=0.510078848403 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3AknnMatch>`__
:func:`DescriptorMatcher::match` :func:`DescriptorMatcher::match`
.. cfunction:: void DescriptorMatcher::knnMatch( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector<vector<DMatch> >\& matches, int k, const Mat\& mask=Mat(), bool compactResult=false ) const .. cfunction:: void DescriptorMatcher::knnMatch( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector<vector<DMatch> >\& matches, int k, const Mat\& mask=Mat(), bool compactResult=false ) const
Find the k best matches for each descriptor from a query set with train descriptors. Find the k best matches for each descriptor from a query set with train descriptors.
Found k (or less if not possible) matches are returned in distance increasing order. Found k (or less if not possible) matches are returned in distance increasing order.
Details about query and train descriptors see in . Details about query and train descriptors see in .
.. cfunction:: void DescriptorMatcher::knnMatch( const Mat\& queryDescriptors, vector<vector<DMatch> >\& matches, int k, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false ) .. cfunction:: void DescriptorMatcher::knnMatch( const Mat\& queryDescriptors, vector<vector<DMatch> >\& matches, int k, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false )
:param queryDescriptors, trainDescriptors, mask, masks: See in :func:`DescriptorMatcher::match` .
:param matches: Mathes. Each ``matches[i]`` is k or less matches for the same query descriptor.
:param k: Count of best matches will be found per each query descriptor (or less if it's not possible).
:param compactResult: It's used when mask (or masks) is not empty. If ``compactResult`` is false ``matches`` vector will have the same size as ``queryDescriptors`` rows. If ``compactResult`` is true ``matches`` vector will not contain matches for fully masked out query descriptors.
:param queryDescriptors, trainDescriptors, mask, masks: See in :func:`DescriptorMatcher::match` .
:param matches: Mathes. Each ``matches[i]`` is k or less matches for the same query descriptor.
:param k: Count of best matches will be found per each query descriptor (or less if it's not possible).
:param compactResult: It's used when mask (or masks) is not empty. If ``compactResult`` is false ``matches`` vector will have the same size as ``queryDescriptors`` rows. If ``compactResult``
is true ``matches`` vector will not contain matches for fully masked out query descriptors.
.. index:: DescriptorMatcher::radiusMatch .. index:: DescriptorMatcher::radiusMatch
cv::DescriptorMatcher::radiusMatch cv::DescriptorMatcher::radiusMatch
---------------------------------- ----------------------------------
`id=0.763278154174 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3AradiusMatch>`__
:func:`DescriptorMatcher::match` :func:`DescriptorMatcher::match`
.. cfunction:: void DescriptorMatcher::radiusMatch( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector<vector<DMatch> >\& matches, float maxDistance, const Mat\& mask=Mat(), bool compactResult=false ) const .. cfunction:: void DescriptorMatcher::radiusMatch( const Mat\& queryDescriptors, const Mat\& trainDescriptors, vector<vector<DMatch> >\& matches, float maxDistance, const Mat\& mask=Mat(), bool compactResult=false ) const
Find the best matches for each query descriptor which have distance less than given threshold. Find the best matches for each query descriptor which have distance less than given threshold.
Found matches are returned in distance increasing order. Details about query and train Found matches are returned in distance increasing order. Details about query and train
descriptors see in . descriptors see in .
.. cfunction:: void DescriptorMatcher::radiusMatch( const Mat\& queryDescriptors, vector<vector<DMatch> >\& matches, float maxDistance, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false ) .. cfunction:: void DescriptorMatcher::radiusMatch( const Mat\& queryDescriptors, vector<vector<DMatch> >\& matches, float maxDistance, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false )
:param queryDescriptors, trainDescriptors, mask, masks: See in :func:`DescriptorMatcher::match` .
:param matches, compactResult: See in :func:`DescriptorMatcher::knnMatch` .
:param maxDistance: The threshold to found match distances.
:param queryDescriptors, trainDescriptors, mask, masks: See in :func:`DescriptorMatcher::match` .
:param matches, compactResult: See in :func:`DescriptorMatcher::knnMatch` .
:param maxDistance: The threshold to found match distances.
.. index:: DescriptorMatcher::clone .. index:: DescriptorMatcher::clone
cv::DescriptorMatcher::clone cv::DescriptorMatcher::clone
---------------------------- ----------------------------
`id=0.743679534249 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Aclone>`__
.. cfunction:: Ptr<DescriptorMatcher> \\DescriptorMatcher::clone( bool emptyTrainData ) const .. cfunction:: Ptr<DescriptorMatcher> \\DescriptorMatcher::clone( bool emptyTrainData ) const
Clone the matcher. Clone the matcher.
:param emptyTrainData: If emptyTrainData is false the method create deep copy of the object, i.e. copies :param emptyTrainData: If emptyTrainData is false the method create deep copy of the object, i.e. copies
both parameters and train data. If emptyTrainData is true the method create object copy with current parameters both parameters and train data. If emptyTrainData is true the method create object copy with current parameters
but with empty train data.. but with empty train data..
.. index:: DescriptorMatcher::create .. index:: DescriptorMatcher::create
cv::DescriptorMatcher::create cv::DescriptorMatcher::create
----------------------------- -----------------------------
`id=0.681869512138 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/DescriptorMatcher%3A%3Acreate>`__
:func:`DescriptorMatcher` :func:`DescriptorMatcher`
.. cfunction:: Ptr<DescriptorMatcher> DescriptorMatcher::create( const string\& descriptorMatcherType ) .. cfunction:: Ptr<DescriptorMatcher> DescriptorMatcher::create( const string\& descriptorMatcherType )
Descriptor matcher factory that creates of Descriptor matcher factory that creates of
given type with default parameters (rather using default constructor). given type with default parameters (rather using default constructor).
:param descriptorMatcherType: Descriptor matcher type.
Now the following matcher types are supported: ``"BruteForce"`` (it uses ``L2`` ), ``"BruteForce-L1"``,``"BruteForce-Hamming"``,``"BruteForce-HammingLUT"``,``"FlannBased"`` .
:param descriptorMatcherType: Descriptor matcher type.
Now the following matcher types are supported:
``"BruteForce"``
(it uses
``L2``
),
``"BruteForce-L1"``
,
``"BruteForce-Hamming"``
,
``"BruteForce-HammingLUT"``
,
``"FlannBased"``
.
.. index:: BruteForceMatcher .. index:: BruteForceMatcher
@ -472,63 +259,40 @@ Now the following matcher types are supported:
BruteForceMatcher BruteForceMatcher
----------------- -----------------
`id=0.47821275438 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BruteForceMatcher>`__
.. ctype:: BruteForceMatcher .. ctype:: BruteForceMatcher
Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest 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 descriptor in the second set by trying each one. This descriptor matcher supports masking
permissible matches between descriptor sets. permissible matches between descriptor sets. ::
::
template<class Distance> template<class Distance>
class BruteForceMatcher : public DescriptorMatcher class BruteForceMatcher : public DescriptorMatcher
{ {
public: public:
BruteForceMatcher( Distance d = Distance() ); BruteForceMatcher( Distance d = Distance() );
virtual ~BruteForceMatcher(); virtual ~BruteForceMatcher();
virtual bool isMaskSupported() const; virtual bool isMaskSupported() const;
virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const; virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected: protected:
... ...
} }
.. ..
For efficiency, BruteForceMatcher is templated on the distance metric. For efficiency, BruteForceMatcher is templated on the distance metric.
For float descriptors, a common choice would be For float descriptors, a common choice would be ``L2<float>`` . Class of supported distances are: ::
``L2<float>``
. Class of supported distances are:
::
template<typename T> template<typename T>
struct Accumulator struct Accumulator
{ {
typedef T Type; typedef T Type;
}; };
template<> struct Accumulator<unsigned char> { typedef unsigned int Type; }; template<> struct Accumulator<unsigned char> { typedef unsigned int Type; };
template<> struct Accumulator<unsigned short> { typedef unsigned int Type; }; template<> struct Accumulator<unsigned short> { typedef unsigned int Type; };
template<> struct Accumulator<char> { typedef int Type; }; template<> struct Accumulator<char> { typedef int Type; };
template<> struct Accumulator<short> { typedef int Type; }; template<> struct Accumulator<short> { typedef int Type; };
/* /*
* Squared Euclidean distance functor * Squared Euclidean distance functor
*/ */
@ -537,10 +301,10 @@ For float descriptors, a common choice would be
{ {
typedef T ValueType; typedef T ValueType;
typedef typename Accumulator<T>::Type ResultType; typedef typename Accumulator<T>::Type ResultType;
ResultType operator()( const T* a, const T* b, int size ) const; ResultType operator()( const T* a, const T* b, int size ) const;
}; };
/* /*
* Manhattan distance (city block distance) functor * Manhattan distance (city block distance) functor
*/ */
@ -549,11 +313,11 @@ For float descriptors, a common choice would be
{ {
typedef T ValueType; typedef T ValueType;
typedef typename Accumulator<T>::Type ResultType; typedef typename Accumulator<T>::Type ResultType;
ResultType operator()( const T* a, const T* b, int size ) const; ResultType operator()( const T* a, const T* b, int size ) const;
... ...
}; };
/* /*
* Hamming distance (city block distance) functor * Hamming distance (city block distance) functor
*/ */
@ -561,77 +325,56 @@ For float descriptors, a common choice would be
{ {
typedef unsigned char ValueType; typedef unsigned char ValueType;
typedef int ResultType; typedef int ResultType;
ResultType operator()( const unsigned char* a, const unsigned char* b, ResultType operator()( const unsigned char* a, const unsigned char* b,
int size ) const; int size ) const;
... ...
}; };
struct Hamming struct Hamming
{ {
typedef unsigned char ValueType; typedef unsigned char ValueType;
typedef int ResultType; typedef int ResultType;
ResultType operator()( const unsigned char* a, const unsigned char* b, ResultType operator()( const unsigned char* a, const unsigned char* b,
int size ) const; int size ) const;
... ...
}; };
.. ..
.. index:: FlannBasedMatcher .. index:: FlannBasedMatcher
.. _FlannBasedMatcher: .. _FlannBasedMatcher:
FlannBasedMatcher FlannBasedMatcher
----------------- -----------------
`id=0.721140850904 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/FlannBasedMatcher>`__
.. ctype:: FlannBasedMatcher .. ctype:: FlannBasedMatcher
Flann based descriptor matcher. This matcher trains
:func:`flann::Index` on
train descriptor collection and calls it's nearest search methods to find best matches.
So this matcher may be faster in cases of matching to large train collection than
brute force matcher. ``FlannBasedMatcher`` does not support masking permissible
matches between descriptor sets, because
:func:`flann::Index` does not
support this. ::
Flann based descriptor matcher. This matcher trains
:func:`flann::Index`
on
train descriptor collection and calls it's nearest search methods to find best matches.
So this matcher may be faster in cases of matching to large train collection than
brute force matcher.
``FlannBasedMatcher``
does not support masking permissible
matches between descriptor sets, because
:func:`flann::Index`
does not
support this.
::
class FlannBasedMatcher : public DescriptorMatcher class FlannBasedMatcher : public DescriptorMatcher
{ {
public: public:
FlannBasedMatcher( FlannBasedMatcher(
const Ptr<flann::IndexParams>& indexParams=new flann::KDTreeIndexParams(), const Ptr<flann::IndexParams>& indexParams=new flann::KDTreeIndexParams(),
const Ptr<flann::SearchParams>& searchParams=new flann::SearchParams() ); const Ptr<flann::SearchParams>& searchParams=new flann::SearchParams() );
virtual void add( const vector<Mat>& descriptors ); virtual void add( const vector<Mat>& descriptors );
virtual void clear(); virtual void clear();
virtual void train(); virtual void train();
virtual bool isMaskSupported() const; virtual bool isMaskSupported() const;
virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const; virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected: protected:
... ...
}; };
.. ..

693
modules/features2d/doc/common_interfaces_of_feature_detectors.rst
View File

File diff suppressed because it is too large Load Diff

453
modules/features2d/doc/common_interfaces_of_generic_descriptor_matchers.rst
View File

@ -3,25 +3,14 @@ Common Interfaces of Generic Descriptor Matchers
.. highlight:: cpp .. highlight:: cpp
Matchers of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily
Matchers of keypoint descriptors in OpenCV have wrappers with common interface that enables to switch easily 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 can not be represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors. It does not make any assumptions about descriptor representation.
that can not be represented as vectors in a multidimensional space. Every descriptor with
``GenericDescriptorMatcher`` :func:`DescriptorExtractor` interface has a wrapper with ``GenericDescriptorMatcher`` interface (see
is a more generic interface for descriptors. It does not make any assumptions about descriptor representation. :func:`VectorDescriptorMatcher` ).
Every descriptor with There are descriptors such as One way descriptor and Ferns that have ``GenericDescriptorMatcher`` interface implemented, but do not support
:func:`DescriptorExtractor` :func:`DescriptorExtractor` .
interface has a wrapper with
``GenericDescriptorMatcher``
interface (see
:func:`VectorDescriptorMatcher`
).
There are descriptors such as One way descriptor and Ferns that have
``GenericDescriptorMatcher``
interface implemented, but do not support
:func:`DescriptorExtractor`
.
.. index:: GenericDescriptorMatcher .. index:: GenericDescriptorMatcher
@ -29,61 +18,42 @@ interface implemented, but do not support
GenericDescriptorMatcher GenericDescriptorMatcher
------------------------ ------------------------
`id=0.973387347242 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher>`__
.. ctype:: GenericDescriptorMatcher .. ctype:: GenericDescriptorMatcher
Abstract interface for a keypoint descriptor extracting and matching.
There is
Abstract interface for a keypoint descriptor extracting and matching. :func:`DescriptorExtractor` and
There is :func:`DescriptorMatcher` for these purposes too, but their interfaces are intended for descriptors
:func:`DescriptorExtractor` represented as vectors in a multidimensional space. ``GenericDescriptorMatcher`` is a more generic interface for descriptors.
and As
:func:`DescriptorMatcher` :func:`DescriptorMatcher`,``GenericDescriptorMatcher`` has two groups
for these purposes too, but their interfaces are intended for descriptors
represented as vectors in a multidimensional space.
``GenericDescriptorMatcher``
is a more generic interface for descriptors.
As
:func:`DescriptorMatcher`
,
``GenericDescriptorMatcher``
has two groups
of match methods: for matching keypoints of one image with other image or of match methods: for matching keypoints of one image with other image or
with image set. with image set. ::
::
class GenericDescriptorMatcher class GenericDescriptorMatcher
{ {
public: public:
GenericDescriptorMatcher(); GenericDescriptorMatcher();
virtual ~GenericDescriptorMatcher(); virtual ~GenericDescriptorMatcher();
virtual void add( const vector<Mat>& images, virtual void add( const vector<Mat>& images,
vector<vector<KeyPoint> >& keypoints ); vector<vector<KeyPoint> >& keypoints );
const vector<Mat>& getTrainImages() const; const vector<Mat>& getTrainImages() const;
const vector<vector<KeyPoint> >& getTrainKeypoints() const; const vector<vector<KeyPoint> >& getTrainKeypoints() const;
virtual void clear(); virtual void clear();
virtual void train() = 0; virtual void train() = 0;
virtual bool isMaskSupported() = 0; virtual bool isMaskSupported() = 0;
void classify( const Mat& queryImage, void classify( const Mat& queryImage,
vector<KeyPoint>& queryKeypoints, vector<KeyPoint>& queryKeypoints,
const Mat& trainImage, const Mat& trainImage,
vector<KeyPoint>& trainKeypoints ) const; vector<KeyPoint>& trainKeypoints ) const;
void classify( const Mat& queryImage, void classify( const Mat& queryImage,
vector<KeyPoint>& queryKeypoints ); vector<KeyPoint>& queryKeypoints );
/* /*
* Group of methods to match keypoints from image pair. * Group of methods to match keypoints from image pair.
*/ */
@ -92,11 +62,11 @@ with image set.
vector<DMatch>& matches, const Mat& mask=Mat() ) const; vector<DMatch>& matches, const Mat& mask=Mat() ) const;
void knnMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints, void knnMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
const Mat& trainImage, vector<KeyPoint>& trainKeypoints, const Mat& trainImage, vector<KeyPoint>& trainKeypoints,
vector<vector<DMatch> >& matches, int k, vector<vector<DMatch> >& matches, int k,
const Mat& mask=Mat(), bool compactResult=false ) const; const Mat& mask=Mat(), bool compactResult=false ) const;
void radiusMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints, void radiusMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
const Mat& trainImage, vector<KeyPoint>& trainKeypoints, const Mat& trainImage, vector<KeyPoint>& trainKeypoints,
vector<vector<DMatch> >& matches, float maxDistance, vector<vector<DMatch> >& matches, float maxDistance,
const Mat& mask=Mat(), bool compactResult=false ) const; const Mat& mask=Mat(), bool compactResult=false ) const;
/* /*
* Group of methods to match keypoints from one image to image set. * Group of methods to match keypoints from one image to image set.
@ -104,364 +74,181 @@ with image set.
void match( const Mat& queryImage, vector<KeyPoint>& queryKeypoints, void match( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>() ); vector<DMatch>& matches, const vector<Mat>& masks=vector<Mat>() );
void knnMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints, void knnMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
vector<vector<DMatch> >& matches, int k, vector<vector<DMatch> >& matches, int k,
const vector<Mat>& masks=vector<Mat>(), bool compactResult=false ); const vector<Mat>& masks=vector<Mat>(), bool compactResult=false );
void radiusMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints, void radiusMatch( const Mat& queryImage, vector<KeyPoint>& queryKeypoints,
vector<vector<DMatch> >& matches, float maxDistance, vector<vector<DMatch> >& matches, float maxDistance,
const vector<Mat>& masks=vector<Mat>(), bool compactResult=false ); const vector<Mat>& masks=vector<Mat>(), bool compactResult=false );
virtual void read( const FileNode& ); virtual void read( const FileNode& );
virtual void write( FileStorage& ) const; virtual void write( FileStorage& ) const;
virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const = 0; virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
protected: protected:
... ...
}; };
.. ..
.. index:: GenericDescriptorMatcher::add .. index:: GenericDescriptorMatcher::add
cv::GenericDescriptorMatcher::add cv::GenericDescriptorMatcher::add
--------------------------------- ---------------------------------
`id=0.507600777855 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Aadd>`__
.. cfunction:: void GenericDescriptorMatcher::add( const vector<Mat>\& images, vector<vector<KeyPoint> >\& keypoints ) .. cfunction:: void GenericDescriptorMatcher::add( const vector<Mat>\& images, vector<vector<KeyPoint> >\& keypoints )
Adds images and keypoints from them to the train collection (descriptors are supposed to be calculated here). Adds images and keypoints from them to the train collection (descriptors are supposed to be calculated here).
If train collection is not empty new image and keypoints from them will be added to If train collection is not empty new image and keypoints from them will be added to
existing data. existing data.
:param images: Image collection.
:param images: Image collection.
:param keypoints: Point collection. Assumes that ``keypoints[i]`` are keypoints :param keypoints: Point collection. Assumes that ``keypoints[i]`` are keypoints
detected in an image ``images[i]`` . detected in an image ``images[i]`` .
.. index:: GenericDescriptorMatcher::getTrainImages .. index:: GenericDescriptorMatcher::getTrainImages
cv::GenericDescriptorMatcher::getTrainImages cv::GenericDescriptorMatcher::getTrainImages
-------------------------------------------- --------------------------------------------
`id=0.520364236881 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3AgetTrainImages>`__
.. cfunction:: const vector<Mat>\& GenericDescriptorMatcher::getTrainImages() const .. cfunction:: const vector<Mat>\& GenericDescriptorMatcher::getTrainImages() const
Returns train image collection. Returns train image collection.
.. index:: GenericDescriptorMatcher::getTrainKeypoints .. index:: GenericDescriptorMatcher::getTrainKeypoints
cv::GenericDescriptorMatcher::getTrainKeypoints cv::GenericDescriptorMatcher::getTrainKeypoints
----------------------------------------------- -----------------------------------------------
`id=0.179197628979 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3AgetTrainKeypoints>`__
.. cfunction:: const vector<vector<KeyPoint> >\& GenericDescriptorMatcher::getTrainKeypoints() const .. cfunction:: const vector<vector<KeyPoint> >\& GenericDescriptorMatcher::getTrainKeypoints() const
Returns train keypoints collection. Returns train keypoints collection.
.. index:: GenericDescriptorMatcher::clear .. index:: GenericDescriptorMatcher::clear
cv::GenericDescriptorMatcher::clear cv::GenericDescriptorMatcher::clear
----------------------------------- -----------------------------------
`id=0.163507435554 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Aclear>`__
.. cfunction:: void GenericDescriptorMatcher::clear() .. cfunction:: void GenericDescriptorMatcher::clear()
Clear train collection (iamges and keypoints). Clear train collection (iamges and keypoints).
.. index:: GenericDescriptorMatcher::train .. index:: GenericDescriptorMatcher::train
cv::GenericDescriptorMatcher::train cv::GenericDescriptorMatcher::train
----------------------------------- -----------------------------------
`id=0.270072381935 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Atrain>`__
.. cfunction:: void GenericDescriptorMatcher::train() .. cfunction:: void GenericDescriptorMatcher::train()
Train the object, e.g. tree-based structure to extract descriptors or Train the object, e.g. tree-based structure to extract descriptors or
to optimize descriptors matching. to optimize descriptors matching.
.. index:: GenericDescriptorMatcher::isMaskSupported .. index:: GenericDescriptorMatcher::isMaskSupported
cv::GenericDescriptorMatcher::isMaskSupported cv::GenericDescriptorMatcher::isMaskSupported
--------------------------------------------- ---------------------------------------------
`id=0.208711469863 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3AisMaskSupported>`__
.. cfunction:: void GenericDescriptorMatcher::isMaskSupported() .. cfunction:: void GenericDescriptorMatcher::isMaskSupported()
Returns true if generic descriptor matcher supports masking permissible matches. Returns true if generic descriptor matcher supports masking permissible matches.
.. index:: GenericDescriptorMatcher::classify .. index:: GenericDescriptorMatcher::classify
cv::GenericDescriptorMatcher::classify cv::GenericDescriptorMatcher::classify
-------------------------------------- --------------------------------------
`id=0.550844968727 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Aclassify>`__
:func:`GenericDescriptorMatcher::add` :func:`GenericDescriptorMatcher::add`
.. cfunction:: void GenericDescriptorMatcher::classify( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints ) const .. cfunction:: void GenericDescriptorMatcher::classify( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints ) const
Classifies query keypoints under keypoints of one train image qiven as input argument Classifies query keypoints under keypoints of one train image qiven as input argument
(first version of the method) or train image collection that set using (second version). (first version of the method) or train image collection that set using (second version).
.. cfunction:: void GenericDescriptorMatcher::classify( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints ) .. cfunction:: void GenericDescriptorMatcher::classify( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints )
:param queryImage: The query image.
:param queryKeypoints: Keypoints from the query image.
:param trainImage: The train image.
:param trainKeypoints: Keypoints from the train image.
:param queryImage: The query image.
:param queryKeypoints: Keypoints from the query image.
:param trainImage: The train image.
:param trainKeypoints: Keypoints from the train image.
.. index:: GenericDescriptorMatcher::match .. index:: GenericDescriptorMatcher::match
cv::GenericDescriptorMatcher::match cv::GenericDescriptorMatcher::match
----------------------------------- -----------------------------------
:func:`GenericDescriptorMatcher::add` :func:`DescriptorMatcher::match`
`id=0.91509902003 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Amatch>`__
:func:`GenericDescriptorMatcher::add`
:func:`DescriptorMatcher::match`
.. cfunction:: void GenericDescriptorMatcher::match( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints, vector<DMatch>\& matches, const Mat\& mask=Mat() ) const .. cfunction:: void GenericDescriptorMatcher::match( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints, vector<DMatch>\& matches, const Mat\& mask=Mat() ) const
Find best match for query keypoints to the training set. In first version of method Find best match for query keypoints to the training set. In first version of method
one train image and keypoints detected on it - are input arguments. In second version one train image and keypoints detected on it - are input arguments. In second version
query keypoints are matched to training collectin that set using . As in the mask can be set. query keypoints are matched to training collectin that set using . As in the mask can be set.
.. cfunction:: void GenericDescriptorMatcher::match( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, vector<DMatch>\& matches, const vector<Mat>\& masks=vector<Mat>() ) .. cfunction:: void GenericDescriptorMatcher::match( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, vector<DMatch>\& matches, const vector<Mat>\& masks=vector<Mat>() )
:param queryImage: Query image.
:param queryKeypoints: Keypoints detected in ``queryImage`` .
:param trainImage: Train image. This will not be added to train image collection
stored in class object.
:param trainKeypoints: Keypoints detected in ``trainImage`` . They will not be added to train points collection
stored in class object.
:param matches: Matches. If some query descriptor (keypoint) masked out in ``mask`` no match will be added for this descriptor.
So ``matches`` size may be less query keypoints count.
:param mask: Mask specifying permissible matches between input query and train keypoints.
:param queryImage: Query image.
:param queryKeypoints: Keypoints detected in ``queryImage`` .
:param trainImage: Train image. This will not be added to train image collection
stored in class object.
:param trainKeypoints: Keypoints detected in ``trainImage`` . They will not be added to train points collection
stored in class object.
:param matches: Matches. If some query descriptor (keypoint) masked out in ``mask``
no match will be added for this descriptor.
So ``matches`` size may be less query keypoints count.
:param mask: Mask specifying permissible matches between input query and train keypoints.
:param masks: The set of masks. Each ``masks[i]`` specifies permissible matches between input query keypoints :param masks: The set of masks. Each ``masks[i]`` specifies permissible matches between input query keypoints
and stored train keypointss from i-th image. and stored train keypointss from i-th image.
.. index:: GenericDescriptorMatcher::knnMatch .. index:: GenericDescriptorMatcher::knnMatch
cv::GenericDescriptorMatcher::knnMatch cv::GenericDescriptorMatcher::knnMatch
-------------------------------------- --------------------------------------
:func:`GenericDescriptorMatcher::match` :func:`DescriptorMatcher::knnMatch`
`id=0.828361496735 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3AknnMatch>`__
:func:`GenericDescriptorMatcher::match`
:func:`DescriptorMatcher::knnMatch`
.. cfunction:: void GenericDescriptorMatcher::knnMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints, vector<vector<DMatch> >\& matches, int k, const Mat\& mask=Mat(), bool compactResult=false ) const .. cfunction:: void GenericDescriptorMatcher::knnMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints, vector<vector<DMatch> >\& matches, int k, const Mat\& mask=Mat(), bool compactResult=false ) const
Find the knn best matches for each keypoint from a query set with train keypoints. Find the knn best matches for each keypoint from a query set with train keypoints.
Found knn (or less if not possible) matches are returned in distance increasing order. Found knn (or less if not possible) matches are returned in distance increasing order.
Details see in and . Details see in and .
.. cfunction:: void GenericDescriptorMatcher::knnMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, vector<vector<DMatch> >\& matches, int k, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false ) .. cfunction:: void GenericDescriptorMatcher::knnMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, vector<vector<DMatch> >\& matches, int k, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false )
.. index:: GenericDescriptorMatcher::radiusMatch .. index:: GenericDescriptorMatcher::radiusMatch
cv::GenericDescriptorMatcher::radiusMatch cv::GenericDescriptorMatcher::radiusMatch
----------------------------------------- -----------------------------------------
:func:`GenericDescriptorMatcher::match` :func:`DescriptorMatcher::radiusMatch`
`id=0.732845229707 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3AradiusMatch>`__
:func:`GenericDescriptorMatcher::match`
:func:`DescriptorMatcher::radiusMatch`
.. cfunction:: void GenericDescriptorMatcher::radiusMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints, vector<vector<DMatch> >\& matches, float maxDistance, const Mat\& mask=Mat(), bool compactResult=false ) const .. cfunction:: void GenericDescriptorMatcher::radiusMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, const Mat\& trainImage, vector<KeyPoint>\& trainKeypoints, vector<vector<DMatch> >\& matches, float maxDistance, const Mat\& mask=Mat(), bool compactResult=false ) const
Find the best matches for each query keypoint which have distance less than given threshold. Find the best matches for each query keypoint which have distance less than given threshold.
Found matches are returned in distance increasing order. Details see in and . Found matches are returned in distance increasing order. Details see in and .
.. cfunction:: void GenericDescriptorMatcher::radiusMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, vector<vector<DMatch> >\& matches, float maxDistance, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false ) .. cfunction:: void GenericDescriptorMatcher::radiusMatch( const Mat\& queryImage, vector<KeyPoint>\& queryKeypoints, vector<vector<DMatch> >\& matches, float maxDistance, const vector<Mat>\& masks=vector<Mat>(), bool compactResult=false )
.. index:: GenericDescriptorMatcher::read .. index:: GenericDescriptorMatcher::read
cv::GenericDescriptorMatcher::read cv::GenericDescriptorMatcher::read
---------------------------------- ----------------------------------
`id=0.937930388921 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Aread>`__
.. cfunction:: void GenericDescriptorMatcher::read( const FileNode\& fn ) .. cfunction:: void GenericDescriptorMatcher::read( const FileNode\& fn )
Reads matcher object from a file node. Reads matcher object from a file node.
.. index:: GenericDescriptorMatcher::write .. index:: GenericDescriptorMatcher::write
cv::GenericDescriptorMatcher::write cv::GenericDescriptorMatcher::write
----------------------------------- -----------------------------------
`id=0.509497773169 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Awrite>`__
.. cfunction:: void GenericDescriptorMatcher::write( FileStorage\& fs ) const .. cfunction:: void GenericDescriptorMatcher::write( FileStorage\& fs ) const
Writes match object to a file storage Writes match object to a file storage
.. index:: GenericDescriptorMatcher::clone .. index:: GenericDescriptorMatcher::clone
cv::GenericDescriptorMatcher::clone cv::GenericDescriptorMatcher::clone
----------------------------------- -----------------------------------
`id=0.864304581549 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/GenericDescriptorMatcher%3A%3Aclone>`__
.. cfunction:: Ptr<GenericDescriptorMatcher>\\GenericDescriptorMatcher::clone( bool emptyTrainData ) const .. cfunction:: Ptr<GenericDescriptorMatcher>\\GenericDescriptorMatcher::clone( bool emptyTrainData ) const
Clone the matcher. Clone the matcher.
:param emptyTrainData: If emptyTrainData is false the method create deep copy of the object, i.e. copies :param emptyTrainData: If emptyTrainData is false the method create deep copy of the object, i.e. copies
both parameters and train data. If emptyTrainData is true the method create object copy with current parameters both parameters and train data. If emptyTrainData is true the method create object copy with current parameters
but with empty train data. but with empty train data.
.. index:: OneWayDescriptorMatcher .. index:: OneWayDescriptorMatcher
@ -469,24 +256,11 @@ cv::GenericDescriptorMatcher::clone
OneWayDescriptorMatcher OneWayDescriptorMatcher
----------------------- -----------------------
`id=0.295296902287 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/OneWayDescriptorMatcher>`__
.. ctype:: OneWayDescriptorMatcher .. ctype:: OneWayDescriptorMatcher
Wrapping class for computing, matching and classification of descriptors using
:func:`OneWayDescriptorBase` class. ::
Wrapping class for computing, matching and classification of descriptors using
:func:`OneWayDescriptorBase`
class.
::
class OneWayDescriptorMatcher : public GenericDescriptorMatcher class OneWayDescriptorMatcher : public GenericDescriptorMatcher
{ {
public: public:
@ -499,71 +273,55 @@ class.
static float GET_MIN_SCALE() { return 0.7f; } static float GET_MIN_SCALE() { return 0.7f; }
static float GET_MAX_SCALE() { return 1.5f; } static float GET_MAX_SCALE() { return 1.5f; }
static float GET_STEP_SCALE() { return 1.2f; } static float GET_STEP_SCALE() { return 1.2f; }
Params( int poseCount = POSE_COUNT, Params( int poseCount = POSE_COUNT,
Size patchSize = Size(PATCH_WIDTH, PATCH_HEIGHT), Size patchSize = Size(PATCH_WIDTH, PATCH_HEIGHT),
string pcaFilename = string(), string pcaFilename = string(),
string trainPath = string(), string trainImagesList = string(), string trainPath = string(), string trainImagesList = string(),
float minScale = GET_MIN_SCALE(), float maxScale = GET_MAX_SCALE(), float minScale = GET_MIN_SCALE(), float maxScale = GET_MAX_SCALE(),
float stepScale = GET_STEP_SCALE() ); float stepScale = GET_STEP_SCALE() );
int poseCount; int poseCount;
Size patchSize; Size patchSize;
string pcaFilename; string pcaFilename;
string trainPath; string trainPath;
string trainImagesList; string trainImagesList;
float minScale, maxScale, stepScale; float minScale, maxScale, stepScale;
}; };
OneWayDescriptorMatcher( const Params& params=Params() ); OneWayDescriptorMatcher( const Params& params=Params() );
virtual ~OneWayDescriptorMatcher(); virtual ~OneWayDescriptorMatcher();
void initialize( const Params& params, const Ptr<OneWayDescriptorBase>& base=Ptr<OneWayDescriptorBase>() ); void initialize( const Params& params, const Ptr<OneWayDescriptorBase>& base=Ptr<OneWayDescriptorBase>() );
// Clears keypoints storing in collection and OneWayDescriptorBase // Clears keypoints storing in collection and OneWayDescriptorBase
virtual void clear(); virtual void clear();
virtual void train(); virtual void train();
virtual bool isMaskSupported(); virtual bool isMaskSupported();
virtual void read( const FileNode &fn ); virtual void read( const FileNode &fn );
virtual void write( FileStorage& fs ) const; virtual void write( FileStorage& fs ) const;
virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const; virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected: protected:
... ...
}; };
.. ..
.. index:: FernDescriptorMatcher .. index:: FernDescriptorMatcher
.. _FernDescriptorMatcher: .. _FernDescriptorMatcher:
FernDescriptorMatcher FernDescriptorMatcher
--------------------- ---------------------
`id=0.410971973421 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/FernDescriptorMatcher>`__
.. ctype:: FernDescriptorMatcher .. ctype:: FernDescriptorMatcher
Wrapping class for computing, matching and classification of descriptors using
:func:`FernClassifier` class. ::
Wrapping class for computing, matching and classification of descriptors using
:func:`FernClassifier`
class.
::
class FernDescriptorMatcher : public GenericDescriptorMatcher class FernDescriptorMatcher : public GenericDescriptorMatcher
{ {
public: public:
@ -578,9 +336,9 @@ class.
int nviews=FernClassifier::DEFAULT_VIEWS, int nviews=FernClassifier::DEFAULT_VIEWS,
int compressionMethod=FernClassifier::COMPRESSION_NONE, int compressionMethod=FernClassifier::COMPRESSION_NONE,
const PatchGenerator& patchGenerator=PatchGenerator() ); const PatchGenerator& patchGenerator=PatchGenerator() );
Params( const string& filename ); Params( const string& filename );
int nclasses; int nclasses;
int patchSize; int patchSize;
int signatureSize; int signatureSize;
@ -589,89 +347,64 @@ class.
int nviews; int nviews;
int compressionMethod; int compressionMethod;
PatchGenerator patchGenerator; PatchGenerator patchGenerator;
string filename; string filename;
}; };
FernDescriptorMatcher( const Params& params=Params() ); FernDescriptorMatcher( const Params& params=Params() );
virtual ~FernDescriptorMatcher(); virtual ~FernDescriptorMatcher();
virtual void clear(); virtual void clear();
virtual void train(); virtual void train();
virtual bool isMaskSupported(); virtual bool isMaskSupported();
virtual void read( const FileNode &fn ); virtual void read( const FileNode &fn );
virtual void write( FileStorage& fs ) const; virtual void write( FileStorage& fs ) const;
virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const; virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected: protected:
... ...
}; };
.. ..
.. index:: VectorDescriptorMatcher .. index:: VectorDescriptorMatcher
.. _VectorDescriptorMatcher: .. _VectorDescriptorMatcher:
VectorDescriptorMatcher VectorDescriptorMatcher
----------------------- -----------------------
`id=0.89575693039 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/VectorDescriptorMatcher>`__
.. ctype:: VectorDescriptorMatcher .. ctype:: VectorDescriptorMatcher
Class used for matching descriptors that can be described as vectors in a finite-dimensional space. ::
Class used for matching descriptors that can be described as vectors in a finite-dimensional space.
::
class CV_EXPORTS VectorDescriptorMatcher : public GenericDescriptorMatcher class CV_EXPORTS VectorDescriptorMatcher : public GenericDescriptorMatcher
{ {
public: public:
VectorDescriptorMatcher( const Ptr<DescriptorExtractor>& extractor, const Ptr<DescriptorMatcher>& matcher ); VectorDescriptorMatcher( const Ptr<DescriptorExtractor>& extractor, const Ptr<DescriptorMatcher>& matcher );
virtual ~VectorDescriptorMatcher(); virtual ~VectorDescriptorMatcher();
virtual void add( const vector<Mat>& imgCollection, virtual void add( const vector<Mat>& imgCollection,
vector<vector<KeyPoint> >& pointCollection ); vector<vector<KeyPoint> >& pointCollection );
virtual void clear(); virtual void clear();
virtual void train(); virtual void train();
virtual bool isMaskSupported(); virtual bool isMaskSupported();
virtual void read( const FileNode& fn ); virtual void read( const FileNode& fn );
virtual void write( FileStorage& fs ) const; virtual void write( FileStorage& fs ) const;
virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const; virtual Ptr<GenericDescriptorMatcher> clone( bool emptyTrainData=false ) const;
protected: protected:
... ...
}; };
.. ..
Example of creating: Example of creating: ::
VectorDescriptorMatcher matcher( new SurfDescriptorExtractor,
::
VectorDescriptorMatcher matcher( new SurfDescriptorExtractor,
new BruteForceMatcher<L2<float> > ); new BruteForceMatcher<L2<float> > );
.. ..

125
modules/features2d/doc/drawing_function_of_keypoints_and_matches.rst
View File

@ -3,138 +3,81 @@ Drawing Function of Keypoints and Matches
.. highlight:: cpp .. highlight:: cpp
.. index:: drawMatches .. index:: drawMatches
cv::drawMatches cv::drawMatches
--------------- ---------------
`id=0.919261687295 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/drawMatches>`__
.. cfunction:: void drawMatches( const Mat\& img1, const vector<KeyPoint>\& keypoints1, const Mat\& img2, const vector<KeyPoint>\& keypoints2, const vector<DMatch>\& matches1to2, Mat\& outImg, const Scalar\& matchColor=Scalar::all(-1), const Scalar\& singlePointColor=Scalar::all(-1), const vector<char>\& matchesMask=vector<char>(), int flags=DrawMatchesFlags::DEFAULT ) .. cfunction:: void drawMatches( const Mat\& img1, const vector<KeyPoint>\& keypoints1, const Mat\& img2, const vector<KeyPoint>\& keypoints2, const vector<DMatch>\& matches1to2, Mat\& outImg, const Scalar\& matchColor=Scalar::all(-1), const Scalar\& singlePointColor=Scalar::all(-1), const vector<char>\& matchesMask=vector<char>(), int flags=DrawMatchesFlags::DEFAULT )
This function draws matches of keypints from two images on output image. This function draws matches of keypints from two images on output image.
Match is a line connecting two keypoints (circles). Match is a line connecting two keypoints (circles).
.. cfunction:: void drawMatches( const Mat\& img1, const vector<KeyPoint>\& keypoints1, const Mat\& img2, const vector<KeyPoint>\& keypoints2, const vector<vector<DMatch> >\& matches1to2, Mat\& outImg, const Scalar\& matchColor=Scalar::all(-1), const Scalar\& singlePointColor=Scalar::all(-1), const vector<vector<char>>\& matchesMask= vector<vector<char> >(), int flags=DrawMatchesFlags::DEFAULT ) .. cfunction:: void drawMatches( const Mat\& img1, const vector<KeyPoint>\& keypoints1, const Mat\& img2, const vector<KeyPoint>\& keypoints2, const vector<vector<DMatch> >\& matches1to2, Mat\& outImg, const Scalar\& matchColor=Scalar::all(-1), const Scalar\& singlePointColor=Scalar::all(-1), const vector<vector<char>>\& matchesMask= vector<vector<char> >(), int flags=DrawMatchesFlags::DEFAULT )
:param img1: First source image.
:param keypoints1: Keypoints from first source image.
:param img2: Second source image.
:param keypoints2: Keypoints from second source image.
:param matches: Matches from first image to second one, i.e. ``keypoints1[i]`` has corresponding point ``keypoints2[matches[i]]`` .
:param img1: First source image.
:param keypoints1: Keypoints from first source image.
:param img2: Second source image.
:param keypoints2: Keypoints from second source image.
:param matches: Matches from first image to second one, i.e. ``keypoints1[i]``
has corresponding point ``keypoints2[matches[i]]`` .
:param outImg: Output image. Its content depends on ``flags`` value
what is drawn in output image. See below possible ``flags`` bit values.
:param matchColor: Color of matches (lines and connected keypoints).
If ``matchColor==Scalar::all(-1)`` color will be generated randomly.
:param singlePointColor: Color of single keypoints (circles), i.e. keypoints not having the matches.
If ``singlePointColor==Scalar::all(-1)`` color will be generated randomly.
:param matchesMask: Mask determining which matches will be drawn. If mask is empty all matches will be drawn.
:param flags: Each bit of ``flags`` sets some feature of drawing.
Possible ``flags`` bit values is defined by ``DrawMatchesFlags`` , see below.
:param outImg: Output image. Its content depends on ``flags`` value
what is drawn in output image. See below possible ``flags`` bit values.
:param matchColor: Color of matches (lines and connected keypoints).
If ``matchColor==Scalar::all(-1)`` color will be generated randomly.
:: :param singlePointColor: Color of single keypoints (circles), i.e. keypoints not having the matches.
If ``singlePointColor==Scalar::all(-1)`` color will be generated randomly.
:param matchesMask: Mask determining which matches will be drawn. If mask is empty all matches will be drawn.
:param flags: Each bit of ``flags`` sets some feature of drawing.
Possible ``flags`` bit values is defined by ``DrawMatchesFlags`` , see below. ::
struct DrawMatchesFlags struct DrawMatchesFlags
{ {
enum{ DEFAULT = 0, // Output image matrix will be created (Mat::create), enum{ DEFAULT = 0, // Output image matrix will be created (Mat::create),
// i.e. existing memory of output image may be reused. // i.e. existing memory of output image may be reused.
// Two source image, matches and single keypoints // Two source image, matches and single keypoints
// will be drawn. // will be drawn.
// For each keypoint only the center point will be // For each keypoint only the center point will be
// drawn (without the circle around keypoint with // drawn (without the circle around keypoint with
// keypoint size and orientation). // keypoint size and orientation).
DRAW_OVER_OUTIMG = 1, // Output image matrix will not be DRAW_OVER_OUTIMG = 1, // Output image matrix will not be
// created (Mat::create). Matches will be drawn // created (Mat::create). Matches will be drawn
// on existing content of output image. // on existing content of output image.
NOT_DRAW_SINGLE_POINTS = 2, // Single keypoints will not be drawn. NOT_DRAW_SINGLE_POINTS = 2, // Single keypoints will not be drawn.
DRAW_RICH_KEYPOINTS = 4 // For each keypoint the circle around DRAW_RICH_KEYPOINTS = 4 // For each keypoint the circle around
// keypoint with keypoint size and orientation will // keypoint with keypoint size and orientation will
// be drawn. // be drawn.
}; };
}; };
.. ..
.. index:: drawKeypoints .. index:: drawKeypoints
cv::drawKeypoints cv::drawKeypoints
----------------- -----------------
`id=0.694314481427 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/drawKeypoints>`__
.. cfunction:: void drawKeypoints( const Mat\& image, const vector<KeyPoint>\& keypoints, Mat\& outImg, const Scalar\& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT ) .. cfunction:: void drawKeypoints( const Mat\& image, const vector<KeyPoint>\& keypoints, Mat\& outImg, const Scalar\& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT )
Draw keypoints. Draw keypoints.
:param image: Source image.
:param keypoints: Keypoints from source image.
:param outImg: Output image. Its content depends on ``flags`` value
what is drawn in output image. See possible ``flags`` bit values.
:param color: Color of keypoints
.
:param flags: Each bit of ``flags`` sets some feature of drawing.
Possible ``flags`` bit values is defined by ``DrawMatchesFlags`` ,
see above in :func:`drawMatches` .
:param image: Source image.
:param keypoints: Keypoints from source image.
:param outImg: Output image. Its content depends on ``flags`` value
what is drawn in output image. See possible ``flags`` bit values.
:param color: Color of keypoints
.
:param flags: Each bit of ``flags`` sets some feature of drawing.
Possible ``flags`` bit values is defined by ``DrawMatchesFlags`` ,
see above in :func:`drawMatches` .

538
modules/features2d/doc/feature_detection_and_description.rst
View File

File diff suppressed because it is too large Load Diff

6
modules/features2d/doc/features2d.rst
View File

@ -1,6 +1,6 @@
********************* *********************************
2D Features Framework features2d. 2D Features Framework
********************* *********************************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

273
modules/features2d/doc/object_categorization.rst
View File

@ -3,155 +3,81 @@ Object Categorization
.. highlight:: cpp .. highlight:: cpp
Some approaches based on local 2D features and used to object categorization
Some approaches based on local 2D features and used to object categorization
are described in this section. are described in this section.
.. index:: BOWTrainer .. index:: BOWTrainer
.. _BOWTrainer: .. _BOWTrainer:
BOWTrainer BOWTrainer
---------- ----------
`id=0.926370937775 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWTrainer>`__
.. ctype:: BOWTrainer .. ctype:: BOWTrainer
Abstract base class for training ''bag of visual words'' vocabulary from a set of descriptors.
See e.g. ''Visual Categorization with Bags of Keypoints'' of Gabriella Csurka, Christopher R. Dance,
Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. ::
Abstract base class for training ''bag of visual words'' vocabulary from a set of descriptors.
See e.g. ''Visual Categorization with Bags of Keypoints'' of Gabriella Csurka, Christopher R. Dance,
Lixin Fan, Jutta Willamowski, Cedric Bray, 2004.
::
class BOWTrainer class BOWTrainer
{ {
public: public:
BOWTrainer(){} BOWTrainer(){}
virtual ~BOWTrainer(){} virtual ~BOWTrainer(){}
void add( const Mat& descriptors ); void add( const Mat& descriptors );
const vector<Mat>& getDescriptors() const; const vector<Mat>& getDescriptors() const;
int descripotorsCount() const; int descripotorsCount() const;
virtual void clear(); virtual void clear();
virtual Mat cluster() const = 0; virtual Mat cluster() const = 0;
virtual Mat cluster( const Mat& descriptors ) const = 0; virtual Mat cluster( const Mat& descriptors ) const = 0;
protected: protected:
... ...
}; };
.. ..
.. index:: BOWTrainer::add .. index:: BOWTrainer::add
cv::BOWTrainer::add cv::BOWTrainer::add
------------------- ------------------- ````
`id=0.849162389183 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWTrainer%3A%3Aadd>`__
````
.. cfunction:: void BOWTrainer::add( const Mat\& descriptors ) .. cfunction:: void BOWTrainer::add( const Mat\& descriptors )
Add descriptors to training set. The training set will be clustered using clustermethod to construct vocabulary. Add descriptors to training set. The training set will be clustered using clustermethod to construct vocabulary.
:param descriptors: Descriptors to add to training set. Each row of ``descriptors`` matrix is a one descriptor.
:param descriptors: Descriptors to add to training set. Each row of ``descriptors``
matrix is a one descriptor.
.. index:: BOWTrainer::getDescriptors .. index:: BOWTrainer::getDescriptors
cv::BOWTrainer::getDescriptors cv::BOWTrainer::getDescriptors
------------------------------ ------------------------------
`id=0.999824242082 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWTrainer%3A%3AgetDescriptors>`__
.. cfunction:: const vector<Mat>\& BOWTrainer::getDescriptors() const .. cfunction:: const vector<Mat>\& BOWTrainer::getDescriptors() const
Returns training set of descriptors. Returns training set of descriptors.
.. index:: BOWTrainer::descripotorsCount .. index:: BOWTrainer::descripotorsCount
cv::BOWTrainer::descripotorsCount cv::BOWTrainer::descripotorsCount
--------------------------------- ---------------------------------
`id=0.497913292449 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWTrainer%3A%3AdescripotorsCount>`__
.. cfunction:: const vector<Mat>\& BOWTrainer::descripotorsCount() const .. cfunction:: const vector<Mat>\& BOWTrainer::descripotorsCount() const
Returns count of all descriptors stored in the training set. Returns count of all descriptors stored in the training set.
.. index:: BOWTrainer::cluster .. index:: BOWTrainer::cluster
cv::BOWTrainer::cluster cv::BOWTrainer::cluster
----------------------- -----------------------
`id=0.560094315089 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWTrainer%3A%3Acluster>`__
.. cfunction:: Mat BOWTrainer::cluster() const .. cfunction:: Mat BOWTrainer::cluster() const
Cluster train descriptors. Vocabulary consists from cluster centers. So this method Cluster train descriptors. Vocabulary consists from cluster centers. So this method
returns vocabulary. In first method variant the stored in object train descriptors will be returns vocabulary. In first method variant the stored in object train descriptors will be
clustered, in second variant -- input descriptors will be clustered. clustered, in second variant -- input descriptors will be clustered.
.. cfunction:: Mat BOWTrainer::cluster( const Mat\& descriptors ) const .. cfunction:: Mat BOWTrainer::cluster( const Mat\& descriptors ) const
:param descriptors: Descriptors to cluster. Each row of ``descriptors`` matrix is a one descriptor. Descriptors will not be added
to the inner train descriptor set.
:param descriptors: Descriptors to cluster. Each row of ``descriptors``
matrix is a one descriptor. Descriptors will not be added
to the inner train descriptor set.
.. index:: BOWKMeansTrainer .. index:: BOWKMeansTrainer
@ -159,250 +85,133 @@ clustered, in second variant -- input descriptors will be clustered.
BOWKMeansTrainer BOWKMeansTrainer
---------------- ----------------
`id=0.588500098443 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWKMeansTrainer>`__
.. ctype:: BOWKMeansTrainer .. ctype:: BOWKMeansTrainer
:func:`kmeans` based class to train visual vocabulary using the ''bag of visual words'' approach. ::
:func:`kmeans`
based class to train visual vocabulary using the ''bag of visual words'' approach.
::
class BOWKMeansTrainer : public BOWTrainer class BOWKMeansTrainer : public BOWTrainer
{ {
public: public:
BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(), BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
int attempts=3, int flags=KMEANS_PP_CENTERS ); int attempts=3, int flags=KMEANS_PP_CENTERS );
virtual ~BOWKMeansTrainer(){} virtual ~BOWKMeansTrainer(){}
// Returns trained vocabulary (i.e. cluster centers). // Returns trained vocabulary (i.e. cluster centers).
virtual Mat cluster() const; virtual Mat cluster() const;
virtual Mat cluster( const Mat& descriptors ) const; virtual Mat cluster( const Mat& descriptors ) const;
protected: protected:
... ...
}; };
.. ..
To gain an understanding of constructor parameters see To gain an understanding of constructor parameters see
:func:`kmeans` :func:`kmeans` function
function
arguments. arguments.
.. index:: BOWImgDescriptorExtractor .. index:: BOWImgDescriptorExtractor
.. _BOWImgDescriptorExtractor: .. _BOWImgDescriptorExtractor:
BOWImgDescriptorExtractor BOWImgDescriptorExtractor
------------------------- -------------------------
`id=0.166378792557 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor>`__
.. ctype:: BOWImgDescriptorExtractor .. ctype:: BOWImgDescriptorExtractor
Class to compute image descriptor using ''bad of visual words''. In few,
such computing consists from the following steps:
Class to compute image descriptor using ''bad of visual words''. In few, 1. Compute descriptors for given image and it's keypoints set,
such computing consists from the following steps:
1. Compute descriptors for given image and it's keypoints set,
\ \
2. Find nearest visual words from vocabulary for each keypoint descriptor, 2. Find nearest visual words from vocabulary for each keypoint descriptor,
\ \
3. Image descriptor is a normalized histogram of vocabulary words encountered in the image. I.e. 3. Image descriptor is a normalized histogram of vocabulary words encountered in the image. I.e.
``i`` -bin of the histogram is a frequency of ``i`` -word of vocabulary in the given image. ::
``i``
-bin of the histogram is a frequency of
``i``
-word of vocabulary in the given image.
::
class BOWImgDescriptorExtractor class BOWImgDescriptorExtractor
{ {
public: public:
BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor, BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
const Ptr<DescriptorMatcher>& dmatcher ); const Ptr<DescriptorMatcher>& dmatcher );
virtual ~BOWImgDescriptorExtractor(){} virtual ~BOWImgDescriptorExtractor(){}
void setVocabulary( const Mat& vocabulary ); void setVocabulary( const Mat& vocabulary );
const Mat& getVocabulary() const; const Mat& getVocabulary() const;
void compute( const Mat& image, vector<KeyPoint>& keypoints, void compute( const Mat& image, vector<KeyPoint>& keypoints,
Mat& imgDescriptor, Mat& imgDescriptor,
vector<vector<int> >* pointIdxsOfClusters=0, vector<vector<int> >* pointIdxsOfClusters=0,
Mat* descriptors=0 ); Mat* descriptors=0 );
int descriptorSize() const; int descriptorSize() const;
int descriptorType() const; int descriptorType() const;
protected: protected:
... ...
}; };
.. ..
.. index:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor .. index:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor
cv::BOWImgDescriptorExtractor::BOWImgDescriptorExtractor cv::BOWImgDescriptorExtractor::BOWImgDescriptorExtractor
-------------------------------------------------------- --------------------------------------------------------
`id=0.355574799377 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor%3A%3ABOWImgDescriptorExtractor>`__
.. cfunction:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>\& dextractor, const Ptr<DescriptorMatcher>\& dmatcher ) .. cfunction:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>\& dextractor, const Ptr<DescriptorMatcher>\& dmatcher )
Constructor. Constructor.
:param dextractor: Descriptor extractor that will be used to compute descriptors
for input image and it's keypoints.
:param dextractor: Descriptor extractor that will be used to compute descriptors
for input image and it's keypoints.
:param dmatcher: Descriptor matcher that will be used to find nearest word of trained vocabulary to :param dmatcher: Descriptor matcher that will be used to find nearest word of trained vocabulary to
each keupoints descriptor of the image. each keupoints descriptor of the image.
.. index:: BOWImgDescriptorExtractor::setVocabulary .. index:: BOWImgDescriptorExtractor::setVocabulary
cv::BOWImgDescriptorExtractor::setVocabulary cv::BOWImgDescriptorExtractor::setVocabulary
-------------------------------------------- --------------------------------------------
`id=0.592484692408 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor%3A%3AsetVocabulary>`__
.. cfunction:: void BOWImgDescriptorExtractor::setVocabulary( const Mat\& vocabulary ) .. cfunction:: void BOWImgDescriptorExtractor::setVocabulary( const Mat\& vocabulary )
Method to set visual vocabulary. Method to set visual vocabulary.
:param vocabulary: Vocabulary (can be trained using inheritor of :func:`BOWTrainer` ).
Each row of vocabulary is a one visual word (cluster center).
:param vocabulary: Vocabulary (can be trained using inheritor of :func:`BOWTrainer` ).
Each row of vocabulary is a one visual word (cluster center).
.. index:: BOWImgDescriptorExtractor::getVocabulary .. index:: BOWImgDescriptorExtractor::getVocabulary
cv::BOWImgDescriptorExtractor::getVocabulary cv::BOWImgDescriptorExtractor::getVocabulary
-------------------------------------------- --------------------------------------------
`id=0.0185667539631 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor%3A%3AgetVocabulary>`__
.. cfunction:: const Mat\& BOWImgDescriptorExtractor::getVocabulary() const .. cfunction:: const Mat\& BOWImgDescriptorExtractor::getVocabulary() const
Returns set vocabulary. Returns set vocabulary.
.. index:: BOWImgDescriptorExtractor::compute .. index:: BOWImgDescriptorExtractor::compute
cv::BOWImgDescriptorExtractor::compute cv::BOWImgDescriptorExtractor::compute
-------------------------------------- --------------------------------------
`id=0.558308680471 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor%3A%3Acompute>`__
.. cfunction:: void BOWImgDescriptorExtractor::compute( const Mat\& image, vector<KeyPoint>\& keypoints, Mat\& imgDescriptor, vector<vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 ) .. cfunction:: void BOWImgDescriptorExtractor::compute( const Mat\& image, vector<KeyPoint>\& keypoints, Mat\& imgDescriptor, vector<vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 )
Compute image descriptor using set visual vocabulary. Compute image descriptor using set visual vocabulary.
:param image: The image. Image descriptor will be computed for this.
:param keypoints: Keypoints detected in the input image.
:param imgDescriptor: This is output, i.e. computed image descriptor.
:param pointIdxsOfClusters: Indices of keypoints which belong to the cluster, i.e. ``pointIdxsOfClusters[i]`` is keypoint indices which belong
to the ``i-`` cluster (word of vocabulary) (returned if it is not 0.)
:param descriptors: Descriptors of the image keypoints (returned if it is not 0.)
:param image: The image. Image descriptor will be computed for this.
:param keypoints: Keypoints detected in the input image.
:param imgDescriptor: This is output, i.e. computed image descriptor.
:param pointIdxsOfClusters: Indices of keypoints which belong to the cluster, i.e.
``pointIdxsOfClusters[i]`` is keypoint indices which belong
to the ``i-`` cluster (word of vocabulary) (returned if it is not 0.)
:param descriptors: Descriptors of the image keypoints (returned if it is not 0.)
.. index:: BOWImgDescriptorExtractor::descriptorSize .. index:: BOWImgDescriptorExtractor::descriptorSize
cv::BOWImgDescriptorExtractor::descriptorSize cv::BOWImgDescriptorExtractor::descriptorSize
--------------------------------------------- ---------------------------------------------
`id=0.758326749957 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor%3A%3AdescriptorSize>`__
.. cfunction:: int BOWImgDescriptorExtractor::descriptorSize() const .. cfunction:: int BOWImgDescriptorExtractor::descriptorSize() const
Returns image discriptor size, if vocabulary was set, and 0 otherwise. Returns image discriptor size, if vocabulary was set, and 0 otherwise.
.. index:: BOWImgDescriptorExtractor::descriptorType .. index:: BOWImgDescriptorExtractor::descriptorType
cv::BOWImgDescriptorExtractor::descriptorType cv::BOWImgDescriptorExtractor::descriptorType
--------------------------------------------- ---------------------------------------------
`id=0.940227909801 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/features2d/BOWImgDescriptorExtractor%3A%3AdescriptorType>`__
.. cfunction:: int BOWImgDescriptorExtractor::descriptorType() const .. cfunction:: int BOWImgDescriptorExtractor::descriptorType() const
Returns image descriptor type. Returns image descriptor type.

681
modules/gpu/doc/camera_calibration_and_3d_reconstruction.rst
View File

File diff suppressed because it is too large Load Diff

566
modules/gpu/doc/data_structures.rst
View File

@ -3,360 +3,217 @@ Data Structures
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::DevMem2D_ .. index:: gpu::DevMem2D_
.. _gpu::DevMem2D_: .. _gpu::DevMem2D_:
gpu::DevMem2D_ gpu::DevMem2D_
-------------- --------------
`id=0.542572017346 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADevMem2D_>`__
.. ctype:: gpu::DevMem2D_ .. ctype:: gpu::DevMem2D_
This is a simple lightweight class that encapsulate pitched memory on GPU. It is intended to pass to nvcc-compiled code, i.e. CUDA kernels. So it is used internally by OpenCV and by users writes own device code. Its members can be called both from host and from device code. ::
template <typename T> struct DevMem2D_
{
int cols;
int rows;
T* data;
size_t step;
This is a simple lightweight class that encapsulate pitched memory on GPU. It is intended to pass to nvcc-compiled code, i.e. CUDA kernels. So it is used internally by OpenCV and by users writes own device code. Its members can be called both from host and from device code. DevMem2D_() : cols(0), rows(0), data(0), step(0){};
DevMem2D_(int rows_, int cols_, T *data_, size_t step_);
template <typename U>
explicit DevMem2D_(const DevMem2D_<U>& d);
typedef T elem_type;
enum { elem_size = sizeof(elem_type) };
:: __CV_GPU_HOST_DEVICE__ size_t elemSize() const;
template <typename T> struct DevMem2D_
{
int cols;
int rows;
T* data;
size_t step;
DevMem2D_() : cols(0), rows(0), data(0), step(0){};
DevMem2D_(int rows_, int cols_, T *data_, size_t step_);
template <typename U>
explicit DevMem2D_(const DevMem2D_<U>& d);
typedef T elem_type;
enum { elem_size = sizeof(elem_type) };
__CV_GPU_HOST_DEVICE__ size_t elemSize() const;
/* returns pointer to the beggining of given image row */
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
/* returns pointer to the beggining of given image row */
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
.. ..
.. index:: gpu::PtrStep_ .. index:: gpu::PtrStep_
.. _gpu::PtrStep_: .. _gpu::PtrStep_:
gpu::PtrStep_ gpu::PtrStep_
------------- -------------
`id=0.130599760293 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3APtrStep_>`__
.. ctype:: gpu::PtrStep_ .. ctype:: gpu::PtrStep_
This is structure is similar to DevMem2D_but contains only pointer and row step. Width and height fields are excluded due to performance reasons. The structure is for internal use or for users who write own device code. ::
template<typename T> struct PtrStep_
{
T* data;
size_t step;
This is structure is similar to DevMem2D PtrStep_();
_ PtrStep_(const DevMem2D_<T>& mem);
but contains only pointer and row step. Width and height fields are excluded due to performance reasons. The structure is for internal use or for users who write own device code.
typedef T elem_type;
enum { elem_size = sizeof(elem_type) };
__CV_GPU_HOST_DEVICE__ size_t elemSize() const;
:: __CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
template<typename T> struct PtrStep_
{
T* data;
size_t step;
PtrStep_();
PtrStep_(const DevMem2D_<T>& mem);
typedef T elem_type;
enum { elem_size = sizeof(elem_type) };
__CV_GPU_HOST_DEVICE__ size_t elemSize() const;
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
.. ..
.. index:: gpu::PtrElemStrp_ .. index:: gpu::PtrElemStrp_
.. _gpu::PtrElemStrp_: .. _gpu::PtrElemStrp_:
gpu::PtrElemStrp_ gpu::PtrElemStrp_
----------------- -----------------
`id=0.837109179392 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3APtrElemStrp_>`__
.. ctype:: gpu::PtrElemStrp_ .. ctype:: gpu::PtrElemStrp_
This is structure is similar to DevMem2D_but contains only pointer and row step in elements. Width and height fields are excluded due to performance reasons. This class is can only be constructed if sizeof(T) is a multiple of 256. The structure is for internal use or for users who write own device code. ::
template<typename T> struct PtrElemStep_ : public PtrStep_<T>
This is structure is similar to DevMem2D {
_ PtrElemStep_(const DevMem2D_<T>& mem);
but contains only pointer and row step in elements. Width and height fields are excluded due to performance reasons. This class is can only be constructed if sizeof(T) is a multiple of 256. The structure is for internal use or for users who write own device code. __CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
::
template<typename T> struct PtrElemStep_ : public PtrStep_<T>
{
PtrElemStep_(const DevMem2D_<T>& mem);
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0);
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const;
};
.. ..
.. index:: gpu::GpuMat .. index:: gpu::GpuMat
.. _gpu::GpuMat: .. _gpu::GpuMat:
gpu::GpuMat gpu::GpuMat
----------- -----------
`id=0.816128758115 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AGpuMat>`__
.. ctype:: gpu::GpuMat .. ctype:: gpu::GpuMat
The base storage class for GPU memory with reference counting. Its interface is almost
:func:`Mat` interface with some limitations, so using it won't be a problem. The limitations are no arbitrary dimensions support (only 2D), no functions that returns references to its data (because references on GPU are not valid for CPU), no expression templates technique support. Because of last limitation please take care with overloaded matrix operators - they cause memory allocations. The GpuMat class is convertible to
and
so it can be passed to directly to kernel.
The base storage class for GPU memory with reference counting. Its interface is almost
:func:`Mat`
interface with some limitations, so using it won't be a problem. The limitations are no arbitrary dimensions support (only 2D), no functions that returns references to its data (because references on GPU are not valid for CPU), no expression templates technique support. Because of last limitation please take care with overloaded matrix operators - they cause memory allocations. The GpuMat class is convertible to
and
so it can be passed to directly to kernel.
**Please note:** **Please note:**
In contrast with In contrast with
:func:`Mat` :func:`Mat` , In most cases ``GpuMat::isContinuous() == false`` , i.e. rows are aligned to size depending on hardware. Also single row GpuMat is always a continuous matrix. ::
, In most cases
``GpuMat::isContinuous() == false``
, i.e. rows are aligned to size depending on hardware. Also single row GpuMat is always a continuous matrix.
class CV_EXPORTS GpuMat
{
public:
//! default constructor
GpuMat();
GpuMat(int rows, int cols, int type);
GpuMat(Size size, int type);
:: .....
//! builds GpuMat from Mat. Perfom blocking upload to device.
explicit GpuMat (const Mat& m);
//! returns lightweight DevMem2D_ structure for passing
class CV_EXPORTS GpuMat //to nvcc-compiled code. Contains size, data ptr and step.
{ template <class T> operator DevMem2D_<T>() const;
public: template <class T> operator PtrStep_<T>() const;
//! default constructor
GpuMat();
GpuMat(int rows, int cols, int type);
GpuMat(Size size, int type);
.....
//! builds GpuMat from Mat. Perfom blocking upload to device.
explicit GpuMat (const Mat& m);
//! returns lightweight DevMem2D_ structure for passing
//to nvcc-compiled code. Contains size, data ptr and step.
template <class T> operator DevMem2D_<T>() const;
template <class T> operator PtrStep_<T>() const;
//! pefroms blocking upload data to GpuMat.
void upload(const cv::Mat& m);
void upload(const CudaMem& m, Stream& stream);
//! downloads data from device to host memory. Blocking calls.
operator Mat() const;
void download(cv::Mat& m) const;
//! download async
void download(CudaMem& m, Stream& stream) const;
};
//! pefroms blocking upload data to GpuMat.
void upload(const cv::Mat& m);
void upload(const CudaMem& m, Stream& stream);
//! downloads data from device to host memory. Blocking calls.
operator Mat() const;
void download(cv::Mat& m) const;
//! download async
void download(CudaMem& m, Stream& stream) const;
};
.. ..
**Please note:** **Please note:**
Is it a bad practice to leave static or global GpuMat variables allocated, i.e. to rely on its destructor. That is because destruction order of such variables and CUDA context is undefined and GPU memory release function returns error if CUDA context has been destroyed before. Is it a bad practice to leave static or global GpuMat variables allocated, i.e. to rely on its destructor. That is because destruction order of such variables and CUDA context is undefined and GPU memory release function returns error if CUDA context has been destroyed before.
See also:
:func:`Mat`
See also:
:func:`Mat`
.. index:: gpu::CudaMem .. index:: gpu::CudaMem
.. _gpu::CudaMem: .. _gpu::CudaMem:
gpu::CudaMem gpu::CudaMem
------------ ------------
`id=0.762477139905 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ACudaMem>`__
.. ctype:: gpu::CudaMem .. ctype:: gpu::CudaMem
This is a class with reference counting that wraps special memory type allocation functions from CUDA. Its interface is also
:func:`Mat` -like but with additional memory type parameter:
* ``ALLOC_PAGE_LOCKED`` Set page locked memory type, used commonly for fast and asynchronous upload/download data from/to GPU.
This is a class with reference counting that wraps special memory type allocation functions from CUDA. Its interface is also * ``ALLOC_ZEROCOPY`` Specifies zero copy memory allocation, i.e. with possibility to map host memory to GPU address space if supported.
:func:`Mat`
-like but with additional memory type parameter:
* ``ALLOC_WRITE_COMBINED`` Sets write combined buffer which is not cached by CPU. Such buffers are used to supply GPU with data when GPU only reads it. The advantage is better CPU cache utilization.
Please note that allocation size of such memory types is usually limited. For more details please see "CUDA 2.2 Pinned Memory APIs" document or "CUDA_C Programming Guide". ::
* class CV_EXPORTS CudaMem
``ALLOC_PAGE_LOCKED`` {
Set page locked memory type, used commonly for fast and asynchronous upload/download data from/to GPU. public:
enum { ALLOC_PAGE_LOCKED = 1, ALLOC_ZEROCOPY = 2,
ALLOC_WRITE_COMBINED = 4 };
* CudaMem(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
``ALLOC_ZEROCOPY``
Specifies zero copy memory allocation, i.e. with possibility to map host memory to GPU address space if supported.
* //! creates from cv::Mat with coping data
``ALLOC_WRITE_COMBINED`` explicit CudaMem(const Mat& m, int alloc_type = ALLOC_PAGE_LOCKED);
Sets write combined buffer which is not cached by CPU. Such buffers are used to supply GPU with data when GPU only reads it. The advantage is better CPU cache utilization.
Please note that allocation size of such memory types is usually limited. For more details please see "CUDA 2.2 Pinned Memory APIs" document or "CUDA
_
C Programming Guide".
......
void create(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
:: //! returns matrix header with disabled ref. counting for CudaMem data.
Mat createMatHeader() const;
operator Mat() const;
//! maps host memory into device address space
GpuMat createGpuMatHeader() const;
operator GpuMat() const;
//if host memory can be mapperd to gpu address space;
class CV_EXPORTS CudaMem static bool canMapHostMemory();
{
public:
enum { ALLOC_PAGE_LOCKED = 1, ALLOC_ZEROCOPY = 2,
ALLOC_WRITE_COMBINED = 4 };
CudaMem(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
//! creates from cv::Mat with coping data
explicit CudaMem(const Mat& m, int alloc_type = ALLOC_PAGE_LOCKED);
......
void create(Size size, int type, int alloc_type = ALLOC_PAGE_LOCKED);
//! returns matrix header with disabled ref. counting for CudaMem data.
Mat createMatHeader() const;
operator Mat() const;
//! maps host memory into device address space
GpuMat createGpuMatHeader() const;
operator GpuMat() const;
//if host memory can be mapperd to gpu address space;
static bool canMapHostMemory();
int alloc_type;
};
int alloc_type;
};
.. ..
.. index:: gpu::CudaMem::createMatHeader .. index:: gpu::CudaMem::createMatHeader
cv::gpu::CudaMem::createMatHeader cv::gpu::CudaMem::createMatHeader
--------------------------------- ---------------------------------
`id=0.772787893445 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ACudaMem%3A%3AcreateMatHeader>`__
:func:`Mat` :func:`Mat`
.. cfunction:: Mat CudaMem::createMatHeader() const .. cfunction:: Mat CudaMem::createMatHeader() const
.. cfunction:: CudaMem::operator Mat() const .. cfunction:: CudaMem::operator Mat() const
Creates header without reference counting to CudaMem data. Creates header without reference counting to CudaMem data.
.. index:: gpu::CudaMem::createGpuMatHeader .. index:: gpu::CudaMem::createGpuMatHeader
cv::gpu::CudaMem::createGpuMatHeader cv::gpu::CudaMem::createGpuMatHeader
------------------------------------ ------------------------------------
:func:`gpu::GpuMat` ``_``
`id=0.759677323147 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ACudaMem%3A%3AcreateGpuMatHeader>`__
:func:`gpu::GpuMat`
``_``
.. cfunction:: GpuMat CudaMem::createGpuMatHeader() const .. cfunction:: GpuMat CudaMem::createGpuMatHeader() const
.. cfunction:: CudaMem::operator GpuMat() const .. cfunction:: CudaMem::operator GpuMat() const
Maps CPU memory to GPU address space and creates header without reference counting for it. This can be done only if memory was allocated with ALLOCZEROCOPYflag and if it is supported by hardware (laptops often share video and CPU memory, so address spaces can be mapped, and that eliminates extra copy). Maps CPU memory to GPU address space and creates header without reference counting for it. This can be done only if memory was allocated with ALLOCZEROCOPYflag and if it is supported by hardware (laptops often share video and CPU memory, so address spaces can be mapped, and that eliminates extra copy).
.. index:: gpu::CudaMem::canMapHostMemory .. index:: gpu::CudaMem::canMapHostMemory
cv::gpu::CudaMem::canMapHostMemory cv::gpu::CudaMem::canMapHostMemory
---------------------------------- ---------------------------------- ``_``
`id=0.317724503486 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ACudaMem%3A%3AcanMapHostMemory>`__
``_``
.. cfunction:: static bool CudaMem::canMapHostMemory() .. cfunction:: static bool CudaMem::canMapHostMemory()
Returns true if the current hardware supports address space mapping and ALLOCZEROCOPYmemory allocation Returns true if the current hardware supports address space mapping and ALLOCZEROCOPYmemory allocation
.. index:: gpu::Stream .. index:: gpu::Stream
@ -364,107 +221,68 @@ cv::gpu::CudaMem::canMapHostMemory
gpu::Stream gpu::Stream
----------- -----------
`id=0.153849663278 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AStream>`__
.. ctype:: gpu::Stream .. ctype:: gpu::Stream
This class encapsulated queue of the asynchronous calls. Some functions have overloads with additional
:func:`gpu::Stream` parameter. The overloads do initialization work (allocate output buffers, upload constants, etc.), start GPU kernel and return before results are ready. A check if all operation are complete can be performed via
:func:`gpu::Stream::queryIfComplete()` . Asynchronous upload/download have to be performed from/to page-locked buffers, i.e. using
:func:`gpu::CudaMem` or
:func:`Mat` header that points to a region of
:func:`gpu::CudaMem` .
This class encapsulated queue of the asynchronous calls. Some functions have overloads with additional
:func:`gpu::Stream`
parameter. The overloads do initialization work (allocate output buffers, upload constants, etc.), start GPU kernel and return before results are ready. A check if all operation are complete can be performed via
:func:`gpu::Stream::queryIfComplete()`
. Asynchronous upload/download have to be performed from/to page-locked buffers, i.e. using
:func:`gpu::CudaMem`
or
:func:`Mat`
header that points to a region of
:func:`gpu::CudaMem`
.
**Please note the limitation** **Please note the limitation**
: currently it is not guaranteed that all will work properly if one operation will be enqueued twice with different data. Some functions use constant GPU memory and next call may update the memory before previous has been finished. But calling asynchronously different operations is safe because each operation has own constant buffer. Memory copy/upload/download/set operations to buffers hold by user are also safe. : currently it is not guaranteed that all will work properly if one operation will be enqueued twice with different data. Some functions use constant GPU memory and next call may update the memory before previous has been finished. But calling asynchronously different operations is safe because each operation has own constant buffer. Memory copy/upload/download/set operations to buffers hold by user are also safe. ::
class CV_EXPORTS Stream
{
public:
Stream();
~Stream();
Stream(const Stream&);
Stream& operator=(const Stream&);
:: bool queryIfComplete();
void waitForCompletion();
//! downloads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its subMat)
void enqueueDownload(const GpuMat& src, CudaMem& dst);
void enqueueDownload(const GpuMat& src, Mat& dst);
//! uploads asynchronously.
class CV_EXPORTS Stream // Warning! cv::Mat must point to page locked memory
{ (i.e. to CudaMem data or to its ROI)
public: void enqueueUpload(const CudaMem& src, GpuMat& dst);
Stream(); void enqueueUpload(const Mat& src, GpuMat& dst);
~Stream();
Stream(const Stream&);
Stream& operator=(const Stream&);
bool queryIfComplete();
void waitForCompletion();
//! downloads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its subMat)
void enqueueDownload(const GpuMat& src, CudaMem& dst);
void enqueueDownload(const GpuMat& src, Mat& dst);
//! uploads asynchronously.
// Warning! cv::Mat must point to page locked memory
(i.e. to CudaMem data or to its ROI)
void enqueueUpload(const CudaMem& src, GpuMat& dst);
void enqueueUpload(const Mat& src, GpuMat& dst);
void enqueueCopy(const GpuMat& src, GpuMat& dst);
void enqueueMemSet(const GpuMat& src, Scalar val);
void enqueueMemSet(const GpuMat& src, Scalar val, const GpuMat& mask);
// converts matrix type, ex from float to uchar depending on type
void enqueueConvert(const GpuMat& src, GpuMat& dst, int type,
double a = 1, double b = 0);
};
void enqueueCopy(const GpuMat& src, GpuMat& dst);
void enqueueMemSet(const GpuMat& src, Scalar val);
void enqueueMemSet(const GpuMat& src, Scalar val, const GpuMat& mask);
// converts matrix type, ex from float to uchar depending on type
void enqueueConvert(const GpuMat& src, GpuMat& dst, int type,
double a = 1, double b = 0);
};
.. ..
.. index:: gpu::Stream::queryIfComplete .. index:: gpu::Stream::queryIfComplete
cv::gpu::Stream::queryIfComplete cv::gpu::Stream::queryIfComplete
-------------------------------- --------------------------------
`id=0.136699172621 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AStream%3A%3AqueryIfComplete>`__
.. cfunction:: bool Stream::queryIfComplete() .. cfunction:: bool Stream::queryIfComplete()
Returns true if the current stream queue is finished, otherwise false. Returns true if the current stream queue is finished, otherwise false.
.. index:: gpu::Stream::waitForCompletion .. index:: gpu::Stream::waitForCompletion
cv::gpu::Stream::waitForCompletion cv::gpu::Stream::waitForCompletion
---------------------------------- ----------------------------------
`id=0.870172270785 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AStream%3A%3AwaitForCompletion>`__
.. cfunction:: void Stream::waitForCompletion() .. cfunction:: void Stream::waitForCompletion()
Blocks until all operations in the stream are complete. Blocks until all operations in the stream are complete.
.. index:: gpu::StreamAccessor .. index:: gpu::StreamAccessor
@ -472,126 +290,60 @@ cv::gpu::Stream::waitForCompletion
gpu::StreamAccessor gpu::StreamAccessor
------------------- -------------------
`id=0.312772323299 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AStreamAccessor>`__
.. ctype:: gpu::StreamAccessor .. ctype:: gpu::StreamAccessor
This class provides possibility to get ``cudaStream_t`` from
:func:`gpu::Stream` . This class is declared in ``stream_accessor.hpp`` because that is only public header that depend on Cuda Runtime API. Including it will bring the dependency to your code. ::
struct StreamAccessor
This class provides possibility to get {
``cudaStream_t`` CV_EXPORTS static cudaStream_t getStream(const Stream& stream);
from };
:func:`gpu::Stream`
. This class is declared in
``stream_accessor.hpp``
because that is only public header that depend on Cuda Runtime API. Including it will bring the dependency to your code.
::
struct StreamAccessor
{
CV_EXPORTS static cudaStream_t getStream(const Stream& stream);
};
.. ..
.. index:: gpu::createContinuous .. index:: gpu::createContinuous
cv::gpu::createContinuous cv::gpu::createContinuous
------------------------- -------------------------
`id=0.638242088099 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AcreateContinuous>`__
.. cfunction:: void createContinuous(int rows, int cols, int type, GpuMat\& m) .. cfunction:: void createContinuous(int rows, int cols, int type, GpuMat\& m)
Creates continuous matrix in GPU memory. Creates continuous matrix in GPU memory.
:param rows: Row count.
:param cols: Column count.
:param type: Type of the matrix.
:param m: Destination matrix. Will be only reshaped if it has proper type and area ( ``rows`` :math:`\times` ``cols`` ).
:param rows: Row count.
:param cols: Column count.
:param type: Type of the matrix.
:param m: Destination matrix. Will be only reshaped if it has proper type and area ( ``rows`` :math:`\times` ``cols`` ).
Also the following wrappers are available:
Also the following wrappers are available:
.. cfunction:: GpuMat createContinuous(int rows, int cols, int type) .. cfunction:: GpuMat createContinuous(int rows, int cols, int type)
.. cfunction:: void createContinuous(Size size, int type, GpuMat\& m) .. cfunction:: void createContinuous(Size size, int type, GpuMat\& m)
.. cfunction:: GpuMat createContinuous(Size size, int type) .. cfunction:: GpuMat createContinuous(Size size, int type)
Matrix is called continuous if its elements are stored continuously, i.e. wuthout gaps in the end of each row.
Matrix is called continuous if its elements are stored continuously, i.e. wuthout gaps in the end of each row.
.. index:: gpu::ensureSizeIsEnough .. index:: gpu::ensureSizeIsEnough
cv::gpu::ensureSizeIsEnough cv::gpu::ensureSizeIsEnough
--------------------------- ---------------------------
`id=0.0969536734629 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AensureSizeIsEnough>`__
.. cfunction:: void ensureSizeIsEnough(int rows, int cols, int type, GpuMat\& m) .. cfunction:: void ensureSizeIsEnough(int rows, int cols, int type, GpuMat\& m)
Ensures that size of matrix is big enough and matrix has proper type. The function doesn't reallocate memory if the matrix has proper attributes already. Ensures that size of matrix is big enough and matrix has proper type. The function doesn't reallocate memory if the matrix has proper attributes already.
:param rows: Minimum desired number of rows.
:param cols: Minimum desired number of cols.
:param type: Desired matrix type.
:param m: Destination matrix.
:param rows: Minimum desired number of rows.
:param cols: Minimum desired number of cols.
:param type: Desired matrix type.
:param m: Destination matrix.
Also the following wrapper is available:
Also the following wrapper is available:
.. cfunction:: void ensureSizeIsEnough(Size size, int type, GpuMat\& m) .. cfunction:: void ensureSizeIsEnough(Size size, int type, GpuMat\& m)

690
modules/gpu/doc/feature_detection_and_description.rst
View File

@ -3,120 +3,77 @@ Feature Detection and Description
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::SURF_GPU .. index:: gpu::SURF_GPU
.. _gpu::SURF_GPU: .. _gpu::SURF_GPU:
gpu::SURF_GPU gpu::SURF_GPU
------------- -------------
`id=0.87802428318 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ASURF_GPU>`__
.. ctype:: gpu::SURF_GPU .. ctype:: gpu::SURF_GPU
Class for extracting Speeded Up Robust Features from an image. ::
class SURF_GPU : public SURFParams_GPU
{
public:
//! returns the descriptor size in float's (64 or 128)
int descriptorSize() const;
Class for extracting Speeded Up Robust Features from an image. //! upload host keypoints to device memory
static void uploadKeypoints(const vector<KeyPoint>& keypoints,
GpuMat& keypointsGPU);
//! download keypoints from device to host memory
static void downloadKeypoints(const GpuMat& keypointsGPU,
vector<KeyPoint>& keypoints);
//! download descriptors from device to host memory
static void downloadDescriptors(const GpuMat& descriptorsGPU,
vector<float>& descriptors);
void operator()(const GpuMat& img, const GpuMat& mask,
GpuMat& keypoints);
:: void operator()(const GpuMat& img, const GpuMat& mask,
GpuMat& keypoints, GpuMat& descriptors,
bool useProvidedKeypoints = false,
bool calcOrientation = true);
void operator()(const GpuMat& img, const GpuMat& mask,
std::vector<KeyPoint>& keypoints);
void operator()(const GpuMat& img, const GpuMat& mask,
class SURF_GPU : public SURFParams_GPU std::vector<KeyPoint>& keypoints, GpuMat& descriptors,
{ bool useProvidedKeypoints = false,
public: bool calcOrientation = true);
//! returns the descriptor size in float's (64 or 128)
int descriptorSize() const;
//! upload host keypoints to device memory
static void uploadKeypoints(const vector<KeyPoint>& keypoints,
GpuMat& keypointsGPU);
//! download keypoints from device to host memory
static void downloadKeypoints(const GpuMat& keypointsGPU,
vector<KeyPoint>& keypoints);
//! download descriptors from device to host memory
static void downloadDescriptors(const GpuMat& descriptorsGPU,
vector<float>& descriptors);
void operator()(const GpuMat& img, const GpuMat& mask,
GpuMat& keypoints);
void operator()(const GpuMat& img, const GpuMat& mask,
GpuMat& keypoints, GpuMat& descriptors,
bool useProvidedKeypoints = false,
bool calcOrientation = true);
void operator()(const GpuMat& img, const GpuMat& mask,
std::vector<KeyPoint>& keypoints);
void operator()(const GpuMat& img, const GpuMat& mask,
std::vector<KeyPoint>& keypoints, GpuMat& descriptors,
bool useProvidedKeypoints = false,
bool calcOrientation = true);
void operator()(const GpuMat& img, const GpuMat& mask,
std::vector<KeyPoint>& keypoints,
std::vector<float>& descriptors,
bool useProvidedKeypoints = false,
bool calcOrientation = true);
GpuMat sum;
GpuMat sumf;
GpuMat mask1;
GpuMat maskSum;
GpuMat hessianBuffer;
GpuMat maxPosBuffer;
GpuMat featuresBuffer;
};
void operator()(const GpuMat& img, const GpuMat& mask,
std::vector<KeyPoint>& keypoints,
std::vector<float>& descriptors,
bool useProvidedKeypoints = false,
bool calcOrientation = true);
GpuMat sum;
GpuMat sumf;
GpuMat mask1;
GpuMat maskSum;
GpuMat hessianBuffer;
GpuMat maxPosBuffer;
GpuMat featuresBuffer;
};
.. ..
The class The class ``SURF_GPU`` implements Speeded Up Robust Features descriptor. There is fast multi-scale Hessian keypoint detector that can be used to find the keypoints (which is the default option), but the descriptors can be also computed for the user-specified keypoints. Supports only 8 bit grayscale images.
``SURF_GPU``
implements Speeded Up Robust Features descriptor. There is fast multi-scale Hessian keypoint detector that can be used to find the keypoints (which is the default option), but the descriptors can be also computed for the user-specified keypoints. Supports only 8 bit grayscale images. The class ``SURF_GPU`` can store results to GPU and CPU memory and provides static functions to convert results between CPU and GPU version ( ``uploadKeypoints``,``downloadKeypoints``,``downloadDescriptors`` ). CPU results has the same format as
results. GPU results are stored to ``GpuMat`` . ``keypoints`` matrix is one row matrix with ``CV_32FC6`` type. It contains 6 float values per feature: ``x, y, size, response, angle, octave`` . ``descriptors`` matrix is
The class :math:`\texttt{nFeatures} \times \texttt{descriptorSize}` matrix with ``CV_32FC1`` type.
``SURF_GPU``
can store results to GPU and CPU memory and provides static functions to convert results between CPU and GPU version ( The class ``SURF_GPU`` uses some buffers and provides access to it. All buffers can be safely released between function calls.
``uploadKeypoints``
, See also:
``downloadKeypoints`` .
,
``downloadDescriptors``
). CPU results has the same format as
results. GPU results are stored to
``GpuMat``
.
``keypoints``
matrix is one row matrix with
``CV_32FC6``
type. It contains 6 float values per feature:
``x, y, size, response, angle, octave``
.
``descriptors``
matrix is
:math:`\texttt{nFeatures} \times \texttt{descriptorSize}`
matrix with
``CV_32FC1``
type.
The class
``SURF_GPU``
uses some buffers and provides access to it. All buffers can be safely released between function calls.
See also:
.
.. index:: gpu::BruteForceMatcher_GPU .. index:: gpu::BruteForceMatcher_GPU
@ -124,126 +81,98 @@ See also:
gpu::BruteForceMatcher_GPU gpu::BruteForceMatcher_GPU
-------------------------- --------------------------
`id=0.776429775465 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ABruteForceMatcher_GPU>`__
.. ctype:: gpu::BruteForceMatcher_GPU .. ctype:: gpu::BruteForceMatcher_GPU
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 between descriptor sets. ::
template<class Distance>
class BruteForceMatcher_GPU
{
public:
// Add descriptors to train descriptor collection.
void add(const std::vector<GpuMat>& descCollection);
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 between descriptor sets. // Get train descriptors collection.
const std::vector<GpuMat>& getTrainDescriptors() const;
// Clear train descriptors collection.
void clear();
// Return true if there are not train descriptors in collection.
bool empty() const;
:: // Return true if the matcher supports mask in match methods.
bool isMaskSupported() const;
void matchSingle(const GpuMat& queryDescs, const GpuMat& trainDescs,
GpuMat& trainIdx, GpuMat& distance,
const GpuMat& mask = GpuMat());
static void matchDownload(const GpuMat& trainIdx,
template<class Distance> const GpuMat& distance, std::vector<DMatch>& matches);
class BruteForceMatcher_GPU
{
public:
// Add descriptors to train descriptor collection.
void add(const std::vector<GpuMat>& descCollection);
// Get train descriptors collection.
const std::vector<GpuMat>& getTrainDescriptors() const;
// Clear train descriptors collection.
void clear();
// Return true if there are not train descriptors in collection.
bool empty() const;
// Return true if the matcher supports mask in match methods.
bool isMaskSupported() const;
void matchSingle(const GpuMat& queryDescs, const GpuMat& trainDescs,
GpuMat& trainIdx, GpuMat& distance,
const GpuMat& mask = GpuMat());
static void matchDownload(const GpuMat& trainIdx,
const GpuMat& distance, std::vector<DMatch>& matches);
void match(const GpuMat& queryDescs, const GpuMat& trainDescs,
std::vector<DMatch>& matches, const GpuMat& mask = GpuMat());
void makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection,
const vector<GpuMat>& masks = std::vector<GpuMat>());
void matchCollection(const GpuMat& queryDescs,
const GpuMat& trainCollection,
GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance,
const GpuMat& maskCollection);
static void matchDownload(const GpuMat& trainIdx, GpuMat& imgIdx,
const GpuMat& distance, std::vector<DMatch>& matches);
void match(const GpuMat& queryDescs, std::vector<DMatch>& matches,
const std::vector<GpuMat>& masks = std::vector<GpuMat>());
void knnMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
GpuMat& trainIdx, GpuMat& distance, GpuMat& allDist, int k,
const GpuMat& mask = GpuMat());
static void knnMatchDownload(const GpuMat& trainIdx,
const GpuMat& distance, std::vector< std::vector<DMatch> >& matches,
bool compactResult = false);
void knnMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
std::vector< std::vector<DMatch> >& matches, int k,
const GpuMat& mask = GpuMat(), bool compactResult = false);
void knnMatch(const GpuMat& queryDescs,
std::vector< std::vector<DMatch> >& matches, int knn,
const std::vector<GpuMat>& masks = std::vector<GpuMat>(),
bool compactResult = false );
void radiusMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
GpuMat& trainIdx, GpuMat& nMatches, GpuMat& distance,
float maxDistance, const GpuMat& mask = GpuMat());
static void radiusMatchDownload(const GpuMat& trainIdx,
const GpuMat& nMatches, const GpuMat& distance,
std::vector< std::vector<DMatch> >& matches,
bool compactResult = false);
void radiusMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
std::vector< std::vector<DMatch> >& matches, float maxDistance,
const GpuMat& mask = GpuMat(), bool compactResult = false);
void radiusMatch(const GpuMat& queryDescs,
std::vector< std::vector<DMatch> >& matches, float maxDistance,
const std::vector<GpuMat>& masks = std::vector<GpuMat>(),
bool compactResult = false);
private:
std::vector<GpuMat> trainDescCollection;
};
void match(const GpuMat& queryDescs, const GpuMat& trainDescs,
std::vector<DMatch>& matches, const GpuMat& mask = GpuMat());
void makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection,
const vector<GpuMat>& masks = std::vector<GpuMat>());
void matchCollection(const GpuMat& queryDescs,
const GpuMat& trainCollection,
GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance,
const GpuMat& maskCollection);
static void matchDownload(const GpuMat& trainIdx, GpuMat& imgIdx,
const GpuMat& distance, std::vector<DMatch>& matches);
void match(const GpuMat& queryDescs, std::vector<DMatch>& matches,
const std::vector<GpuMat>& masks = std::vector<GpuMat>());
void knnMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
GpuMat& trainIdx, GpuMat& distance, GpuMat& allDist, int k,
const GpuMat& mask = GpuMat());
static void knnMatchDownload(const GpuMat& trainIdx,
const GpuMat& distance, std::vector< std::vector<DMatch> >& matches,
bool compactResult = false);
void knnMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
std::vector< std::vector<DMatch> >& matches, int k,
const GpuMat& mask = GpuMat(), bool compactResult = false);
void knnMatch(const GpuMat& queryDescs,
std::vector< std::vector<DMatch> >& matches, int knn,
const std::vector<GpuMat>& masks = std::vector<GpuMat>(),
bool compactResult = false );
void radiusMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
GpuMat& trainIdx, GpuMat& nMatches, GpuMat& distance,
float maxDistance, const GpuMat& mask = GpuMat());
static void radiusMatchDownload(const GpuMat& trainIdx,
const GpuMat& nMatches, const GpuMat& distance,
std::vector< std::vector<DMatch> >& matches,
bool compactResult = false);
void radiusMatch(const GpuMat& queryDescs, const GpuMat& trainDescs,
std::vector< std::vector<DMatch> >& matches, float maxDistance,
const GpuMat& mask = GpuMat(), bool compactResult = false);
void radiusMatch(const GpuMat& queryDescs,
std::vector< std::vector<DMatch> >& matches, float maxDistance,
const std::vector<GpuMat>& masks = std::vector<GpuMat>(),
bool compactResult = false);
private:
std::vector<GpuMat> trainDescCollection;
};
.. ..
The class The class ``BruteForceMatcher_GPU`` has the similar interface to class
``BruteForceMatcher_GPU`` . It has two groups of match methods: for matching descriptors of one image with other image or with image set. Also all functions have alternative: save results to GPU memory or to CPU memory.
has the similar interface to class ``Distance`` template parameter is kept for CPU/GPU interfaces similarity. ``BruteForceMatcher_GPU`` supports only ``L1<float>`` and ``L2<float>`` distance types.
. It has two groups of match methods: for matching descriptors of one image with other image or with image set. Also all functions have alternative: save results to GPU memory or to CPU memory.
See also:,.
``Distance``
template parameter is kept for CPU/GPU interfaces similarity.
``BruteForceMatcher_GPU``
supports only
``L1<float>``
and
``L2<float>``
distance types.
See also:
,
.
.. index:: cv::gpu::BruteForceMatcher_GPU::match .. index:: cv::gpu::BruteForceMatcher_GPU::match
@ -251,27 +180,14 @@ See also:
cv::gpu::BruteForceMatcher_GPU::match cv::gpu::BruteForceMatcher_GPU::match
------------------------------------- -------------------------------------
`id=0.164151048457 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3Amatch>`__
.. cfunction:: void match(const GpuMat\& queryDescs, const GpuMat\& trainDescs, std::vector<DMatch>\& matches, const GpuMat\& mask = GpuMat()) .. cfunction:: void match(const GpuMat\& queryDescs, const GpuMat\& trainDescs, std::vector<DMatch>\& matches, const GpuMat\& mask = GpuMat())
.. cfunction:: void match(const GpuMat\& queryDescs, std::vector<DMatch>\& matches, const std::vector<GpuMat>\& masks = std::vector<GpuMat>()) .. cfunction:: void match(const GpuMat\& queryDescs, std::vector<DMatch>\& matches, const std::vector<GpuMat>\& masks = std::vector<GpuMat>())
Finds the best match for each descriptor from a query set with train descriptors. Finds the best match for each descriptor from a query set with train descriptors.
See also:
See also: :func:`DescriptorMatcher::match` .
:func:`DescriptorMatcher::match`
.
.. index:: cv::gpu::BruteForceMatcher_GPU::matchSingle .. index:: cv::gpu::BruteForceMatcher_GPU::matchSingle
@ -279,39 +195,16 @@ See also:
cv::gpu::BruteForceMatcher_GPU::matchSingle cv::gpu::BruteForceMatcher_GPU::matchSingle
------------------------------------------- -------------------------------------------
`id=0.230978706047 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AmatchSingle>`__
.. cfunction:: void matchSingle(const GpuMat\& queryDescs, const GpuMat\& trainDescs, GpuMat\& trainIdx, GpuMat\& distance, const GpuMat\& mask = GpuMat()) .. cfunction:: void matchSingle(const GpuMat\& queryDescs, const GpuMat\& trainDescs, GpuMat\& trainIdx, GpuMat\& distance, const GpuMat\& mask = GpuMat())
Finds the best match for each query descriptor. Results will be stored to GPU memory. Finds the best match for each query descriptor. Results will be stored to GPU memory.
{Query set of descriptors.}
{Train set of descriptors. This will not be added to train descriptors collection stored in class object.}
{One row ``CV_32SC1`` matrix. Will contain the best train index for each query. If some query descriptors are masked out in ``mask`` it will contain -1.}
{One row ``CV_32FC1`` matrix. Will contain the best distance for each query. If some query descriptors are masked out in ``mask`` it will contain ``FLT_MAX`` .}
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
{Query set of descriptors.}
{Train set of descriptors. This will not be added to train descriptors collection stored in class object.}
{One row
``CV_32SC1``
matrix. Will contain the best train index for each query. If some query descriptors are masked out in
``mask``
it will contain -1.}
{One row
``CV_32FC1``
matrix. Will contain the best distance for each query. If some query descriptors are masked out in
``mask``
it will contain
``FLT_MAX``
.}
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
.. index:: cv::gpu::BruteForceMatcher_GPU::matchCollection .. index:: cv::gpu::BruteForceMatcher_GPU::matchCollection
@ -319,51 +212,18 @@ cv::gpu::BruteForceMatcher_GPU::matchSingle
cv::gpu::BruteForceMatcher_GPU::matchCollection cv::gpu::BruteForceMatcher_GPU::matchCollection
----------------------------------------------- -----------------------------------------------
`id=0.934341769456 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AmatchCollection>`__
.. cfunction:: void matchCollection(const GpuMat\& queryDescs, const GpuMat\& trainCollection, GpuMat\& trainIdx, GpuMat\& imgIdx, GpuMat\& distance, const GpuMat\& maskCollection) .. cfunction:: void matchCollection(const GpuMat\& queryDescs, const GpuMat\& trainCollection, GpuMat\& trainIdx, GpuMat\& imgIdx, GpuMat\& distance, const GpuMat\& maskCollection)
Find the best match for each query descriptor from train collection. Results will be stored to GPU memory. Find the best match for each query descriptor from train collection. Results will be stored to GPU memory.
{Query set of descriptors.}
{ ``GpuMat`` containing train collection. It can be obtained from train descriptors collection that was set using ``add`` method by
. Or it can contain user defined collection. It must be one row matrix, each element is a ``DevMem2D`` that points to one train descriptors matrix.}
{One row ``CV_32SC1`` matrix. Will contain the best train index for each query. If some query descriptors are masked out in ``maskCollection`` it will contain -1.}
{One row ``CV_32SC1`` matrix. Will contain image train index for each query. If some query descriptors are masked out in ``maskCollection`` it will contain -1.}
{One row ``CV_32FC1`` matrix. Will contain the best distance for each query. If some query descriptors are masked out in ``maskCollection`` it will contain ``FLT_MAX`` .}
:param maskCollection: ``GpuMat`` containing set of masks. It can be obtained from ``std::vector<GpuMat>`` by . Or it can contain user defined mask set. It must be empty matrix or one row matrix, each element is a ``PtrStep`` that points to one mask.
{Query set of descriptors.}
{
``GpuMat``
containing train collection. It can be obtained from train descriptors collection that was set using
``add``
method by
. Or it can contain user defined collection. It must be one row matrix, each element is a
``DevMem2D``
that points to one train descriptors matrix.}
{One row
``CV_32SC1``
matrix. Will contain the best train index for each query. If some query descriptors are masked out in
``maskCollection``
it will contain -1.}
{One row
``CV_32SC1``
matrix. Will contain image train index for each query. If some query descriptors are masked out in
``maskCollection``
it will contain -1.}
{One row
``CV_32FC1``
matrix. Will contain the best distance for each query. If some query descriptors are masked out in
``maskCollection``
it will contain
``FLT_MAX``
.}
:param maskCollection: ``GpuMat`` containing set of masks. It can be obtained from ``std::vector<GpuMat>`` by . Or it can contain user defined mask set. It must be empty matrix or one row matrix, each element is a ``PtrStep`` that points to one mask.
.. index:: cv::gpu::BruteForceMatcher_GPU::makeGpuCollection .. index:: cv::gpu::BruteForceMatcher_GPU::makeGpuCollection
@ -371,44 +231,21 @@ cv::gpu::BruteForceMatcher_GPU::matchCollection
cv::gpu::BruteForceMatcher_GPU::makeGpuCollection cv::gpu::BruteForceMatcher_GPU::makeGpuCollection
------------------------------------------------- -------------------------------------------------
`id=0.285830043662 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AmakeGpuCollection>`__
.. cfunction:: void makeGpuCollection(GpuMat\& trainCollection, GpuMat\& maskCollection, const vector<GpuMat>\& masks = std::vector<GpuMat>()) .. cfunction:: void makeGpuCollection(GpuMat\& trainCollection, GpuMat\& maskCollection, const vector<GpuMat>\& masks = std::vector<GpuMat>())
Makes gpu collection of train descriptors and masks in suitable format for function. Makes gpu collection of train descriptors and masks in suitable format for function.
.. index:: cv::gpu::BruteForceMatcher_GPU::matchDownload .. index:: cv::gpu::BruteForceMatcher_GPU::matchDownload
.. _cv::gpu::BruteForceMatcher_GPU::matchDownload: .. _cv::gpu::BruteForceMatcher_GPU::matchDownload:
cv::gpu::BruteForceMatcher_GPU::matchDownload cv::gpu::BruteForceMatcher_GPU::matchDownload
--------------------------------------------- --------------------------------------------- ```` ```` ````
`id=0.171611509706 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AmatchDownload>`__
````
````
````
.. cfunction:: void matchDownload(const GpuMat\& trainIdx, const GpuMat\& distance, std::vector<DMatch>\& matches) .. cfunction:: void matchDownload(const GpuMat\& trainIdx, const GpuMat\& distance, std::vector<DMatch>\& matches)
.. cfunction:: void matchDownload(const GpuMat\& trainIdx, GpuMat\& imgIdx, const GpuMat\& distance, std::vector<DMatch>\& matches) .. cfunction:: void matchDownload(const GpuMat\& trainIdx, GpuMat\& imgIdx, const GpuMat\& distance, std::vector<DMatch>\& matches)
Downloads trainIdx, imgIdxand distancematrices obtained via or to CPU vector with . Downloads trainIdx, imgIdxand distancematrices obtained via or to CPU vector with .
.. index:: cv::gpu::BruteForceMatcher_GPU::knnMatch .. index:: cv::gpu::BruteForceMatcher_GPU::knnMatch
@ -416,29 +253,14 @@ cv::gpu::BruteForceMatcher_GPU::matchDownload
cv::gpu::BruteForceMatcher_GPU::knnMatch cv::gpu::BruteForceMatcher_GPU::knnMatch
---------------------------------------- ----------------------------------------
`id=0.619005099272 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AknnMatch>`__
.. cfunction:: void knnMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, std::vector< std::vector<DMatch> >\& matches, int k, const GpuMat\& mask = GpuMat(), bool compactResult = false) .. cfunction:: void knnMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, std::vector< std::vector<DMatch> >\& matches, int k, const GpuMat\& mask = GpuMat(), bool compactResult = false)
Finds the k best matches for each descriptor from a query set with train descriptors. Found k (or less if not possible) matches are returned in distance increasing order. Finds the k best matches for each descriptor from a query set with train descriptors. Found k (or less if not possible) matches are returned in distance increasing order.
.. cfunction:: void knnMatch(const GpuMat\& queryDescs, std::vector< std::vector<DMatch> >\& matches, int k, const std::vector<GpuMat>\& masks = std::vector<GpuMat>(), bool compactResult = false ) .. cfunction:: void knnMatch(const GpuMat\& queryDescs, std::vector< std::vector<DMatch> >\& matches, int k, const std::vector<GpuMat>\& masks = std::vector<GpuMat>(), bool compactResult = false )
See also:
:func:`DescriptorMatcher::knnMatch` .
See also:
:func:`DescriptorMatcher::knnMatch`
.
.. index:: cv::gpu::BruteForceMatcher_GPU::knnMatch .. index:: cv::gpu::BruteForceMatcher_GPU::knnMatch
@ -446,86 +268,32 @@ See also:
cv::gpu::BruteForceMatcher_GPU::knnMatch cv::gpu::BruteForceMatcher_GPU::knnMatch
---------------------------------------- ----------------------------------------
`id=0.852761934257 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AknnMatch>`__
.. cfunction:: void knnMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, GpuMat\& trainIdx, GpuMat\& distance, GpuMat\& allDist, int k, const GpuMat\& mask = GpuMat()) .. cfunction:: void knnMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, GpuMat\& trainIdx, GpuMat\& distance, GpuMat\& allDist, int k, const GpuMat\& mask = GpuMat())
Finds the k best matches for each descriptor from a query set with train descriptors. Found k (or less if not possible) matches are returned in distance increasing order. Results will be stored to GPU memory. Finds the k best matches for each descriptor from a query set with train descriptors. Found k (or less if not possible) matches are returned in distance increasing order. Results will be stored to GPU memory.
{Query set of descriptors.}
{Train set of descriptors. This will not be added to train descriptors collection stored in class object.}
{Matrix with
:math:`\texttt{nQueries} \times \texttt{k}` size and ``CV_32SC1`` type. ``trainIdx.at<int>(queryIdx, i)`` will contain index of the i'th best trains. If some query descriptors are masked out in ``mask`` it will contain -1.}
{Matrix with
:math:`\texttt{nQuery} \times \texttt{k}` and ``CV_32FC1`` type. Will contain distance for each query and the i'th best trains. If some query descriptors are masked out in ``mask`` it will contain ``FLT_MAX`` .}
{Buffer to store all distances between query descriptors and train descriptors. It will have
:math:`\texttt{nQuery} \times \texttt{nTrain}` size and ``CV_32FC1`` type. ``allDist.at<float>(queryIdx, trainIdx)`` will contain ``FLT_MAX`` , if ``trainIdx`` is one from k best, otherwise it will contain distance between ``queryIdx`` and ``trainIdx`` descriptors.}
:param k: Number of the best matches will be found per each query descriptor (or less if it's not possible).
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
{Query set of descriptors.}
{Train set of descriptors. This will not be added to train descriptors collection stored in class object.}
{Matrix with
:math:`\texttt{nQueries} \times \texttt{k}`
size and
``CV_32SC1``
type.
``trainIdx.at<int>(queryIdx, i)``
will contain index of the i'th best trains. If some query descriptors are masked out in
``mask``
it will contain -1.}
{Matrix with
:math:`\texttt{nQuery} \times \texttt{k}`
and
``CV_32FC1``
type. Will contain distance for each query and the i'th best trains. If some query descriptors are masked out in
``mask``
it will contain
``FLT_MAX``
.}
{Buffer to store all distances between query descriptors and train descriptors. It will have
:math:`\texttt{nQuery} \times \texttt{nTrain}`
size and
``CV_32FC1``
type.
``allDist.at<float>(queryIdx, trainIdx)``
will contain
``FLT_MAX``
, if
``trainIdx``
is one from k best, otherwise it will contain distance between
``queryIdx``
and
``trainIdx``
descriptors.}
:param k: Number of the best matches will be found per each query descriptor (or less if it's not possible).
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
.. index:: cv::gpu::BruteForceMatcher_GPU::knnMatchDownload .. index:: cv::gpu::BruteForceMatcher_GPU::knnMatchDownload
.. _cv::gpu::BruteForceMatcher_GPU::knnMatchDownload: .. _cv::gpu::BruteForceMatcher_GPU::knnMatchDownload:
cv::gpu::BruteForceMatcher_GPU::knnMatchDownload cv::gpu::BruteForceMatcher_GPU::knnMatchDownload
------------------------------------------------ ------------------------------------------------ ```` ```` ```` ````
`id=0.735745722087 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AknnMatchDownload>`__
````
````
````
````
.. cfunction:: void knnMatchDownload(const GpuMat\& trainIdx, const GpuMat\& distance, std::vector< std::vector<DMatch> >\& matches, bool compactResult = false) .. cfunction:: void knnMatchDownload(const GpuMat\& trainIdx, const GpuMat\& distance, std::vector< std::vector<DMatch> >\& matches, bool compactResult = false)
Downloads trainIdxand distancematrices obtained via to CPU vector with . If compactResultis true matchesvector will not contain matches for fully masked out query descriptors. Downloads trainIdxand distancematrices obtained via to CPU vector with . If compactResultis true matchesvector will not contain matches for fully masked out query descriptors.
.. index:: cv::gpu::BruteForceMatcher_GPU::radiusMatch .. index:: cv::gpu::BruteForceMatcher_GPU::radiusMatch
@ -533,33 +301,17 @@ cv::gpu::BruteForceMatcher_GPU::knnMatchDownload
cv::gpu::BruteForceMatcher_GPU::radiusMatch cv::gpu::BruteForceMatcher_GPU::radiusMatch
------------------------------------------- -------------------------------------------
`id=0.964758287221 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AradiusMatch>`__
.. cfunction:: void radiusMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, std::vector< std::vector<DMatch> >\& matches, float maxDistance, const GpuMat\& mask = GpuMat(), bool compactResult = false) .. cfunction:: void radiusMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, std::vector< std::vector<DMatch> >\& matches, float maxDistance, const GpuMat\& mask = GpuMat(), bool compactResult = false)
Finds the best matches for each query descriptor which have distance less than given threshold. Found matches are returned in distance increasing order. Finds the best matches for each query descriptor which have distance less than given threshold. Found matches are returned in distance increasing order.
.. cfunction:: void radiusMatch(const GpuMat\& queryDescs, std::vector< std::vector<DMatch> >\& matches, float maxDistance, const std::vector<GpuMat>\& masks = std::vector<GpuMat>(), bool compactResult = false) .. cfunction:: void radiusMatch(const GpuMat\& queryDescs, std::vector< std::vector<DMatch> >\& matches, float maxDistance, const std::vector<GpuMat>\& masks = std::vector<GpuMat>(), bool compactResult = false)
This function works only on devices with Compute Capability
:math:`>=` 1.1.
See also:
This function works only on devices with Compute Capability :func:`DescriptorMatcher::radiusMatch` .
:math:`>=`
1.1.
See also:
:func:`DescriptorMatcher::radiusMatch`
.
.. index:: cv::gpu::BruteForceMatcher_GPU::radiusMatch .. index:: cv::gpu::BruteForceMatcher_GPU::radiusMatch
@ -567,95 +319,35 @@ See also:
cv::gpu::BruteForceMatcher_GPU::radiusMatch cv::gpu::BruteForceMatcher_GPU::radiusMatch
------------------------------------------- -------------------------------------------
`id=0.499772925784 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AradiusMatch>`__
.. cfunction:: void radiusMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, GpuMat\& trainIdx, GpuMat\& nMatches, GpuMat\& distance, float maxDistance, const GpuMat\& mask = GpuMat()) .. cfunction:: void radiusMatch(const GpuMat\& queryDescs, const GpuMat\& trainDescs, GpuMat\& trainIdx, GpuMat\& nMatches, GpuMat\& distance, float maxDistance, const GpuMat\& mask = GpuMat())
Finds the best matches for each query descriptor which have distance less than given threshold. Results will be stored to GPU memory. Finds the best matches for each query descriptor which have distance less than given threshold. Results will be stored to GPU memory.
{Query set of descriptors.}
{Train set of descriptors. This will not be added to train descriptors collection stored in class object.}
{ ``trainIdx.at<int>(queryIdx, i)`` will contain i'th train index ``(i < min(nMatches.at<unsigned int>(0, queryIdx), trainIdx.cols)`` . If ``trainIdx`` is empty, it will be created with size
:math:`\texttt{nQuery} \times \texttt{nTrain}` . Or it can be allocated by user (it must have ``nQuery`` rows and ``CV_32SC1`` type). Cols can be less than ``nTrain`` , but it can be that matcher won't find all matches, because it haven't enough memory to store results.}
{ ``nMatches.at<unsigned int>(0, queryIdx)`` will contain matches count for ``queryIdx`` . Carefully, ``nMatches`` can be greater than ``trainIdx.cols`` - it means that matcher didn't find all matches, because it didn't have enough memory.}
{ ``distance.at<int>(queryIdx, i)`` will contain i'th distance ``(i < min(nMatches.at<unsigned int>(0, queryIdx), trainIdx.cols)`` . If ``trainIdx`` is empty, it will be created with size
:math:`\texttt{nQuery} \times \texttt{nTrain}` . Otherwise it must be also allocated by user (it must have the same size as ``trainIdx`` and ``CV_32FC1`` type).}
:param maxDistance: Distance threshold.
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
{Query set of descriptors.} In contrast to
{Train set of descriptors. This will not be added to train descriptors collection stored in class object.} results are not sorted by distance increasing order.
{
``trainIdx.at<int>(queryIdx, i)`` This function works only on devices with Compute Capability
will contain i'th train index :math:`>=` 1.1.
``(i < min(nMatches.at<unsigned int>(0, queryIdx), trainIdx.cols)``
. If
``trainIdx``
is empty, it will be created with size
:math:`\texttt{nQuery} \times \texttt{nTrain}`
. Or it can be allocated by user (it must have
``nQuery``
rows and
``CV_32SC1``
type). Cols can be less than
``nTrain``
, but it can be that matcher won't find all matches, because it haven't enough memory to store results.}
{
``nMatches.at<unsigned int>(0, queryIdx)``
will contain matches count for
``queryIdx``
. Carefully,
``nMatches``
can be greater than
``trainIdx.cols``
- it means that matcher didn't find all matches, because it didn't have enough memory.}
{
``distance.at<int>(queryIdx, i)``
will contain i'th distance
``(i < min(nMatches.at<unsigned int>(0, queryIdx), trainIdx.cols)``
. If
``trainIdx``
is empty, it will be created with size
:math:`\texttt{nQuery} \times \texttt{nTrain}`
. Otherwise it must be also allocated by user (it must have the same size as
``trainIdx``
and
``CV_32FC1``
type).}
:param maxDistance: Distance threshold.
:param mask: Mask specifying permissible matches between input query and train matrices of descriptors.
In contrast to
results are not sorted by distance increasing order.
This function works only on devices with Compute Capability
:math:`>=`
1.1.
.. index:: cv::gpu::BruteForceMatcher_GPU::radiusMatchDownload .. index:: cv::gpu::BruteForceMatcher_GPU::radiusMatchDownload
.. _cv::gpu::BruteForceMatcher_GPU::radiusMatchDownload: .. _cv::gpu::BruteForceMatcher_GPU::radiusMatchDownload:
cv::gpu::BruteForceMatcher_GPU::radiusMatchDownload cv::gpu::BruteForceMatcher_GPU::radiusMatchDownload
--------------------------------------------------- --------------------------------------------------- ```` ```` ```` ```` ````
`id=0.627360663551 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ABruteForceMatcher_GPU%3A%3AradiusMatchDownload>`__
````
````
````
````
````
.. cfunction:: void radiusMatchDownload(const GpuMat\& trainIdx, const GpuMat\& nMatches, const GpuMat\& distance, std::vector< std::vector<DMatch> >\& matches, bool compactResult = false) .. cfunction:: void radiusMatchDownload(const GpuMat\& trainIdx, const GpuMat\& nMatches, const GpuMat\& distance, std::vector< std::vector<DMatch> >\& matches, bool compactResult = false)
Downloads trainIdx, nMatchesand distancematrices obtained via to CPU vector with . If compactResultis true matchesvector will not contain matches for fully masked out query descriptors. Downloads trainIdx, nMatchesand distancematrices obtained via to CPU vector with . If compactResultis true matchesvector will not contain matches for fully masked out query descriptors.

6
modules/gpu/doc/gpu.rst
View File

@ -1,6 +1,6 @@
******************************* ************************************
GPU-accelerated Computer Vision gpu. GPU-accelerated Computer Vision
******************************* ************************************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

1344
modules/gpu/doc/image_filtering.rst
View File

File diff suppressed because it is too large Load Diff

1180
modules/gpu/doc/image_processing.rst
View File

File diff suppressed because it is too large Load Diff

236
modules/gpu/doc/initalization_and_information.rst
View File

@ -3,91 +3,42 @@ Initalization and Information
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::getCudaEnabledDeviceCount .. index:: gpu::getCudaEnabledDeviceCount
cv::gpu::getCudaEnabledDeviceCount cv::gpu::getCudaEnabledDeviceCount
---------------------------------- ----------------------------------
`id=0.541856697999 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AgetCudaEnabledDeviceCount>`__
.. cfunction:: int getCudaEnabledDeviceCount() .. cfunction:: int getCudaEnabledDeviceCount()
Returns number of CUDA-enabled devices installed. It is to be used before any other GPU functions calls. If OpenCV is compiled without GPU support this function returns 0. Returns number of CUDA-enabled devices installed. It is to be used before any other GPU functions calls. If OpenCV is compiled without GPU support this function returns 0.
.. index:: gpu::setDevice .. index:: gpu::setDevice
cv::gpu::setDevice cv::gpu::setDevice
------------------ ------------------
`id=0.817295536445 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AsetDevice>`__
.. cfunction:: void setDevice(int device) .. cfunction:: void setDevice(int device)
Sets device and initializes it for the current thread. Call of this function can be omitted, but in this case a default device will be initialized on fist GPU usage. Sets device and initializes it for the current thread. Call of this function can be omitted, but in this case a default device will be initialized on fist GPU usage.
:param device: index of GPU device in system starting with 0.
:param device: index of GPU device in system starting with 0.
.. index:: gpu::getDevice .. index:: gpu::getDevice
cv::gpu::getDevice cv::gpu::getDevice
------------------ ------------------
`id=0.908782607162 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AgetDevice>`__
.. cfunction:: int getDevice() .. cfunction:: int getDevice()
Returns the current device index, which was set by {gpu::getDevice} or initialized by default. Returns the current device index, which was set by {gpu::getDevice} or initialized by default.
.. index:: gpu::GpuFeature .. index:: gpu::GpuFeature
.. _gpu::GpuFeature: .. _gpu::GpuFeature:
gpu::GpuFeature gpu::GpuFeature
--------------- ---------------
`id=0.185426029041 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AGpuFeature>`__
.. ctype:: gpu::GpuFeature .. ctype:: gpu::GpuFeature
GPU compute features. ::
GPU compute features.
::
enum GpuFeature enum GpuFeature
{ {
COMPUTE_10, COMPUTE_11, COMPUTE_10, COMPUTE_11,
@ -95,308 +46,153 @@ GPU compute features.
COMPUTE_20, COMPUTE_21, COMPUTE_20, COMPUTE_21,
ATOMICS, NATIVE_DOUBLE ATOMICS, NATIVE_DOUBLE
}; };
.. ..
.. index:: gpu::DeviceInfo .. index:: gpu::DeviceInfo
.. _gpu::DeviceInfo: .. _gpu::DeviceInfo:
gpu::DeviceInfo gpu::DeviceInfo
--------------- ---------------
`id=0.91098225386 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo>`__
.. ctype:: gpu::DeviceInfo .. ctype:: gpu::DeviceInfo
This class provides functionality for querying the specified GPU properties. ::
This class provides functionality for querying the specified GPU properties.
::
class CV_EXPORTS DeviceInfo class CV_EXPORTS DeviceInfo
{ {
public: public:
DeviceInfo(); DeviceInfo();
DeviceInfo(int device_id); DeviceInfo(int device_id);
string name() const; string name() const;
int majorVersion() const; int majorVersion() const;
int minorVersion() const; int minorVersion() const;
int multiProcessorCount() const; int multiProcessorCount() const;
size_t freeMemory() const; size_t freeMemory() const;
size_t totalMemory() const; size_t totalMemory() const;
bool supports(GpuFeature feature) const; bool supports(GpuFeature feature) const;
bool isCompatible() const; bool isCompatible() const;
}; };
.. ..
.. index:: gpu::DeviceInfo::DeviceInfo .. index:: gpu::DeviceInfo::DeviceInfo
cv::gpu::DeviceInfo::DeviceInfo cv::gpu::DeviceInfo::DeviceInfo
------------------------------- ------------------------------- ``_``
`id=0.971366637207 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3ADeviceInfo>`__
``_``
.. cfunction:: DeviceInfo::DeviceInfo() .. cfunction:: DeviceInfo::DeviceInfo()
.. cfunction:: DeviceInfo::DeviceInfo(int device_id) .. cfunction:: DeviceInfo::DeviceInfo(int device_id)
Constructs DeviceInfo object for the specified device. If deviceidparameter is missed it constructs object for the current device. Constructs DeviceInfo object for the specified device. If deviceidparameter is missed it constructs object for the current device.
:param device_id: Index of the GPU device in system starting with 0.
:param device_id: Index of the GPU device in system starting with 0.
.. index:: gpu::DeviceInfo::name .. index:: gpu::DeviceInfo::name
cv::gpu::DeviceInfo::name cv::gpu::DeviceInfo::name
------------------------- -------------------------
`id=0.472941921148 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3Aname>`__
.. cfunction:: string DeviceInfo::name() .. cfunction:: string DeviceInfo::name()
Returns the device name. Returns the device name.
.. index:: gpu::DeviceInfo::majorVersion .. index:: gpu::DeviceInfo::majorVersion
cv::gpu::DeviceInfo::majorVersion cv::gpu::DeviceInfo::majorVersion
--------------------------------- ---------------------------------
`id=0.982334984119 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3AmajorVersion>`__
.. cfunction:: int DeviceInfo::majorVersion() .. cfunction:: int DeviceInfo::majorVersion()
Returns the major compute capability version. Returns the major compute capability version.
.. index:: gpu::DeviceInfo::minorVersion .. index:: gpu::DeviceInfo::minorVersion
cv::gpu::DeviceInfo::minorVersion cv::gpu::DeviceInfo::minorVersion
--------------------------------- ---------------------------------
`id=0.309433581176 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3AminorVersion>`__
.. cfunction:: int DeviceInfo::minorVersion() .. cfunction:: int DeviceInfo::minorVersion()
Returns the minor compute capability version. Returns the minor compute capability version.
.. index:: gpu::DeviceInfo::multiProcessorCount .. index:: gpu::DeviceInfo::multiProcessorCount
cv::gpu::DeviceInfo::multiProcessorCount cv::gpu::DeviceInfo::multiProcessorCount
---------------------------------------- ----------------------------------------
`id=0.417609601388 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3AmultiProcessorCount>`__
.. cfunction:: int DeviceInfo::multiProcessorCount() .. cfunction:: int DeviceInfo::multiProcessorCount()
Returns the number of streaming multiprocessors. Returns the number of streaming multiprocessors.
.. index:: gpu::DeviceInfo::freeMemory .. index:: gpu::DeviceInfo::freeMemory
cv::gpu::DeviceInfo::freeMemory cv::gpu::DeviceInfo::freeMemory
------------------------------- -------------------------------
`id=0.961189453269 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3AfreeMemory>`__
.. cfunction:: size_t DeviceInfo::freeMemory() .. cfunction:: size_t DeviceInfo::freeMemory()
Returns the amount of free memory in bytes. Returns the amount of free memory in bytes.
.. index:: gpu::DeviceInfo::totalMemory .. index:: gpu::DeviceInfo::totalMemory
cv::gpu::DeviceInfo::totalMemory cv::gpu::DeviceInfo::totalMemory
-------------------------------- --------------------------------
`id=0.884488673579 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3AtotalMemory>`__
.. cfunction:: size_t DeviceInfo::totalMemory() .. cfunction:: size_t DeviceInfo::totalMemory()
Returns the amount of total memory in bytes. Returns the amount of total memory in bytes.
.. index:: gpu::DeviceInfo::supports .. index:: gpu::DeviceInfo::supports
cv::gpu::DeviceInfo::supports cv::gpu::DeviceInfo::supports
----------------------------- -----------------------------
`id=0.141435828088 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3Asupports>`__
.. cfunction:: bool DeviceInfo::supports(GpuFeature feature) .. cfunction:: bool DeviceInfo::supports(GpuFeature feature)
Returns true if the device has the given GPU feature, otherwise false. Returns true if the device has the given GPU feature, otherwise false.
:param feature: Feature to be checked. See .
:param feature: Feature to be checked. See .
.. index:: gpu::DeviceInfo::isCompatible .. index:: gpu::DeviceInfo::isCompatible
cv::gpu::DeviceInfo::isCompatible cv::gpu::DeviceInfo::isCompatible
--------------------------------- ---------------------------------
`id=0.564690282768 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ADeviceInfo%3A%3AisCompatible>`__
.. cfunction:: bool DeviceInfo::isCompatible() .. cfunction:: bool DeviceInfo::isCompatible()
Returns true if the GPU module can be run on the specified device, otherwise false. Returns true if the GPU module can be run on the specified device, otherwise false.
.. index:: gpu::TargetArchs .. index:: gpu::TargetArchs
.. _gpu::TargetArchs: .. _gpu::TargetArchs:
gpu::TargetArchs gpu::TargetArchs
---------------- ----------------
`id=0.200853353999 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ATargetArchs>`__
.. ctype:: gpu::TargetArchs .. ctype:: gpu::TargetArchs
This class provides functionality (as set of static methods) for checking which NVIDIA card architectures the GPU module was built for. This class provides functionality (as set of static methods) for checking which NVIDIA card architectures the GPU module was built for.
bigskip bigskip
The following method checks whether the module was built with the support of the given feature: The following method checks whether the module was built with the support of the given feature:
.. cfunction:: static bool builtWith(GpuFeature feature) .. cfunction:: static bool builtWith(GpuFeature feature)
:param feature: Feature to be checked. See .
:param feature: Feature to be checked. See .
There are a set of methods for checking whether the module contains intermediate (PTX) or binary GPU code for the given architecture(s): There are a set of methods for checking whether the module contains intermediate (PTX) or binary GPU code for the given architecture(s):
.. cfunction:: static bool has(int major, int minor) .. cfunction:: static bool has(int major, int minor)
.. cfunction:: static bool hasPtx(int major, int minor) .. cfunction:: static bool hasPtx(int major, int minor)
.. cfunction:: static bool hasBin(int major, int minor) .. cfunction:: static bool hasBin(int major, int minor)
.. cfunction:: static bool hasEqualOrLessPtx(int major, int minor) .. cfunction:: static bool hasEqualOrLessPtx(int major, int minor)
.. cfunction:: static bool hasEqualOrGreater(int major, int minor) .. cfunction:: static bool hasEqualOrGreater(int major, int minor)
.. cfunction:: static bool hasEqualOrGreaterPtx(int major, int minor) .. cfunction:: static bool hasEqualOrGreaterPtx(int major, int minor)
.. cfunction:: static bool hasEqualOrGreaterBin(int major, int minor) .. cfunction:: static bool hasEqualOrGreaterBin(int major, int minor)
* **major** Major compute capability version.
* **minor** Minor compute capability version.
According to the CUDA C Programming Guide Version 3.2: "PTX code produced for some specific compute capability can always be compiled to binary code of greater or equal compute capability".
* **major** Major compute capability version.
* **minor** Minor compute capability version.
According to the CUDA C Programming Guide Version 3.2: "PTX code produced for some specific compute capability can always be compiled to binary code of greater or equal compute capability".

118
modules/gpu/doc/introduction.rst
View File

@ -3,120 +3,78 @@ GPU module introduction
.. highlight:: cpp .. highlight:: cpp
General information General information
------------------- -------------------
The OpenCV GPU module is a set of classes and functions to utilize GPU computational capabilities. It is implemented using NVidia CUDA Runtime API, so only the NVidia GPUs are supported. It includes utility functions, low-level vision primitives as well as high-level algorithms. The utility functions and low-level primitives provide a powerful infrastructure for developing fast vision algorithms taking advantage of GPU. Whereas the high-level functionality includes some state-of-the-art algorithms (such as stereo correspondence, face and people detectors etc.), ready to be used by the application developers.
The OpenCV GPU module is a set of classes and functions to utilize GPU computational capabilities. It is implemented using NVidia CUDA Runtime API, so only the NVidia GPUs are supported. It includes utility functions, low-level vision primitives as well as high-level algorithms. The utility functions and low-level primitives provide a powerful infrastructure for developing fast vision algorithms taking advantage of GPU. Whereas the high-level functionality includes some state-of-the-art algorithms (such as stereo correspondence, face and people detectors etc.), ready to be used by the application developers. The GPU module is designed as host-level API, i.e. if a user has pre-compiled OpenCV GPU binaries, it is not necessary to have Cuda Toolkit installed or write any extra code to make use of the GPU.
The GPU module is designed as host-level API, i.e. if a user has pre-compiled OpenCV GPU binaries, it is not necessary to have Cuda Toolkit installed or write any extra code to make use of the GPU. The GPU module depends on the Cuda Toolkit and NVidia Performance Primitives library (NPP). Make sure you have the latest versions of those. The two libraries can be downloaded from NVidia site for all supported platforms. To compile OpenCV GPU module you will need a compiler compatible with Cuda Runtime Toolkit.
The GPU module depends on the Cuda Toolkit and NVidia Performance Primitives library (NPP). Make sure you have the latest versions of those. The two libraries can be downloaded from NVidia site for all supported platforms. To compile OpenCV GPU module you will need a compiler compatible with Cuda Runtime Toolkit. OpenCV GPU module is designed for ease of use and does not require any knowledge of Cuda. Though, such a knowledge will certainly be useful in non-trivial cases, or when you want to get the highest performance. It is helpful to have understanding of the costs of various operations, what the GPU does, what are the preferred data formats etc. The GPU module is an effective instrument for quick implementation of GPU-accelerated computer vision algorithms. However, if you algorithm involves many simple operations, then for the best possible performance you may still need to write your own kernels, to avoid extra write and read operations on the intermediate results.
OpenCV GPU module is designed for ease of use and does not require any knowledge of Cuda. Though, such a knowledge will certainly be useful in non-trivial cases, or when you want to get the highest performance. It is helpful to have understanding of the costs of various operations, what the GPU does, what are the preferred data formats etc. The GPU module is an effective instrument for quick implementation of GPU-accelerated computer vision algorithms. However, if you algorithm involves many simple operations, then for the best possible performance you may still need to write your own kernels, to avoid extra write and read operations on the intermediate results. To enable CUDA support, configure OpenCV using CMake with ``WITH_CUDA=ON`` . When the flag is set and if CUDA is installed, the full-featured OpenCV GPU module will be built. Otherwise, the module will still be built, but at runtime all functions from the module will throw
:func:`Exception` with ``CV_GpuNotSupported`` error code, except for
To enable CUDA support, configure OpenCV using CMake with :func:`gpu::getCudaEnabledDeviceCount()` . The latter function will return zero GPU count in this case. Building OpenCV without CUDA support does not perform device code compilation, so it does not require Cuda Toolkit installed. Therefore, using
``WITH_CUDA=ON`` :func:`gpu::getCudaEnabledDeviceCount()` function it is possible to implement a high-level algorithm that will detect GPU presence at runtime and choose the appropriate implementation (CPU or GPU) accordingly.
. When the flag is set and if CUDA is installed, the full-featured OpenCV GPU module will be built. Otherwise, the module will still be built, but at runtime all functions from the module will throw
:func:`Exception`
with
``CV_GpuNotSupported``
error code, except for
:func:`gpu::getCudaEnabledDeviceCount()`
. The latter function will return zero GPU count in this case. Building OpenCV without CUDA support does not perform device code compilation, so it does not require Cuda Toolkit installed. Therefore, using
:func:`gpu::getCudaEnabledDeviceCount()`
function it is possible to implement a high-level algorithm that will detect GPU presence at runtime and choose the appropriate implementation (CPU or GPU) accordingly.
Compilation for different NVidia platforms. Compilation for different NVidia platforms.
------------------------------------------- -------------------------------------------
NVidia compiler allows generating binary code (cubin and fatbin) and intermediate code (PTX). Binary code often implies a specific GPU architecture and generation, so the compatibility with other GPUs is not guaranteed. PTX is targeted for a virtual platform, which is defined entirely by the set of capabilities, or features. Depending on the virtual platform chosen, some of the instructions will be emulated or disabled, even if the real hardware supports all the features.
NVidia compiler allows generating binary code (cubin and fatbin) and intermediate code (PTX). Binary code often implies a specific GPU architecture and generation, so the compatibility with other GPUs is not guaranteed. PTX is targeted for a virtual platform, which is defined entirely by the set of capabilities, or features. Depending on the virtual platform chosen, some of the instructions will be emulated or disabled, even if the real hardware supports all the features. On first call, the PTX code is compiled to binary code for the particular GPU using JIT compiler. When the target GPU has lower "compute capability" (CC) than the PTX code, JIT fails.
On first call, the PTX code is compiled to binary code for the particular GPU using JIT compiler. When the target GPU has lower "compute capability" (CC) than the PTX code, JIT fails.
By default, the OpenCV GPU module includes:
By default, the OpenCV GPU module includes:
* *
Binaries for compute capabilities 1.3 and 2.0 (controlled by Binaries for compute capabilities 1.3 and 2.0 (controlled by ``CUDA_ARCH_BIN`` in CMake)
``CUDA_ARCH_BIN``
in CMake)
* *
PTX code for compute capabilities 1.1 and 1.3 (controlled by PTX code for compute capabilities 1.1 and 1.3 (controlled by ``CUDA_ARCH_PTX`` in CMake)
``CUDA_ARCH_PTX``
in CMake) That means for devices with CC 1.3 and 2.0 binary images are ready to run. For all newer platforms the PTX code for 1.3 is JIT'ed to a binary image. For devices with 1.1 and 1.2 the PTX for 1.1 is JIT'ed. For devices with CC 1.0 no code is available and the functions will throw
:func:`Exception` . For platforms where JIT compilation is performed first run will be slow.
That means for devices with CC 1.3 and 2.0 binary images are ready to run. For all newer platforms the PTX code for 1.3 is JIT'ed to a binary image. For devices with 1.1 and 1.2 the PTX for 1.1 is JIT'ed. For devices with CC 1.0 no code is available and the functions will throw If you happen to have GPU with CC 1.0, the GPU module can still be compiled on it and most of the functions will run just fine on such card. Simply add "1.0" to the list of binaries, for example, ``CUDA_ARCH_BIN="1.0 1.3 2.0"`` . The functions that can not be run on CC 1.0 GPUs will throw an exception.
:func:`Exception`
. For platforms where JIT compilation is performed first run will be slow. You can always determine at runtime whether OpenCV GPU built binaries (or PTX code) are compatible with your GPU. The function
:func:`gpu::DeviceInfo::isCompatible` return the compatibility status (true/false).
If you happen to have GPU with CC 1.0, the GPU module can still be compiled on it and most of the functions will run just fine on such card. Simply add "1.0" to the list of binaries, for example,
``CUDA_ARCH_BIN="1.0 1.3 2.0"``
. The functions that can not be run on CC 1.0 GPUs will throw an exception.
You can always determine at runtime whether OpenCV GPU built binaries (or PTX code) are compatible with your GPU. The function
:func:`gpu::DeviceInfo::isCompatible`
return the compatibility status (true/false).
Threading and multi-threading. Threading and multi-threading.
------------------------------ ------------------------------
OpenCV GPU module follows Cuda Runtime API conventions regarding the multi-threaded programming. That is, on first the API call a Cuda context is created implicitly, attached to the current CPU thread and then is used as the thread's "current" context. All further operations, such as memory allocation, GPU code compilation, will be associated with the context and the thread. Because any other thread is not attached to the context, memory (and other resources) allocated in the first thread can not be accessed by the other thread. Instead, for this other thread Cuda will create another context associated with it. In short, by default different threads do not share resources.
OpenCV GPU module follows Cuda Runtime API conventions regarding the multi-threaded programming. That is, on first the API call a Cuda context is created implicitly, attached to the current CPU thread and then is used as the thread's "current" context. All further operations, such as memory allocation, GPU code compilation, will be associated with the context and the thread. Because any other thread is not attached to the context, memory (and other resources) allocated in the first thread can not be accessed by the other thread. Instead, for this other thread Cuda will create another context associated with it. In short, by default different threads do not share resources. But such limitation can be removed using Cuda Driver API (version 3.1 or later). User can retrieve context reference for one thread, attach it to another thread and make it "current" for that thread. Then the threads can share memory and other resources. It is also possible to create a context explicitly before calling any GPU code and attach it to all the threads that you want to share the resources.
But such limitation can be removed using Cuda Driver API (version 3.1 or later). User can retrieve context reference for one thread, attach it to another thread and make it "current" for that thread. Then the threads can share memory and other resources. It is also possible to create a context explicitly before calling any GPU code and attach it to all the threads that you want to share the resources. Also it is possible to create context explicitly using Cuda Driver API, attach and make "current" for all necessary threads. Cuda Runtime API (and OpenCV functions respectively) will pick up it.
Also it is possible to create context explicitly using Cuda Driver API, attach and make "current" for all necessary threads. Cuda Runtime API (and OpenCV functions respectively) will pick up it.
Multi-GPU Multi-GPU
--------- ---------
In the current version each of the OpenCV GPU algorithms can use only a single GPU. So, to utilize multiple GPUs, user has to manually distribute the work between the GPUs. Here are the two ways of utilizing multiple GPUs:
In the current version each of the OpenCV GPU algorithms can use only a single GPU. So, to utilize multiple GPUs, user has to manually distribute the work between the GPUs. Here are the two ways of utilizing multiple GPUs:
* *
If you only use synchronous functions, first, create several CPU threads (one per each GPU) and from within each thread create CUDA context for the corresponding GPU using If you only use synchronous functions, first, create several CPU threads (one per each GPU) and from within each thread create CUDA context for the corresponding GPU using
:func:`gpu::setDevice()` :func:`gpu::setDevice()` or Driver API. That's it. Now each of the threads will use the associated GPU.
or Driver API. That's it. Now each of the threads will use the associated GPU.
* *
In case of asynchronous functions, it is possible to create several Cuda contexts associated with different GPUs but attached to one CPU thread. This can be done only by Driver API. Within the thread you can switch from one GPU to another by making the corresponding context "current". With non-blocking GPU calls managing algorithm is clear. In case of asynchronous functions, it is possible to create several Cuda contexts associated with different GPUs but attached to one CPU thread. This can be done only by Driver API. Within the thread you can switch from one GPU to another by making the corresponding context "current". With non-blocking GPU calls managing algorithm is clear.
While developing algorithms for multiple GPUs a data passing overhead have to be taken into consideration. For primitive functions and for small images it can be significant and eliminate all the advantages of having multiple GPUs. But for high level algorithms Multi-GPU acceleration may be suitable. For example, Stereo Block Matching algorithm has been successfully parallelized using the following algorithm:
While developing algorithms for multiple GPUs a data passing overhead have to be taken into consideration. For primitive functions and for small images it can be significant and eliminate all the advantages of having multiple GPUs. But for high level algorithms Multi-GPU acceleration may be suitable. For example, Stereo Block Matching algorithm has been successfully parallelized using the following algorithm:
* *
Each image of the stereo pair is split into two horizontal overlapping stripes. Each image of the stereo pair is split into two horizontal overlapping stripes.
* *
Each pair of stripes (from the left and the right images) has been processed on a separate Fermi GPU Each pair of stripes (from the left and the right images) has been processed on a separate Fermi GPU
* *
The results are merged into the single disparity map. The results are merged into the single disparity map.
With this scheme dual GPU gave 180 With this scheme dual GPU gave 180
% %
performance increase comparing to the single Fermi GPU. The source code of the example is available at performance increase comparing to the single Fermi GPU. The source code of the example is available at
https://code.ros.org/svn/opencv/trunk/opencv/examples/gpu/ https://code.ros.org/svn/opencv/trunk/opencv/examples/gpu/

325
modules/gpu/doc/matrix_reductions.rst
View File

@ -3,364 +3,171 @@ Matrix Reductions
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::meanStdDev .. index:: gpu::meanStdDev
cv::gpu::meanStdDev cv::gpu::meanStdDev
------------------- -------------------
`id=0.607789005794 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AmeanStdDev>`__
.. cfunction:: void meanStdDev(const GpuMat\& mtx, Scalar\& mean, Scalar\& stddev) .. cfunction:: void meanStdDev(const GpuMat\& mtx, Scalar\& mean, Scalar\& stddev)
Computes mean value and standard deviation of matrix elements. Computes mean value and standard deviation of matrix elements.
:param mtx: Source matrix. ``CV_8UC1`` matrices are supported for now.
:param mean: Mean value.
:param stddev: Standard deviation value.
See also:
:param mtx: Source matrix. ``CV_8UC1`` matrices are supported for now. :func:`meanStdDev` .
:param mean: Mean value.
:param stddev: Standard deviation value.
See also:
:func:`meanStdDev`
.
.. index:: gpu::norm .. index:: gpu::norm
cv::gpu::norm cv::gpu::norm
------------- -------------
`id=0.423726153071 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Anorm>`__
.. cfunction:: double norm(const GpuMat\& src, int normType=NORM_L2) .. cfunction:: double norm(const GpuMat\& src, int normType=NORM_L2)
Returns norm of matrix (or of two matrices difference). Returns norm of matrix (or of two matrices difference).
:param src: Source matrix. Any matrices except 64F are supported.
:param normType: Norm type. ``NORM_L1`` , ``NORM_L2`` and ``NORM_INF`` are supported for now.
:param src: Source matrix. Any matrices except 64F are supported.
:param normType: Norm type. ``NORM_L1`` , ``NORM_L2`` and ``NORM_INF`` are supported for now.
.. cfunction:: double norm(const GpuMat\& src, int normType, GpuMat\& buf) .. cfunction:: double norm(const GpuMat\& src, int normType, GpuMat\& buf)
* **src** Source matrix. Any matrices except 64F are supported.
* **normType** Norm type. ``NORM_L1`` , ``NORM_L2`` and ``NORM_INF`` are supported for now.
* **buf** Optional buffer to avoid extra memory allocations. It's resized automatically.
* **src** Source matrix. Any matrices except 64F are supported.
* **normType** Norm type. ``NORM_L1`` , ``NORM_L2`` and ``NORM_INF`` are supported for now.
* **buf** Optional buffer to avoid extra memory allocations. It's resized automatically.
.. cfunction:: double norm(const GpuMat\& src1, const GpuMat\& src2, int normType=NORM_L2) .. cfunction:: double norm(const GpuMat\& src1, const GpuMat\& src2, int normType=NORM_L2)
* **src1** First source matrix. ``CV_8UC1`` matrices are supported for now.
* **src2** Second source matrix. Must have the same size and type as ``src1``
.
* **normType** Norm type. ``NORM_L1`` , ``NORM_L2`` and ``NORM_INF`` are supported for now.
See also:
:func:`norm` .
* **src1** First source matrix. ``CV_8UC1`` matrices are supported for now.
* **src2** Second source matrix. Must have the same size and type as ``src1``
.
* **normType** Norm type. ``NORM_L1`` , ``NORM_L2`` and ``NORM_INF`` are supported for now.
See also:
:func:`norm`
.
.. index:: gpu::sum .. index:: gpu::sum
cv::gpu::sum cv::gpu::sum
------------ ------------
`id=0.979123982078 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Asum>`__
.. cfunction:: Scalar sum(const GpuMat\& src) .. cfunction:: Scalar sum(const GpuMat\& src)
.. cfunction:: Scalar sum(const GpuMat\& src, GpuMat\& buf) .. cfunction:: Scalar sum(const GpuMat\& src, GpuMat\& buf)
Returns sum of matrix elements. Returns sum of matrix elements.
:param src: Source image of any depth except ``CV_64F`` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
See also:
:func:`sum` .
:param src: Source image of any depth except ``CV_64F`` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
See also:
:func:`sum`
.
.. index:: gpu::absSum .. index:: gpu::absSum
cv::gpu::absSum cv::gpu::absSum
--------------- ---------------
`id=0.607738316178 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AabsSum>`__
.. cfunction:: Scalar absSum(const GpuMat\& src) .. cfunction:: Scalar absSum(const GpuMat\& src)
.. cfunction:: Scalar absSum(const GpuMat\& src, GpuMat\& buf) .. cfunction:: Scalar absSum(const GpuMat\& src, GpuMat\& buf)
Returns sum of matrix elements absolute values. Returns sum of matrix elements absolute values.
:param src: Source image of any depth except ``CV_64F`` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
:param src: Source image of any depth except ``CV_64F`` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
.. index:: gpu::sqrSum .. index:: gpu::sqrSum
cv::gpu::sqrSum cv::gpu::sqrSum
--------------- ---------------
`id=0.470934615291 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AsqrSum>`__
.. cfunction:: Scalar sqrSum(const GpuMat\& src) .. cfunction:: Scalar sqrSum(const GpuMat\& src)
.. cfunction:: Scalar sqrSum(const GpuMat\& src, GpuMat\& buf) .. cfunction:: Scalar sqrSum(const GpuMat\& src, GpuMat\& buf)
Returns squared sum of matrix elements. Returns squared sum of matrix elements.
:param src: Source image of any depth except ``CV_64F`` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
:param src: Source image of any depth except ``CV_64F`` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
.. index:: gpu::minMax .. index:: gpu::minMax
cv::gpu::minMax cv::gpu::minMax
--------------- ---------------
`id=0.0207742957447 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AminMax>`__
.. cfunction:: void minMax(const GpuMat\& src, double* minVal, double* maxVal=0, const GpuMat\& mask=GpuMat()) .. cfunction:: void minMax(const GpuMat\& src, double* minVal, double* maxVal=0, const GpuMat\& mask=GpuMat())
.. cfunction:: void minMax(const GpuMat\& src, double* minVal, double* maxVal, const GpuMat\& mask, GpuMat\& buf) .. cfunction:: void minMax(const GpuMat\& src, double* minVal, double* maxVal, const GpuMat\& mask, GpuMat\& buf)
Finds global minimum and maximum matrix elements and returns their values. Finds global minimum and maximum matrix elements and returns their values.
:param src: Single-channel source image.
:param minVal: Pointer to returned minimum value. ``NULL`` if not required.
:param maxVal: Pointer to returned maximum value. ``NULL`` if not required.
:param mask: Optional mask to select a sub-matrix.
:param src: Single-channel source image.
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
:param minVal: Pointer to returned minimum value. ``NULL`` if not required. Function doesn't work with ``CV_64F`` images on GPU with compute capability
:math:`<` 1.3.
See also:
:param maxVal: Pointer to returned maximum value. ``NULL`` if not required. :func:`minMaxLoc` .
:param mask: Optional mask to select a sub-matrix.
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
Function doesn't work with
``CV_64F``
images on GPU with compute capability
:math:`<`
1.3.
See also:
:func:`minMaxLoc`
.
.. index:: gpu::minMaxLoc .. index:: gpu::minMaxLoc
cv::gpu::minMaxLoc cv::gpu::minMaxLoc
------------------ ------------------
`id=0.985111829483 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AminMaxLoc>`__
.. cfunction:: void minMaxLoc(const GpuMat\& src, double\* minVal, double* maxVal=0, Point* minLoc=0, Point* maxLoc=0, const GpuMat\& mask=GpuMat()) .. cfunction:: void minMaxLoc(const GpuMat\& src, double\* minVal, double* maxVal=0, Point* minLoc=0, Point* maxLoc=0, const GpuMat\& mask=GpuMat())
.. cfunction:: void minMaxLoc(const GpuMat\& src, double* minVal, double* maxVal, Point* minLoc, Point* maxLoc, const GpuMat\& mask, GpuMat\& valbuf, GpuMat\& locbuf) .. cfunction:: void minMaxLoc(const GpuMat\& src, double* minVal, double* maxVal, Point* minLoc, Point* maxLoc, const GpuMat\& mask, GpuMat\& valbuf, GpuMat\& locbuf)
Finds global minimum and maximum matrix elements and returns their values with locations. Finds global minimum and maximum matrix elements and returns their values with locations.
:param src: Single-channel source image.
:param minVal: Pointer to returned minimum value. ``NULL`` if not required.
:param maxVal: Pointer to returned maximum value. ``NULL`` if not required.
:param minValLoc: Pointer to returned minimum location. ``NULL`` if not required.
:param src: Single-channel source image.
:param maxValLoc: Pointer to returned maximum location. ``NULL`` if not required.
:param minVal: Pointer to returned minimum value. ``NULL`` if not required. :param mask: Optional mask to select a sub-matrix.
:param valbuf: Optional values buffer to avoid extra memory allocations. It's resized automatically.
:param maxVal: Pointer to returned maximum value. ``NULL`` if not required.
:param locbuf: Optional locations buffer to avoid extra memory allocations. It's resized automatically.
:param minValLoc: Pointer to returned minimum location. ``NULL`` if not required. Function doesn't work with ``CV_64F`` images on GPU with compute capability
:math:`<` 1.3.
See also:
:param maxValLoc: Pointer to returned maximum location. ``NULL`` if not required. :func:`minMaxLoc` .
:param mask: Optional mask to select a sub-matrix.
:param valbuf: Optional values buffer to avoid extra memory allocations. It's resized automatically.
:param locbuf: Optional locations buffer to avoid extra memory allocations. It's resized automatically.
Function doesn't work with
``CV_64F``
images on GPU with compute capability
:math:`<`
1.3.
See also:
:func:`minMaxLoc`
.
.. index:: gpu::countNonZero .. index:: gpu::countNonZero
cv::gpu::countNonZero cv::gpu::countNonZero
--------------------- ---------------------
`id=0.904273321304 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AcountNonZero>`__
.. cfunction:: int countNonZero(const GpuMat\& src) .. cfunction:: int countNonZero(const GpuMat\& src)
.. cfunction:: int countNonZero(const GpuMat\& src, GpuMat\& buf) .. cfunction:: int countNonZero(const GpuMat\& src, GpuMat\& buf)
Counts non-zero matrix elements. Counts non-zero matrix elements.
:param src: Single-channel source image.
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
Function doesn't work with ``CV_64F`` images on GPU with compute capability
:math:`<` 1.3.
:param src: Single-channel source image. See also:
:func:`countNonZero` .
:param buf: Optional buffer to avoid extra memory allocations. It's resized automatically.
Function doesn't work with
``CV_64F``
images on GPU with compute capability
:math:`<`
1.3.
See also:
:func:`countNonZero`
.

534
modules/gpu/doc/object_detection.rst
View File

@ -3,366 +3,204 @@ Object Detection
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::HOGDescriptor .. index:: gpu::HOGDescriptor
.. _gpu::HOGDescriptor: .. _gpu::HOGDescriptor:
gpu::HOGDescriptor gpu::HOGDescriptor
------------------ ------------------
`id=0.263285034412 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor>`__
.. ctype:: gpu::HOGDescriptor .. ctype:: gpu::HOGDescriptor
Histogram of Oriented Gradients
Histogram of Oriented Gradients
dalal_hog dalal_hog
descriptor and detector. descriptor and detector. ::
struct CV_EXPORTS HOGDescriptor
{
enum { DEFAULT_WIN_SIGMA = -1 };
enum { DEFAULT_NLEVELS = 64 };
enum { DESCR_FORMAT_ROW_BY_ROW, DESCR_FORMAT_COL_BY_COL };
HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16),
Size block_stride=Size(8, 8), Size cell_size=Size(8, 8),
int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA,
double threshold_L2hys=0.2, bool gamma_correction=true,
int nlevels=DEFAULT_NLEVELS);
:: size_t getDescriptorSize() const;
size_t getBlockHistogramSize() const;
void setSVMDetector(const vector<float>& detector);
static vector<float> getDefaultPeopleDetector();
struct CV_EXPORTS HOGDescriptor static vector<float> getPeopleDetector48x96();
{ static vector<float> getPeopleDetector64x128();
enum { DEFAULT_WIN_SIGMA = -1 };
enum { DEFAULT_NLEVELS = 64 };
enum { DESCR_FORMAT_ROW_BY_ROW, DESCR_FORMAT_COL_BY_COL };
HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16),
Size block_stride=Size(8, 8), Size cell_size=Size(8, 8),
int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA,
double threshold_L2hys=0.2, bool gamma_correction=true,
int nlevels=DEFAULT_NLEVELS);
size_t getDescriptorSize() const;
size_t getBlockHistogramSize() const;
void setSVMDetector(const vector<float>& detector);
static vector<float> getDefaultPeopleDetector();
static vector<float> getPeopleDetector48x96();
static vector<float> getPeopleDetector64x128();
void detect(const GpuMat& img, vector<Point>& found_locations,
double hit_threshold=0, Size win_stride=Size(),
Size padding=Size());
void detectMultiScale(const GpuMat& img, vector<Rect>& found_locations,
double hit_threshold=0, Size win_stride=Size(),
Size padding=Size(), double scale0=1.05,
int group_threshold=2);
void getDescriptors(const GpuMat& img, Size win_stride,
GpuMat& descriptors,
int descr_format=DESCR_FORMAT_COL_BY_COL);
Size win_size;
Size block_size;
Size block_stride;
Size cell_size;
int nbins;
double win_sigma;
double threshold_L2hys;
bool gamma_correction;
int nlevels;
private:
// Hidden
}
void detect(const GpuMat& img, vector<Point>& found_locations,
double hit_threshold=0, Size win_stride=Size(),
Size padding=Size());
void detectMultiScale(const GpuMat& img, vector<Rect>& found_locations,
double hit_threshold=0, Size win_stride=Size(),
Size padding=Size(), double scale0=1.05,
int group_threshold=2);
void getDescriptors(const GpuMat& img, Size win_stride,
GpuMat& descriptors,
int descr_format=DESCR_FORMAT_COL_BY_COL);
Size win_size;
Size block_size;
Size block_stride;
Size cell_size;
int nbins;
double win_sigma;
double threshold_L2hys;
bool gamma_correction;
int nlevels;
private:
// Hidden
}
.. ..
Interfaces of all methods are kept similar to CPU HOG descriptor and detector analogues as much as possible. Interfaces of all methods are kept similar to CPU HOG descriptor and detector analogues as much as possible.
.. index:: gpu::HOGDescriptor::HOGDescriptor .. index:: gpu::HOGDescriptor::HOGDescriptor
cv::gpu::HOGDescriptor::HOGDescriptor cv::gpu::HOGDescriptor::HOGDescriptor
------------------------------------- -------------------------------------
`id=0.377426649644 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AHOGDescriptor>`__
.. cfunction:: HOGDescriptor::HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16), Size block_stride=Size(8, 8), Size cell_size=Size(8, 8), int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA, double threshold_L2hys=0.2, bool gamma_correction=true, int nlevels=DEFAULT_NLEVELS) .. cfunction:: HOGDescriptor::HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16), Size block_stride=Size(8, 8), Size cell_size=Size(8, 8), int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA, double threshold_L2hys=0.2, bool gamma_correction=true, int nlevels=DEFAULT_NLEVELS)
Creates HOG descriptor and detector. Creates HOG descriptor and detector.
:param win_size: Detection window size. Must be aligned to block size and block stride.
:param block_size: Block size in pixels. Must be aligned to cell size. Only (16,16) is supported for now.
:param block_stride: Block stride. Must be a multiple of cell size.
:param cell_size: Cell size. Only (8, 8) is supported for now.
:param win_size: Detection window size. Must be aligned to block size and block stride.
:param nbins: Number of bins. Only 9 bins per cell is supported for now.
:param block_size: Block size in pixels. Must be aligned to cell size. Only (16,16) is supported for now. :param win_sigma: Gaussian smoothing window parameter.
:param threshold_L2Hys: L2-Hys normalization method shrinkage.
:param block_stride: Block stride. Must be a multiple of cell size.
:param gamma_correction: Do gamma correction preprocessing or not.
:param cell_size: Cell size. Only (8, 8) is supported for now. :param nlevels: Maximum number of detection window increases.
:param nbins: Number of bins. Only 9 bins per cell is supported for now.
:param win_sigma: Gaussian smoothing window parameter.
:param threshold_L2Hys: L2-Hys normalization method shrinkage.
:param gamma_correction: Do gamma correction preprocessing or not.
:param nlevels: Maximum number of detection window increases.
.. index:: gpu::HOGDescriptor::getDescriptorSize .. index:: gpu::HOGDescriptor::getDescriptorSize
cv::gpu::HOGDescriptor::getDescriptorSize cv::gpu::HOGDescriptor::getDescriptorSize
----------------------------------------- -----------------------------------------
`id=0.25703536307 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AgetDescriptorSize>`__
.. cfunction:: size_t HOGDescriptor::getDescriptorSize() const .. cfunction:: size_t HOGDescriptor::getDescriptorSize() const
Returns number of coefficients required for the classification. Returns number of coefficients required for the classification.
.. index:: gpu::HOGDescriptor::getBlockHistogramSize .. index:: gpu::HOGDescriptor::getBlockHistogramSize
cv::gpu::HOGDescriptor::getBlockHistogramSize cv::gpu::HOGDescriptor::getBlockHistogramSize
--------------------------------------------- ---------------------------------------------
`id=0.91431196569 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AgetBlockHistogramSize>`__
.. cfunction:: size_t HOGDescriptor::getBlockHistogramSize() const .. cfunction:: size_t HOGDescriptor::getBlockHistogramSize() const
Returns block histogram size. Returns block histogram size.
.. index:: gpu::HOGDescriptor::setSVMDetector .. index:: gpu::HOGDescriptor::setSVMDetector
cv::gpu::HOGDescriptor::setSVMDetector cv::gpu::HOGDescriptor::setSVMDetector
-------------------------------------- --------------------------------------
`id=0.719708439759 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AsetSVMDetector>`__
.. cfunction:: void HOGDescriptor::setSVMDetector(const vector<float>\& detector) .. cfunction:: void HOGDescriptor::setSVMDetector(const vector<float>\& detector)
Sets coefficients for the linear SVM classifier. Sets coefficients for the linear SVM classifier.
.. index:: gpu::HOGDescriptor::getDefaultPeopleDetector .. index:: gpu::HOGDescriptor::getDefaultPeopleDetector
cv::gpu::HOGDescriptor::getDefaultPeopleDetector cv::gpu::HOGDescriptor::getDefaultPeopleDetector
------------------------------------------------ ------------------------------------------------
`id=0.941470897866 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AgetDefaultPeopleDetector>`__
.. cfunction:: static vector<float> HOGDescriptor::getDefaultPeopleDetector() .. cfunction:: static vector<float> HOGDescriptor::getDefaultPeopleDetector()
Returns coefficients of the classifier trained for people detection (for default window size). Returns coefficients of the classifier trained for people detection (for default window size).
.. index:: gpu::HOGDescriptor::getPeopleDetector48x96 .. index:: gpu::HOGDescriptor::getPeopleDetector48x96
cv::gpu::HOGDescriptor::getPeopleDetector48x96 cv::gpu::HOGDescriptor::getPeopleDetector48x96
---------------------------------------------- ----------------------------------------------
`id=0.600273723778 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AgetPeopleDetector48x96>`__
.. cfunction:: static vector<float> HOGDescriptor::getPeopleDetector48x96() .. cfunction:: static vector<float> HOGDescriptor::getPeopleDetector48x96()
Returns coefficients of the classifier trained for people detection (for 48x96 windows). Returns coefficients of the classifier trained for people detection (for 48x96 windows).
.. index:: gpu::HOGDescriptor::getPeopleDetector64x128 .. index:: gpu::HOGDescriptor::getPeopleDetector64x128
cv::gpu::HOGDescriptor::getPeopleDetector64x128 cv::gpu::HOGDescriptor::getPeopleDetector64x128
----------------------------------------------- -----------------------------------------------
`id=0.583356812364 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AgetPeopleDetector64x128>`__
.. cfunction:: static vector<float> HOGDescriptor::getPeopleDetector64x128() .. cfunction:: static vector<float> HOGDescriptor::getPeopleDetector64x128()
Returns coefficients of the classifier trained for people detection (for 64x128 windows). Returns coefficients of the classifier trained for people detection (for 64x128 windows).
.. index:: gpu::HOGDescriptor::detect .. index:: gpu::HOGDescriptor::detect
cv::gpu::HOGDescriptor::detect cv::gpu::HOGDescriptor::detect
------------------------------ ------------------------------
`id=0.0364241115122 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3Adetect>`__
.. cfunction:: void HOGDescriptor::detect(const GpuMat\& img, vector<Point>\& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size()) .. cfunction:: void HOGDescriptor::detect(const GpuMat\& img, vector<Point>\& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size())
Perfroms object detection without multiscale window. Perfroms object detection without multiscale window.
:param img: Source image. ``CV_8UC1`` and ``CV_8UC4`` types are supported for now.
:param found_locations: Will contain left-top corner points of detected objects boundaries.
:param hit_threshold: Threshold for the distance between features and SVM classifying plane. Usually it's 0 and should be specfied in the detector coefficients (as the last free coefficient), but if the free coefficient is omitted (it's allowed) you can specify it manually here.
:param win_stride: Window stride. Must be a multiple of block stride.
:param img: Source image. ``CV_8UC1`` and ``CV_8UC4`` types are supported for now.
:param padding: Mock parameter to keep CPU interface compatibility. Must be (0,0).
:param found_locations: Will contain left-top corner points of detected objects boundaries.
:param hit_threshold: Threshold for the distance between features and SVM classifying plane. Usually it's 0 and should be specfied in the detector coefficients (as the last free coefficient), but if the free coefficient is omitted (it's allowed) you can specify it manually here.
:param win_stride: Window stride. Must be a multiple of block stride.
:param padding: Mock parameter to keep CPU interface compatibility. Must be (0,0).
.. index:: gpu::HOGDescriptor::detectMultiScale .. index:: gpu::HOGDescriptor::detectMultiScale
cv::gpu::HOGDescriptor::detectMultiScale cv::gpu::HOGDescriptor::detectMultiScale
---------------------------------------- ----------------------------------------
`id=0.125190830083 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AdetectMultiScale>`__
.. cfunction:: void HOGDescriptor::detectMultiScale(const GpuMat\& img, vector<Rect>\& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size(), double scale0=1.05, int group_threshold=2) .. cfunction:: void HOGDescriptor::detectMultiScale(const GpuMat\& img, vector<Rect>\& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size(), double scale0=1.05, int group_threshold=2)
Perfroms object detection with multiscale window. Perfroms object detection with multiscale window.
:param img: Source image. See :func:`gpu::HOGDescriptor::detect` for type limitations.
:param found_locations: Will contain detected objects boundaries.
:param hit_threshold: The threshold for the distance between features and SVM classifying plane. See :func:`gpu::HOGDescriptor::detect` for details.
:param win_stride: Window stride. Must be a multiple of block stride.
:param img: Source image. See :func:`gpu::HOGDescriptor::detect` for type limitations.
:param padding: Mock parameter to keep CPU interface compatibility. Must be (0,0).
:param found_locations: Will contain detected objects boundaries. :param scale0: Coefficient of the detection window increase.
:param group_threshold: After detection some objects could be covered by many rectangles. This coefficient regulates similarity threshold. 0 means don't perform grouping.
:param hit_threshold: The threshold for the distance between features and SVM classifying plane. See :func:`gpu::HOGDescriptor::detect` for details. See :func:`groupRectangles` .
:param win_stride: Window stride. Must be a multiple of block stride.
:param padding: Mock parameter to keep CPU interface compatibility. Must be (0,0).
:param scale0: Coefficient of the detection window increase.
:param group_threshold: After detection some objects could be covered by many rectangles. This coefficient regulates similarity threshold. 0 means don't perform grouping.
See :func:`groupRectangles` .
.. index:: gpu::HOGDescriptor::getDescriptors .. index:: gpu::HOGDescriptor::getDescriptors
cv::gpu::HOGDescriptor::getDescriptors cv::gpu::HOGDescriptor::getDescriptors
-------------------------------------- --------------------------------------
`id=0.128234884479 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AHOGDescriptor%3A%3AgetDescriptors>`__
.. cfunction:: void HOGDescriptor::getDescriptors(const GpuMat\& img, Size win_stride, GpuMat\& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL) .. cfunction:: void HOGDescriptor::getDescriptors(const GpuMat\& img, Size win_stride, GpuMat\& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL)
Returns block descriptors computed for the whole image. It's mainly used for classifier learning purposes. Returns block descriptors computed for the whole image. It's mainly used for classifier learning purposes.
:param img: Source image. See :func:`gpu::HOGDescriptor::detect` for type limitations.
:param win_stride: Window stride. Must be a multiple of block stride.
:param descriptors: 2D array of descriptors.
:param descr_format: Descriptor storage format:
:param img: Source image. See :func:`gpu::HOGDescriptor::detect` for type limitations.
* **DESCR_FORMAT_ROW_BY_ROW** Row-major order.
:param win_stride: Window stride. Must be a multiple of block stride. * **DESCR_FORMAT_COL_BY_COL** Column-major order.
:param descriptors: 2D array of descriptors.
:param descr_format: Descriptor storage format:
* **DESCR_FORMAT_ROW_BY_ROW** Row-major order.
* **DESCR_FORMAT_COL_BY_COL** Column-major order.
.. index:: gpu::CascadeClassifier_GPU .. index:: gpu::CascadeClassifier_GPU
@ -370,73 +208,45 @@ cv::gpu::HOGDescriptor::getDescriptors
gpu::CascadeClassifier_GPU gpu::CascadeClassifier_GPU
-------------------------- --------------------------
`id=0.362290729184 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ACascadeClassifier_GPU>`__
.. ctype:: gpu::CascadeClassifier_GPU .. ctype:: gpu::CascadeClassifier_GPU
The cascade classifier class for object detection. ::
class CV_EXPORTS CascadeClassifier_GPU
{
public:
CascadeClassifier_GPU();
CascadeClassifier_GPU(const string& filename);
~CascadeClassifier_GPU();
The cascade classifier class for object detection. bool empty() const;
bool load(const string& filename);
void release();
/* returns number of detected objects */
int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size());
/* Finds only the largest object. Special mode for need to training*/
bool findLargestObject;
:: /* Draws rectangles in input image */
bool visualizeInPlace;
class CV_EXPORTS CascadeClassifier_GPU
{
public:
CascadeClassifier_GPU();
CascadeClassifier_GPU(const string& filename);
~CascadeClassifier_GPU();
bool empty() const;
bool load(const string& filename);
void release();
/* returns number of detected objects */
int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size());
/* Finds only the largest object. Special mode for need to training*/
bool findLargestObject;
/* Draws rectangles in input image */
bool visualizeInPlace;
Size getClassifierSize() const;
};
Size getClassifierSize() const;
};
.. ..
.. index:: cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU .. index:: cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU
.. _cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU: .. _cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU:
cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU
----------------------------------------------------- -----------------------------------------------------
`id=0.502164537388 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ACascadeClassifier_GPU%3A%3ACascadeClassifier_GPU>`__
.. cfunction:: cv::CascadeClassifier_GPU(const string\& filename) .. cfunction:: cv::CascadeClassifier_GPU(const string\& filename)
Loads the classifier from file. Loads the classifier from file.
:param filename: Name of file from which classifier will be load. Only old haar classifier (trained by haartraining application) and NVidia's nvbin are supported.
:param filename: Name of file from which classifier will be load. Only old haar classifier (trained by haartraining application) and NVidia's nvbin are supported.
.. index:: cv::gpu::CascadeClassifier_GPU::empty .. index:: cv::gpu::CascadeClassifier_GPU::empty
@ -444,17 +254,9 @@ cv::gpu::CascadeClassifier_GPU::CascadeClassifier_GPU
cv::gpu::CascadeClassifier_GPU::empty cv::gpu::CascadeClassifier_GPU::empty
------------------------------------- -------------------------------------
`id=0.00879679914574 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ACascadeClassifier_GPU%3A%3Aempty>`__
.. cfunction:: bool CascadeClassifier_GPU::empty() const .. cfunction:: bool CascadeClassifier_GPU::empty() const
Checks if the classifier has been loaded or not. Checks if the classifier has been loaded or not.
.. index:: cv::gpu::CascadeClassifier_GPU::load .. index:: cv::gpu::CascadeClassifier_GPU::load
@ -462,24 +264,11 @@ cv::gpu::CascadeClassifier_GPU::empty
cv::gpu::CascadeClassifier_GPU::load cv::gpu::CascadeClassifier_GPU::load
------------------------------------ ------------------------------------
`id=0.831994730738 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ACascadeClassifier_GPU%3A%3Aload>`__
.. cfunction:: bool CascadeClassifier_GPU::load(const string\& filename) .. cfunction:: bool CascadeClassifier_GPU::load(const string\& filename)
Loads the classifier from file. The previous content is destroyed. Loads the classifier from file. The previous content is destroyed.
:param filename: Name of file from which classifier will be load. Only old haar classifier (trained by haartraining application) and NVidia's nvbin are supported.
:param filename: Name of file from which classifier will be load. Only old haar classifier (trained by haartraining application) and NVidia's nvbin are supported.
.. index:: cv::gpu::CascadeClassifier_GPU::release .. index:: cv::gpu::CascadeClassifier_GPU::release
@ -487,17 +276,9 @@ cv::gpu::CascadeClassifier_GPU::load
cv::gpu::CascadeClassifier_GPU::release cv::gpu::CascadeClassifier_GPU::release
--------------------------------------- ---------------------------------------
`id=0.524456582811 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ACascadeClassifier_GPU%3A%3Arelease>`__
.. cfunction:: void CascadeClassifier_GPU::release() .. cfunction:: void CascadeClassifier_GPU::release()
Destroys loaded classifier. Destroys loaded classifier.
.. index:: cv::gpu::CascadeClassifier_GPU::detectMultiScale .. index:: cv::gpu::CascadeClassifier_GPU::detectMultiScale
@ -505,71 +286,42 @@ cv::gpu::CascadeClassifier_GPU::release
cv::gpu::CascadeClassifier_GPU::detectMultiScale cv::gpu::CascadeClassifier_GPU::detectMultiScale
------------------------------------------------ ------------------------------------------------
`id=0.0605957110589 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3ACascadeClassifier_GPU%3A%3AdetectMultiScale>`__
.. cfunction:: int CascadeClassifier_GPU::detectMultiScale(const GpuMat\& image, GpuMat\& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size()) .. cfunction:: int CascadeClassifier_GPU::detectMultiScale(const GpuMat\& image, GpuMat\& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size())
Detects objects of different sizes in the input image. The detected objects are returned as a list of rectangles. Detects objects of different sizes in the input image. The detected objects are returned as a list of rectangles.
:param image: Matrix of type ``CV_8U`` containing the image in which to detect objects.
:param objects: Buffer to store detected objects (rectangles). If it is empty, it will be allocated with default size. If not empty, function will search not more than N objects, where N = sizeof(objectsBufer's data)/sizeof(cv::Rect).
:param scaleFactor: Specifies how much the image size is reduced at each image scale.
:param minNeighbors: Specifies how many neighbors should each candidate rectangle have to retain it.
:param image: Matrix of type ``CV_8U`` containing the image in which to detect objects.
:param objects: Buffer to store detected objects (rectangles). If it is empty, it will be allocated with default size. If not empty, function will search not more than N objects, where N = sizeof(objectsBufer's data)/sizeof(cv::Rect).
:param scaleFactor: Specifies how much the image size is reduced at each image scale.
:param minNeighbors: Specifies how many neighbors should each candidate rectangle have to retain it.
:param minSize: The minimum possible object size. Objects smaller than that are ignored.
The function returns number of detected objects, so you can retrieve them as in following example:
:param minSize: The minimum possible object size. Objects smaller than that are ignored.
The function returns number of detected objects, so you can retrieve them as in following example: ::
:: cv::gpu::CascadeClassifier_GPU cascade_gpu(...);
Mat image_cpu = imread(...)
GpuMat image_gpu(image_cpu);
GpuMat objbuf;
int detections_number = cascade_gpu.detectMultiScale( image_gpu,
cv::gpu::CascadeClassifier_GPU cascade_gpu(...); objbuf, 1.2, minNeighbors);
Mat image_cpu = imread(...)
GpuMat image_gpu(image_cpu);
GpuMat objbuf;
int detections_number = cascade_gpu.detectMultiScale( image_gpu,
objbuf, 1.2, minNeighbors);
Mat obj_host;
// download only detected number of rectangles
objbuf.colRange(0, detections_number).download(obj_host);
Rect* faces = obj_host.ptr<Rect>();
for(int i = 0; i < detections_num; ++i)
cv::rectangle(image_cpu, faces[i], Scalar(255));
imshow("Faces", image_cpu);
Mat obj_host;
// download only detected number of rectangles
objbuf.colRange(0, detections_number).download(obj_host);
Rect* faces = obj_host.ptr<Rect>();
for(int i = 0; i < detections_num; ++i)
cv::rectangle(image_cpu, faces[i], Scalar(255));
imshow("Faces", image_cpu);
.. ..
See also: See also:
:func:`CascadeClassifier::detectMultiScale` :func:`CascadeClassifier::detectMultiScale` .
.

449
modules/gpu/doc/operations_on_matrices.rst
View File

@ -3,507 +3,246 @@ Operations on Matrices
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::transpose .. index:: gpu::transpose
cv::gpu::transpose cv::gpu::transpose
------------------ ------------------
`id=0.581518039061 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Atranspose>`__
.. cfunction:: void transpose(const GpuMat\& src, GpuMat\& dst) .. cfunction:: void transpose(const GpuMat\& src, GpuMat\& dst)
Transposes a matrix. Transposes a matrix.
:param src: Source matrix. 1, 4, 8 bytes element sizes are supported for now.
:param dst: Destination matrix.
See also:
:func:`transpose` .
:param src: Source matrix. 1, 4, 8 bytes element sizes are supported for now.
:param dst: Destination matrix.
See also:
:func:`transpose`
.
.. index:: gpu::flip .. index:: gpu::flip
cv::gpu::flip cv::gpu::flip
------------- -------------
`id=0.29725445638 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Aflip>`__
.. cfunction:: void flip(const GpuMat\& a, GpuMat\& b, int flipCode) .. cfunction:: void flip(const GpuMat\& a, GpuMat\& b, int flipCode)
Flips a 2D matrix around vertical, horizontal or both axes. Flips a 2D matrix around vertical, horizontal or both axes.
:param a: Source matrix. Only ``CV_8UC1`` and ``CV_8UC4`` matrices are supported for now.
:param b: Destination matrix.
:param flipCode: Specifies how to flip the source:
* **0** Flip around x-axis.
* **:math:`>`0** Flip around y-axis.
* **:math:`<`0** Flip around both axes.
See also:
:param a: Source matrix. Only ``CV_8UC1`` and ``CV_8UC4`` matrices are supported for now. :func:`flip` .
:param b: Destination matrix.
:param flipCode: Specifies how to flip the source:
* **0** Flip around x-axis.
* **:math:`>`0** Flip around y-axis.
* **:math:`<`0** Flip around both axes.
See also:
:func:`flip`
.
.. index:: gpu::LUT .. index:: gpu::LUT
cv::gpu::LUT cv::gpu::LUT
------------ ------------
`id=0.279602538414 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ALUT>`__
.. math:: .. math::
dst(I) = lut(src(I)) dst(I) = lut(src(I))
.. cfunction:: void LUT(const GpuMat\& src, const Mat\& lut, GpuMat\& dst) .. cfunction:: void LUT(const GpuMat\& src, const Mat\& lut, GpuMat\& dst)
Transforms the source matrix into the destination matrix using given look-up table: Transforms the source matrix into the destination matrix using given look-up table:
:param src: Source matrix. ``CV_8UC1`` and ``CV_8UC3`` matrixes are supported for now.
:param lut: Look-up table. Must be continuous, ``CV_8U`` depth matrix. Its area must satisfy to ``lut.rows`` :math:`\times` ``lut.cols`` = 256 condition.
:param dst: Destination matrix. Will have the same depth as ``lut`` and the same number of channels as ``src`` .
See also:
:param src: Source matrix. ``CV_8UC1`` and ``CV_8UC3`` matrixes are supported for now. :func:`LUT` .
:param lut: Look-up table. Must be continuous, ``CV_8U`` depth matrix. Its area must satisfy to ``lut.rows`` :math:`\times` ``lut.cols`` = 256 condition.
:param dst: Destination matrix. Will have the same depth as ``lut`` and the same number of channels as ``src`` .
See also:
:func:`LUT`
.
.. index:: gpu::merge .. index:: gpu::merge
cv::gpu::merge cv::gpu::merge
-------------- --------------
`id=0.568969773318 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Amerge>`__
.. cfunction:: void merge(const GpuMat* src, size_t n, GpuMat\& dst) .. cfunction:: void merge(const GpuMat* src, size_t n, GpuMat\& dst)
.. cfunction:: void merge(const GpuMat* src, size_t n, GpuMat\& dst, const Stream\& stream) .. cfunction:: void merge(const GpuMat* src, size_t n, GpuMat\& dst, const Stream\& stream)
Makes a multi-channel matrix out of several single-channel matrices. Makes a multi-channel matrix out of several single-channel matrices.
:param src: Pointer to array of the source matrices.
:param n: Number of source matrices.
:param dst: Destination matrix.
:param stream: Stream for the asynchronous version.
:param src: Pointer to array of the source matrices.
:param n: Number of source matrices.
:param dst: Destination matrix.
:param stream: Stream for the asynchronous version.
.. cfunction:: void merge(const vector$<$GpuMat$>$\& src, GpuMat\& dst) .. cfunction:: void merge(const vector$<$GpuMat$>$\& src, GpuMat\& dst)
.. cfunction:: void merge(const vector$<$GpuMat$>$\& src, GpuMat\& dst, const Stream\& stream) .. cfunction:: void merge(const vector$<$GpuMat$>$\& src, GpuMat\& dst, const Stream\& stream)
* **src** Vector of the source matrices.
* **dst** Destination matrix.
* **stream** Stream for the asynchronous version.
See also:
:func:`merge` .
* **src** Vector of the source matrices.
* **dst** Destination matrix.
* **stream** Stream for the asynchronous version.
See also:
:func:`merge`
.
.. index:: gpu::split .. index:: gpu::split
cv::gpu::split cv::gpu::split
-------------- --------------
`id=0.117653518739 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Asplit>`__
.. cfunction:: void split(const GpuMat\& src, GpuMat* dst) .. cfunction:: void split(const GpuMat\& src, GpuMat* dst)
.. cfunction:: void split(const GpuMat\& src, GpuMat* dst, const Stream\& stream) .. cfunction:: void split(const GpuMat\& src, GpuMat* dst, const Stream\& stream)
Copies each plane of a multi-channel matrix into an array. Copies each plane of a multi-channel matrix into an array.
:param src: Source matrix.
:param dst: Pointer to array of single-channel matrices.
:param stream: Stream for the asynchronous version.
:param src: Source matrix.
:param dst: Pointer to array of single-channel matrices.
:param stream: Stream for the asynchronous version.
.. cfunction:: void split(const GpuMat\& src, vector$<$GpuMat$>$\& dst) .. cfunction:: void split(const GpuMat\& src, vector$<$GpuMat$>$\& dst)
.. cfunction:: void split(const GpuMat\& src, vector$<$GpuMat$>$\& dst, const Stream\& stream) .. cfunction:: void split(const GpuMat\& src, vector$<$GpuMat$>$\& dst, const Stream\& stream)
* **src** Source matrix.
* **dst** Destination vector of single-channel matrices.
* **stream** Stream for the asynchronous version.
See also:
:func:`split` .
* **src** Source matrix.
* **dst** Destination vector of single-channel matrices.
* **stream** Stream for the asynchronous version.
See also:
:func:`split`
.
.. index:: gpu::magnitude .. index:: gpu::magnitude
cv::gpu::magnitude cv::gpu::magnitude
------------------ ------------------
`id=0.0879492693083 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Amagnitude>`__
.. cfunction:: void magnitude(const GpuMat\& x, GpuMat\& magnitude) .. cfunction:: void magnitude(const GpuMat\& x, GpuMat\& magnitude)
Computes magnitudes of complex matrix elements. Computes magnitudes of complex matrix elements.
:param x: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
:param magnitude: Destination matrix of float magnitudes ( ``CV_32FC1`` ).
:param x: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
:param magnitude: Destination matrix of float magnitudes ( ``CV_32FC1`` ).
.. cfunction:: void magnitude(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude) .. cfunction:: void magnitude(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude)
.. cfunction:: void magnitude(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, const Stream\& stream) .. cfunction:: void magnitude(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, const Stream\& stream)
* **x** Source matrix, containing real components ( ``CV_32FC1`` ).
* **y** Source matrix, containing imaginary components ( ``CV_32FC1`` ).
* **magnitude** Destination matrix of float magnitudes ( ``CV_32FC1`` ).
* **stream** Stream for the asynchronous version.
See also:
* **x** Source matrix, containing real components ( ``CV_32FC1`` ). :func:`magnitude` .
* **y** Source matrix, containing imaginary components ( ``CV_32FC1`` ).
* **magnitude** Destination matrix of float magnitudes ( ``CV_32FC1`` ).
* **stream** Stream for the asynchronous version.
See also:
:func:`magnitude`
.
.. index:: gpu::magnitudeSqr .. index:: gpu::magnitudeSqr
cv::gpu::magnitudeSqr cv::gpu::magnitudeSqr
--------------------- ---------------------
`id=0.0350196817871 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AmagnitudeSqr>`__
.. cfunction:: void magnitudeSqr(const GpuMat\& x, GpuMat\& magnitude) .. cfunction:: void magnitudeSqr(const GpuMat\& x, GpuMat\& magnitude)
Computes squared magnitudes of complex matrix elements. Computes squared magnitudes of complex matrix elements.
:param x: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
:param magnitude: Destination matrix of float magnitude squares ( ``CV_32FC1`` ).
:param x: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
:param magnitude: Destination matrix of float magnitude squares ( ``CV_32FC1`` ).
.. cfunction:: void magnitudeSqr(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude) .. cfunction:: void magnitudeSqr(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude)
.. cfunction:: void magnitudeSqr(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, const Stream\& stream) .. cfunction:: void magnitudeSqr(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, const Stream\& stream)
* **x** Source matrix, containing real components ( ``CV_32FC1`` ).
* **y** Source matrix, containing imaginary components ( ``CV_32FC1`` ).
* **magnitude** Destination matrix of float magnitude squares ( ``CV_32FC1`` ).
* **stream** Stream for the asynchronous version.
* **x** Source matrix, containing real components ( ``CV_32FC1`` ).
* **y** Source matrix, containing imaginary components ( ``CV_32FC1`` ).
* **magnitude** Destination matrix of float magnitude squares ( ``CV_32FC1`` ).
* **stream** Stream for the asynchronous version.
.. index:: gpu::phase .. index:: gpu::phase
cv::gpu::phase cv::gpu::phase
-------------- --------------
`id=0.274224468378 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Aphase>`__
.. cfunction:: void phase(const GpuMat\& x, const GpuMat\& y, GpuMat\& angle, bool angleInDegrees=false) .. cfunction:: void phase(const GpuMat\& x, const GpuMat\& y, GpuMat\& angle, bool angleInDegrees=false)
.. cfunction:: void phase(const GpuMat\& x, const GpuMat\& y, GpuMat\& angle, bool angleInDegrees, const Stream\& stream) .. cfunction:: void phase(const GpuMat\& x, const GpuMat\& y, GpuMat\& angle, bool angleInDegrees, const Stream\& stream)
Computes polar angles of complex matrix elements. Computes polar angles of complex matrix elements.
:param x: Source matrix, containing real components ( ``CV_32FC1`` ).
:param y: Source matrix, containing imaginary components ( ``CV_32FC1`` ).
:param angle: Destionation matrix of angles ( ``CV_32FC1`` ).
:param angleInDegress: Flag which indicates angles must be evaluated in degress.
:param x: Source matrix, containing real components ( ``CV_32FC1`` ).
:param stream: Stream for the asynchronous version.
:param y: Source matrix, containing imaginary components ( ``CV_32FC1`` ). See also:
:func:`phase` .
:param angle: Destionation matrix of angles ( ``CV_32FC1`` ).
:param angleInDegress: Flag which indicates angles must be evaluated in degress.
:param stream: Stream for the asynchronous version.
See also:
:func:`phase`
.
.. index:: gpu::cartToPolar .. index:: gpu::cartToPolar
cv::gpu::cartToPolar cv::gpu::cartToPolar
-------------------- --------------------
`id=0.813292348151 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3AcartToPolar>`__
.. cfunction:: void cartToPolar(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, GpuMat\& angle, bool angleInDegrees=false) .. cfunction:: void cartToPolar(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, GpuMat\& angle, bool angleInDegrees=false)
.. cfunction:: void cartToPolar(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, GpuMat\& angle, bool angleInDegrees, const Stream\& stream) .. cfunction:: void cartToPolar(const GpuMat\& x, const GpuMat\& y, GpuMat\& magnitude, GpuMat\& angle, bool angleInDegrees, const Stream\& stream)
Converts Cartesian coordinates into polar. Converts Cartesian coordinates into polar.
:param x: Source matrix, containing real components ( ``CV_32FC1`` ).
:param y: Source matrix, containing imaginary components ( ``CV_32FC1`` ).
:param magnitude: Destination matrix of float magnituds ( ``CV_32FC1`` ).
:param angle: Destionation matrix of angles ( ``CV_32FC1`` ).
:param x: Source matrix, containing real components ( ``CV_32FC1`` ).
:param angleInDegress: Flag which indicates angles must be evaluated in degress.
:param y: Source matrix, containing imaginary components ( ``CV_32FC1`` ). :param stream: Stream for the asynchronous version.
See also:
:param magnitude: Destination matrix of float magnituds ( ``CV_32FC1`` ). :func:`cartToPolar` .
:param angle: Destionation matrix of angles ( ``CV_32FC1`` ).
:param angleInDegress: Flag which indicates angles must be evaluated in degress.
:param stream: Stream for the asynchronous version.
See also:
:func:`cartToPolar`
.
.. index:: gpu::polarToCart .. index:: gpu::polarToCart
cv::gpu::polarToCart cv::gpu::polarToCart
-------------------- --------------------
`id=0.108746506092 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3ApolarToCart>`__
.. cfunction:: void polarToCart(const GpuMat\& magnitude, const GpuMat\& angle, GpuMat\& x, GpuMat\& y, bool angleInDegrees=false) .. cfunction:: void polarToCart(const GpuMat\& magnitude, const GpuMat\& angle, GpuMat\& x, GpuMat\& y, bool angleInDegrees=false)
.. cfunction:: void polarToCart(const GpuMat\& magnitude, const GpuMat\& angle, GpuMat\& x, GpuMat\& y, bool angleInDegrees, const Stream\& stream) .. cfunction:: void polarToCart(const GpuMat\& magnitude, const GpuMat\& angle, GpuMat\& x, GpuMat\& y, bool angleInDegrees, const Stream\& stream)
Converts polar coordinates into Cartesian. Converts polar coordinates into Cartesian.
:param magnitude: Source matrix, containing magnitudes ( ``CV_32FC1`` ).
:param angle: Source matrix, containing angles ( ``CV_32FC1`` ).
:param x: Destination matrix of real components ( ``CV_32FC1`` ).
:param y: Destination matrix of imaginary components ( ``CV_32FC1`` ).
:param magnitude: Source matrix, containing magnitudes ( ``CV_32FC1`` ).
:param angleInDegress: Flag which indicates angles are in degress.
:param angle: Source matrix, containing angles ( ``CV_32FC1`` ). :param stream: Stream for the asynchronous version.
See also:
:param x: Destination matrix of real components ( ``CV_32FC1`` ). :func:`polarToCart` .
:param y: Destination matrix of imaginary components ( ``CV_32FC1`` ).
:param angleInDegress: Flag which indicates angles are in degress.
:param stream: Stream for the asynchronous version.
See also:
:func:`polarToCart`
.

634
modules/gpu/doc/per_element_operations..rst
View File

@ -3,405 +3,190 @@ Per-element Operations.
.. highlight:: cpp .. highlight:: cpp
.. index:: gpu::add .. index:: gpu::add
cv::gpu::add cv::gpu::add
------------ ------------
`id=0.387694196113 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Aadd>`__
.. cfunction:: void add(const GpuMat\& a, const GpuMat\& b, GpuMat\& c) .. cfunction:: void add(const GpuMat\& a, const GpuMat\& b, GpuMat\& c)
Computes matrix-matrix or matrix-scalar sum. Computes matrix-matrix or matrix-scalar sum.
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destination matrix. Will have the same size and type as ``a`` .
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destination matrix. Will have the same size and type as ``a`` .
.. cfunction:: void add(const GpuMat\& a, const Scalar\& sc, GpuMat\& c) .. cfunction:: void add(const GpuMat\& a, const Scalar\& sc, GpuMat\& c)
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Source scalar to be added to the source matrix.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`add` .
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Source scalar to be added to the source matrix.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`add`
.
.. index:: gpu::subtract .. index:: gpu::subtract
cv::gpu::subtract cv::gpu::subtract
----------------- -----------------
`id=0.316386979537 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Asubtract>`__
.. cfunction:: void subtract(const GpuMat\& a, const GpuMat\& b, GpuMat\& c) .. cfunction:: void subtract(const GpuMat\& a, const GpuMat\& b, GpuMat\& c)
Subtracts matrix from another matrix (or scalar from matrix). Subtracts matrix from another matrix (or scalar from matrix).
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destination matrix. Will have the same size and type as ``a`` .
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destination matrix. Will have the same size and type as ``a`` .
.. cfunction:: void subtract(const GpuMat\& a, const Scalar\& sc, GpuMat\& c) .. cfunction:: void subtract(const GpuMat\& a, const Scalar\& sc, GpuMat\& c)
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Scalar to be subtracted from the source matrix elements.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`subtract` .
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Scalar to be subtracted from the source matrix elements.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`subtract`
.
.. index:: gpu::multiply .. index:: gpu::multiply
cv::gpu::multiply cv::gpu::multiply
----------------- -----------------
`id=0.12843407457 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Amultiply>`__
.. cfunction:: void multiply(const GpuMat\& a, const GpuMat\& b, GpuMat\& c) .. cfunction:: void multiply(const GpuMat\& a, const GpuMat\& b, GpuMat\& c)
Computes per-element product of two matrices (or of matrix and scalar). Computes per-element product of two matrices (or of matrix and scalar).
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destionation matrix. Will have the same size and type as ``a`` .
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destionation matrix. Will have the same size and type as ``a`` .
.. cfunction:: void multiply(const GpuMat\& a, const Scalar\& sc, GpuMat\& c) .. cfunction:: void multiply(const GpuMat\& a, const Scalar\& sc, GpuMat\& c)
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Scalar to be multiplied by.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`multiply` .
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Scalar to be multiplied by.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`multiply`
.
.. index:: gpu::divide .. index:: gpu::divide
cv::gpu::divide cv::gpu::divide
--------------- ---------------
`id=0.178699823123 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Adivide>`__
.. cfunction:: void divide(const GpuMat\& a, const GpuMat\& b, GpuMat\& c) .. cfunction:: void divide(const GpuMat\& a, const GpuMat\& b, GpuMat\& c)
Performs per-element division of two matrices (or division of matrix by scalar). Performs per-element division of two matrices (or division of matrix by scalar).
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destionation matrix. Will have the same size and type as ``a`` .
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destionation matrix. Will have the same size and type as ``a`` .
.. cfunction:: void divide(const GpuMat\& a, const Scalar\& sc, GpuMat\& c) .. cfunction:: void divide(const GpuMat\& a, const Scalar\& sc, GpuMat\& c)
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now.
* **b** Scalar to be divided by.
* **c** Destination matrix. Will have the same size and type as ``a`` .
This function in contrast to
:func:`divide` uses round-down rounding mode.
See also:
* **a** Source matrix. ``CV_32FC1`` and ``CV_32FC2`` matrixes are supported for now. :func:`divide` .
* **b** Scalar to be divided by.
* **c** Destination matrix. Will have the same size and type as ``a`` .
This function in contrast to
:func:`divide`
uses round-down rounding mode.
See also:
:func:`divide`
.
.. index:: gpu::exp .. index:: gpu::exp
cv::gpu::exp cv::gpu::exp
------------ ------------
`id=0.0437158645609 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Aexp>`__
.. cfunction:: void exp(const GpuMat\& a, GpuMat\& b) .. cfunction:: void exp(const GpuMat\& a, GpuMat\& b)
Computes exponent of each matrix element. Computes exponent of each matrix element.
:param a: Source matrix. ``CV_32FC1`` matrixes are supported for now.
:param b: Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`exp` .
:param a: Source matrix. ``CV_32FC1`` matrixes are supported for now.
:param b: Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`exp`
.
.. index:: gpu::log .. index:: gpu::log
cv::gpu::log cv::gpu::log
------------ ------------
`id=0.726514219732 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Alog>`__
.. cfunction:: void log(const GpuMat\& a, GpuMat\& b) .. cfunction:: void log(const GpuMat\& a, GpuMat\& b)
Computes natural logarithm of absolute value of each matrix element. Computes natural logarithm of absolute value of each matrix element.
:param a: Source matrix. ``CV_32FC1`` matrixes are supported for now.
:param b: Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`log` .
:param a: Source matrix. ``CV_32FC1`` matrixes are supported for now.
:param b: Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`log`
.
.. index:: gpu::absdiff .. index:: gpu::absdiff
cv::gpu::absdiff cv::gpu::absdiff
---------------- ----------------
`id=0.0449517502969 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Aabsdiff>`__
.. cfunction:: void absdiff(const GpuMat\& a, const GpuMat\& b, GpuMat\& c) .. cfunction:: void absdiff(const GpuMat\& a, const GpuMat\& b, GpuMat\& c)
Computes per-element absolute difference of two matrices (or of matrix and scalar). Computes per-element absolute difference of two matrices (or of matrix and scalar).
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destionation matrix. Will have the same size and type as ``a`` .
:param a: First source matrix. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destionation matrix. Will have the same size and type as ``a`` .
.. cfunction:: void absdiff(const GpuMat\& a, const Scalar\& s, GpuMat\& c) .. cfunction:: void absdiff(const GpuMat\& a, const Scalar\& s, GpuMat\& c)
* **a** Source matrix. ``CV_32FC1`` matrixes are supported for now.
* **b** Scalar to be subtracted from the source matrix elements.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`absdiff` .
* **a** Source matrix. ``CV_32FC1`` matrixes are supported for now.
* **b** Scalar to be subtracted from the source matrix elements.
* **c** Destination matrix. Will have the same size and type as ``a`` .
See also:
:func:`absdiff`
.
.. index:: gpu::compare .. index:: gpu::compare
cv::gpu::compare cv::gpu::compare
---------------- ----------------
`id=0.346307736999 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Acompare>`__
.. cfunction:: void compare(const GpuMat\& a, const GpuMat\& b, GpuMat\& c, int cmpop) .. cfunction:: void compare(const GpuMat\& a, const GpuMat\& b, GpuMat\& c, int cmpop)
Compares elements of two matrices. Compares elements of two matrices.
:param a: First source matrix. ``CV_8UC4`` and ``CV_32FC1`` matrices are supported for now.
:param b: Second source matrix. Must have the same size and type as ``a`` .
:param c: Destination matrix. Will have the same size as ``a`` and be ``CV_8UC1`` type.
:param cmpop: Flag specifying the relation between the elements to be checked:
:param a: First source matrix. ``CV_8UC4`` and ``CV_32FC1`` matrices are supported for now.
* **CMP_EQ** :math:`=`
* **CMP_GT** :math:`>`
:param b: Second source matrix. Must have the same size and type as ``a`` . * **CMP_GE** :math:`\ge`
* **CMP_LT** :math:`<`
* **CMP_LE** :math:`\le`
:param c: Destination matrix. Will have the same size as ``a`` and be ``CV_8UC1`` type. * **CMP_NE** :math:`\ne`
:param cmpop: Flag specifying the relation between the elements to be checked: See also:
:func:`compare` .
* **CMP_EQ** :math:`=`
* **CMP_GT** :math:`>`
* **CMP_GE** :math:`\ge`
* **CMP_LT** :math:`<`
* **CMP_LE** :math:`\le`
* **CMP_NE** :math:`\ne`
See also:
:func:`compare`
.
.. index:: cv::gpu::bitwise_not .. index:: cv::gpu::bitwise_not
@ -409,42 +194,22 @@ See also:
cv::gpu::bitwise_not cv::gpu::bitwise_not
-------------------- --------------------
`id=0.242780097451 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3Abitwise_not>`__
.. cfunction:: void bitwise_not(const GpuMat\& src, GpuMat\& dst, const GpuMat\& mask=GpuMat()) .. cfunction:: void bitwise_not(const GpuMat\& src, GpuMat\& dst, const GpuMat\& mask=GpuMat())
.. cfunction:: void bitwise_not(const GpuMat\& src, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream) .. cfunction:: void bitwise_not(const GpuMat\& src, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream)
Performs per-element bitwise inversion. Performs per-element bitwise inversion.
:param src: Source matrix.
:param dst: Destination matrix. Will have the same size and type as ``src`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param stream: Stream for the asynchronous version.
:param src: Source matrix.
See also:
.
:param dst: Destination matrix. Will have the same size and type as ``src`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param stream: Stream for the asynchronous version.
See also:
.
.. index:: cv::gpu::bitwise_or .. index:: cv::gpu::bitwise_or
@ -452,45 +217,24 @@ See also:
cv::gpu::bitwise_or cv::gpu::bitwise_or
------------------- -------------------
`id=0.762303417062 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3Abitwise_or>`__
.. cfunction:: void bitwise_or(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask=GpuMat()) .. cfunction:: void bitwise_or(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask=GpuMat())
.. cfunction:: void bitwise_or(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream) .. cfunction:: void bitwise_or(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream)
Performs per-element bitwise disjunction of two matrices. Performs per-element bitwise disjunction of two matrices.
:param src1: First source matrix.
:param src2: Second source matrix. It must have the same size and type as ``src1`` .
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param src1: First source matrix.
:param stream: Stream for the asynchronous version.
:param src2: Second source matrix. It must have the same size and type as ``src1`` . See also:
.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param stream: Stream for the asynchronous version.
See also:
.
.. index:: cv::gpu::bitwise_and .. index:: cv::gpu::bitwise_and
@ -498,45 +242,24 @@ See also:
cv::gpu::bitwise_and cv::gpu::bitwise_and
-------------------- --------------------
`id=0.621591376205 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3Abitwise_and>`__
.. cfunction:: void bitwise_and(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask=GpuMat()) .. cfunction:: void bitwise_and(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask=GpuMat())
.. cfunction:: void bitwise_and(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream) .. cfunction:: void bitwise_and(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream)
Performs per-element bitwise conjunction of two matrices. Performs per-element bitwise conjunction of two matrices.
:param src1: First source matrix.
:param src2: Second source matrix. It must have the same size and type as ``src1`` .
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param src1: First source matrix.
:param stream: Stream for the asynchronous version.
:param src2: Second source matrix. It must have the same size and type as ``src1`` . See also:
.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param stream: Stream for the asynchronous version.
See also:
.
.. index:: cv::gpu::bitwise_xor .. index:: cv::gpu::bitwise_xor
@ -544,178 +267,87 @@ See also:
cv::gpu::bitwise_xor cv::gpu::bitwise_xor
-------------------- --------------------
`id=0.684217951074 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/cv%3A%3Agpu%3A%3Abitwise_xor>`__
.. cfunction:: void bitwise_xor(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask=GpuMat()) .. cfunction:: void bitwise_xor(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask=GpuMat())
.. cfunction:: void bitwise_xor(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream) .. cfunction:: void bitwise_xor(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const GpuMat\& mask, const Stream\& stream)
Performs per-element bitwise "exclusive or" of two matrices. Performs per-element bitwise "exclusive or" of two matrices.
:param src1: First source matrix.
:param src2: Second source matrix. It must have the same size and type as ``src1`` .
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param src1: First source matrix.
:param stream: Stream for the asynchronous version.
:param src2: Second source matrix. It must have the same size and type as ``src1`` . See also:
.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param mask: Optional operation mask. 8-bit single channel image.
:param stream: Stream for the asynchronous version.
See also:
.
.. index:: gpu::min .. index:: gpu::min
cv::gpu::min cv::gpu::min
------------ ------------
`id=0.276176266158 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Amin>`__
.. cfunction:: void min(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst) .. cfunction:: void min(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst)
.. cfunction:: void min(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const Stream\& stream) .. cfunction:: void min(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const Stream\& stream)
Computes per-element minimum of two matrices (or of matrix and scalar). Computes per-element minimum of two matrices (or of matrix and scalar).
:param src1: First source matrix.
:param src2: Second source matrix.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param stream: Stream for the asynchronous version.
:param src1: First source matrix.
:param src2: Second source matrix.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param stream: Stream for the asynchronous version.
.. cfunction:: void min(const GpuMat\& src1, double src2, GpuMat\& dst) .. cfunction:: void min(const GpuMat\& src1, double src2, GpuMat\& dst)
.. cfunction:: void min(const GpuMat\& src1, double src2, GpuMat\& dst, const Stream\& stream) .. cfunction:: void min(const GpuMat\& src1, double src2, GpuMat\& dst, const Stream\& stream)
* **src1** Source matrix.
* **src2** Scalar to be compared with.
* **dst** Destination matrix. Will have the same size and type as ``src1`` .
* **stream** Stream for the asynchronous version.
See also:
* **src1** Source matrix. :func:`min` .
* **src2** Scalar to be compared with.
* **dst** Destination matrix. Will have the same size and type as ``src1`` .
* **stream** Stream for the asynchronous version.
See also:
:func:`min`
.
.. index:: gpu::max .. index:: gpu::max
cv::gpu::max cv::gpu::max
------------ ------------
`id=0.175554622377 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/gpu/gpu%3A%3Amax>`__
.. cfunction:: void max(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst) .. cfunction:: void max(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst)
.. cfunction:: void max(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const Stream\& stream) .. cfunction:: void max(const GpuMat\& src1, const GpuMat\& src2, GpuMat\& dst, const Stream\& stream)
Computes per-element maximum of two matrices (or of matrix and scalar). Computes per-element maximum of two matrices (or of matrix and scalar).
:param src1: First source matrix.
:param src2: Second source matrix.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param stream: Stream for the asynchronous version.
:param src1: First source matrix.
:param src2: Second source matrix.
:param dst: Destination matrix. Will have the same size and type as ``src1`` .
:param stream: Stream for the asynchronous version.
.. cfunction:: void max(const GpuMat\& src1, double src2, GpuMat\& dst) .. cfunction:: void max(const GpuMat\& src1, double src2, GpuMat\& dst)
.. cfunction:: void max(const GpuMat\& src1, double src2, GpuMat\& dst, const Stream\& stream) .. cfunction:: void max(const GpuMat\& src1, double src2, GpuMat\& dst, const Stream\& stream)
* **src1** Source matrix.
* **src2** Scalar to be compared with.
* **dst** Destination matrix. Will have the same size and type as ``src1`` .
* **stream** Stream for the asynchronous version.
See also:
* **src1** Source matrix. :func:`max` .
* **src2** Scalar to be compared with.
* **dst** Destination matrix. Will have the same size and type as ``src1`` .
* **stream** Stream for the asynchronous version.
See also:
:func:`max`
.

8
modules/highgui/doc/highgui.rst
View File

@ -1,7 +1,6 @@
**************************** *************************************
High-level GUI and Media I/O highgui. High-level GUI and Media I/O
**************************** *************************************
While OpenCV was designed for use in full-scale While OpenCV was designed for use in full-scale
applications and can be used within functionally rich UI frameworks (such as Qt, WinForms or Cocoa) or without any UI at all, sometimes there is a need to try some functionality quickly and visualize the results. This is what the HighGUI module has been designed for. applications and can be used within functionally rich UI frameworks (such as Qt, WinForms or Cocoa) or without any UI at all, sometimes there is a need to try some functionality quickly and visualize the results. This is what the HighGUI module has been designed for.
@ -12,7 +11,6 @@ It provides easy interface to:
* add trackbars to the windows, handle simple mouse events as well as keyboard commmands * add trackbars to the windows, handle simple mouse events as well as keyboard commmands
* read and write images to/from disk or memory. * read and write images to/from disk or memory.
* read video from camera or file and write video to a file. * read video from camera or file and write video to a file.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

12
modules/highgui/doc/highgui__high-level_gui_and_media_i_o.rst
View File

@ -2,34 +2,22 @@
highgui. High-level GUI and Media I/O highgui. High-level GUI and Media I/O
************************************* *************************************
While OpenCV was designed for use in full-scale While OpenCV was designed for use in full-scale
applications and can be used within functionally rich UI frameworks (such as Qt, WinForms or Cocoa) or without any UI at all, sometimes there is a need to try some functionality quickly and visualize the results. This is what the HighGUI module has been designed for. applications and can be used within functionally rich UI frameworks (such as Qt, WinForms or Cocoa) or without any UI at all, sometimes there is a need to try some functionality quickly and visualize the results. This is what the HighGUI module has been designed for.
It provides easy interface to: It provides easy interface to:
* *
create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS) create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS)
* *
add trackbars to the windows, handle simple mouse events as well as keyboard commmands add trackbars to the windows, handle simple mouse events as well as keyboard commmands
* *
read and write images to/from disk or memory. read and write images to/from disk or memory.
* *
read video from camera or file and write video to a file. read video from camera or file and write video to a file.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

640
modules/highgui/doc/qt_new_functions.rst
View File

@ -3,605 +3,353 @@ Qt new functions
.. highlight:: cpp .. highlight:: cpp
.. image:: ../../pics/Qt_GUI.png .. image:: ../../pics/Qt_GUI.png
This figure explains the new functionalities implemented with Qt GUI. As we can see, the new GUI provides a statusbar, a toolbar, and a control panel. The control panel can have trackbars and buttonbars attached to it.
This figure explains the new functionalities implemented with Qt GUI. As we can see, the new GUI provides a statusbar, a toolbar, and a control panel. The control panel can have trackbars and buttonbars attached to it.
* *
To attach a trackbar, the window To attach a trackbar, the window_ name parameter must be NULL.
_
name parameter must be NULL.
* *
To attach a buttonbar, a button must be created. To attach a buttonbar, a button must be created.
If the last bar attached to the control panel is a buttonbar, the new button is added on the right of the last button. If the last bar attached to the control panel is a buttonbar, the new button is added on the right of the last button.
If the last bar attached to the control panel is a trackbar, or the control panel is empty, a new buttonbar is created. Then a new button is attached to it. If the last bar attached to the control panel is a trackbar, or the control panel is empty, a new buttonbar is created. Then a new button is attached to it.
The following code is an example used to generate the figure.
The following code is an example used to generate the figure. ::
int main(int argc, char *argv[])
int value = 50;
int value2 = 0;
:: cvNamedWindow("main1",CV_WINDOW_NORMAL);
cvNamedWindow("main2",CV_WINDOW_AUTOSIZE | CV_GUI_NORMAL);
cvCreateTrackbar( "track1", "main1", &value, 255, NULL);//OK tested
char* nameb1 = "button1";
char* nameb2 = "button2";
cvCreateButton(nameb1,callbackButton,nameb1,CV_CHECKBOX,1);
cvCreateButton(nameb2,callbackButton,nameb2,CV_CHECKBOX,0);
int main(int argc, char *argv[]) cvCreateTrackbar( "track2", NULL, &value2, 255, NULL);
int value = 50; cvCreateButton("button5",callbackButton1,NULL,CV_RADIOBOX,0);
int value2 = 0; cvCreateButton("button6",callbackButton2,NULL,CV_RADIOBOX,1);
cvNamedWindow("main1",CV_WINDOW_NORMAL);
cvNamedWindow("main2",CV_WINDOW_AUTOSIZE | CV_GUI_NORMAL);
cvCreateTrackbar( "track1", "main1", &value, 255, NULL);//OK tested
char* nameb1 = "button1";
char* nameb2 = "button2";
cvCreateButton(nameb1,callbackButton,nameb1,CV_CHECKBOX,1);
cvCreateButton(nameb2,callbackButton,nameb2,CV_CHECKBOX,0);
cvCreateTrackbar( "track2", NULL, &value2, 255, NULL);
cvCreateButton("button5",callbackButton1,NULL,CV_RADIOBOX,0);
cvCreateButton("button6",callbackButton2,NULL,CV_RADIOBOX,1);
cvSetMouseCallback( "main2",on_mouse,NULL );
IplImage* img1 = cvLoadImage("files/flower.jpg");
IplImage* img2 = cvCreateImage(cvGetSize(img1),8,3);
CvCapture* video = cvCaptureFromFile("files/hockey.avi");
IplImage* img3 = cvCreateImage(cvGetSize(cvQueryFrame(video)),8,3);
while(cvWaitKey(33) != 27)
{
cvAddS(img1,cvScalarAll(value),img2);
cvAddS(cvQueryFrame(video),cvScalarAll(value2),img3);
cvShowImage("main1",img2);
cvShowImage("main2",img3);
}
cvDestroyAllWindows();
cvReleaseImage(&img1);
cvReleaseImage(&img2);
cvReleaseImage(&img3);
cvReleaseCapture(&video);
return 0;
}
cvSetMouseCallback( "main2",on_mouse,NULL );
IplImage* img1 = cvLoadImage("files/flower.jpg");
IplImage* img2 = cvCreateImage(cvGetSize(img1),8,3);
CvCapture* video = cvCaptureFromFile("files/hockey.avi");
IplImage* img3 = cvCreateImage(cvGetSize(cvQueryFrame(video)),8,3);
while(cvWaitKey(33) != 27)
{
cvAddS(img1,cvScalarAll(value),img2);
cvAddS(cvQueryFrame(video),cvScalarAll(value2),img3);
cvShowImage("main1",img2);
cvShowImage("main2",img3);
}
cvDestroyAllWindows();
cvReleaseImage(&img1);
cvReleaseImage(&img2);
cvReleaseImage(&img3);
cvReleaseCapture(&video);
return 0;
}
.. ..
.. index:: setWindowProperty .. index:: setWindowProperty
cv::setWindowProperty cv::setWindowProperty
--------------------- ---------------------
`id=0.202216555435 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/setWindowProperty>`__
.. cfunction:: void setWindowProperty(const string\& name, int prop_id, double prop_value) .. cfunction:: void setWindowProperty(const string\& name, int prop_id, double prop_value)
Change the parameters of the window dynamically. Change the parameters of the window dynamically.
:param name: Name of the window.
:param prop_id: Window's property to edit. The operation flags:
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the user can resize the window (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the image's aspect ratio is preserved (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
:param prop_value: New value of the Window's property. The operation flags:
* **CV_WINDOW_NORMAL** Change the window in normal size, or allows the user to resize the window.
* **CV_WINDOW_AUTOSIZE** The user cannot resize the window, the size is constrainted by the image displayed.
* **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
* **CV_WINDOW_FREERATIO** The image expends as much as it can (no ratio constraint)
* **CV_WINDOW_KEEPRATIO** The ration image is respected.
The function `` setWindowProperty`` allows to change the window's properties.
:param name: Name of the window.
:param prop_id: Window's property to edit. The operation flags:
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the user can resize the window (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the image's aspect ratio is preserved (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
:param prop_value: New value of the Window's property. The operation flags:
* **CV_WINDOW_NORMAL** Change the window in normal size, or allows the user to resize the window.
* **CV_WINDOW_AUTOSIZE** The user cannot resize the window, the size is constrainted by the image displayed.
* **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
* **CV_WINDOW_FREERATIO** The image expends as much as it can (no ratio constraint)
* **CV_WINDOW_KEEPRATIO** The ration image is respected.
The function
`` setWindowProperty``
allows to change the window's properties.
.. index:: getWindowProperty .. index:: getWindowProperty
cv::getWindowProperty cv::getWindowProperty
--------------------- ---------------------
`id=0.467280795493 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/getWindowProperty>`__
.. cfunction:: void getWindowProperty(const char* name, int prop_id) .. cfunction:: void getWindowProperty(const char* name, int prop_id)
Get the parameters of the window. Get the parameters of the window.
:param name: Name of the window.
:param prop_id: Window's property to retrive. The operation flags:
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the user can resize the window (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the image's aspect ratio is preserved (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
See
:ref:`setWindowProperty` to know the meaning of the returned values.
The function `` getWindowProperty`` return window's properties.
:param name: Name of the window.
:param prop_id: Window's property to retrive. The operation flags:
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
* **CV_WND_PROP_AUTOSIZE** Change if the user can resize the window (texttt {CV\_WINDOW\_NORMAL} or ``CV_WINDOW_AUTOSIZE`` ).
* **CV_WND_PROP_ASPECTRATIO** Change if the image's aspect ratio is preserved (texttt {CV\_WINDOW\_FREERATIO} or ``CV_WINDOW_KEEPRATIO`` ).
See
:ref:`setWindowProperty`
to know the meaning of the returned values.
The function
`` getWindowProperty``
return window's properties.
.. index:: fontQt .. index:: fontQt
cv::fontQt cv::fontQt
---------- ----------
`id=0.680350496921 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/fontQt>`__
.. cfunction:: CvFont fontQt(const string\& nameFont, int pointSize = -1, Scalar color = Scalar::all(0), int weight = CV_FONT_NORMAL, int style = CV_STYLE_NORMAL, int spacing = 0) .. cfunction:: CvFont fontQt(const string\& nameFont, int pointSize = -1, Scalar color = Scalar::all(0), int weight = CV_FONT_NORMAL, int style = CV_STYLE_NORMAL, int spacing = 0)
Create the font to be used to draw text on an image. Create the font to be used to draw text on an image.
:param nameFont: Name of the font. The name should match the name of a system font (such as ``Times''). If the font is not found, a default one will be used.
:param pointSize: Size of the font. If not specified, equal zero or negative, the point size of the font is set to a system-dependent default value. Generally, this is 12 points.
:param color: Color of the font in BGRA -- A = 255 is fully transparent. Use the macro CV _ RGB for simplicity.
:param weight: The operation flags:
:param nameFont: Name of the font. The name should match the name of a system font (such as ``Times''). If the font is not found, a default one will be used.
* **CV_FONT_LIGHT** Weight of 25
:param pointSize: Size of the font. If not specified, equal zero or negative, the point size of the font is set to a system-dependent default value. Generally, this is 12 points.
:param color: Color of the font in BGRA -- A = 255 is fully transparent. Use the macro CV _ RGB for simplicity.
:param weight: The operation flags:
* **CV_FONT_LIGHT** Weight of 25
* **CV_FONT_NORMAL** Weight of 50
* **CV_FONT_DEMIBOLD** Weight of 63
* **CV_FONT_BOLD** Weight of 75
* **CV_FONT_BLACK** Weight of 87
You can also specify a positive integer for more control. * **CV_FONT_NORMAL** Weight of 50
* **CV_FONT_DEMIBOLD** Weight of 63
:param style: The operation flags: * **CV_FONT_BOLD** Weight of 75
* **CV_STYLE_NORMAL** Font is normal * **CV_FONT_BLACK** Weight of 87
* **CV_STYLE_ITALIC** Font is in italic
* **CV_STYLE_OBLIQUE** Font is oblique
:param spacing: Spacing between characters. Can be negative or positive
The function
``fontQt``
creates a CvFont object. This CvFont is not compatible with putText.
A basic usage of this function is:
You can also specify a positive integer for more control.
:param style: The operation flags:
* **CV_STYLE_NORMAL** Font is normal
* **CV_STYLE_ITALIC** Font is in italic
* **CV_STYLE_OBLIQUE** Font is oblique
:: :param spacing: Spacing between characters. Can be negative or positive
The function ``fontQt`` creates a CvFont object. This CvFont is not compatible with putText.
A basic usage of this function is: ::
CvFont font = fontQt(''Times'');
addText( img1, ``Hello World !'', Point(50,50), font);
CvFont font = fontQt(''Times'');
addText( img1, ``Hello World !'', Point(50,50), font);
.. ..
.. index:: addText .. index:: addText
cv::addText cv::addText
----------- -----------
`id=0.0425492674947 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/addText>`__
.. cfunction:: void addText(const Mat\& img, const string\& text, Point location, CvFont *font) .. cfunction:: void addText(const Mat\& img, const string\& text, Point location, CvFont *font)
Create the font to be used to draw text on an image Create the font to be used to draw text on an image
:param img: Image where the text should be drawn
:param text: Text to write on the image
:param location: Point(x,y) where the text should start on the image
:param font: Font to use to draw the text
:param img: Image where the text should be drawn
The function ``addText`` draw
:param text: Text to write on the image
:param location: Point(x,y) where the text should start on the image
:param font: Font to use to draw the text
The function
``addText``
draw
*text* *text*
on the image on the image
*img* *img*
using a specific font using a specific font
*font* *font*
(see example (see example
:ref:`fontQt` :ref:`fontQt` )
)
.. index:: displayOverlay .. index:: displayOverlay
cv::displayOverlay cv::displayOverlay
------------------ ------------------
`id=0.969508597197 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/displayOverlay>`__
.. cfunction:: void displayOverlay(const string\& name, const string\& text, int delay) .. cfunction:: void displayOverlay(const string\& name, const string\& text, int delay)
Display text on the window's image as an overlay for delay milliseconds. This is not editing the image's data. The text is display on the top of the image. Display text on the window's image as an overlay for delay milliseconds. This is not editing the image's data. The text is display on the top of the image.
:param name: Name of the window
:param text: Overlay text to write on the window's image
:param delay: Delay to display the overlay text. If this function is called before the previous overlay text time out, the timer is restarted and the text updated. . If this value is zero, the text never disapers.
The function ``displayOverlay`` aims at displaying useful information/tips on the window for a certain amount of time
:param name: Name of the window
:param text: Overlay text to write on the window's image
:param delay: Delay to display the overlay text. If this function is called before the previous overlay text time out, the timer is restarted and the text updated. . If this value is zero, the text never disapers.
The function
``displayOverlay``
aims at displaying useful information/tips on the window for a certain amount of time
*delay* *delay*
. This information is display on the top of the window. . This information is display on the top of the window.
.. index:: displayStatusBar .. index:: displayStatusBar
cv::displayStatusBar cv::displayStatusBar
-------------------- --------------------
`id=0.132014751496 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/displayStatusBar>`__
.. cfunction:: void displayStatusBar(const string\& name, const string\& text, int delayms) .. cfunction:: void displayStatusBar(const string\& name, const string\& text, int delayms)
Display text on the window's statusbar as for delay milliseconds. Display text on the window's statusbar as for delay milliseconds.
:param name: Name of the window
:param text: Text to write on the window's statusbar
:param delay: Delay to display the text. If this function is called before the previous text time out, the timer is restarted and the text updated. If this value is zero, the text never disapers.
The function ``displayOverlay`` aims at displaying useful information/tips on the window for a certain amount of time
:param name: Name of the window
:param text: Text to write on the window's statusbar
:param delay: Delay to display the text. If this function is called before the previous text time out, the timer is restarted and the text updated. If this value is zero, the text never disapers.
The function
``displayOverlay``
aims at displaying useful information/tips on the window for a certain amount of time
*delay* *delay*
. This information is displayed on the window's statubar (the window must be created with . This information is displayed on the window's statubar (the window must be created with ``CV_GUI_EXPANDED`` flags).
``CV_GUI_EXPANDED``
flags).
.. index:: createOpenGLCallback .. index:: createOpenGLCallback
cv::createOpenGLCallback cv::createOpenGLCallback
------------------------ ------------------------
`id=0.0486773148219 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/createOpenGLCallback>`__
*_* *_*
.. cfunction:: void createOpenGLCallback( const string\& window_name, OpenGLCallback callbackOpenGL, void* userdata CV_DEFAULT(NULL), double angle CV_DEFAULT(-1), double zmin CV_DEFAULT(-1), double zmax CV_DEFAULT(-1) .. cfunction:: void createOpenGLCallback( const string\& window_name, OpenGLCallback callbackOpenGL, void* userdata CV_DEFAULT(NULL), double angle CV_DEFAULT(-1), double zmin CV_DEFAULT(-1), double zmax CV_DEFAULT(-1)
Create a callback function called to draw OpenGL on top the the image display by windowname. Create a callback function called to draw OpenGL on top the the image display by windowname.
:param window_name: Name of the window
:param callbackOpenGL:
Pointer to the function to be called every frame.
This function should be prototyped as ``void Foo(*void);`` .
:param userdata: pointer passed to the callback function. *(Optional)*
:param angle: Specifies the field of view angle, in degrees, in the y direction.. *(Optional - Default 45 degree)*
:param window_name: Name of the window
:param callbackOpenGL:
Pointer to the function to be called every frame.
This function should be prototyped as ``void Foo(*void);`` .
:param userdata: pointer passed to the callback function. *(Optional)*
:param angle: Specifies the field of view angle, in degrees, in the y direction.. *(Optional - Default 45 degree)*
:param zmin: Specifies the distance from the viewer to the near clipping plane (always positive). *(Optional - Default 0.01)*
:param zmax: Specifies the distance from the viewer to the far clipping plane (always positive). *(Optional - Default 1000)*
The function
``createOpenGLCallback``
can be used to draw 3D data on the window. An example of callback could be:
:param zmin: Specifies the distance from the viewer to the near clipping plane (always positive). *(Optional - Default 0.01)*
:param zmax: Specifies the distance from the viewer to the far clipping plane (always positive). *(Optional - Default 1000)*
:: The function ``createOpenGLCallback`` can be used to draw 3D data on the window. An example of callback could be: ::
void on_opengl(void* param)
{
glLoadIdentity();
glTranslated(0.0, 0.0, -1.0);
void on_opengl(void* param)
{
glLoadIdentity();
glTranslated(0.0, 0.0, -1.0);
glRotatef( 55, 1, 0, 0 );
glRotatef( 45, 0, 1, 0 );
glRotatef( 0, 0, 0, 1 );
static const int coords[6][4][3] = {
{ { +1, -1, -1 }, { -1, -1, -1 }, { -1, +1, -1 }, { +1, +1, -1 } },
{ { +1, +1, -1 }, { -1, +1, -1 }, { -1, +1, +1 }, { +1, +1, +1 } },
{ { +1, -1, +1 }, { +1, -1, -1 }, { +1, +1, -1 }, { +1, +1, +1 } },
{ { -1, -1, -1 }, { -1, -1, +1 }, { -1, +1, +1 }, { -1, +1, -1 } },
{ { +1, -1, +1 }, { -1, -1, +1 }, { -1, -1, -1 }, { +1, -1, -1 } },
{ { -1, -1, +1 }, { +1, -1, +1 }, { +1, +1, +1 }, { -1, +1, +1 } }
};
for (int i = 0; i < 6; ++i) {
glColor3ub( i*20, 100+i*10, i*42 );
glBegin(GL_QUADS);
for (int j = 0; j < 4; ++j) {
glVertex3d(0.2 * coords[i][j][0], 0.2 * coords[i][j][1], 0.2 * coords[i][j][2]);
}
glEnd();
}
}
glRotatef( 55, 1, 0, 0 );
glRotatef( 45, 0, 1, 0 );
glRotatef( 0, 0, 0, 1 );
static const int coords[6][4][3] = {
{ { +1, -1, -1 }, { -1, -1, -1 }, { -1, +1, -1 }, { +1, +1, -1 } },
{ { +1, +1, -1 }, { -1, +1, -1 }, { -1, +1, +1 }, { +1, +1, +1 } },
{ { +1, -1, +1 }, { +1, -1, -1 }, { +1, +1, -1 }, { +1, +1, +1 } },
{ { -1, -1, -1 }, { -1, -1, +1 }, { -1, +1, +1 }, { -1, +1, -1 } },
{ { +1, -1, +1 }, { -1, -1, +1 }, { -1, -1, -1 }, { +1, -1, -1 } },
{ { -1, -1, +1 }, { +1, -1, +1 }, { +1, +1, +1 }, { -1, +1, +1 } }
};
for (int i = 0; i < 6; ++i) {
glColor3ub( i*20, 100+i*10, i*42 );
glBegin(GL_QUADS);
for (int j = 0; j < 4; ++j) {
glVertex3d(0.2 * coords[i][j][0], 0.2 * coords[i][j][1], 0.2 * coords[i][j][2]);
}
glEnd();
}
}
.. ..
.. index:: saveWindowParameters .. index:: saveWindowParameters
cv::saveWindowParameters cv::saveWindowParameters
------------------------ ------------------------
`id=0.189887022151 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/saveWindowParameters>`__
*_* *_*
.. cfunction:: void saveWindowParameters(const string\& name) .. cfunction:: void saveWindowParameters(const string\& name)
Save parameters of the window windowname. Save parameters of the window windowname.
:param name: Name of the window
The function ``saveWindowParameters`` saves size, location, flags, trackbars' value, zoom and panning location of the window
:param name: Name of the window
The function
``saveWindowParameters``
saves size, location, flags, trackbars' value, zoom and panning location of the window
*window_name* *window_name*
.. index:: loadWindowParameters .. index:: loadWindowParameters
cv::loadWindowParameters cv::loadWindowParameters
------------------------ ------------------------
`id=0.922344403304 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/loadWindowParameters>`__
*_* *_*
.. cfunction:: void loadWindowParameters(const string\& name) .. cfunction:: void loadWindowParameters(const string\& name)
Load parameters of the window windowname. Load parameters of the window windowname.
:param name: Name of the window
The function ``loadWindowParameters`` load size, location, flags, trackbars' value, zoom and panning location of the window
:param name: Name of the window
The function
``loadWindowParameters``
load size, location, flags, trackbars' value, zoom and panning location of the window
*window_name* *window_name*
.. index:: createButton .. index:: createButton
cv::createButton cv::createButton
---------------- ----------------
`id=0.367650849719 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/createButton>`__
*_* *_*
.. cfunction:: createButton( const string\& button_name CV_DEFAULT(NULL),ButtonCallback on_change CV_DEFAULT(NULL), void* userdata CV_DEFAULT(NULL) , int button_type CV_DEFAULT(CV_PUSH_BUTTON), int initial_button_state CV_DEFAULT(0) .. cfunction:: createButton( const string\& button_name CV_DEFAULT(NULL),ButtonCallback on_change CV_DEFAULT(NULL), void* userdata CV_DEFAULT(NULL) , int button_type CV_DEFAULT(CV_PUSH_BUTTON), int initial_button_state CV_DEFAULT(0)
Create a callback function called to draw OpenGL on top the the image display by windowname. Create a callback function called to draw OpenGL on top the the image display by windowname.
:param button_name: Name of the button *( if NULL, the name will be "button <number of boutton>")*
:param on_change:
Pointer to the function to be called every time the button changed its state.
This function should be prototyped as ``void Foo(int state,*void);`` . *state* is the current state of the button. It could be -1 for a push button, 0 or 1 for a check/radio box button.
:param userdata: pointer passed to the callback function. *(Optional)*
The ``button_type`` parameter can be :
*(Optional -- Will be a push button by default.)
* **CV_PUSH_BUTTON** The button will be a push button.
* **CV_CHECKBOX** The button will be a checkbox button.
* **CV_RADIOBOX** The button will be a radiobox button. The radiobox on the same buttonbar (same line) are exclusive; one on can be select at the time.
:param button_name: Name of the button *( if NULL, the name will be "button <number of boutton>")*
:param on_change:
Pointer to the function to be called every time the button changed its state.
This function should be prototyped as ``void Foo(int state,*void);`` . *state* is the current state of the button. It could be -1 for a push button, 0 or 1 for a check/radio box button.
:param userdata: pointer passed to the callback function. *(Optional)*
The
``button_type``
parameter can be :
*(Optional -- Will be a push button by default.)
* **CV_PUSH_BUTTON** The button will be a push button.
* **CV_CHECKBOX** The button will be a checkbox button.
* **CV_RADIOBOX** The button will be a radiobox button. The radiobox on the same buttonbar (same line) are exclusive; one on can be select at the time.
* *
* **initial_button_state** Default state of the button. Use for checkbox and radiobox, its value could be 0 or 1. *(Optional)*
The function ``createButton`` attach a button to the control panel. Each button is added to a buttonbar on the right of the last button.
* **initial_button_state** Default state of the button. Use for checkbox and radiobox, its value could be 0 or 1. *(Optional)* A new buttonbar is create if nothing was attached to the control panel before, or if the last element attached to the control panel was a trackbar.
The function
``createButton``
attach a button to the control panel. Each button is added to a buttonbar on the right of the last button.
A new buttonbar is create if nothing was attached to the control panel before, or if the last element attached to the control panel was a trackbar.
Here are various example of
``createButton``
function call:
Here are various example of ``createButton`` function call: ::
createButton(NULL,callbackButton);//create a push button "button 0", that will call callbackButton.
:: createButton("button2",callbackButton,NULL,CV_CHECKBOX,0);
createButton("button3",callbackButton,&value);
createButton("button5",callbackButton1,NULL,CV_RADIOBOX);
createButton("button6",callbackButton2,NULL,CV_PUSH_BUTTON,1);
createButton(NULL,callbackButton);//create a push button "button 0", that will call callbackButton.
createButton("button2",callbackButton,NULL,CV_CHECKBOX,0);
createButton("button3",callbackButton,&value);
createButton("button5",callbackButton1,NULL,CV_RADIOBOX);
createButton("button6",callbackButton2,NULL,CV_PUSH_BUTTON,1);
.. ..

523
modules/highgui/doc/reading_and_writing_images_and_video.rst
View File

@ -3,246 +3,123 @@ Reading and Writing Images and Video
.. highlight:: cpp .. highlight:: cpp
.. index:: imdecode .. index:: imdecode
cv::imdecode cv::imdecode
------------ ------------
`id=0.524391584247 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imdecode>`__
.. cfunction:: Mat imdecode( const Mat\& buf, int flags ) .. cfunction:: Mat imdecode( const Mat\& buf, int flags )
Reads an image from a buffer in memory. Reads an image from a buffer in memory.
:param buf: The input array of vector of bytes
:param flags: The same flags as in :ref:`imread`
:param buf: The input array of vector of bytes
:param flags: The same flags as in :ref:`imread`
The function reads image from the specified buffer in memory. The function reads image from the specified buffer in memory.
If the buffer is too short or contains invalid data, the empty matrix will be returned. If the buffer is too short or contains invalid data, the empty matrix will be returned.
See See
:ref:`imread` :ref:`imread` for the list of supported formats and the flags description.
for the list of supported formats and the flags description.
.. index:: imencode .. index:: imencode
cv::imencode cv::imencode
------------ ------------
`id=0.960190095821 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imencode>`__
.. cfunction:: bool imencode( const string\& ext, const Mat\& img, vector<uchar>\& buf, const vector<int>\& params=vector<int>()) .. cfunction:: bool imencode( const string\& ext, const Mat\& img, vector<uchar>\& buf, const vector<int>\& params=vector<int>())
Encode an image into a memory buffer. Encode an image into a memory buffer.
:param ext: The file extension that defines the output format
:param img: The image to be written
:param buf: The output buffer; resized to fit the compressed image
:param params: The format-specific parameters; see :ref:`imwrite`
:param ext: The file extension that defines the output format
:param img: The image to be written
:param buf: The output buffer; resized to fit the compressed image
:param params: The format-specific parameters; see :ref:`imwrite`
The function compresses the image and stores it in the memory buffer, which is resized to fit the result. The function compresses the image and stores it in the memory buffer, which is resized to fit the result.
See See
:ref:`imwrite` :ref:`imwrite` for the list of supported formats and the flags description.
for the list of supported formats and the flags description.
.. index:: imread .. index:: imread
cv::imread cv::imread
---------- ----------
`id=0.16110153292 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imread>`__
.. cfunction:: Mat imread( const string\& filename, int flags=1 ) .. cfunction:: Mat imread( const string\& filename, int flags=1 )
Loads an image from a file. Loads an image from a file.
:param filename: Name of file to be loaded.
:param flags: Specifies color type of the loaded image:
* **>0** the loaded image is forced to be a 3-channel color image
* **=0** the loaded image is forced to be grayscale
* **<0** the loaded image will be loaded as-is (note that in the current implementation the alpha channel, if any, is stripped from the output image, e.g. 4-channel RGBA image will be loaded as RGB if :math:`flags\ge0` ).
:param filename: Name of file to be loaded.
:param flags: Specifies color type of the loaded image:
* **>0** the loaded image is forced to be a 3-channel color image
* **=0** the loaded image is forced to be grayscale
* **<0** the loaded image will be loaded as-is (note that in the current implementation the alpha channel, if any, is stripped from the output image, e.g. 4-channel RGBA image will be loaded as RGB if :math:`flags\ge0` ).
The function
``imread``
loads an image from the specified file and returns it. If the image can not be read (because of missing file, improper permissions, unsupported or invalid format), the function returns empty matrix (
``Mat::data==NULL``
).Currently, the following file formats are supported:
The function ``imread`` loads an image from the specified file and returns it. If the image can not be read (because of missing file, improper permissions, unsupported or invalid format), the function returns empty matrix ( ``Mat::data==NULL`` ).Currently, the following file formats are supported:
* *
Windows bitmaps - Windows bitmaps - ``*.bmp, *.dib`` (always supported)
``*.bmp, *.dib``
(always supported)
* *
JPEG files - JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see
``*.jpeg, *.jpg, *.jpe``
(see
**Note2** **Note2**
) )
* *
JPEG 2000 files - JPEG 2000 files - ``*.jp2`` (see
``*.jp2``
(see
**Note2** **Note2**
) )
* *
Portable Network Graphics - Portable Network Graphics - ``*.png`` (see
``*.png``
(see
**Note2** **Note2**
) )
* *
Portable image format - Portable image format - ``*.pbm, *.pgm, *.ppm`` (always supported)
``*.pbm, *.pgm, *.ppm``
(always supported)
* *
Sun rasters - Sun rasters - ``*.sr, *.ras`` (always supported)
``*.sr, *.ras``
(always supported)
* *
TIFF files - TIFF files - ``*.tiff, *.tif`` (see
``*.tiff, *.tif``
(see
**Note2** **Note2**
) )
**Note1** **Note1**
: The function determines type of the image by the content, not by the file extension. : The function determines type of the image by the content, not by the file extension.
**Note2** **Note2**
: On Windows and MacOSX the shipped with OpenCV image codecs (libjpeg, libpng, libtiff and libjasper) are used by default; so OpenCV can always read JPEGs, PNGs and TIFFs. On MacOSX there is also the option to use native MacOSX image readers. But beware that currently these native image loaders give images with somewhat different pixel values, because of the embedded into MacOSX color management. : On Windows and MacOSX the shipped with OpenCV image codecs (libjpeg, libpng, libtiff and libjasper) are used by default; so OpenCV can always read JPEGs, PNGs and TIFFs. On MacOSX there is also the option to use native MacOSX image readers. But beware that currently these native image loaders give images with somewhat different pixel values, because of the embedded into MacOSX color management.
On Linux, BSD flavors and other Unix-like open-source operating systems OpenCV looks for the supplied with OS image codecs. Please, install the relevant packages (do not forget the development files, e.g. "libjpeg-dev" etc. in Debian and Ubuntu) in order to get the codec support, or turn on On Linux, BSD flavors and other Unix-like open-source operating systems OpenCV looks for the supplied with OS image codecs. Please, install the relevant packages (do not forget the development files, e.g. "libjpeg-dev" etc. in Debian and Ubuntu) in order to get the codec support, or turn on ``OPENCV_BUILD_3RDPARTY_LIBS`` flag in CMake.
``OPENCV_BUILD_3RDPARTY_LIBS``
flag in CMake.
.. index:: imwrite .. index:: imwrite
cv::imwrite cv::imwrite
----------- -----------
`id=0.00846497387051 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imwrite>`__
.. cfunction:: bool imwrite( const string\& filename, const Mat\& img, const vector<int>\& params=vector<int>()) .. cfunction:: bool imwrite( const string\& filename, const Mat\& img, const vector<int>\& params=vector<int>())
Saves an image to a specified file. Saves an image to a specified file.
:param filename: Name of the file.
:param img: The image to be saved.
:param params: The format-specific save parameters, encoded as pairs ``paramId_1, paramValue_1, paramId_2, paramValue_2, ...`` . The following parameters are currently supported:
:param filename: Name of the file.
:param img: The image to be saved.
:param params: The format-specific save parameters, encoded as pairs ``paramId_1, paramValue_1, paramId_2, paramValue_2, ...`` . The following parameters are currently supported:
* In the case of JPEG it can be a quality ( ``CV_IMWRITE_JPEG_QUALITY`` ), from 0 to 100 (the higher is the better), 95 by default. * In the case of JPEG it can be a quality ( ``CV_IMWRITE_JPEG_QUALITY`` ), from 0 to 100 (the higher is the better), 95 by default.
* In the case of PNG it can be the compression level ( ``CV_IMWRITE_PNG_COMPRESSION`` ), from 0 to 9 (the higher value means smaller size and longer compression time), 3 by default. * In the case of PNG it can be the compression level ( ``CV_IMWRITE_PNG_COMPRESSION`` ), from 0 to 9 (the higher value means smaller size and longer compression time), 3 by default.
* In the case of PPM, PGM or PBM it can a binary format flag ( ``CV_IMWRITE_PXM_BINARY`` ), 0 or 1, 1 by default.
The function
``imwrite``
saves the image to the specified file. The image format is chosen based on the
``filename``
extension, see
:ref:`imread`
for the list of extensions. Only 8-bit (or 16-bit in the case of PNG, JPEG 2000 and TIFF) single-channel or 3-channel (with 'BGR' channel order) images can be saved using this function. If the format, depth or channel order is different, use
:ref:`Mat::convertTo`
, and
:ref:`cvtColor`
to convert it before saving, or use the universal XML I/O functions to save the image to XML or YAML format.
* In the case of PPM, PGM or PBM it can a binary format flag ( ``CV_IMWRITE_PXM_BINARY`` ), 0 or 1, 1 by default.
The function ``imwrite`` saves the image to the specified file. The image format is chosen based on the ``filename`` extension, see
:ref:`imread` for the list of extensions. Only 8-bit (or 16-bit in the case of PNG, JPEG 2000 and TIFF) single-channel or 3-channel (with 'BGR' channel order) images can be saved using this function. If the format, depth or channel order is different, use
:ref:`Mat::convertTo` , and
:ref:`cvtColor` to convert it before saving, or use the universal XML I/O functions to save the image to XML or YAML format.
.. index:: VideoCapture .. index:: VideoCapture
@ -250,22 +127,10 @@ to convert it before saving, or use the universal XML I/O functions to save the
VideoCapture VideoCapture
------------ ------------
`id=0.267295181599 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture>`__
.. ctype:: VideoCapture .. ctype:: VideoCapture
Class for video capturing from video files or cameras ::
Class for video capturing from video files or cameras
::
class VideoCapture class VideoCapture
{ {
public: public:
@ -275,24 +140,24 @@ Class for video capturing from video files or cameras
VideoCapture(const string& filename); VideoCapture(const string& filename);
// the constructor that starts streaming from the camera // the constructor that starts streaming from the camera
VideoCapture(int device); VideoCapture(int device);
// the destructor // the destructor
virtual ~VideoCapture(); virtual ~VideoCapture();
// opens the specified video file // opens the specified video file
virtual bool open(const string& filename); virtual bool open(const string& filename);
// starts streaming from the specified camera by its id // starts streaming from the specified camera by its id
virtual bool open(int device); virtual bool open(int device);
// returns true if the file was open successfully or if the camera // returns true if the file was open successfully or if the camera
// has been initialized succesfully // has been initialized succesfully
virtual bool isOpened() const; virtual bool isOpened() const;
// closes the camera stream or the video file // closes the camera stream or the video file
// (automatically called by the destructor) // (automatically called by the destructor)
virtual void release(); virtual void release();
// grab the next frame or a set of frames from a multi-head camera; // grab the next frame or a set of frames from a multi-head camera;
// returns false if there are no more frames // returns false if there are no more frames
virtual bool grab(); virtual bool grab();
@ -301,39 +166,30 @@ Class for video capturing from video files or cameras
virtual bool retrieve(Mat& image, int channel=0); virtual bool retrieve(Mat& image, int channel=0);
// equivalent to grab() + retrieve(image, 0); // equivalent to grab() + retrieve(image, 0);
virtual VideoCapture& operator >> (Mat& image); virtual VideoCapture& operator >> (Mat& image);
// sets the specified property propId to the specified value // sets the specified property propId to the specified value
virtual bool set(int propId, double value); virtual bool set(int propId, double value);
// retrieves value of the specified property // retrieves value of the specified property
virtual double get(int propId); virtual double get(int propId);
protected: protected:
... ...
}; };
.. ..
The class provides C++ video capturing API. Here is how the class can be used: The class provides C++ video capturing API. Here is how the class can be used: ::
::
#include "cv.h" #include "cv.h"
#include "highgui.h" #include "highgui.h"
using namespace cv; using namespace cv;
int main(int, char**) int main(int, char**)
{ {
VideoCapture cap(0); // open the default camera VideoCapture cap(0); // open the default camera
if(!cap.isOpened()) // check if we succeeded if(!cap.isOpened()) // check if we succeeded
return -1; return -1;
Mat edges; Mat edges;
namedWindow("edges",1); namedWindow("edges",1);
for(;;) for(;;)
@ -349,276 +205,161 @@ The class provides C++ video capturing API. Here is how the class can be used:
// the camera will be deinitialized automatically in VideoCapture destructor // the camera will be deinitialized automatically in VideoCapture destructor
return 0; return 0;
} }
.. ..
.. index:: VideoCapture::VideoCapture .. index:: VideoCapture::VideoCapture
cv::VideoCapture::VideoCapture cv::VideoCapture::VideoCapture
------------------------------ ------------------------------
`id=0.788880569149 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture%3A%3AVideoCapture>`__
.. cfunction:: VideoCapture::VideoCapture() .. cfunction:: VideoCapture::VideoCapture()
.. cfunction:: VideoCapture::VideoCapture(const string\& filename) .. cfunction:: VideoCapture::VideoCapture(const string\& filename)
.. cfunction:: VideoCapture::VideoCapture(int device) .. cfunction:: VideoCapture::VideoCapture(int device)
:param filename: TOWRITE
:param device: TOWRITE
:param filename: TOWRITE
:param device: TOWRITE
VideoCapture constructors. VideoCapture constructors.
.. index:: VideoCapture::get .. index:: VideoCapture::get
cv::VideoCapture::get cv::VideoCapture::get
--------------------- ---------------------
`id=0.977076859044 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture%3A%3Aget>`__
.. cfunction:: double VideoCapture::get(int property_id) .. cfunction:: double VideoCapture::get(int property_id)
:param property_id: Property identifier. Can be one of the following:
* **CV_CAP_PROP_POS_MSEC** Film current position in milliseconds or video capture timestamp
* **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next
* **CV_CAP_PROP_POS_AVI_RATIO** Relative position of the video file (0 - start of the film, 1 - end of the film)
* **CV_CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream
* **CV_CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream
* **CV_CAP_PROP_FPS** Frame rate
* **CV_CAP_PROP_FOURCC** 4-character code of codec
* **CV_CAP_PROP_FRAME_COUNT** Number of frames in the video file
* **CV_CAP_PROP_FORMAT** The format of the Mat objects returned by retrieve()
* **CV_CAP_PROP_MODE** A backend-specific value indicating the current capture mode
* **CV_CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras)
* **CV_CAP_PROP_CONTRAST** Contrast of the image (only for cameras)
* **CV_CAP_PROP_SATURATION** Saturation of the image (only for cameras)
* **CV_CAP_PROP_HUE** Hue of the image (only for cameras)
* **CV_CAP_PROP_GAIN** Gain of the image (only for cameras)
* **CV_CAP_PROP_EXPOSURE** Exposure (only for cameras)
* **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB
* **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
* **CV_CAP_PROP_RECTIFICATION** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
:param property_id: Property identifier. Can be one of the following:
* **CV_CAP_PROP_POS_MSEC** Film current position in milliseconds or video capture timestamp
* **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next
* **CV_CAP_PROP_POS_AVI_RATIO** Relative position of the video file (0 - start of the film, 1 - end of the film)
* **CV_CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream
* **CV_CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream
* **CV_CAP_PROP_FPS** Frame rate
* **CV_CAP_PROP_FOURCC** 4-character code of codec
* **CV_CAP_PROP_FRAME_COUNT** Number of frames in the video file
* **CV_CAP_PROP_FORMAT** The format of the Mat objects returned by retrieve()
* **CV_CAP_PROP_MODE** A backend-specific value indicating the current capture mode
* **CV_CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras)
* **CV_CAP_PROP_CONTRAST** Contrast of the image (only for cameras)
* **CV_CAP_PROP_SATURATION** Saturation of the image (only for cameras)
* **CV_CAP_PROP_HUE** Hue of the image (only for cameras)
* **CV_CAP_PROP_GAIN** Gain of the image (only for cameras)
* **CV_CAP_PROP_EXPOSURE** Exposure (only for cameras)
* **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB
* **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
* **CV_CAP_PROP_RECTIFICATION** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
Note that when querying a property which is unsupported by the backend used by the VideoCapture class, the value 0 is returned. Note that when querying a property which is unsupported by the backend used by the VideoCapture class, the value 0 is returned.
.. index:: VideoCapture::set .. index:: VideoCapture::set
cv::VideoCapture::set cv::VideoCapture::set
--------------------- ---------------------
`id=0.845027627213 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoCapture%3A%3Aset>`__
.. cfunction:: bool VideoCapture::set(int property_id, double value) .. cfunction:: bool VideoCapture::set(int property_id, double value)
:param property_id: Property identifier. Can be one of the following:
* **CV_CAP_PROP_POS_MSEC** Film current position in milliseconds or video capture timestamp
* **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next
* **CV_CAP_PROP_POS_AVI_RATIO** Relative position of the video file (0 - start of the film, 1 - end of the film)
* **CV_CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream
* **CV_CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream
* **CV_CAP_PROP_FPS** Frame rate
* **CV_CAP_PROP_FOURCC** 4-character code of codec
* **CV_CAP_PROP_FRAME_COUNT** Number of frames in the video file
* **CV_CAP_PROP_FORMAT** The format of the Mat objects returned by retrieve()
* **CV_CAP_PROP_MODE** A backend-specific value indicating the current capture mode
* **CV_CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras)
* **CV_CAP_PROP_CONTRAST** Contrast of the image (only for cameras)
* **CV_CAP_PROP_SATURATION** Saturation of the image (only for cameras)
* **CV_CAP_PROP_HUE** Hue of the image (only for cameras)
* **CV_CAP_PROP_GAIN** Gain of the image (only for cameras)
* **CV_CAP_PROP_EXPOSURE** Exposure (only for cameras)
* **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB
* **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
* **CV_CAP_PROP_RECTIFICATION** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
:param value: value of the property.
:param property_id: Property identifier. Can be one of the following:
* **CV_CAP_PROP_POS_MSEC** Film current position in milliseconds or video capture timestamp
* **CV_CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next
* **CV_CAP_PROP_POS_AVI_RATIO** Relative position of the video file (0 - start of the film, 1 - end of the film)
* **CV_CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream
* **CV_CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream
* **CV_CAP_PROP_FPS** Frame rate
* **CV_CAP_PROP_FOURCC** 4-character code of codec
* **CV_CAP_PROP_FRAME_COUNT** Number of frames in the video file
* **CV_CAP_PROP_FORMAT** The format of the Mat objects returned by retrieve()
* **CV_CAP_PROP_MODE** A backend-specific value indicating the current capture mode
* **CV_CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras)
* **CV_CAP_PROP_CONTRAST** Contrast of the image (only for cameras)
* **CV_CAP_PROP_SATURATION** Saturation of the image (only for cameras)
* **CV_CAP_PROP_HUE** Hue of the image (only for cameras)
* **CV_CAP_PROP_GAIN** Gain of the image (only for cameras)
* **CV_CAP_PROP_EXPOSURE** Exposure (only for cameras)
* **CV_CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted to RGB
* **CV_CAP_PROP_WHITE_BALANCE** Currently unsupported
* **CV_CAP_PROP_RECTIFICATION** TOWRITE (note: only supported by DC1394 v 2.x backend currently)
:param value: value of the property.
Sets a property in the VideoCapture backend. Sets a property in the VideoCapture backend.
.. index:: VideoWriter .. index:: VideoWriter
.. _VideoWriter: .. _VideoWriter:
VideoWriter VideoWriter
----------- -----------
`id=0.234127975013 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/VideoWriter>`__
.. ctype:: VideoWriter .. ctype:: VideoWriter
Video writer class ::
Video writer class
::
class VideoWriter class VideoWriter
{ {
public: public:
// default constructor // default constructor
VideoWriter(); VideoWriter();
// constructor that calls open // constructor that calls open
VideoWriter(const string& filename, int fourcc, VideoWriter(const string& filename, int fourcc,
double fps, Size frameSize, bool isColor=true); double fps, Size frameSize, bool isColor=true);
// the destructor // the destructor
virtual ~VideoWriter(); virtual ~VideoWriter();
// opens the file and initializes the video writer. // opens the file and initializes the video writer.
// filename - the output file name. // filename - the output file name.
// fourcc - the codec // fourcc - the codec
// fps - the number of frames per second // fps - the number of frames per second
// frameSize - the video frame size // frameSize - the video frame size
// isColor - specifies whether the video stream is color or grayscale // isColor - specifies whether the video stream is color or grayscale
virtual bool open(const string& filename, int fourcc, virtual bool open(const string& filename, int fourcc,
double fps, Size frameSize, bool isColor=true); double fps, Size frameSize, bool isColor=true);
// returns true if the writer has been initialized successfully // returns true if the writer has been initialized successfully
virtual bool isOpened() const; virtual bool isOpened() const;
// writes the next video frame to the stream // writes the next video frame to the stream
virtual VideoWriter& operator << (const Mat& image); virtual VideoWriter& operator << (const Mat& image);
protected: protected:
... ...
}; };
.. ..

240
modules/highgui/doc/user_interface.rst
View File

@ -3,195 +3,98 @@ User Interface
.. highlight:: cpp .. highlight:: cpp
.. index:: createTrackbar .. index:: createTrackbar
cv::createTrackbar cv::createTrackbar
------------------ ------------------
`id=0.122963695249 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/createTrackbar>`__
.. cfunction:: int createTrackbar( const string\& trackbarname, const string\& winname, int* value, int count, TrackbarCallback onChange CV_DEFAULT(0), void* userdata CV_DEFAULT(0)) .. cfunction:: int createTrackbar( const string\& trackbarname, const string\& winname, int* value, int count, TrackbarCallback onChange CV_DEFAULT(0), void* userdata CV_DEFAULT(0))
Creates a trackbar and attaches it to the specified window Creates a trackbar and attaches it to the specified window
:param trackbarname: Name of the created trackbar.
:param winname: Name of the window which will be used as a parent of the created trackbar.
:param value: The optional pointer to an integer variable, whose value will reflect the position of the slider. Upon creation, the slider position is defined by this variable.
:param count: The maximal position of the slider. The minimal position is always 0.
:param onChange: Pointer to the function to be called every time the slider changes position. This function should be prototyped as ``void Foo(int,void*);`` , where the first parameter is the trackbar position and the second parameter is the user data (see the next parameter). If the callback is NULL pointer, then no callbacks is called, but only ``value`` is updated
:param trackbarname: Name of the created trackbar.
:param userdata: The user data that is passed as-is to the callback; it can be used to handle trackbar events without using global variables
:param winname: Name of the window which will be used as a parent of the created trackbar. The function ``createTrackbar`` creates a trackbar (a.k.a. slider or range control) with the specified name and range, assigns a variable ``value`` to be syncronized with trackbar position and specifies a callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed on the top of the given window.
:param value: The optional pointer to an integer variable, whose value will reflect the position of the slider. Upon creation, the slider position is defined by this variable.
:param count: The maximal position of the slider. The minimal position is always 0.
:param onChange: Pointer to the function to be called every time the slider changes position. This function should be prototyped as ``void Foo(int,void*);`` , where the first parameter is the trackbar position and the second parameter is the user data (see the next parameter). If the callback is NULL pointer, then no callbacks is called, but only ``value`` is updated
:param userdata: The user data that is passed as-is to the callback; it can be used to handle trackbar events without using global variables
The function
``createTrackbar``
creates a trackbar (a.k.a. slider or range control) with the specified name and range, assigns a variable
``value``
to be syncronized with trackbar position and specifies a callback function
``onChange``
to be called on the trackbar position change. The created trackbar is displayed on the top of the given window.
\ \
\ \
**[Qt Backend Only]** **[Qt Backend Only]**
qt-specific details: qt-specific details:
* **winname** Name of the window which will be used as a parent for created trackbar. Can be NULL if the trackbar should be attached to the control panel.
The created trackbar is displayed at the bottom of the given window if
* **winname** Name of the window which will be used as a parent for created trackbar. Can be NULL if the trackbar should be attached to the control panel.
The created trackbar is displayed at the bottom of the given window if
*winname* *winname*
is correctly provided, or displayed on the control panel if is correctly provided, or displayed on the control panel if
*winname* *winname*
is NULL. is NULL.
By clicking on the label of each trackbar, it is possible to edit the trackbar's value manually for a more accurate control of it. By clicking on the label of each trackbar, it is possible to edit the trackbar's value manually for a more accurate control of it.
.. index:: getTrackbarPos .. index:: getTrackbarPos
cv::getTrackbarPos cv::getTrackbarPos
------------------ ------------------
`id=0.51821188779 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/getTrackbarPos>`__
.. cfunction:: int getTrackbarPos( const string\& trackbarname, const string\& winname ) .. cfunction:: int getTrackbarPos( const string\& trackbarname, const string\& winname )
Returns the trackbar position. Returns the trackbar position.
:param trackbarname: Name of the trackbar.
:param winname: Name of the window which is the parent of the trackbar.
:param trackbarname: Name of the trackbar.
:param winname: Name of the window which is the parent of the trackbar.
The function returns the current position of the specified trackbar. The function returns the current position of the specified trackbar.
\ \
\ \
**[Qt Backend Only]** **[Qt Backend Only]**
qt-specific details: qt-specific details:
* **winname** Name of the window which is the parent of the trackbar. Can be NULL if the trackbar is attached to the control panel.
* **winname** Name of the window which is the parent of the trackbar. Can be NULL if the trackbar is attached to the control panel.
.. index:: imshow .. index:: imshow
cv::imshow cv::imshow
---------- ----------
`id=0.765508098436 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/imshow>`__
.. cfunction:: void imshow( const string\& winname, const Mat\& image ) .. cfunction:: void imshow( const string\& winname, const Mat\& image )
Displays the image in the specified window Displays the image in the specified window
:param winname: Name of the window.
:param image: Image to be shown.
The function ``imshow`` displays the image in the specified window. If the window was created with the ``CV_WINDOW_AUTOSIZE`` flag then the image is shown with its original size, otherwise the image is scaled to fit in the window. The function may scale the image, depending on its depth:
:param winname: Name of the window.
:param image: Image to be shown.
The function
``imshow``
displays the image in the specified window. If the window was created with the
``CV_WINDOW_AUTOSIZE``
flag then the image is shown with its original size, otherwise the image is scaled to fit in the window. The function may scale the image, depending on its depth:
* *
If the image is 8-bit unsigned, it is displayed as is. If the image is 8-bit unsigned, it is displayed as is.
* *
If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255]. If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255].
* *
If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255]. If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
.. index:: namedWindow .. index:: namedWindow
cv::namedWindow cv::namedWindow
--------------- ---------------
`id=0.618574996458 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/namedWindow>`__
.. cfunction:: void namedWindow( const string\& winname, int flags ) .. cfunction:: void namedWindow( const string\& winname, int flags )
Creates a window. Creates a window.
:param name: Name of the window in the window caption that may be used as a window identifier.
:param flags: Flags of the window. Currently the only supported flag is ``CV_WINDOW_AUTOSIZE`` . If this is set, the window size is automatically adjusted to fit the displayed image (see :ref:`imshow` ), and the user can not change the window size manually.
The function ``namedWindow`` creates a window which can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
:param name: Name of the window in the window caption that may be used as a window identifier.
:param flags: Flags of the window. Currently the only supported flag is ``CV_WINDOW_AUTOSIZE`` . If this is set, the window size is automatically adjusted to fit the displayed image (see :ref:`imshow` ), and the user can not change the window size manually.
The function
``namedWindow``
creates a window which can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
If a window with the same name already exists, the function does nothing. If a window with the same name already exists, the function does nothing.
\ \
@ -199,113 +102,58 @@ If a window with the same name already exists, the function does nothing.
**[Qt Backend Only]** **[Qt Backend Only]**
qt-specific details: qt-specific details:
* **flags** Flags of the window. Currently the supported flags are:
* **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` let the user resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window's size to fit the displayed image (see :ref:`ShowImage` ), and the user can not change the window size manually.
* **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjust the image without respect the its ration, whereas ``CV_WINDOW_KEEPRATIO`` keep the image's ratio.
* **CV_GUI_NORMAL or CV_GUI_EXPANDED:** ``CV_GUI_NORMAL`` is the old way to draw the window without statusbar and toolbar, whereas ``CV_GUI_EXPANDED`` is the new enhance GUI.
* **flags** Flags of the window. Currently the supported flags are:
* **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` let the user resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window's size to fit the displayed image (see :ref:`ShowImage` ), and the user can not change the window size manually.
* **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjust the image without respect the its ration, whereas ``CV_WINDOW_KEEPRATIO`` keep the image's ratio.
* **CV_GUI_NORMAL or CV_GUI_EXPANDED:** ``CV_GUI_NORMAL`` is the old way to draw the window without statusbar and toolbar, whereas ``CV_GUI_EXPANDED`` is the new enhance GUI.
This parameter is optional. The default flags set for a new window are ``CV_WINDOW_AUTOSIZE`` , ``CV_WINDOW_KEEPRATIO`` , and ``CV_GUI_EXPANDED`` . This parameter is optional. The default flags set for a new window are ``CV_WINDOW_AUTOSIZE`` , ``CV_WINDOW_KEEPRATIO`` , and ``CV_GUI_EXPANDED`` .
However, if you want to modify the flags, you can combine them using OR operator, ie:
::
namedWindow( ``myWindow'', ``CV_WINDOW_NORMAL`` textbar ``CV_GUI_NORMAL`` );
..
.. index:: setTrackbarPos
However, if you want to modify the flags, you can combine them using OR operator, ie:
::
namedWindow( ``myWindow'', ``CV_WINDOW_NORMAL`` textbar ``CV_GUI_NORMAL`` );
..
.. index:: setTrackbarPos
cv::setTrackbarPos cv::setTrackbarPos
------------------ ------------------
`id=0.247665233354 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/setTrackbarPos>`__
.. cfunction:: void setTrackbarPos( const string\& trackbarname, const string\& winname, int pos ) .. cfunction:: void setTrackbarPos( const string\& trackbarname, const string\& winname, int pos )
Sets the trackbar position. Sets the trackbar position.
:param trackbarname: Name of the trackbar.
:param winname: Name of the window which is the parent of trackbar.
:param pos: The new position.
:param trackbarname: Name of the trackbar.
:param winname: Name of the window which is the parent of trackbar.
:param pos: The new position.
The function sets the position of the specified trackbar in the specified window. The function sets the position of the specified trackbar in the specified window.
\ \
\ \
**[Qt Backend Only]** **[Qt Backend Only]**
qt-specific details: qt-specific details:
* **winname** Name of the window which is the parent of trackbar. Can be NULL if the trackbar is attached to the control panel.
* **winname** Name of the window which is the parent of trackbar. Can be NULL if the trackbar is attached to the control panel.
.. index:: waitKey .. index:: waitKey
cv::waitKey cv::waitKey
----------- -----------
`id=0.777845991089 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/highgui/waitKey>`__
.. cfunction:: int waitKey(int delay=0) .. cfunction:: int waitKey(int delay=0)
Waits for a pressed key. Waits for a pressed key.
:param delay: Delay in milliseconds. 0 is the special value that means "forever"
The function ``waitKey`` waits for key event infinitely (when
:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it's positive. Returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
:param delay: Delay in milliseconds. 0 is the special value that means "forever"
The function
``waitKey``
waits for key event infinitely (when
:math:`\texttt{delay}\leq 0`
) or for
``delay``
milliseconds, when it's positive. Returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
**Note:** **Note:**
This function is the only method in HighGUI that can fetch and handle events, so it needs to be called periodically for normal event processing, unless HighGUI is used within some environment that takes care of event processing. This function is the only method in HighGUI that can fetch and handle events, so it needs to be called periodically for normal event processing, unless HighGUI is used within some environment that takes care of event processing.

703
modules/imgproc/doc/feature_detection.rst
View File

@ -3,545 +3,268 @@ Feature Detection
.. highlight:: cpp .. highlight:: cpp
.. index:: Canny .. index:: Canny
cv::Canny cv::Canny
--------- ---------
`id=0.626295418243 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/Canny>`__
.. cfunction:: void Canny( const Mat\& image, Mat\& edges, double threshold1, double threshold2, int apertureSize=3, bool L2gradient=false ) .. cfunction:: void Canny( const Mat\& image, Mat\& edges, double threshold1, double threshold2, int apertureSize=3, bool L2gradient=false )
Finds edges in an image using Canny algorithm. Finds edges in an image using Canny algorithm.
:param image: Single-channel 8-bit input image
:param edges: The output edge map. It will have the same size and the same type as ``image``
:param threshold1: The first threshold for the hysteresis procedure
:param threshold2: The second threshold for the hysteresis procedure
:param apertureSize: Aperture size for the :func:`Sobel` operator
:param L2gradient: Indicates, whether the more accurate :math:`L_2` norm :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}` should be used to compute the image gradient magnitude ( ``L2gradient=true`` ), or a faster default :math:`L_1` norm :math:`=|dI/dx|+|dI/dy|` is enough ( ``L2gradient=false`` )
:param image: Single-channel 8-bit input image
The function finds edges in the input image ``image`` and marks them in the output map ``edges`` using the Canny algorithm. The smallest value between ``threshold1`` and ``threshold2`` is used for edge linking, the largest value is used to find the initial segments of strong edges, see
:param edges: The output edge map. It will have the same size and the same type as ``image``
:param threshold1: The first threshold for the hysteresis procedure
:param threshold2: The second threshold for the hysteresis procedure
:param apertureSize: Aperture size for the :func:`Sobel` operator
:param L2gradient: Indicates, whether the more accurate :math:`L_2` norm :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}` should be used to compute the image gradient magnitude ( ``L2gradient=true`` ), or a faster default :math:`L_1` norm :math:`=|dI/dx|+|dI/dy|` is enough ( ``L2gradient=false`` )
The function finds edges in the input image
``image``
and marks them in the output map
``edges``
using the Canny algorithm. The smallest value between
``threshold1``
and
``threshold2``
is used for edge linking, the largest value is used to find the initial segments of strong edges, see
http://en.wikipedia.org/wiki/Canny_edge_detector http://en.wikipedia.org/wiki/Canny_edge_detector
.. index:: cornerEigenValsAndVecs .. index:: cornerEigenValsAndVecs
cv::cornerEigenValsAndVecs cv::cornerEigenValsAndVecs
-------------------------- --------------------------
`id=0.211221916008 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/cornerEigenValsAndVecs>`__
.. cfunction:: void cornerEigenValsAndVecs( const Mat\& src, Mat\& dst, int blockSize, int apertureSize, int borderType=BORDER_DEFAULT ) .. cfunction:: void cornerEigenValsAndVecs( const Mat\& src, Mat\& dst, int blockSize, int apertureSize, int borderType=BORDER_DEFAULT )
Calculates eigenvalues and eigenvectors of image blocks for corner detection. Calculates eigenvalues and eigenvectors of image blocks for corner detection.
:param src: Input single-channel 8-bit or floating-point image
:param dst: Image to store the results. It will have the same size as ``src`` and the type ``CV_32FC(6)``
:param blockSize: Neighborhood size (see discussion)
:param apertureSize: Aperture parameter for the :func:`Sobel` operator
:param boderType: Pixel extrapolation method; see :func:`borderInterpolate`
For every pixel
:param src: Input single-channel 8-bit or floating-point image :math:`p` , the function ``cornerEigenValsAndVecs`` considers a ``blockSize`` :math:`\times` ``blockSize`` neigborhood
:math:`S(p)` . It calculates the covariation matrix of derivatives over the neighborhood as:
:param dst: Image to store the results. It will have the same size as ``src`` and the type ``CV_32FC(6)``
:param blockSize: Neighborhood size (see discussion)
:param apertureSize: Aperture parameter for the :func:`Sobel` operator
:param boderType: Pixel extrapolation method; see :func:`borderInterpolate`
For every pixel
:math:`p`
, the function
``cornerEigenValsAndVecs``
considers a
``blockSize``
:math:`\times`
``blockSize``
neigborhood
:math:`S(p)`
. It calculates the covariation matrix of derivatives over the neighborhood as:
.. math:: .. math::
M = \begin{bmatrix} \sum _{S(p)}(dI/dx)^2 & \sum _{S(p)}(dI/dx dI/dy)^2 \\ \sum _{S(p)}(dI/dx dI/dy)^2 & \sum _{S(p)}(dI/dy)^2 \end{bmatrix} M = \begin{bmatrix} \sum _{S(p)}(dI/dx)^2 & \sum _{S(p)}(dI/dx dI/dy)^2 \\ \sum _{S(p)}(dI/dx dI/dy)^2 & \sum _{S(p)}(dI/dy)^2 \end{bmatrix}
Where the derivatives are computed using
:func:`Sobel` operator.
Where the derivatives are computed using After that it finds eigenvectors and eigenvalues of
:func:`Sobel` :math:`M` and stores them into destination image in the form
operator. :math:`(\lambda_1, \lambda_2, x_1, y_1, x_2, y_2)` where
After that it finds eigenvectors and eigenvalues of * :math:`\lambda_1, \lambda_2` are the eigenvalues of
:math:`M` :math:`M` ; not sorted
and stores them into destination image in the form
:math:`(\lambda_1, \lambda_2, x_1, y_1, x_2, y_2)`
where
* :math:`x_1, y_1` are the eigenvectors corresponding to
* :math:`\lambda_1, \lambda_2`
are the eigenvalues of
:math:`M`
; not sorted
* :math:`x_1, y_1`
are the eigenvectors corresponding to
:math:`\lambda_1` :math:`\lambda_1`
* :math:`x_2, y_2` are the eigenvectors corresponding to
* :math:`x_2, y_2`
are the eigenvectors corresponding to
:math:`\lambda_2` :math:`\lambda_2`
The output of the function can be used for robust edge or corner detection. The output of the function can be used for robust edge or corner detection.
See also: See also:
:func:`cornerMinEigenVal` :func:`cornerMinEigenVal`,:func:`cornerHarris`,:func:`preCornerDetect`
,
:func:`cornerHarris`
,
:func:`preCornerDetect`
.. index:: cornerHarris .. index:: cornerHarris
cv::cornerHarris cv::cornerHarris
---------------- ----------------
`id=0.781956530281 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/cornerHarris>`__
.. cfunction:: void cornerHarris( const Mat\& src, Mat\& dst, int blockSize, int apertureSize, double k, int borderType=BORDER_DEFAULT ) .. cfunction:: void cornerHarris( const Mat\& src, Mat\& dst, int blockSize, int apertureSize, double k, int borderType=BORDER_DEFAULT )
Harris edge detector. Harris edge detector.
:param src: Input single-channel 8-bit or floating-point image
:param dst: Image to store the Harris detector responses; will have type ``CV_32FC1`` and the same size as ``src``
:param blockSize: Neighborhood size (see the discussion of :func:`cornerEigenValsAndVecs` )
:param apertureSize: Aperture parameter for the :func:`Sobel` operator
:param k: Harris detector free parameter. See the formula below
:param boderType: Pixel extrapolation method; see :func:`borderInterpolate`
:param src: Input single-channel 8-bit or floating-point image The function runs the Harris edge detector on the image. Similarly to
:func:`cornerMinEigenVal` and
:func:`cornerEigenValsAndVecs` , for each pixel
:param dst: Image to store the Harris detector responses; will have type ``CV_32FC1`` and the same size as ``src`` :math:`(x, y)` it calculates a
:math:`2\times2` gradient covariation matrix
:math:`M^{(x,y)}` over a
:param blockSize: Neighborhood size (see the discussion of :func:`cornerEigenValsAndVecs` ) :math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood. Then, it computes the following characteristic:
:param apertureSize: Aperture parameter for the :func:`Sobel` operator
:param k: Harris detector free parameter. See the formula below
:param boderType: Pixel extrapolation method; see :func:`borderInterpolate`
The function runs the Harris edge detector on the image. Similarly to
:func:`cornerMinEigenVal`
and
:func:`cornerEigenValsAndVecs`
, for each pixel
:math:`(x, y)`
it calculates a
:math:`2\times2`
gradient covariation matrix
:math:`M^{(x,y)}`
over a
:math:`\texttt{blockSize} \times \texttt{blockSize}`
neighborhood. Then, it computes the following characteristic:
.. math:: .. math::
\texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2 \texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2
Corners in the image can be found as the local maxima of this response map. Corners in the image can be found as the local maxima of this response map.
.. index:: cornerMinEigenVal .. index:: cornerMinEigenVal
cv::cornerMinEigenVal cv::cornerMinEigenVal
--------------------- ---------------------
`id=0.604155117868 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/cornerMinEigenVal>`__
.. cfunction:: void cornerMinEigenVal( const Mat\& src, Mat\& dst, int blockSize, int apertureSize=3, int borderType=BORDER_DEFAULT ) .. cfunction:: void cornerMinEigenVal( const Mat\& src, Mat\& dst, int blockSize, int apertureSize=3, int borderType=BORDER_DEFAULT )
Calculates the minimal eigenvalue of gradient matrices for corner detection. Calculates the minimal eigenvalue of gradient matrices for corner detection.
:param src: Input single-channel 8-bit or floating-point image
:param dst: Image to store the minimal eigenvalues; will have type ``CV_32FC1`` and the same size as ``src``
:param blockSize: Neighborhood size (see the discussion of :func:`cornerEigenValsAndVecs` )
:param apertureSize: Aperture parameter for the :func:`Sobel` operator
:param boderType: Pixel extrapolation method; see :func:`borderInterpolate`
The function is similar to
:param src: Input single-channel 8-bit or floating-point image :func:`cornerEigenValsAndVecs` but it calculates and stores only the minimal eigenvalue of the covariation matrix of derivatives, i.e.
:math:`\min(\lambda_1, \lambda_2)` in terms of the formulae in
:func:`cornerEigenValsAndVecs` description.
:param dst: Image to store the minimal eigenvalues; will have type ``CV_32FC1`` and the same size as ``src``
:param blockSize: Neighborhood size (see the discussion of :func:`cornerEigenValsAndVecs` )
:param apertureSize: Aperture parameter for the :func:`Sobel` operator
:param boderType: Pixel extrapolation method; see :func:`borderInterpolate`
The function is similar to
:func:`cornerEigenValsAndVecs`
but it calculates and stores only the minimal eigenvalue of the covariation matrix of derivatives, i.e.
:math:`\min(\lambda_1, \lambda_2)`
in terms of the formulae in
:func:`cornerEigenValsAndVecs`
description.
.. index:: cornerSubPix .. index:: cornerSubPix
cv::cornerSubPix cv::cornerSubPix
---------------- ----------------
`id=0.0211213978919 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/cornerSubPix>`__
.. cfunction:: void cornerSubPix( const Mat\& image, vector<Point2f>\& corners, Size winSize, Size zeroZone, TermCriteria criteria ) .. cfunction:: void cornerSubPix( const Mat\& image, vector<Point2f>\& corners, Size winSize, Size zeroZone, TermCriteria criteria )
Refines the corner locations. Refines the corner locations.
:param image: Input image
:param corners: Initial coordinates of the input corners; refined coordinates on output
:param winSize: Half of the side length of the search window. For example, if ``winSize=Size(5,5)`` , then a :math:`5*2+1 \times 5*2+1 = 11 \times 11` search window would be used
:param zeroZone: Half of the size of the dead region in the middle of the search zone over which the summation in the formula below is not done. It is used sometimes to avoid possible singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such size
:param criteria: Criteria for termination of the iterative process of corner refinement. That is, the process of corner position refinement stops either after a certain number of iterations or when a required accuracy is achieved. The ``criteria`` may specify either of or both the maximum number of iteration and the required accuracy
:param image: Input image
:param corners: Initial coordinates of the input corners; refined coordinates on output
:param winSize: Half of the side length of the search window. For example, if ``winSize=Size(5,5)`` , then a :math:`5*2+1 \times 5*2+1 = 11 \times 11` search window would be used
:param zeroZone: Half of the size of the dead region in the middle of the search zone over which the summation in the formula below is not done. It is used sometimes to avoid possible singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such size
:param criteria: Criteria for termination of the iterative process of corner refinement. That is, the process of corner position refinement stops either after a certain number of iterations or when a required accuracy is achieved. The ``criteria`` may specify either of or both the maximum number of iteration and the required accuracy
The function iterates to find the sub-pixel accurate location of corners, or radial saddle points, as shown in on the picture below. The function iterates to find the sub-pixel accurate location of corners, or radial saddle points, as shown in on the picture below.
.. image:: ../../pics/cornersubpix.png .. image:: ../../pics/cornersubpix.png
Sub-pixel accurate corner locator is based on the observation that every vector from the center
:math:`q` to a point
Sub-pixel accurate corner locator is based on the observation that every vector from the center :math:`p` located within a neighborhood of
:math:`q` :math:`q` is orthogonal to the image gradient at
to a point :math:`p` subject to image and measurement noise. Consider the expression:
:math:`p`
located within a neighborhood of
:math:`q`
is orthogonal to the image gradient at
:math:`p`
subject to image and measurement noise. Consider the expression:
.. math:: .. math::
\epsilon _i = {DI_{p_i}}^T \cdot (q - p_i) \epsilon _i = {DI_{p_i}}^T \cdot (q - p_i)
where
:math:`{DI_{p_i}}`
is the image gradient at the one of the points
:math:`p_i`
in a neighborhood of
:math:`q`
. The value of
:math:`q`
is to be found such that
:math:`\epsilon_i`
is minimized. A system of equations may be set up with
:math:`\epsilon_i`
set to zero:
where
:math:`{DI_{p_i}}` is the image gradient at the one of the points
:math:`p_i` in a neighborhood of
:math:`q` . The value of
:math:`q` is to be found such that
:math:`\epsilon_i` is minimized. A system of equations may be set up with
:math:`\epsilon_i` set to zero:
.. math:: .. math::
\sum _i(DI_{p_i} \cdot {DI_{p_i}}^T) - \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T \cdot p_i) \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T) - \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T \cdot p_i)
where the gradients are summed within a neighborhood ("search window") of
:math:`q`
. Calling the first gradient term
:math:`G`
and the second gradient term
:math:`b`
gives:
where the gradients are summed within a neighborhood ("search window") of
:math:`q` . Calling the first gradient term
:math:`G` and the second gradient term
:math:`b` gives:
.. math:: .. math::
q = G^{-1} \cdot b q = G^{-1} \cdot b
The algorithm sets the center of the neighborhood window at this new center
:math:`q`
and then iterates until the center keeps within a set threshold.
The algorithm sets the center of the neighborhood window at this new center
:math:`q` and then iterates until the center keeps within a set threshold.
.. index:: goodFeaturesToTrack .. index:: goodFeaturesToTrack
cv::goodFeaturesToTrack cv::goodFeaturesToTrack
----------------------- -----------------------
`id=0.784762708085 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/goodFeaturesToTrack>`__
.. cfunction:: void goodFeaturesToTrack( const Mat\& image, vector<Point2f>\& corners, int maxCorners, double qualityLevel, double minDistance, const Mat\& mask=Mat(), int blockSize=3, bool useHarrisDetector=false, double k=0.04 ) .. cfunction:: void goodFeaturesToTrack( const Mat\& image, vector<Point2f>\& corners, int maxCorners, double qualityLevel, double minDistance, const Mat\& mask=Mat(), int blockSize=3, bool useHarrisDetector=false, double k=0.04 )
Determines strong corners on an image. Determines strong corners on an image.
:param image: The input 8-bit or floating-point 32-bit, single-channel image
:param corners: The output vector of detected corners
:param maxCorners: The maximum number of corners to return. If there are more corners than that will be found, the strongest of them will be returned
:param qualityLevel: Characterizes the minimal accepted quality of image corners; the value of the parameter is multiplied by the by the best corner quality measure (which is the min eigenvalue, see :func:`cornerMinEigenVal` , or the Harris function response, see :func:`cornerHarris` ). The corners, which quality measure is less than the product, will be rejected. For example, if the best corner has the quality measure = 1500, and the ``qualityLevel=0.01`` , then all the corners which quality measure is less than 15 will be rejected.
:param minDistance: The minimum possible Euclidean distance between the returned corners
:param mask: The optional region of interest. If the image is not empty (then it needs to have the type ``CV_8UC1`` and the same size as ``image`` ), it will specify the region in which the corners are detected
:param blockSize: Size of the averaging block for computing derivative covariation matrix over each pixel neighborhood, see :func:`cornerEigenValsAndVecs`
:param useHarrisDetector: Indicates, whether to use operator or :func:`cornerMinEigenVal`
:param k: Free parameter of Harris detector
:param image: The input 8-bit or floating-point 32-bit, single-channel image
:param corners: The output vector of detected corners
:param maxCorners: The maximum number of corners to return. If there are more corners than that will be found, the strongest of them will be returned
:param qualityLevel: Characterizes the minimal accepted quality of image corners; the value of the parameter is multiplied by the by the best corner quality measure (which is the min eigenvalue, see :func:`cornerMinEigenVal` , or the Harris function response, see :func:`cornerHarris` ). The corners, which quality measure is less than the product, will be rejected. For example, if the best corner has the quality measure = 1500, and the ``qualityLevel=0.01`` , then all the corners which quality measure is less than 15 will be rejected.
:param minDistance: The minimum possible Euclidean distance between the returned corners
:param mask: The optional region of interest. If the image is not empty (then it needs to have the type ``CV_8UC1`` and the same size as ``image`` ), it will specify the region in which the corners are detected
:param blockSize: Size of the averaging block for computing derivative covariation matrix over each pixel neighborhood, see :func:`cornerEigenValsAndVecs`
:param useHarrisDetector: Indicates, whether to use operator or :func:`cornerMinEigenVal`
:param k: Free parameter of Harris detector
The function finds the most prominent corners in the image or in the specified image region, as described The function finds the most prominent corners in the image or in the specified image region, as described
in in
Shi94 Shi94
: :
#. #.
the function first calculates the corner quality measure at every source image pixel using the the function first calculates the corner quality measure at every source image pixel using the
:func:`cornerMinEigenVal` :func:`cornerMinEigenVal` or
or
:func:`cornerHarris` :func:`cornerHarris`
#. #.
then it performs non-maxima suppression (the local maxima in then it performs non-maxima suppression (the local maxima in
:math:`3\times 3` :math:`3\times 3` neighborhood
neighborhood
are retained). are retained).
#. #.
the next step rejects the corners with the minimal eigenvalue less than the next step rejects the corners with the minimal eigenvalue less than
:math:`\texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y)` :math:`\texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y)` .
.
#. #.
the remaining corners are then sorted by the quality measure in the descending order. the remaining corners are then sorted by the quality measure in the descending order.
#. #.
finally, the function throws away each corner finally, the function throws away each corner
:math:`pt_j` :math:`pt_j` if there is a stronger corner
if there is a stronger corner :math:`pt_i` (
:math:`pt_i` :math:`i < j` ) such that the distance between them is less than ``minDistance``
(
:math:`i < j`
) such that the distance between them is less than
``minDistance``
The function can be used to initialize a point-based tracker of an object. The function can be used to initialize a point-based tracker of an object.
Note that the if the function is called with different values Note that the if the function is called with different values ``A`` and ``B`` of the parameter ``qualityLevel`` , and ``A`` > {B}, the vector of returned corners with ``qualityLevel=A`` will be the prefix of the output vector with ``qualityLevel=B`` .
``A``
and
``B``
of the parameter
``qualityLevel``
, and
``A``
> {B}, the vector of returned corners with
``qualityLevel=A``
will be the prefix of the output vector with
``qualityLevel=B``
.
See also:
:func:`cornerMinEigenVal`
,
:func:`cornerHarris`
,
:func:`calcOpticalFlowPyrLK`
,
:func:`estimateRigidMotion`
,
:func:`PlanarObjectDetector`
,
:func:`OneWayDescriptor`
See also:
:func:`cornerMinEigenVal`,:func:`cornerHarris`,:func:`calcOpticalFlowPyrLK`,:func:`estimateRigidMotion`,:func:`PlanarObjectDetector`,:func:`OneWayDescriptor`
.. index:: HoughCircles .. index:: HoughCircles
cv::HoughCircles cv::HoughCircles
---------------- ----------------
`id=0.474895262744 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/HoughCircles>`__
.. cfunction:: void HoughCircles( Mat\& image, vector<Vec3f>\& circles, int method, double dp, double minDist, double param1=100, double param2=100, int minRadius=0, int maxRadius=0 ) .. cfunction:: void HoughCircles( Mat\& image, vector<Vec3f>\& circles, int method, double dp, double minDist, double param1=100, double param2=100, int minRadius=0, int maxRadius=0 )
Finds circles in a grayscale image using a Hough transform. Finds circles in a grayscale image using a Hough transform.
:param image: The 8-bit, single-channel, grayscale input image
:param circles: The output vector of found circles. Each vector is encoded as 3-element floating-point vector :math:`(x, y, radius)`
:param method: Currently, the only implemented method is ``CV_HOUGH_GRADIENT`` , which is basically *21HT* , described in Yuen90 .
:param dp: The inverse ratio of the accumulator resolution to the image resolution. For example, if ``dp=1`` , the accumulator will have the same resolution as the input image, if ``dp=2`` - accumulator will have half as big width and height, etc
:param minDist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed
:param param1: The first method-specific parameter. in the case of ``CV_HOUGH_GRADIENT`` it is the higher threshold of the two passed to :func:`Canny` edge detector (the lower one will be twice smaller)
:param image: The 8-bit, single-channel, grayscale input image
:param circles: The output vector of found circles. Each vector is encoded as 3-element floating-point vector :math:`(x, y, radius)`
:param method: Currently, the only implemented method is ``CV_HOUGH_GRADIENT`` , which is basically *21HT* , described in Yuen90 .
:param dp: The inverse ratio of the accumulator resolution to the image resolution. For example, if ``dp=1`` , the accumulator will have the same resolution as the input image, if ``dp=2`` - accumulator will have half as big width and height, etc
:param minDist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed
:param param1: The first method-specific parameter. in the case of ``CV_HOUGH_GRADIENT`` it is the higher threshold of the two passed to :func:`Canny` edge detector (the lower one will be twice smaller)
:param param2: The second method-specific parameter. in the case of ``CV_HOUGH_GRADIENT`` it is the accumulator threshold at the center detection stage. The smaller it is, the more false circles may be detected. Circles, corresponding to the larger accumulator values, will be returned first
:param minRadius: Minimum circle radius
:param maxRadius: Maximum circle radius
The function finds circles in a grayscale image using some modification of Hough transform. Here is a short usage example:
:param param2: The second method-specific parameter. in the case of ``CV_HOUGH_GRADIENT`` it is the accumulator threshold at the center detection stage. The smaller it is, the more false circles may be detected. Circles, corresponding to the larger accumulator values, will be returned first
:param minRadius: Minimum circle radius
:param maxRadius: Maximum circle radius
:: The function finds circles in a grayscale image using some modification of Hough transform. Here is a short usage example: ::
#include <cv.h> #include <cv.h>
#include <highgui.h> #include <highgui.h>
#include <math.h> #include <math.h>
using namespace cv; using namespace cv;
int main(int argc, char** argv) int main(int argc, char** argv)
{ {
Mat img, gray; Mat img, gray;
@ -566,144 +289,84 @@ The function finds circles in a grayscale image using some modification of Hough
imshow( "circles", img ); imshow( "circles", img );
return 0; return 0;
} }
.. ..
Note that usually the function detects the circles' centers well, however it may fail to find the correct radii. You can assist the function by specifying the radius range ( Note that usually the function detects the circles' centers well, however it may fail to find the correct radii. You can assist the function by specifying the radius range ( ``minRadius`` and ``maxRadius`` ) if you know it, or you may ignore the returned radius, use only the center and find the correct radius using some additional procedure.
``minRadius``
and
``maxRadius``
) if you know it, or you may ignore the returned radius, use only the center and find the correct radius using some additional procedure.
See also:
:func:`fitEllipse`
,
:func:`minEnclosingCircle`
See also:
:func:`fitEllipse`,:func:`minEnclosingCircle`
.. index:: HoughLines .. index:: HoughLines
cv::HoughLines cv::HoughLines
-------------- --------------
`id=0.877791227007 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/HoughLines>`__
.. cfunction:: void HoughLines( Mat\& image, vector<Vec2f>\& lines, double rho, double theta, int threshold, double srn=0, double stn=0 ) .. cfunction:: void HoughLines( Mat\& image, vector<Vec2f>\& lines, double rho, double theta, int threshold, double srn=0, double stn=0 )
Finds lines in a binary image using standard Hough transform. Finds lines in a binary image using standard Hough transform.
:param image: The 8-bit, single-channel, binary source image. The image may be modified by the function
:param lines: The output vector of lines. Each line is represented by a two-element vector :math:`(\rho, \theta)` . :math:`\rho` is the distance from the coordinate origin :math:`(0,0)` (top-left corner of the image) and :math:`\theta` is the line rotation angle in radians ( :math:`0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}` )
:param rho: Distance resolution of the accumulator in pixels
:param theta: Angle resolution of the accumulator in radians
:param threshold: The accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` )
:param image: The 8-bit, single-channel, binary source image. The image may be modified by the function
:param lines: The output vector of lines. Each line is represented by a two-element vector :math:`(\rho, \theta)` . :math:`\rho` is the distance from the coordinate origin :math:`(0,0)` (top-left corner of the image) and :math:`\theta` is the line rotation angle in radians ( :math:`0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}` )
:param rho: Distance resolution of the accumulator in pixels
:param theta: Angle resolution of the accumulator in radians
:param threshold: The accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` )
:param srn: For the multi-scale Hough transform it is the divisor for the distance resolution ``rho`` . The coarse accumulator distance resolution will be ``rho`` and the accurate accumulator resolution will be ``rho/srn`` . If both ``srn=0`` and ``stn=0`` then the classical Hough transform is used, otherwise both these parameters should be positive.
:param stn: For the multi-scale Hough transform it is the divisor for the distance resolution ``theta``
The function implements standard or standard multi-scale Hough transform algorithm for line detection. See
:func:`HoughLinesP`
for the code example.
:param srn: For the multi-scale Hough transform it is the divisor for the distance resolution ``rho`` . The coarse accumulator distance resolution will be ``rho`` and the accurate accumulator resolution will be ``rho/srn`` . If both ``srn=0`` and ``stn=0`` then the classical Hough transform is used, otherwise both these parameters should be positive.
:param stn: For the multi-scale Hough transform it is the divisor for the distance resolution ``theta``
The function implements standard or standard multi-scale Hough transform algorithm for line detection. See
:func:`HoughLinesP` for the code example.
.. index:: HoughLinesP .. index:: HoughLinesP
cv::HoughLinesP cv::HoughLinesP
--------------- ---------------
`id=0.855533341526 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/HoughLinesP>`__
.. cfunction:: void HoughLinesP( Mat\& image, vector<Vec4i>\& lines, double rho, double theta, int threshold, double minLineLength=0, double maxLineGap=0 ) .. cfunction:: void HoughLinesP( Mat\& image, vector<Vec4i>\& lines, double rho, double theta, int threshold, double minLineLength=0, double maxLineGap=0 )
Finds lines segments in a binary image using probabilistic Hough transform. Finds lines segments in a binary image using probabilistic Hough transform.
:param image: The 8-bit, single-channel, binary source image. The image may be modified by the function
:param lines: The output vector of lines. Each line is represented by a 4-element vector :math:`(x_1, y_1, x_2, y_2)` , where :math:`(x_1,y_1)` and :math:`(x_2, y_2)` are the ending points of each line segment detected.
:param rho: Distance resolution of the accumulator in pixels
:param theta: Angle resolution of the accumulator in radians
:param threshold: The accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` )
:param image: The 8-bit, single-channel, binary source image. The image may be modified by the function
:param minLineLength: The minimum line length. Line segments shorter than that will be rejected
:param lines: The output vector of lines. Each line is represented by a 4-element vector :math:`(x_1, y_1, x_2, y_2)` , where :math:`(x_1,y_1)` and :math:`(x_2, y_2)` are the ending points of each line segment detected. :param maxLineGap: The maximum allowed gap between points on the same line to link them.
The function implements probabilistic Hough transform algorithm for line detection, described in
:param rho: Distance resolution of the accumulator in pixels
:param theta: Angle resolution of the accumulator in radians
:param threshold: The accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` )
:param minLineLength: The minimum line length. Line segments shorter than that will be rejected
:param maxLineGap: The maximum allowed gap between points on the same line to link them.
The function implements probabilistic Hough transform algorithm for line detection, described in
Matas00 Matas00
. Below is line detection example: . Below is line detection example: ::
::
/* This is a standalone program. Pass an image name as a first parameter /* This is a standalone program. Pass an image name as a first parameter
of the program. Switch between standard and probabilistic Hough transform of the program. Switch between standard and probabilistic Hough transform
by changing "#if 1" to "#if 0" and back */ by changing "#if 1" to "#if 0" and back */
#include <cv.h> #include <cv.h>
#include <highgui.h> #include <highgui.h>
#include <math.h> #include <math.h>
using namespace cv; using namespace cv;
int main(int argc, char** argv) int main(int argc, char** argv)
{ {
Mat src, dst, color_dst; Mat src, dst, color_dst;
if( argc != 2 || !(src=imread(argv[1], 0)).data) if( argc != 2 || !(src=imread(argv[1], 0)).data)
return -1; return -1;
Canny( src, dst, 50, 200, 3 ); Canny( src, dst, 50, 200, 3 );
cvtColor( dst, color_dst, CV_GRAY2BGR ); cvtColor( dst, color_dst, CV_GRAY2BGR );
#if 0 #if 0
vector<Vec2f> lines; vector<Vec2f> lines;
HoughLines( dst, lines, 1, CV_PI/180, 100 ); HoughLines( dst, lines, 1, CV_PI/180, 100 );
for( size_t i = 0; i < lines.size(); i++ ) for( size_t i = 0; i < lines.size(); i++ )
{ {
float rho = lines[i][0]; float rho = lines[i][0];
@ -727,103 +390,53 @@ Matas00
#endif #endif
namedWindow( "Source", 1 ); namedWindow( "Source", 1 );
imshow( "Source", src ); imshow( "Source", src );
namedWindow( "Detected Lines", 1 ); namedWindow( "Detected Lines", 1 );
imshow( "Detected Lines", color_dst ); imshow( "Detected Lines", color_dst );
waitKey(0); waitKey(0);
return 0; return 0;
} }
.. ..
This is the sample picture the function parameters have been tuned for: This is the sample picture the function parameters have been tuned for:
.. image:: ../../pics/building.jpg .. image:: ../../pics/building.jpg
And this is the output of the above program in the case of probabilistic Hough transform And this is the output of the above program in the case of probabilistic Hough transform
.. image:: ../../pics/houghp.png .. image:: ../../pics/houghp.png
.. index:: preCornerDetect .. index:: preCornerDetect
cv::preCornerDetect cv::preCornerDetect
------------------- -------------------
`id=0.828630230352 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/preCornerDetect>`__
.. cfunction:: void preCornerDetect( const Mat\& src, Mat\& dst, int apertureSize, int borderType=BORDER_DEFAULT ) .. cfunction:: void preCornerDetect( const Mat\& src, Mat\& dst, int apertureSize, int borderType=BORDER_DEFAULT )
Calculates the feature map for corner detection Calculates the feature map for corner detection
:param src: The source single-channel 8-bit of floating-point image
:param dst: The output image; will have type ``CV_32F`` and the same size as ``src``
:param apertureSize: Aperture size of :func:`Sobel`
:param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
:param src: The source single-channel 8-bit of floating-point image
:param dst: The output image; will have type ``CV_32F`` and the same size as ``src``
:param apertureSize: Aperture size of :func:`Sobel`
:param borderType: The pixel extrapolation method; see :func:`borderInterpolate`
The function calculates the complex spatial derivative-based function of the source image The function calculates the complex spatial derivative-based function of the source image
.. math:: .. math::
\texttt{dst} = (D_x \texttt{src} )^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src} )^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src} \texttt{dst} = (D_x \texttt{src} )^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src} )^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src}
where
:math:`D_x`,:math:`D_y` are the first image derivatives,
:math:`D_{xx}`,:math:`D_{yy}` are the second image derivatives and
:math:`D_{xy}` is the mixed derivative.
where The corners can be found as local maximums of the functions, as shown below: ::
:math:`D_x`
,
:math:`D_y`
are the first image derivatives,
:math:`D_{xx}`
,
:math:`D_{yy}`
are the second image derivatives and
:math:`D_{xy}`
is the mixed derivative.
The corners can be found as local maximums of the functions, as shown below:
::
Mat corners, dilated_corners; Mat corners, dilated_corners;
preCornerDetect(image, corners, 3); preCornerDetect(image, corners, 3);
// dilation with 3x3 rectangular structuring element // dilation with 3x3 rectangular structuring element
dilate(corners, dilated_corners, Mat(), 1); dilate(corners, dilated_corners, Mat(), 1);
Mat corner_mask = corners == dilated_corners; Mat corner_mask = corners == dilated_corners;
.. ..

2087
modules/imgproc/doc/filtering.rst
View File

File diff suppressed because it is too large Load Diff

698
modules/imgproc/doc/geometric_transformations.rst
View File

@ -3,772 +3,378 @@ Geometric Image Transformations
.. highlight:: cpp .. highlight:: cpp
The functions in this section perform various geometrical transformations of 2D images. That is, they do not change the image content, but deform the pixel grid, and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel
The functions in this section perform various geometrical transformations of 2D images. That is, they do not change the image content, but deform the pixel grid, and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel :math:`(x, y)` of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value, that is:
:math:`(x, y)`
of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value, that is:
.. math:: .. math::
\texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y)) \texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))
In the case when the user specifies the forward mapping:
:math:`\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}` , the OpenCV functions first compute the corresponding inverse mapping:
:math:`\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}` and then use the above formula.
In the case when the user specifies the forward mapping: The actual implementations of the geometrical transformations, from the most generic
:math:`\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}` :ref:`Remap` and to the simplest and the fastest
, the OpenCV functions first compute the corresponding inverse mapping: :ref:`Resize` , need to solve the 2 main problems with the above formula:
:math:`\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}`
and then use the above formula.
The actual implementations of the geometrical transformations, from the most generic
:ref:`Remap`
and to the simplest and the fastest
:ref:`Resize`
, need to solve the 2 main problems with the above formula:
#. #.
extrapolation of non-existing pixels. Similarly to the filtering functions, described in the previous section, for some extrapolation of non-existing pixels. Similarly to the filtering functions, described in the previous section, for some
:math:`(x,y)` :math:`(x,y)` one of
one of :math:`f_x(x,y)` or
:math:`f_x(x,y)` :math:`f_y(x,y)` , or they both, may fall outside of the image, in which case some extrapolation method needs to be used. OpenCV provides the same selection of the extrapolation methods as in the filtering functions, but also an additional method ``BORDER_TRANSPARENT`` , which means that the corresponding pixels in the destination image will not be modified at all.
or
:math:`f_y(x,y)`
, or they both, may fall outside of the image, in which case some extrapolation method needs to be used. OpenCV provides the same selection of the extrapolation methods as in the filtering functions, but also an additional method
``BORDER_TRANSPARENT``
, which means that the corresponding pixels in the destination image will not be modified at all.
#. #.
interpolation of pixel values. Usually interpolation of pixel values. Usually
:math:`f_x(x,y)` :math:`f_x(x,y)` and
and :math:`f_y(x,y)` are floating-point numbers (i.e.
:math:`f_y(x,y)` :math:`\left<f_x, f_y\right>` can be an affine or perspective transformation, or radial lens distortion correction etc.), so a pixel values at fractional coordinates needs to be retrieved. In the simplest case the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel used, which is called nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated `interpolation methods <http://en.wikipedia.org/wiki/Multivariate_interpolation>`_
are floating-point numbers (i.e. , where a polynomial function is fit into some neighborhood of the computed pixel
:math:`\left<f_x, f_y\right>` :math:`(f_x(x,y), f_y(x,y))` and then the value of the polynomial at
can be an affine or perspective transformation, or radial lens distortion correction etc.), so a pixel values at fractional coordinates needs to be retrieved. In the simplest case the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel used, which is called nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated :math:`(f_x(x,y), f_y(x,y))` is taken as the interpolated pixel value. In OpenCV you can choose between several interpolation methods, see
`interpolation methods <http://en.wikipedia.org/wiki/Multivariate_interpolation>`_ :ref:`Resize` .
, where a polynomial function is fit into some neighborhood of the computed pixel
:math:`(f_x(x,y), f_y(x,y))`
and then the value of the polynomial at
:math:`(f_x(x,y), f_y(x,y))`
is taken as the interpolated pixel value. In OpenCV you can choose between several interpolation methods, see
:ref:`Resize`
.
.. index:: convertMaps .. index:: convertMaps
cv::convertMaps cv::convertMaps
--------------- ---------------
`id=0.830076060616 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/convertMaps>`__
.. cfunction:: void convertMaps( const Mat\& map1, const Mat\& map2, Mat\& dstmap1, Mat\& dstmap2, int dstmap1type, bool nninterpolation=false ) .. cfunction:: void convertMaps( const Mat\& map1, const Mat\& map2, Mat\& dstmap1, Mat\& dstmap2, int dstmap1type, bool nninterpolation=false )
Converts image transformation maps from one representation to another Converts image transformation maps from one representation to another
:param map1: The first input map of type ``CV_16SC2`` or ``CV_32FC1`` or ``CV_32FC2``
:param map2: The second input map of type ``CV_16UC1`` or ``CV_32FC1`` or none (empty matrix), respectively
:param dstmap1: The first output map; will have type ``dstmap1type`` and the same size as ``src``
:param dstmap2: The second output map
:param dstmap1type: The type of the first output map; should be ``CV_16SC2`` , ``CV_32FC1`` or ``CV_32FC2``
:param nninterpolation: Indicates whether the fixed-point maps will be used for nearest-neighbor or for more complex interpolation
The function converts a pair of maps for
:func:`remap` from one representation to another. The following options ( ``(map1.type(), map2.type())`` :math:`\rightarrow` ``(dstmap1.type(), dstmap2.type())`` ) are supported:
:param map1: The first input map of type ``CV_16SC2`` or ``CV_32FC1`` or ``CV_32FC2``
:param map2: The second input map of type ``CV_16UC1`` or ``CV_32FC1`` or none (empty matrix), respectively
:param dstmap1: The first output map; will have type ``dstmap1type`` and the same size as ``src``
:param dstmap2: The second output map
:param dstmap1type: The type of the first output map; should be ``CV_16SC2`` , ``CV_32FC1`` or ``CV_32FC2``
:param nninterpolation: Indicates whether the fixed-point maps will be used for nearest-neighbor or for more complex interpolation
The function converts a pair of maps for
:func:`remap`
from one representation to another. The following options (
``(map1.type(), map2.type())``
:math:`\rightarrow`
``(dstmap1.type(), dstmap2.type())``
) are supported:
#. #.
:math:`\texttt{(CV\_32FC1, CV\_32FC1)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` :math:`\texttt{(CV\_32FC1, CV\_32FC1)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . This is the most frequently used conversion operation, in which the original floating-point maps (see
. This is the most frequently used conversion operation, in which the original floating-point maps (see :func:`remap` ) are converted to more compact and much faster fixed-point representation. The first output array will contain the rounded coordinates and the second array (created only when ``nninterpolation=false`` ) will contain indices in the interpolation tables.
:func:`remap`
) are converted to more compact and much faster fixed-point representation. The first output array will contain the rounded coordinates and the second array (created only when
``nninterpolation=false``
) will contain indices in the interpolation tables.
#. #.
:math:`\texttt{(CV\_32FC2)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` :math:`\texttt{(CV\_32FC2)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . The same as above, but the original maps are stored in one 2-channel matrix.
. The same as above, but the original maps are stored in one 2-channel matrix.
#. #.
the reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals. the reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.
See also:
:func:`remap`
,
:func:`undisort`
,
:func:`initUndistortRectifyMap`
See also:
:func:`remap`,:func:`undisort`,:func:`initUndistortRectifyMap`
.. index:: getAffineTransform .. index:: getAffineTransform
cv::getAffineTransform cv::getAffineTransform
---------------------- ----------------------
`id=0.578246613742 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/getAffineTransform>`__
.. cfunction:: Mat getAffineTransform( const Point2f src[], const Point2f dst[] ) .. cfunction:: Mat getAffineTransform( const Point2f src[], const Point2f dst[] )
Calculates the affine transform from 3 pairs of the corresponding points Calculates the affine transform from 3 pairs of the corresponding points
:param src: Coordinates of a triangle vertices in the source image
:param dst: Coordinates of the corresponding triangle vertices in the destination image
The function calculates the
:math:`2 \times 3` matrix of an affine transform such that:
:param src: Coordinates of a triangle vertices in the source image
:param dst: Coordinates of the corresponding triangle vertices in the destination image
The function calculates the
:math:`2 \times 3`
matrix of an affine transform such that:
.. math:: .. math::
\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix} \begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}
where where
.. math:: .. math::
dst(i)=(x'_i,y'_i), dst(i)=(x'_i,y'_i),
src(i)=(x_i, y_i), src(i)=(x_i, y_i),
i=0,1,2 i=0,1,2
See also:
:func:`warpAffine`
,
:func:`transform`
See also:
:func:`warpAffine`,:func:`transform`
.. index:: getPerspectiveTransform .. index:: getPerspectiveTransform
cv::getPerspectiveTransform cv::getPerspectiveTransform
--------------------------- ---------------------------
`id=0.124978390322 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/getPerspectiveTransform>`__
.. cfunction:: Mat getPerspectiveTransform( const Point2f src[], const Point2f dst[] ) .. cfunction:: Mat getPerspectiveTransform( const Point2f src[], const Point2f dst[] )
Calculates the perspective transform from 4 pairs of the corresponding points Calculates the perspective transform from 4 pairs of the corresponding points
:param src: Coordinates of a quadrange vertices in the source image
:param dst: Coordinates of the corresponding quadrangle vertices in the destination image
The function calculates the
:math:`3 \times 3` matrix of a perspective transform such that:
:param src: Coordinates of a quadrange vertices in the source image
:param dst: Coordinates of the corresponding quadrangle vertices in the destination image
The function calculates the
:math:`3 \times 3`
matrix of a perspective transform such that:
.. math:: .. math::
\begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix} \begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}
where where
.. math:: .. math::
dst(i)=(x'_i,y'_i), dst(i)=(x'_i,y'_i),
src(i)=(x_i, y_i), src(i)=(x_i, y_i),
i=0,1,2 i=0,1,2
See also:
:func:`findHomography`
,
:func:`warpPerspective`
,
:func:`perspectiveTransform`
See also:
:func:`findHomography`,:func:`warpPerspective`,:func:`perspectiveTransform`
.. index:: getRectSubPix .. index:: getRectSubPix
cv::getRectSubPix cv::getRectSubPix
----------------- -----------------
`id=0.0571919909094 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/getRectSubPix>`__
.. cfunction:: void getRectSubPix( const Mat\& image, Size patchSize, Point2f center, Mat\& dst, int patchType=-1 ) .. cfunction:: void getRectSubPix( const Mat\& image, Size patchSize, Point2f center, Mat\& dst, int patchType=-1 )
Retrieves the pixel rectangle from an image with sub-pixel accuracy Retrieves the pixel rectangle from an image with sub-pixel accuracy
:param src: Source image
:param patchSize: Size of the extracted patch
:param center: Floating point coordinates of the extracted rectangle center within the source image. The center must be inside the image
:param dst: The extracted patch; will have the size ``patchSize`` and the same number of channels as ``src``
:param patchType: The depth of the extracted pixels. By default they will have the same depth as ``src``
:param src: Source image The function ``getRectSubPix`` extracts pixels from ``src`` :
:param patchSize: Size of the extracted patch
:param center: Floating point coordinates of the extracted rectangle center within the source image. The center must be inside the image
:param dst: The extracted patch; will have the size ``patchSize`` and the same number of channels as ``src``
:param patchType: The depth of the extracted pixels. By default they will have the same depth as ``src``
The function
``getRectSubPix``
extracts pixels from
``src``
:
.. math:: .. math::
dst(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5) dst(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)
where the values of the pixels at non-integer coordinates are retrieved where the values of the pixels at non-integer coordinates are retrieved
using bilinear interpolation. Every channel of multiple-channel using bilinear interpolation. Every channel of multiple-channel
images is processed independently. While the rectangle center images is processed independently. While the rectangle center
must be inside the image, parts of the rectangle may be must be inside the image, parts of the rectangle may be
outside. In this case, the replication border mode (see outside. In this case, the replication border mode (see
:func:`borderInterpolate` :func:`borderInterpolate` ) is used to extrapolate
) is used to extrapolate
the pixel values outside of the image. the pixel values outside of the image.
See also: See also:
:func:`warpAffine` :func:`warpAffine`,:func:`warpPerspective`
,
:func:`warpPerspective`
.. index:: getRotationMatrix2D .. index:: getRotationMatrix2D
cv::getRotationMatrix2D cv::getRotationMatrix2D
----------------------- -----------------------
`id=0.641646199188 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/getRotationMatrix2D>`__
.. cfunction:: Mat getRotationMatrix2D( Point2f center, double angle, double scale ) .. cfunction:: Mat getRotationMatrix2D( Point2f center, double angle, double scale )
Calculates the affine matrix of 2d rotation. Calculates the affine matrix of 2d rotation.
:param center: Center of the rotation in the source image
:param angle: The rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner)
:param scale: Isotropic scale factor
:param center: Center of the rotation in the source image
:param angle: The rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner)
:param scale: Isotropic scale factor
The function calculates the following matrix: The function calculates the following matrix:
.. math:: .. math::
\begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot \texttt{center.x} - \beta \cdot \texttt{center.y} \\ - \beta & \alpha & \beta \cdot \texttt{center.x} - (1- \alpha ) \cdot \texttt{center.y} \end{bmatrix} \begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot \texttt{center.x} - \beta \cdot \texttt{center.y} \\ - \beta & \alpha & \beta \cdot \texttt{center.x} - (1- \alpha ) \cdot \texttt{center.y} \end{bmatrix}
where where
.. math:: .. math::
\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array} \begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}
The transformation maps the rotation center to itself. If this is not the purpose, the shift should be adjusted. The transformation maps the rotation center to itself. If this is not the purpose, the shift should be adjusted.
See also: See also:
:func:`getAffineTransform` :func:`getAffineTransform`,:func:`warpAffine`,:func:`transform`
,
:func:`warpAffine`
,
:func:`transform`
.. index:: invertAffineTransform .. index:: invertAffineTransform
cv::invertAffineTransform cv::invertAffineTransform
------------------------- -------------------------
`id=0.772575709646 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/invertAffineTransform>`__
.. cfunction:: void invertAffineTransform(const Mat\& M, Mat\& iM) .. cfunction:: void invertAffineTransform(const Mat\& M, Mat\& iM)
Inverts an affine transformation Inverts an affine transformation
:param M: The original affine transformation
:param iM: The output reverse affine transformation
The function computes inverse affine transformation represented by
:math:`2 \times 3` matrix ``M`` :
:param M: The original affine transformation
:param iM: The output reverse affine transformation
The function computes inverse affine transformation represented by
:math:`2 \times 3`
matrix
``M``
:
.. math:: .. math::
\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix} \begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}
The result will also be a
:math:`2 \times 3`
matrix of the same type as
``M``
.
The result will also be a
:math:`2 \times 3` matrix of the same type as ``M`` .
.. index:: remap .. index:: remap
cv::remap cv::remap
--------- ---------
`id=0.948217317394 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/remap>`__
.. cfunction:: void remap( const Mat\& src, Mat\& dst, const Mat\& map1, const Mat\& map2, int interpolation, int borderMode=BORDER_CONSTANT, const Scalar\& borderValue=Scalar()) .. cfunction:: void remap( const Mat\& src, Mat\& dst, const Mat\& map1, const Mat\& map2, int interpolation, int borderMode=BORDER_CONSTANT, const Scalar\& borderValue=Scalar())
Applies a generic geometrical transformation to an image. Applies a generic geometrical transformation to an image.
:param src: Source image
:param dst: Destination image. It will have the same size as ``map1`` and the same type as ``src``
:param map1: The first map of either ``(x,y)`` points or just ``x`` values having type ``CV_16SC2`` , ``CV_32FC1`` or ``CV_32FC2`` . See :func:`convertMaps` for converting floating point representation to fixed-point for speed.
:param map2: The second map of ``y`` values having type ``CV_16UC1`` , ``CV_32FC1`` or none (empty map if map1 is ``(x,y)`` points), respectively
:param interpolation: The interpolation method, see :func:`resize` . The method ``INTER_AREA`` is not supported by this function
:param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
:param src: Source image
:param dst: Destination image. It will have the same size as ``map1`` and the same type as ``src``
:param map1: The first map of either ``(x,y)`` points or just ``x`` values having type ``CV_16SC2`` , ``CV_32FC1`` or ``CV_32FC2`` . See :func:`convertMaps` for converting floating point representation to fixed-point for speed.
:param map2: The second map of ``y`` values having type ``CV_16UC1`` , ``CV_32FC1`` or none (empty map if map1 is ``(x,y)`` points), respectively
:param interpolation: The interpolation method, see :func:`resize` . The method ``INTER_AREA`` is not supported by this function
:param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
:param borderValue: A value used in the case of a constant border. By default it is 0
The function
``remap``
transforms the source image using the specified map:
:param borderValue: A value used in the case of a constant border. By default it is 0
The function ``remap`` transforms the source image using the specified map:
.. math:: .. math::
\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y)) \texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))
Where values of pixels with non-integer coordinates are computed using one of the available interpolation methods.
Where values of pixels with non-integer coordinates are computed using one of the available interpolation methods. :math:`map_x` and
:math:`map_x` :math:`map_y` can be encoded as separate floating-point maps in
and :math:`map_1` and
:math:`map_y` :math:`map_2` respectively, or interleaved floating-point maps of
can be encoded as separate floating-point maps in :math:`(x,y)` in
:math:`map_1` :math:`map_1` , or
and fixed-point maps made by using
:math:`map_2` :func:`convertMaps` . The reason you might want to convert from floating to fixed-point
respectively, or interleaved floating-point maps of representations of a map is that they can yield much faster (~2x) remapping operations. In the converted case,
:math:`(x,y)` :math:`map_1` contains pairs ``(cvFloor(x), cvFloor(y))`` and
in :math:`map_2` contains indices in a table of interpolation coefficients.
:math:`map_1`
, or
fixed-point maps made by using
:func:`convertMaps`
. The reason you might want to convert from floating to fixed-point
representations of a map is that they can yield much faster (~2x) remapping operations. In the converted case,
:math:`map_1`
contains pairs
``(cvFloor(x), cvFloor(y))``
and
:math:`map_2`
contains indices in a table of interpolation coefficients.
This function can not operate in-place. This function can not operate in-place.
.. index:: resize .. index:: resize
cv::resize cv::resize
---------- ----------
`id=0.927768028114 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/resize>`__
.. cfunction:: void resize( const Mat\& src, Mat\& dst, Size dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR ) .. cfunction:: void resize( const Mat\& src, Mat\& dst, Size dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR )
Resizes an image Resizes an image
:param src: Source image
:param dst: Destination image. It will have size ``dsize`` (when it is non-zero) or the size computed from ``src.size()`` and ``fx`` and ``fy`` . The type of ``dst`` will be the same as of ``src`` .
:param dsize: The destination image size. If it is zero, then it is computed as:
:param src: Source image
:param dst: Destination image. It will have size ``dsize`` (when it is non-zero) or the size computed from ``src.size()``
and ``fx`` and ``fy`` . The type of ``dst`` will be the same as of ``src`` .
:param dsize: The destination image size. If it is zero, then it is computed as:
.. math:: .. math::
\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))} \texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
. .
Either ``dsize`` or both ``fx`` or ``fy`` must be non-zero. Either ``dsize`` or both ``fx`` or ``fy`` must be non-zero.
:param fx: The scale factor along the horizontal axis. When 0, it is computed as
:param fx: The scale factor along the horizontal axis. When 0, it is computed as
.. math:: .. math::
\texttt{(double)dsize.width/src.cols} \texttt{(double)dsize.width/src.cols}
:param fy: The scale factor along the vertical axis. When 0, it is computed as
:param fy: The scale factor along the vertical axis. When 0, it is computed as
.. math:: .. math::
\texttt{(double)dsize.height/src.rows}
:param interpolation: The interpolation method:
* **INTER_NEAREST** nearest-neighbor interpolation
* **INTER_LINEAR** bilinear interpolation (used by default)
* **INTER_AREA** resampling using pixel area relation. It may be the preferred method for image decimation, as it gives moire-free results. But when the image is zoomed, it is similar to the ``INTER_NEAREST`` method
* **INTER_CUBIC** bicubic interpolation over 4x4 pixel neighborhood
* **INTER_LANCZOS4** Lanczos interpolation over 8x8 pixel neighborhood
The function
``resize``
resizes an image
``src``
down to or up to the specified size.
Note that the initial
``dst``
type or size are not taken into account. Instead the size and type are derived from the
``src``
,
``dsize``
,
``fx``
and
``fy``
. If you want to resize
``src``
so that it fits the pre-created
``dst``
, you may call the function as:
\texttt{(double)dsize.height/src.rows}
:param interpolation: The interpolation method:
* **INTER_NEAREST** nearest-neighbor interpolation
:: * **INTER_LINEAR** bilinear interpolation (used by default)
* **INTER_AREA** resampling using pixel area relation. It may be the preferred method for image decimation, as it gives moire-free results. But when the image is zoomed, it is similar to the ``INTER_NEAREST`` method
* **INTER_CUBIC** bicubic interpolation over 4x4 pixel neighborhood
* **INTER_LANCZOS4** Lanczos interpolation over 8x8 pixel neighborhood
The function ``resize`` resizes an image ``src`` down to or up to the specified size.
Note that the initial ``dst`` type or size are not taken into account. Instead the size and type are derived from the ``src``,``dsize``,``fx`` and ``fy`` . If you want to resize ``src`` so that it fits the pre-created ``dst`` , you may call the function as: ::
// explicitly specify dsize=dst.size(); fx and fy will be computed from that. // explicitly specify dsize=dst.size(); fx and fy will be computed from that.
resize(src, dst, dst.size(), 0, 0, interpolation); resize(src, dst, dst.size(), 0, 0, interpolation);
.. ..
If you want to decimate the image by factor of 2 in each direction, you can call the function this way: If you want to decimate the image by factor of 2 in each direction, you can call the function this way: ::
::
// specify fx and fy and let the function to compute the destination image size. // specify fx and fy and let the function to compute the destination image size.
resize(src, dst, Size(), 0.5, 0.5, interpolation); resize(src, dst, Size(), 0.5, 0.5, interpolation);
.. ..
See also: See also:
:func:`warpAffine` :func:`warpAffine`,:func:`warpPerspective`,:func:`remap` .
,
:func:`warpPerspective`
,
:func:`remap`
.
.. index:: warpAffine .. index:: warpAffine
cv::warpAffine cv::warpAffine
-------------- --------------
`id=0.796627178227 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/warpAffine>`__
.. cfunction:: void warpAffine( const Mat\& src, Mat\& dst, const Mat\& M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar\& borderValue=Scalar()) .. cfunction:: void warpAffine( const Mat\& src, Mat\& dst, const Mat\& M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar\& borderValue=Scalar())
Applies an affine transformation to an image. Applies an affine transformation to an image.
:param src: Source image
:param dst: Destination image; will have size ``dsize`` and the same type as ``src``
:param M: :math:`2\times 3` transformation matrix
:param dsize: Size of the destination image
:param flags: A combination of interpolation methods, see :func:`resize` , and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` )
:param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
:param src: Source image
:param dst: Destination image; will have size ``dsize`` and the same type as ``src``
:param M: :math:`2\times 3` transformation matrix
:param dsize: Size of the destination image
:param flags: A combination of interpolation methods, see :func:`resize` , and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` )
:param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
:param borderValue: A value used in case of a constant border. By default it is 0
The function
``warpAffine``
transforms the source image using the specified matrix:
:param borderValue: A value used in case of a constant border. By default it is 0
The function ``warpAffine`` transforms the source image using the specified matrix:
.. math:: .. math::
\texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23}) \texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23})
when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
when the flag :func:`invertAffineTransform` and then put in the formula above instead of ``M`` .
``WARP_INVERSE_MAP``
is set. Otherwise, the transformation is first inverted with
:func:`invertAffineTransform`
and then put in the formula above instead of
``M``
.
The function can not operate in-place. The function can not operate in-place.
See also: See also:
:func:`warpPerspective` :func:`warpPerspective`,:func:`resize`,:func:`remap`,:func:`getRectSubPix`,:func:`transform`
,
:func:`resize`
,
:func:`remap`
,
:func:`getRectSubPix`
,
:func:`transform`
.. index:: warpPerspective .. index:: warpPerspective
cv::warpPerspective cv::warpPerspective
------------------- -------------------
`id=0.733510667556 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/warpPerspective>`__
.. cfunction:: void warpPerspective( const Mat\& src, Mat\& dst, const Mat\& M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar\& borderValue=Scalar()) .. cfunction:: void warpPerspective( const Mat\& src, Mat\& dst, const Mat\& M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar\& borderValue=Scalar())
Applies a perspective transformation to an image. Applies a perspective transformation to an image.
:param src: Source image
:param dst: Destination image; will have size ``dsize`` and the same type as ``src``
:param M: :math:`3\times 3` transformation matrix
:param dsize: Size of the destination image
:param flags: A combination of interpolation methods, see :func:`resize` , and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` )
:param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
:param src: Source image
:param dst: Destination image; will have size ``dsize`` and the same type as ``src``
:param M: :math:`3\times 3` transformation matrix
:param dsize: Size of the destination image
:param flags: A combination of interpolation methods, see :func:`resize` , and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` )
:param borderMode: The pixel extrapolation method, see :func:`borderInterpolate` . When the \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function
:param borderValue: A value used in case of a constant border. By default it is 0
The function
``warpPerspective``
transforms the source image using the specified matrix:
:param borderValue: A value used in case of a constant border. By default it is 0
The function ``warpPerspective`` transforms the source image using the specified matrix:
.. math:: .. math::
\texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} , \texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} ,
\frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right ) \frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )
when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
when the flag :func:`invert` and then put in the formula above instead of ``M`` .
``WARP_INVERSE_MAP``
is set. Otherwise, the transformation is first inverted with
:func:`invert`
and then put in the formula above instead of
``M``
.
The function can not operate in-place. The function can not operate in-place.
See also: See also:
:func:`warpAffine` :func:`warpAffine`,:func:`resize`,:func:`remap`,:func:`getRectSubPix`,:func:`perspectiveTransform`
,
:func:`resize`
,
:func:`remap`
,
:func:`getRectSubPix`
,
:func:`perspectiveTransform`

330
modules/imgproc/doc/histograms.rst
View File

@ -3,90 +3,54 @@ Histograms
.. highlight:: cpp .. highlight:: cpp
.. index:: calcHist .. index:: calcHist
cv::calcHist cv::calcHist
------------ ------------
`id=0.023612377096 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/calcHist>`__
.. cfunction:: void calcHist( const Mat* arrays, int narrays, const int* channels, const Mat\& mask, MatND\& hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false ) .. cfunction:: void calcHist( const Mat* arrays, int narrays, const int* channels, const Mat\& mask, MatND\& hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false )
.. cfunction:: void calcHist( const Mat* arrays, int narrays, const int* channels, const Mat\& mask, SparseMat\& hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false ) .. cfunction:: void calcHist( const Mat* arrays, int narrays, const int* channels, const Mat\& mask, SparseMat\& hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false )
Calculates histogram of a set of arrays Calculates histogram of a set of arrays
:param arrays: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels
:param narrays: The number of source arrays
:param channels: The list of ``dims`` channels that are used to compute the histogram. The first array channels are numerated from 0 to ``arrays[0].channels()-1`` , the second array channels are counted from ``arrays[0].channels()`` to ``arrays[0].channels() + arrays[1].channels()-1`` etc.
:param mask: The optional mask. If the matrix is not empty, it must be 8-bit array of the same size as ``arrays[i]`` . The non-zero mask elements mark the array elements that are counted in the histogram
:param hist: The output histogram, a dense or sparse ``dims`` -dimensional array
:param arrays: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels
:param dims: The histogram dimensionality; must be positive and not greater than ``CV_MAX_DIMS`` (=32 in the current OpenCV version)
:param narrays: The number of source arrays :param histSize: The array of histogram sizes in each dimension
:param ranges: The array of ``dims`` arrays of the histogram bin boundaries in each dimension. When the histogram is uniform ( ``uniform`` =true), then for each dimension ``i`` it's enough to specify the lower (inclusive) boundary :math:`L_0` of the 0-th histogram bin and the upper (exclusive) boundary :math:`U_{\texttt{histSize}[i]-1}` for the last histogram bin ``histSize[i]-1`` . That is, in the case of uniform histogram each of ``ranges[i]`` is an array of 2 elements. When the histogram is not uniform ( ``uniform=false`` ), then each of ``ranges[i]`` contains ``histSize[i]+1`` elements: :math:`L_0, U_0=L_1, U_1=L_2, ..., U_{\texttt{histSize[i]}-2}=L_{\texttt{histSize[i]}-1}, U_{\texttt{histSize[i]}-1}` . The array elements, which are not between :math:`L_0` and :math:`U_{\texttt{histSize[i]}-1}` , are not counted in the histogram
:param channels: The list of ``dims`` channels that are used to compute the histogram. The first array channels are numerated from 0 to ``arrays[0].channels()-1`` , the second array channels are counted from ``arrays[0].channels()`` to ``arrays[0].channels() + arrays[1].channels()-1`` etc.
:param uniform: Indicates whether the histogram is uniform or not, see above
:param mask: The optional mask. If the matrix is not empty, it must be 8-bit array of the same size as ``arrays[i]`` . The non-zero mask elements mark the array elements that are counted in the histogram :param accumulate: Accumulation flag. If it is set, the histogram is not cleared in the beginning (when it is allocated). This feature allows user to compute a single histogram from several sets of arrays, or to update the histogram in time
The functions ``calcHist`` calculate the histogram of one or more
:param hist: The output histogram, a dense or sparse ``dims`` -dimensional array
:param dims: The histogram dimensionality; must be positive and not greater than ``CV_MAX_DIMS`` (=32 in the current OpenCV version)
:param histSize: The array of histogram sizes in each dimension
:param ranges: The array of ``dims`` arrays of the histogram bin boundaries in each dimension. When the histogram is uniform ( ``uniform`` =true), then for each dimension ``i`` it's enough to specify the lower (inclusive) boundary :math:`L_0` of the 0-th histogram bin and the upper (exclusive) boundary :math:`U_{\texttt{histSize}[i]-1}` for the last histogram bin ``histSize[i]-1`` . That is, in the case of uniform histogram each of ``ranges[i]`` is an array of 2 elements. When the histogram is not uniform ( ``uniform=false`` ), then each of ``ranges[i]`` contains ``histSize[i]+1`` elements: :math:`L_0, U_0=L_1, U_1=L_2, ..., U_{\texttt{histSize[i]}-2}=L_{\texttt{histSize[i]}-1}, U_{\texttt{histSize[i]}-1}` . The array elements, which are not between :math:`L_0` and :math:`U_{\texttt{histSize[i]}-1}` , are not counted in the histogram
:param uniform: Indicates whether the histogram is uniform or not, see above
:param accumulate: Accumulation flag. If it is set, the histogram is not cleared in the beginning (when it is allocated). This feature allows user to compute a single histogram from several sets of arrays, or to update the histogram in time
The functions
``calcHist``
calculate the histogram of one or more
arrays. The elements of a tuple that is used to increment arrays. The elements of a tuple that is used to increment
a histogram bin are taken at the same location from the corresponding a histogram bin are taken at the same location from the corresponding
input arrays. The sample below shows how to compute 2D Hue-Saturation histogram for a color imag input arrays. The sample below shows how to compute 2D Hue-Saturation histogram for a color imag ::
::
#include <cv.h> #include <cv.h>
#include <highgui.h> #include <highgui.h>
using namespace cv; using namespace cv;
int main( int argc, char** argv ) int main( int argc, char** argv )
{ {
Mat src, hsv; Mat src, hsv;
if( argc != 2 || !(src=imread(argv[1], 1)).data ) if( argc != 2 || !(src=imread(argv[1], 1)).data )
return -1; return -1;
cvtColor(src, hsv, CV_BGR2HSV); cvtColor(src, hsv, CV_BGR2HSV);
// let's quantize the hue to 30 levels // let's quantize the hue to 30 levels
// and the saturation to 32 levels // and the saturation to 32 levels
int hbins = 30, sbins = 32; int hbins = 30, sbins = 32;
@ -100,17 +64,17 @@ input arrays. The sample below shows how to compute 2D Hue-Saturation histogram
MatND hist; MatND hist;
// we compute the histogram from the 0-th and 1-st channels // we compute the histogram from the 0-th and 1-st channels
int channels[] = {0, 1}; int channels[] = {0, 1};
calcHist( &hsv, 1, channels, Mat(), // do not use mask calcHist( &hsv, 1, channels, Mat(), // do not use mask
hist, 2, histSize, ranges, hist, 2, histSize, ranges,
true, // the histogram is uniform true, // the histogram is uniform
false ); false );
double maxVal=0; double maxVal=0;
minMaxLoc(hist, 0, &maxVal, 0, 0); minMaxLoc(hist, 0, &maxVal, 0, 0);
int scale = 10; int scale = 10;
Mat histImg = Mat::zeros(sbins*scale, hbins*10, CV_8UC3); Mat histImg = Mat::zeros(sbins*scale, hbins*10, CV_8UC3);
for( int h = 0; h < hbins; h++ ) for( int h = 0; h < hbins; h++ )
for( int s = 0; s < sbins; s++ ) for( int s = 0; s < sbins; s++ )
{ {
@ -121,284 +85,150 @@ input arrays. The sample below shows how to compute 2D Hue-Saturation histogram
Scalar::all(intensity), Scalar::all(intensity),
CV_FILLED ); CV_FILLED );
} }
namedWindow( "Source", 1 ); namedWindow( "Source", 1 );
imshow( "Source", src ); imshow( "Source", src );
namedWindow( "H-S Histogram", 1 ); namedWindow( "H-S Histogram", 1 );
imshow( "H-S Histogram", histImg ); imshow( "H-S Histogram", histImg );
waitKey(); waitKey();
} }
.. ..
.. index:: calcBackProject .. index:: calcBackProject
cv::calcBackProject cv::calcBackProject
------------------- -------------------
`id=0.307675677402 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/calcBackProject>`__
.. cfunction:: void calcBackProject( const Mat* arrays, int narrays, const int* channels, const MatND\& hist, Mat\& backProject, const float** ranges, double scale=1, bool uniform=true ) .. cfunction:: void calcBackProject( const Mat* arrays, int narrays, const int* channels, const MatND\& hist, Mat\& backProject, const float** ranges, double scale=1, bool uniform=true )
.. cfunction:: void calcBackProject( const Mat* arrays, int narrays, const int* channels, const SparseMat\& hist, Mat\& backProject, const float** ranges, double scale=1, bool uniform=true ) .. cfunction:: void calcBackProject( const Mat* arrays, int narrays, const int* channels, const SparseMat\& hist, Mat\& backProject, const float** ranges, double scale=1, bool uniform=true )
Calculates the back projection of a histogram. Calculates the back projection of a histogram.
:param arrays: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels
:param narrays: The number of source arrays
:param channels: The list of channels that are used to compute the back projection. The number of channels must match the histogram dimensionality. The first array channels are numerated from 0 to ``arrays[0].channels()-1`` , the second array channels are counted from ``arrays[0].channels()`` to ``arrays[0].channels() + arrays[1].channels()-1`` etc.
:param hist: The input histogram, a dense or sparse
:param backProject: Destination back projection aray; will be a single-channel array of the same size and the same depth as ``arrays[0]``
:param arrays: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels :param ranges: The array of arrays of the histogram bin boundaries in each dimension. See :func:`calcHist`
:param scale: The optional scale factor for the output back projection
:param narrays: The number of source arrays
:param channels: The list of channels that are used to compute the back projection. The number of channels must match the histogram dimensionality. The first array channels are numerated from 0 to ``arrays[0].channels()-1`` , the second array channels are counted from ``arrays[0].channels()`` to ``arrays[0].channels() + arrays[1].channels()-1`` etc.
:param hist: The input histogram, a dense or sparse
:param backProject: Destination back projection aray; will be a single-channel array of the same size and the same depth as ``arrays[0]``
:param ranges: The array of arrays of the histogram bin boundaries in each dimension. See :func:`calcHist`
:param scale: The optional scale factor for the output back projection
:param uniform: Indicates whether the histogram is uniform or not, see above
The functions
``calcBackProject``
calculate the back project of the histogram. That is, similarly to
``calcHist``
, at each location
``(x, y)``
the function collects the values from the selected channels in the input images and finds the corresponding histogram bin. But instead of incrementing it, the function reads the bin value, scales it by
``scale``
and stores in
``backProject(x,y)``
. In terms of statistics, the function computes probability of each element value in respect with the empirical probability distribution represented by the histogram. Here is how, for example, you can find and track a bright-colored object in a scene:
:param uniform: Indicates whether the histogram is uniform or not, see above
The functions ``calcBackProject`` calculate the back project of the histogram. That is, similarly to ``calcHist`` , at each location ``(x, y)`` the function collects the values from the selected channels in the input images and finds the corresponding histogram bin. But instead of incrementing it, the function reads the bin value, scales it by ``scale`` and stores in ``backProject(x,y)`` . In terms of statistics, the function computes probability of each element value in respect with the empirical probability distribution represented by the histogram. Here is how, for example, you can find and track a bright-colored object in a scene:
#. #.
Before the tracking, show the object to the camera such that covers almost the whole frame. Calculate a hue histogram. The histogram will likely have a strong maximums, corresponding to the dominant colors in the object. Before the tracking, show the object to the camera such that covers almost the whole frame. Calculate a hue histogram. The histogram will likely have a strong maximums, corresponding to the dominant colors in the object.
#. #.
During the tracking, calculate back projection of a hue plane of each input video frame using that pre-computed histogram. Threshold the back projection to suppress weak colors. It may also have sense to suppress pixels with non sufficient color saturation and too dark or too bright pixels. During the tracking, calculate back projection of a hue plane of each input video frame using that pre-computed histogram. Threshold the back projection to suppress weak colors. It may also have sense to suppress pixels with non sufficient color saturation and too dark or too bright pixels.
#. #.
Find connected components in the resulting picture and choose, for example, the largest component. Find connected components in the resulting picture and choose, for example, the largest component.
That is the approximate algorithm of
:func:`CAMShift`
color object tracker.
See also: That is the approximate algorithm of
:func:`CAMShift` color object tracker.
See also:
:func:`calcHist` :func:`calcHist`
.. index:: compareHist .. index:: compareHist
cv::compareHist cv::compareHist
--------------- ---------------
`id=0.679842058679 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/compareHist>`__
.. cfunction:: double compareHist( const MatND\& H1, const MatND\& H2, int method ) .. cfunction:: double compareHist( const MatND\& H1, const MatND\& H2, int method )
.. cfunction:: double compareHist( const SparseMat\& H1, const SparseMat\& H2, int method ) .. cfunction:: double compareHist( const SparseMat\& H1, const SparseMat\& H2, int method )
Compares two histograms Compares two histograms
:param H1: The first compared histogram
:param H2: The second compared histogram of the same size as ``H1``
:param method: The comparison method, one of the following:
* **CV_COMP_CORREL** Correlation
* **CV_COMP_CHISQR** Chi-Square
* **CV_COMP_INTERSECT** Intersection
:param H1: The first compared histogram
:param H2: The second compared histogram of the same size as ``H1``
:param method: The comparison method, one of the following:
* **CV_COMP_CORREL** Correlation
* **CV_COMP_CHISQR** Chi-Square
* **CV_COMP_INTERSECT** Intersection
* **CV_COMP_BHATTACHARYYA** Bhattacharyya distance
The functions
``compareHist``
compare two dense or two sparse histograms using the specified method:
* **CV_COMP_BHATTACHARYYA** Bhattacharyya distance
The functions ``compareHist`` compare two dense or two sparse histograms using the specified method:
* Correlation (method=CV\_COMP\_CORREL) * Correlation (method=CV\_COMP\_CORREL)
.. math:: .. math::
d(H_1,H_2) = \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}} d(H_1,H_2) = \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}}
where where
.. math:: .. math::
\bar{H_k} = \frac{1}{N} \sum _J H_k(J) \bar{H_k} = \frac{1}{N} \sum _J H_k(J)
and
and :math:`N` is the total number of histogram bins.
:math:`N`
is the total number of histogram bins.
* Chi-Square (method=CV\_COMP\_CHISQR) * Chi-Square (method=CV\_COMP\_CHISQR)
.. math:: .. math::
d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)} d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)}
* Intersection (method=CV\_COMP\_INTERSECT) * Intersection (method=CV\_COMP\_INTERSECT)
.. math:: .. math::
d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I)) d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I))
* Bhattacharyya distance (method=CV\_COMP\_BHATTACHARYYA) * Bhattacharyya distance (method=CV\_COMP\_BHATTACHARYYA)
.. math:: .. math::
d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}
The function returns
:math:`d(H_1, H_2)`
.
While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable for high-dimensional sparse histograms, where, because of aliasing and sampling problems the coordinates of non-zero histogram bins can slightly shift. To compare such histograms or more general sparse configurations of weighted points, consider using the d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}
:func:`calcEMD`
function.
The function returns
:math:`d(H_1, H_2)` .
While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable for high-dimensional sparse histograms, where, because of aliasing and sampling problems the coordinates of non-zero histogram bins can slightly shift. To compare such histograms or more general sparse configurations of weighted points, consider using the
:func:`calcEMD` function.
.. index:: equalizeHist .. index:: equalizeHist
cv::equalizeHist cv::equalizeHist
---------------- ----------------
`id=0.125539341699 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/equalizeHist>`__
.. cfunction:: void equalizeHist( const Mat\& src, Mat\& dst ) .. cfunction:: void equalizeHist( const Mat\& src, Mat\& dst )
Equalizes the histogram of a grayscale image. Equalizes the histogram of a grayscale image.
:param src: The source 8-bit single channel image
:param dst: The destination image; will have the same size and the same type as ``src``
:param src: The source 8-bit single channel image
:param dst: The destination image; will have the same size and the same type as ``src``
The function equalizes the histogram of the input image using the following algorithm: The function equalizes the histogram of the input image using the following algorithm:
#. #.
calculate the histogram calculate the histogram
:math:`H` :math:`H` for ``src`` .
for
``src``
.
#. #.
normalize the histogram so that the sum of histogram bins is 255. normalize the histogram so that the sum of histogram bins is 255.
#. #.
compute the integral of the histogram: compute the integral of the histogram:
.. math:: .. math::
H'_i = \sum _{0 \le j < i} H(j) H'_i = \sum _{0 \le j < i} H(j)
#. #.
transform the image using transform the image using
:math:`H'` :math:`H'` as a look-up table:
as a look-up table:
:math:`\texttt{dst}(x,y) = H'(\texttt{src}(x,y))` :math:`\texttt{dst}(x,y) = H'(\texttt{src}(x,y))`
The algorithm normalizes the brightness and increases the contrast of the image. The algorithm normalizes the brightness and increases the contrast of the image.

8
modules/imgproc/doc/imgproc.rst
View File

@ -1,14 +1,14 @@
**************** *************************
Image Processing imgproc. Image Processing
**************** *************************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
histograms
filtering filtering
geometric_transformations geometric_transformations
miscellaneous_transformations miscellaneous_transformations
histograms
structural_analysis_and_shape_descriptors structural_analysis_and_shape_descriptors
planar_subdivisions planar_subdivisions
motion_analysis_and_object_tracking motion_analysis_and_object_tracking

1438
modules/imgproc/doc/miscellaneous_transformations.rst
View File

File diff suppressed because it is too large Load Diff

184
modules/imgproc/doc/motion_analysis_and_object_tracking.rst
View File

@ -3,225 +3,105 @@ Motion Analysis and Object Tracking
.. highlight:: cpp .. highlight:: cpp
.. index:: accumulate .. index:: accumulate
cv::accumulate cv::accumulate
-------------- --------------
`id=0.681079907994 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/accumulate>`__
.. cfunction:: void accumulate( const Mat\& src, Mat\& dst, const Mat\& mask=Mat() ) .. cfunction:: void accumulate( const Mat\& src, Mat\& dst, const Mat\& mask=Mat() )
Adds image to the accumulator. Adds image to the accumulator.
:param src: The input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param dst: The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point
:param mask: Optional operation mask
The function adds ``src`` , or some of its elements, to ``dst`` :
:param src: The input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param dst: The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point
:param mask: Optional operation mask
The function adds
``src``
, or some of its elements, to
``dst``
:
.. math:: .. math::
\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0 \texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
The function supports multi-channel images; each channel is processed independently. The function supports multi-channel images; each channel is processed independently.
The functions The functions ``accumulate*`` can be used, for example, to collect statistic of background of a scene, viewed by a still camera, for the further foreground-background segmentation.
``accumulate*``
can be used, for example, to collect statistic of background of a scene, viewed by a still camera, for the further foreground-background segmentation.
See also:
:func:`accumulateSquare`
,
:func:`accumulateProduct`
,
:func:`accumulateWeighted`
See also:
:func:`accumulateSquare`,:func:`accumulateProduct`,:func:`accumulateWeighted`
.. index:: accumulateSquare .. index:: accumulateSquare
cv::accumulateSquare cv::accumulateSquare
-------------------- --------------------
`id=0.655955936814 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/accumulateSquare>`__
.. cfunction:: void accumulateSquare( const Mat\& src, Mat\& dst, const Mat\& mask=Mat() ) .. cfunction:: void accumulateSquare( const Mat\& src, Mat\& dst, const Mat\& mask=Mat() )
Adds the square of the source image to the accumulator. Adds the square of the source image to the accumulator.
:param src: The input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param dst: The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point
:param mask: Optional operation mask
The function adds the input image ``src`` or its selected region, raised to power 2, to the accumulator ``dst`` :
:param src: The input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param dst: The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point
:param mask: Optional operation mask
The function adds the input image
``src``
or its selected region, raised to power 2, to the accumulator
``dst``
:
.. math:: .. math::
\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y)^2 \quad \text{if} \quad \texttt{mask} (x,y) \ne 0 \texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y)^2 \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
The function supports multi-channel images; each channel is processed independently. The function supports multi-channel images; each channel is processed independently.
See also: See also:
:func:`accumulateSquare` :func:`accumulateSquare`,:func:`accumulateProduct`,:func:`accumulateWeighted`
,
:func:`accumulateProduct`
,
:func:`accumulateWeighted`
.. index:: accumulateProduct .. index:: accumulateProduct
cv::accumulateProduct cv::accumulateProduct
--------------------- ---------------------
`id=0.866927763669 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/accumulateProduct>`__
.. cfunction:: void accumulateProduct( const Mat\& src1, const Mat\& src2, Mat\& dst, const Mat\& mask=Mat() ) .. cfunction:: void accumulateProduct( const Mat\& src1, const Mat\& src2, Mat\& dst, const Mat\& mask=Mat() )
Adds the per-element product of two input images to the accumulator. Adds the per-element product of two input images to the accumulator.
:param src1: The first input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param src2: The second input image of the same type and the same size as ``src1``
:param dst: Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point
:param mask: Optional operation mask
The function adds the product of 2 images or their selected regions to the accumulator ``dst`` :
:param src1: The first input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param src2: The second input image of the same type and the same size as ``src1``
:param dst: Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point
:param mask: Optional operation mask
The function adds the product of 2 images or their selected regions to the accumulator
``dst``
:
.. math:: .. math::
\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src1} (x,y) \cdot \texttt{src2} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0 \texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src1} (x,y) \cdot \texttt{src2} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
The function supports multi-channel images; each channel is processed independently. The function supports multi-channel images; each channel is processed independently.
See also: See also:
:func:`accumulate` :func:`accumulate`,:func:`accumulateSquare`,:func:`accumulateWeighted`
,
:func:`accumulateSquare`
,
:func:`accumulateWeighted`
.. index:: accumulateWeighted .. index:: accumulateWeighted
cv::accumulateWeighted cv::accumulateWeighted
---------------------- ----------------------
`id=0.956120320296 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/accumulateWeighted>`__
.. cfunction:: void accumulateWeighted( const Mat\& src, Mat\& dst, double alpha, const Mat\& mask=Mat() ) .. cfunction:: void accumulateWeighted( const Mat\& src, Mat\& dst, double alpha, const Mat\& mask=Mat() )
Updates the running average. Updates the running average.
:param src: The input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param dst: The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point
:param alpha: Weight of the input image
:param mask: Optional operation mask
The function calculates the weighted sum of the input image ``src`` and the accumulator ``dst`` so that ``dst`` becomes a running average of frame sequence:
:param src: The input image, 1- or 3-channel, 8-bit or 32-bit floating point
:param dst: The accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point
:param alpha: Weight of the input image
:param mask: Optional operation mask
The function calculates the weighted sum of the input image
``src``
and the accumulator
``dst``
so that
``dst``
becomes a running average of frame sequence:
.. math:: .. math::
\texttt{dst} (x,y) \leftarrow (1- \texttt{alpha} ) \cdot \texttt{dst} (x,y) + \texttt{alpha} \cdot \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0 \texttt{dst} (x,y) \leftarrow (1- \texttt{alpha} ) \cdot \texttt{dst} (x,y) + \texttt{alpha} \cdot \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
that is, ``alpha`` regulates the update speed (how fast the accumulator "forgets" about earlier images).
that is,
``alpha``
regulates the update speed (how fast the accumulator "forgets" about earlier images).
The function supports multi-channel images; each channel is processed independently. The function supports multi-channel images; each channel is processed independently.
See also: See also:
:func:`accumulate` :func:`accumulate`,:func:`accumulateSquare`,:func:`accumulateProduct`
,
:func:`accumulateSquare`
,
:func:`accumulateProduct`

145
modules/imgproc/doc/object_detection.rst
View File

@ -3,144 +3,71 @@ Object Detection
.. highlight:: cpp .. highlight:: cpp
.. index:: matchTemplate .. index:: matchTemplate
cv::matchTemplate cv::matchTemplate
----------------- -----------------
`id=0.821462672178 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/imgproc/matchTemplate>`__
.. cfunction:: void matchTemplate( const Mat\& image, const Mat\& templ, Mat\& result, int method ) .. cfunction:: void matchTemplate( const Mat\& image, const Mat\& templ, Mat\& result, int method )
Compares a template against overlapped image regions. Compares a template against overlapped image regions.
:param image: Image where the search is running; should be 8-bit or 32-bit floating-point
:param templ: Searched template; must be not greater than the source image and have the same data type
:param image: Image where the search is running; should be 8-bit or 32-bit floating-point
:param templ: Searched template; must be not greater than the source image and have the same data type
:param result: A map of comparison results; will be single-channel 32-bit floating-point. :param result: A map of comparison results; will be single-channel 32-bit floating-point.
If ``image`` is :math:`W \times H` and ``templ`` is :math:`w \times h` then ``result`` will be :math:`(W-w+1) \times (H-h+1)` If ``image`` is :math:`W \times H` and ``templ`` is :math:`w \times h` then ``result`` will be :math:`(W-w+1) \times (H-h+1)`
:param method: Specifies the comparison method (see below)
:param method: Specifies the comparison method (see below) The function slides through ``image`` , compares the
overlapped patches of size
:math:`w \times h` against ``templ`` using the specified method and stores the comparison results to ``result`` . Here are the formulas for the available comparison
The function slides through
``image``
, compares the
overlapped patches of size
:math:`w \times h`
against
``templ``
using the specified method and stores the comparison results to
``result``
. Here are the formulas for the available comparison
methods ( methods (
:math:`I` :math:`I` denotes ``image``,:math:`T` ``template``,:math:`R` ``result`` ). The summation is done over template and/or the
denotes image patch:
``image``
,
:math:`T`
``template``
,
:math:`R`
``result``
). The summation is done over template and/or the
image patch:
:math:`x' = 0...w-1, y' = 0...h-1` :math:`x' = 0...w-1, y' = 0...h-1`
* method=CV\_TM\_SQDIFF * method=CV\_TM\_SQDIFF
.. math:: .. math::
R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2 R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2
* method=CV\_TM\_SQDIFF\_NORMED * method=CV\_TM\_SQDIFF\_NORMED
.. math:: .. math::
R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}} R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
* method=CV\_TM\_CCORR * method=CV\_TM\_CCORR
.. math:: .. math::
R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y')) R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))
* method=CV\_TM\_CCORR\_NORMED * method=CV\_TM\_CCORR\_NORMED
.. math:: .. math::
R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I'(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}} R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I'(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
* method=CV\_TM\_CCOEFF * method=CV\_TM\_CCOEFF
.. math:: .. math::
R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I(x+x',y+y')) R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I(x+x',y+y'))
where where
.. math:: .. math::
\begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array} \begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}
* method=CV\_TM\_CCOEFF\_NORMED * method=CV\_TM\_CCOEFF\_NORMED
.. math::
.. math::
R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
After the function finishes the comparison, the best matches can be found as global minimums (when ``CV_TM_SQDIFF`` was used) or maximums (when ``CV_TM_CCORR`` or ``CV_TM_CCOEFF`` was used) using the
:func:`minMaxLoc` function. In the case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels (and separate mean values are used for each channel). That is, the function can take a color template and a color image; the result will still be a single-channel image, which is easier to analyze.
After the function finishes the comparison, the best matches can be found as global minimums (when
``CV_TM_SQDIFF``
was used) or maximums (when
``CV_TM_CCORR``
or
``CV_TM_CCOEFF``
was used) using the
:func:`minMaxLoc`
function. In the case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels (and separate mean values are used for each channel). That is, the function can take a color template and a color image; the result will still be a single-channel image, which is easier to analyze.

1
modules/imgproc/doc/planar_subdivisions.rst
View File

@ -3,4 +3,3 @@ Planar Subdivisions
.. highlight:: cpp .. highlight:: cpp

902
modules/imgproc/doc/structural_analysis_and_shape_descriptors.rst
View File

File diff suppressed because it is too large Load Diff

7
modules/index.rst
View File

@ -10,7 +10,7 @@ Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
core/doc/intro.rst core/doc/intro.rst
core/doc/core.rst core/doc/core.rst
imgproc/doc/imgproc.rst imgproc/doc/imgproc.rst
@ -25,7 +25,4 @@ Contents:
Indices and tables Indices and tables
================== ==================
* :ref:`genindex` * :ref:`genindex` * :ref:`modindex` * :ref:`search`
* :ref:`modindex`
* :ref:`search`

310
modules/ml/doc/boosting.rst
View File

@ -3,130 +3,76 @@ Boosting
.. highlight:: cpp .. highlight:: cpp
A common machine learning task is supervised learning. In supervised learning, the goal is to learn the functional relationship
:math:`F: y = F(x)` between the input
:math:`x` and the output
:math:`y` . Predicting the qualitative output is called classification, while predicting the quantitative output is called regression.
A common machine learning task is supervised learning. In supervised learning, the goal is to learn the functional relationship Boosting is a powerful learning concept, which provide a solution to the supervised classification learning task. It combines the performance of many "weak" classifiers to produce a powerful 'committee'
:math:`F: y = F(x)` :ref:`HTF01` . A weak classifier is only required to be better than chance, and thus can be very simple and computationally inexpensive. Many of them smartly combined, however, results in a strong classifier, which often outperforms most 'monolithic' strong classifiers such as SVMs and Neural Networks.
between the input
:math:`x`
and the output
:math:`y`
. Predicting the qualitative output is called classification, while predicting the quantitative output is called regression.
Boosting is a powerful learning concept, which provide a solution to the supervised classification learning task. It combines the performance of many "weak" classifiers to produce a powerful 'committee'
:ref:`HTF01`
. A weak classifier is only required to be better than chance, and thus can be very simple and computationally inexpensive. Many of them smartly combined, however, results in a strong classifier, which often outperforms most 'monolithic' strong classifiers such as SVMs and Neural Networks.
Decision trees are the most popular weak classifiers used in boosting schemes. Often the simplest decision trees with only a single split node per tree (called stumps) are sufficient. Decision trees are the most popular weak classifiers used in boosting schemes. Often the simplest decision trees with only a single split node per tree (called stumps) are sufficient.
The boosted model is based on The boosted model is based on
:math:`N` :math:`N` training examples
training examples :math:`{(x_i,y_i)}1N` with
:math:`{(x_i,y_i)}1N` :math:`x_i \in{R^K}` and
with :math:`y_i \in{-1, +1}` .
:math:`x_i \in{R^K}` :math:`x_i` is a
and :math:`K` -component vector. Each component encodes a feature relevant for the learning task at hand. The desired two-class output is encoded as -1 and +1.
:math:`y_i \in{-1, +1}`
.
:math:`x_i`
is a
:math:`K`
-component vector. Each component encodes a feature relevant for the learning task at hand. The desired two-class output is encoded as -1 and +1.
Different variants of boosting are known such as Discrete Adaboost, Real AdaBoost, LogitBoost, and Gentle AdaBoost Different variants of boosting are known such as Discrete Adaboost, Real AdaBoost, LogitBoost, and Gentle AdaBoost
:ref:`FHT98` :ref:`FHT98` . All of them are very similar in their overall structure. Therefore, we will look only at the standard two-class Discrete AdaBoost algorithm as shown in the box below. Each sample is initially assigned the same weight (step 2). Next a weak classifier
. All of them are very similar in their overall structure. Therefore, we will look only at the standard two-class Discrete AdaBoost algorithm as shown in the box below. Each sample is initially assigned the same weight (step 2). Next a weak classifier :math:`f_{m(x)}` is trained on the weighted training data (step 3a). Its weighted training error and scaling factor
:math:`f_{m(x)}` :math:`c_m` is computed (step 3b). The weights are increased for training samples, which have been misclassified (step 3c). All weights are then normalized, and the process of finding the next weak classifier continues for another
is trained on the weighted training data (step 3a). Its weighted training error and scaling factor :math:`M` -1 times. The final classifier
:math:`c_m` :math:`F(x)` is the sign of the weighted sum over the individual weak classifiers (step 4).
is computed (step 3b). The weights are increased for training samples, which have been misclassified (step 3c). All weights are then normalized, and the process of finding the next weak classifier continues for another
:math:`M`
-1 times. The final classifier
:math:`F(x)`
is the sign of the weighted sum over the individual weak classifiers (step 4).
* *
Given Given
:math:`N` :math:`N` examples
examples :math:`{(x_i,y_i)}1N` with
:math:`{(x_i,y_i)}1N` :math:`x_i \in{R^K}, y_i \in{-1, +1}` .
with
:math:`x_i \in{R^K}, y_i \in{-1, +1}`
.
* *
Start with weights Start with weights
:math:`w_i = 1/N, i = 1,...,N` :math:`w_i = 1/N, i = 1,...,N` .
.
* *
Repeat for Repeat for
:math:`m` :math:`m` =
= :math:`1,2,...,M` :
:math:`1,2,...,M`
:
* *
Fit the classifier Fit the classifier
:math:`f_m(x) \in{-1,1}` :math:`f_m(x) \in{-1,1}` , using weights
, using weights :math:`w_i` on the training data.
:math:`w_i`
on the training data.
* *
Compute Compute
:math:`err_m = E_w [1_{(y =\neq f_m(x))}], c_m = log((1 - err_m)/err_m)` :math:`err_m = E_w [1_{(y =\neq f_m(x))}], c_m = log((1 - err_m)/err_m)` .
.
* *
Set Set
:math:`w_i \Leftarrow w_i exp[c_m 1_{(y_i \neq f_m(x_i))}], i = 1,2,...,N,` :math:`w_i \Leftarrow w_i exp[c_m 1_{(y_i \neq f_m(x_i))}], i = 1,2,...,N,` and renormalize so that
and renormalize so that :math:`\Sigma i w_i = 1` .
:math:`\Sigma i w_i = 1`
.
* *
Output the classifier sign Output the classifier sign
:math:`[\Sigma m = 1M c_m f_m(x)]` :math:`[\Sigma m = 1M c_m f_m(x)]` .
.
Two-class Discrete AdaBoost Algorithm: Training (steps 1 to 3) and Evaluation (step 4) Two-class Discrete AdaBoost Algorithm: Training (steps 1 to 3) and Evaluation (step 4)
**NOTE:** **NOTE:**
As well as the classical boosting methods, the current implementation supports 2-class classifiers only. For M As well as the classical boosting methods, the current implementation supports 2-class classifiers only. For M
:math:`>` :math:`>` 2 classes there is the
2 classes there is the
**AdaBoost.MH** **AdaBoost.MH**
algorithm, described in algorithm, described in
:ref:`FHT98` :ref:`FHT98` , that reduces the problem to the 2-class problem, yet with a much larger training set.
, that reduces the problem to the 2-class problem, yet with a much larger training set.
In order to reduce computation time for boosted models without substantially losing accuracy, the influence trimming technique may be employed. As the training algorithm proceeds and the number of trees in the ensemble is increased, a larger number of the training samples are classified correctly and with increasing confidence, thereby those samples receive smaller weights on the subsequent iterations. Examples with very low relative weight have small impact on training of the weak classifier. Thus such examples may be excluded during the weak classifier training without having much effect on the induced classifier. This process is controlled with the weight In order to reduce computation time for boosted models without substantially losing accuracy, the influence trimming technique may be employed. As the training algorithm proceeds and the number of trees in the ensemble is increased, a larger number of the training samples are classified correctly and with increasing confidence, thereby those samples receive smaller weights on the subsequent iterations. Examples with very low relative weight have small impact on training of the weak classifier. Thus such examples may be excluded during the weak classifier training without having much effect on the induced classifier. This process is controlled with the weight_trim_rate parameter. Only examples with the summary fraction weight_trim_rate of the total weight mass are used in the weak classifier training. Note that the weights for
_
trim
_
rate parameter. Only examples with the summary fraction weight
_
trim
_
rate of the total weight mass are used in the weak classifier training. Note that the weights for
**all** **all**
training examples are recomputed at each training iteration. Examples deleted at a particular iteration may be used again for learning some of the weak classifiers further training examples are recomputed at each training iteration. Examples deleted at a particular iteration may be used again for learning some of the weak classifiers further
:ref:`FHT98` :ref:`FHT98` .
.
**[HTF01] Hastie, T., Tibshirani, R., Friedman, J. H. The Elements of Statistical Learning: Data Mining, Inference, and Prediction. Springer Series in Statistics. 2001.** **[HTF01] Hastie, T., Tibshirani, R., Friedman, J. H. The Elements of Statistical Learning: Data Mining, Inference, and Prediction. Springer Series in Statistics. 2001.**
**[FHT98] Friedman, J. H., Hastie, T. and Tibshirani, R. Additive Logistic Regression: a Statistical View of Boosting. Technical Report, Dept. of Statistics, Stanford University, 1998.** **[FHT98] Friedman, J. H., Hastie, T. and Tibshirani, R. Additive Logistic Regression: a Statistical View of Boosting. Technical Report, Dept. of Statistics, Stanford University, 1998.**
@ -137,42 +83,25 @@ training examples are recomputed at each training iteration. Examples deleted at
CvBoostParams CvBoostParams
------------- -------------
`id=0.227680975216 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoostParams>`__
.. ctype:: CvBoostParams .. ctype:: CvBoostParams
Boosting training parameters. ::
Boosting training parameters.
::
struct CvBoostParams : public CvDTreeParams struct CvBoostParams : public CvDTreeParams
{ {
int boost_type; int boost_type;
int weak_count; int weak_count;
int split_criteria; int split_criteria;
double weight_trim_rate; double weight_trim_rate;
CvBoostParams(); CvBoostParams();
CvBoostParams( int boost_type, int weak_count, double weight_trim_rate, CvBoostParams( int boost_type, int weak_count, double weight_trim_rate,
int max_depth, bool use_surrogates, const float* priors ); int max_depth, bool use_surrogates, const float* priors );
}; };
.. ..
The structure is derived from The structure is derived from
:ref:`CvDTreeParams` :ref:`CvDTreeParams` , but not all of the decision tree parameters are supported. In particular, cross-validation is not supported.
, but not all of the decision tree parameters are supported. In particular, cross-validation is not supported.
.. index:: CvBoostTree .. index:: CvBoostTree
@ -180,66 +109,38 @@ The structure is derived from
CvBoostTree CvBoostTree
----------- -----------
`id=0.166418635075 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoostTree>`__
.. ctype:: CvBoostTree .. ctype:: CvBoostTree
Weak tree classifier. ::
Weak tree classifier.
::
class CvBoostTree: public CvDTree class CvBoostTree: public CvDTree
{ {
public: public:
CvBoostTree(); CvBoostTree();
virtual ~CvBoostTree(); virtual ~CvBoostTree();
virtual bool train( CvDTreeTrainData* _train_data, virtual bool train( CvDTreeTrainData* _train_data,
const CvMat* subsample_idx, CvBoost* ensemble ); const CvMat* subsample_idx, CvBoost* ensemble );
virtual void scale( double s ); virtual void scale( double s );
virtual void read( CvFileStorage* fs, CvFileNode* node, virtual void read( CvFileStorage* fs, CvFileNode* node,
CvBoost* ensemble, CvDTreeTrainData* _data ); CvBoost* ensemble, CvDTreeTrainData* _data );
virtual void clear(); virtual void clear();
protected: protected:
... ...
CvBoost* ensemble; CvBoost* ensemble;
}; };
.. ..
The weak classifier, a component of the boosted tree classifier The weak classifier, a component of the boosted tree classifier
:ref:`CvBoost` :ref:`CvBoost` , is a derivative of
, is a derivative of :ref:`CvDTree` . Normally, there is no need to use the weak classifiers directly, however they can be accessed as elements of the sequence ``CvBoost::weak`` , retrieved by ``CvBoost::get_weak_predictors`` .
:ref:`CvDTree`
. Normally, there is no need to use the weak classifiers directly, however they can be accessed as elements of the sequence
``CvBoost::weak``
, retrieved by
``CvBoost::get_weak_predictors``
.
Note, that in the case of LogitBoost and Gentle AdaBoost each weak predictor is a regression tree, rather than a classification tree. Even in the case of Discrete AdaBoost and Real AdaBoost the Note, that in the case of LogitBoost and Gentle AdaBoost each weak predictor is a regression tree, rather than a classification tree. Even in the case of Discrete AdaBoost and Real AdaBoost the ``CvBoostTree::predict`` return value ( ``CvDTreeNode::value`` ) is not the output class label; a negative value "votes" for class
``CvBoostTree::predict``
return value (
``CvDTreeNode::value``
) is not the output class label; a negative value "votes" for class
# #
0, a positive - for class 0, a positive - for class
# #
1. And the votes are weighted. The weight of each individual tree may be increased or decreased using the method 1. And the votes are weighted. The weight of each individual tree may be increased or decreased using the method ``CvBoostTree::scale`` .
``CvBoostTree::scale``
.
.. index:: CvBoost .. index:: CvBoost
@ -247,102 +148,75 @@ return value (
CvBoost CvBoost
------- -------
`id=0.0263891264552 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoost>`__
.. ctype:: CvBoost .. ctype:: CvBoost
Boosted tree classifier. ::
Boosted tree classifier.
::
class CvBoost : public CvStatModel class CvBoost : public CvStatModel
{ {
public: public:
// Boosting type // Boosting type
enum { DISCRETE=0, REAL=1, LOGIT=2, GENTLE=3 }; enum { DISCRETE=0, REAL=1, LOGIT=2, GENTLE=3 };
// Splitting criteria // Splitting criteria
enum { DEFAULT=0, GINI=1, MISCLASS=3, SQERR=4 }; enum { DEFAULT=0, GINI=1, MISCLASS=3, SQERR=4 };
CvBoost(); CvBoost();
virtual ~CvBoost(); virtual ~CvBoost();
CvBoost( const CvMat* _train_data, int _tflag, CvBoost( const CvMat* _train_data, int _tflag,
const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _responses, const CvMat* _var_idx=0,
const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0,
const CvMat* _missing_mask=0, const CvMat* _missing_mask=0,
CvBoostParams params=CvBoostParams() ); CvBoostParams params=CvBoostParams() );
virtual bool train( const CvMat* _train_data, int _tflag, virtual bool train( const CvMat* _train_data, int _tflag,
const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _responses, const CvMat* _var_idx=0,
const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0,
const CvMat* _missing_mask=0, const CvMat* _missing_mask=0,
CvBoostParams params=CvBoostParams(), CvBoostParams params=CvBoostParams(),
bool update=false ); bool update=false );
virtual float predict( const CvMat* _sample, const CvMat* _missing=0, virtual float predict( const CvMat* _sample, const CvMat* _missing=0,
CvMat* weak_responses=0, CvSlice slice=CV_WHOLE_SEQ, CvMat* weak_responses=0, CvSlice slice=CV_WHOLE_SEQ,
bool raw_mode=false ) const; bool raw_mode=false ) const;
virtual void prune( CvSlice slice ); virtual void prune( CvSlice slice );
virtual void clear(); virtual void clear();
virtual void write( CvFileStorage* storage, const char* name ); virtual void write( CvFileStorage* storage, const char* name );
virtual void read( CvFileStorage* storage, CvFileNode* node ); virtual void read( CvFileStorage* storage, CvFileNode* node );
CvSeq* get_weak_predictors(); CvSeq* get_weak_predictors();
const CvBoostParams& get_params() const; const CvBoostParams& get_params() const;
... ...
protected: protected:
virtual bool set_params( const CvBoostParams& _params ); virtual bool set_params( const CvBoostParams& _params );
virtual void update_weights( CvBoostTree* tree ); virtual void update_weights( CvBoostTree* tree );
virtual void trim_weights(); virtual void trim_weights();
virtual void write_params( CvFileStorage* fs ); virtual void write_params( CvFileStorage* fs );
virtual void read_params( CvFileStorage* fs, CvFileNode* node ); virtual void read_params( CvFileStorage* fs, CvFileNode* node );
CvDTreeTrainData* data; CvDTreeTrainData* data;
CvBoostParams params; CvBoostParams params;
CvSeq* weak; CvSeq* weak;
... ...
}; };
.. ..
.. index:: CvBoost::train .. index:: CvBoost::train
.. _CvBoost::train: .. _CvBoost::train:
CvBoost::train CvBoost::train
-------------- --------------
`id=0.756448003801 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoost%3A%3Atrain>`__
.. cfunction:: bool CvBoost::train( const CvMat* _train_data, int _tflag, const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _missing_mask=0, CvBoostParams params=CvBoostParams(), bool update=false ) .. cfunction:: bool CvBoost::train( const CvMat* _train_data, int _tflag, const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _missing_mask=0, CvBoostParams params=CvBoostParams(), bool update=false )
Trains a boosted tree classifier. Trains a boosted tree classifier.
The train method follows the common template; the last parameter ``update`` specifies whether the classifier needs to be updated (i.e. the new weak tree classifiers added to the existing ensemble), or the classifier needs to be rebuilt from scratch. The responses must be categorical, i.e. boosted trees can not be built for regression, and there should be 2 classes.
The train method follows the common template; the last parameter
``update``
specifies whether the classifier needs to be updated (i.e. the new weak tree classifiers added to the existing ensemble), or the classifier needs to be rebuilt from scratch. The responses must be categorical, i.e. boosted trees can not be built for regression, and there should be 2 classes.
.. index:: CvBoost::predict .. index:: CvBoost::predict
@ -350,23 +224,11 @@ specifies whether the classifier needs to be updated (i.e. the new weak tree cla
CvBoost::predict CvBoost::predict
---------------- ----------------
`id=0.275883150474 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoost%3A%3Apredict>`__
.. cfunction:: float CvBoost::predict( const CvMat* sample, const CvMat* missing=0, CvMat* weak_responses=0, CvSlice slice=CV_WHOLE_SEQ, bool raw_mode=false ) const .. cfunction:: float CvBoost::predict( const CvMat* sample, const CvMat* missing=0, CvMat* weak_responses=0, CvSlice slice=CV_WHOLE_SEQ, bool raw_mode=false ) const
Predicts a response for the input sample. Predicts a response for the input sample.
The method ``CvBoost::predict`` runs the sample through the trees in the ensemble and returns the output class label based on the weighted voting.
The method
``CvBoost::predict``
runs the sample through the trees in the ensemble and returns the output class label based on the weighted voting.
.. index:: CvBoost::prune .. index:: CvBoost::prune
@ -374,41 +236,21 @@ runs the sample through the trees in the ensemble and returns the output class l
CvBoost::prune CvBoost::prune
-------------- --------------
`id=0.22443448309 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoost%3A%3Aprune>`__
.. cfunction:: void CvBoost::prune( CvSlice slice ) .. cfunction:: void CvBoost::prune( CvSlice slice )
Removes the specified weak classifiers. Removes the specified weak classifiers.
The method removes the specified weak classifiers from the sequence. Note that this method should not be confused with the pruning of individual decision trees, which is currently not supported. The method removes the specified weak classifiers from the sequence. Note that this method should not be confused with the pruning of individual decision trees, which is currently not supported.
.. index:: CvBoost::get_weak_predictors .. index:: CvBoost::get_weak_predictors
.. _CvBoost::get_weak_predictors: .. _CvBoost::get_weak_predictors:
CvBoost::get_weak_predictors CvBoost::get_weak_predictors
---------------------------- ----------------------------
`id=0.670781607621 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvBoost%3A%3Aget_weak_predictors>`__
.. cfunction:: CvSeq* CvBoost::get_weak_predictors() .. cfunction:: CvSeq* CvBoost::get_weak_predictors()
Returns the sequence of weak tree classifiers. Returns the sequence of weak tree classifiers.
The method returns the sequence of weak classifiers. Each element of the sequence is a pointer to a ``CvBoostTree`` class (or, probably, to some of its derivatives).
The method returns the sequence of weak classifiers. Each element of the sequence is a pointer to a
``CvBoostTree``
class (or, probably, to some of its derivatives).

348
modules/ml/doc/decision_trees.rst
View File

@ -3,26 +3,19 @@ Decision Trees
.. highlight:: cpp .. highlight:: cpp
The ML classes discussed in this section implement Classification And Regression Tree algorithms, which are described in `[Breiman84] <#paper_Breiman84>`_
The ML classes discussed in this section implement Classification And Regression Tree algorithms, which are described in
`[Breiman84] <#paper_Breiman84>`_
. .
The class The class
:ref:`CvDTree` :ref:`CvDTree` represents a single decision tree that may be used alone, or as a base class in tree ensembles (see
represents a single decision tree that may be used alone, or as a base class in tree ensembles (see :ref:`Boosting` and
:ref:`Boosting` :ref:`Random Trees` ).
and
:ref:`Random Trees`
).
A decision tree is a binary tree (i.e. tree where each non-leaf node has exactly 2 child nodes). It can be used either for classification, when each tree leaf is marked with some class label (multiple leafs may have the same label), or for regression, when each tree leaf is also assigned a constant (so the approximation function is piecewise constant). A decision tree is a binary tree (i.e. tree where each non-leaf node has exactly 2 child nodes). It can be used either for classification, when each tree leaf is marked with some class label (multiple leafs may have the same label), or for regression, when each tree leaf is also assigned a constant (so the approximation function is piecewise constant).
Predicting with Decision Trees Predicting with Decision Trees
------------------------------ ------------------------------
To reach a leaf node, and to obtain a response for the input feature To reach a leaf node, and to obtain a response for the input feature
vector, the prediction procedure starts with the root node. From each vector, the prediction procedure starts with the root node. From each
non-leaf node the procedure goes to the left (i.e. selects the left non-leaf node the procedure goes to the left (i.e. selects the left
@ -38,50 +31,31 @@ tested to see if it belongs to a certain subset of values (also stored
in the node) from a limited set of values the variable could take; if in the node) from a limited set of values the variable could take; if
yes, the procedure goes to the left, else - to the right (for example, yes, the procedure goes to the left, else - to the right (for example,
if the color is green or red, go to the left, else to the right). That if the color is green or red, go to the left, else to the right). That
is, in each node, a pair of entities (variable is, in each node, a pair of entities (variable_index, decision_rule
_
index, decision
_
rule
(threshold/subset)) is used. This pair is called a split (split on (threshold/subset)) is used. This pair is called a split (split on
the variable variable the variable variable_index). Once a leaf node is reached, the value
_
index). Once a leaf node is reached, the value
assigned to this node is used as the output of prediction procedure. assigned to this node is used as the output of prediction procedure.
Sometimes, certain features of the input vector are missed (for example, in the darkness it is difficult to determine the object color), and the prediction procedure may get stuck in the certain node (in the mentioned example if the node is split by color). To avoid such situations, decision trees use so-called surrogate splits. That is, in addition to the best "primary" split, every tree node may also be split on one or more other variables with nearly the same results. Sometimes, certain features of the input vector are missed (for example, in the darkness it is difficult to determine the object color), and the prediction procedure may get stuck in the certain node (in the mentioned example if the node is split by color). To avoid such situations, decision trees use so-called surrogate splits. That is, in addition to the best "primary" split, every tree node may also be split on one or more other variables with nearly the same results.
Training Decision Trees Training Decision Trees
----------------------- -----------------------
The tree is built recursively, starting from the root node. All of the training data (feature vectors and the responses) is used to split the root node. In each node the optimum decision rule (i.e. the best "primary" split) is found based on some criteria (in ML ``gini`` "purity" criteria is used for classification, and sum of squared errors is used for regression). Then, if necessary, the surrogate splits are found that resemble the results of the primary split on the training data; all of the data is divided using the primary and the surrogate splits (just like it is done in the prediction procedure) between the left and the right child node. Then the procedure recursively splits both left and right nodes. At each node the recursive procedure may stop (i.e. stop splitting the node further) in one of the following cases:
The tree is built recursively, starting from the root node. All of the training data (feature vectors and the responses) is used to split the root node. In each node the optimum decision rule (i.e. the best "primary" split) is found based on some criteria (in ML
``gini``
"purity" criteria is used for classification, and sum of squared errors is used for regression). Then, if necessary, the surrogate splits are found that resemble the results of the primary split on the training data; all of the data is divided using the primary and the surrogate splits (just like it is done in the prediction procedure) between the left and the right child node. Then the procedure recursively splits both left and right nodes. At each node the recursive procedure may stop (i.e. stop splitting the node further) in one of the following cases:
* depth of the tree branch being constructed has reached the specified maximum value. * depth of the tree branch being constructed has reached the specified maximum value.
* number of training samples in the node is less than the specified threshold, when it is not statistically representative to split the node further. * number of training samples in the node is less than the specified threshold, when it is not statistically representative to split the node further.
* all the samples in the node belong to the same class (or, in the case of regression, the variation is too small). * all the samples in the node belong to the same class (or, in the case of regression, the variation is too small).
* the best split found does not give any noticeable improvement compared to a random choice. * the best split found does not give any noticeable improvement compared to a random choice.
When the tree is built, it may be pruned using a cross-validation procedure, if necessary. That is, some branches of the tree that may lead to the model overfitting are cut off. Normally this procedure is only applied to standalone decision trees, while tree ensembles usually build small enough trees and use their own protection schemes against overfitting.
When the tree is built, it may be pruned using a cross-validation procedure, if necessary. That is, some branches of the tree that may lead to the model overfitting are cut off. Normally this procedure is only applied to standalone decision trees, while tree ensembles usually build small enough trees and use their own protection schemes against overfitting.
Variable importance Variable importance
------------------- -------------------
Besides the obvious use of decision trees - prediction, the tree can be also used for various data analysis. One of the key properties of the constructed decision tree algorithms is that it is possible to compute importance (relative decisive power) of each variable. For example, in a spam filter that uses a set of words occurred in the message as a feature vector, the variable importance rating can be used to determine the most "spam-indicating" words and thus help to keep the dictionary size reasonable. Besides the obvious use of decision trees - prediction, the tree can be also used for various data analysis. One of the key properties of the constructed decision tree algorithms is that it is possible to compute importance (relative decisive power) of each variable. For example, in a spam filter that uses a set of words occurred in the message as a feature vector, the variable importance rating can be used to determine the most "spam-indicating" words and thus help to keep the dictionary size reasonable.
Importance of each variable is computed over all the splits on this variable in the tree, primary and surrogate ones. Thus, to compute variable importance correctly, the surrogate splits must be enabled in the training parameters, even if there is no missing data. Importance of each variable is computed over all the splits on this variable in the tree, primary and surrogate ones. Thus, to compute variable importance correctly, the surrogate splits must be enabled in the training parameters, even if there is no missing data.
@ -94,22 +68,10 @@ Importance of each variable is computed over all the splits on this variable in
CvDTreeSplit CvDTreeSplit
------------ ------------
`id=0.286654154683 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTreeSplit>`__
.. ctype:: CvDTreeSplit .. ctype:: CvDTreeSplit
Decision tree node split. ::
Decision tree node split.
::
struct CvDTreeSplit struct CvDTreeSplit
{ {
int var_idx; int var_idx;
@ -127,58 +89,37 @@ Decision tree node split.
ord; ord;
}; };
}; };
.. ..
.. index:: CvDTreeNode .. index:: CvDTreeNode
.. _CvDTreeNode: .. _CvDTreeNode:
CvDTreeNode CvDTreeNode
----------- -----------
`id=0.948528874157 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTreeNode>`__
.. ctype:: CvDTreeNode .. ctype:: CvDTreeNode
Decision tree node. ::
Decision tree node.
::
struct CvDTreeNode struct CvDTreeNode
{ {
int class_idx; int class_idx;
int Tn; int Tn;
double value; double value;
CvDTreeNode* parent; CvDTreeNode* parent;
CvDTreeNode* left; CvDTreeNode* left;
CvDTreeNode* right; CvDTreeNode* right;
CvDTreeSplit* split; CvDTreeSplit* split;
int sample_count; int sample_count;
int depth; int depth;
... ...
}; };
.. ..
Other numerous fields of Other numerous fields of ``CvDTreeNode`` are used internally at the training stage.
``CvDTreeNode``
are used internally at the training stage.
.. index:: CvDTreeParams .. index:: CvDTreeParams
@ -186,22 +127,10 @@ are used internally at the training stage.
CvDTreeParams CvDTreeParams
------------- -------------
`id=0.924935526415 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTreeParams>`__
.. ctype:: CvDTreeParams .. ctype:: CvDTreeParams
Decision tree training parameters. ::
Decision tree training parameters.
::
struct CvDTreeParams struct CvDTreeParams
{ {
int max_categories; int max_categories;
@ -213,48 +142,32 @@ Decision tree training parameters.
bool truncate_pruned_tree; bool truncate_pruned_tree;
float regression_accuracy; float regression_accuracy;
const float* priors; const float* priors;
CvDTreeParams() : max_categories(10), max_depth(INT_MAX), min_sample_count(10), CvDTreeParams() : max_categories(10), max_depth(INT_MAX), min_sample_count(10),
cv_folds(10), use_surrogates(true), use_1se_rule(true), cv_folds(10), use_surrogates(true), use_1se_rule(true),
truncate_pruned_tree(true), regression_accuracy(0.01f), priors(0) truncate_pruned_tree(true), regression_accuracy(0.01f), priors(0)
{} {}
CvDTreeParams( int _max_depth, int _min_sample_count, CvDTreeParams( int _max_depth, int _min_sample_count,
float _regression_accuracy, bool _use_surrogates, float _regression_accuracy, bool _use_surrogates,
int _max_categories, int _cv_folds, int _max_categories, int _cv_folds,
bool _use_1se_rule, bool _truncate_pruned_tree, bool _use_1se_rule, bool _truncate_pruned_tree,
const float* _priors ); const float* _priors );
}; };
.. ..
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 standalone classification tree. Any of the parameters can be overridden then, or the structure may be fully initialized using the advanced variant of the constructor. 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 standalone classification tree. Any of the parameters can be overridden then, or the structure may be fully initialized using the advanced variant of the constructor.
.. index:: CvDTreeTrainData .. index:: CvDTreeTrainData
.. _CvDTreeTrainData: .. _CvDTreeTrainData:
CvDTreeTrainData CvDTreeTrainData
---------------- ----------------
`id=0.0482986639469 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTreeTrainData>`__
.. ctype:: CvDTreeTrainData .. ctype:: CvDTreeTrainData
Decision tree training data and shared data for tree ensembles. ::
Decision tree training data and shared data for tree ensembles.
::
struct CvDTreeTrainData struct CvDTreeTrainData
{ {
CvDTreeTrainData(); CvDTreeTrainData();
@ -265,7 +178,7 @@ Decision tree training data and shared data for tree ensembles.
const CvDTreeParams& _params=CvDTreeParams(), const CvDTreeParams& _params=CvDTreeParams(),
bool _shared=false, bool _add_labels=false ); bool _shared=false, bool _add_labels=false );
virtual ~CvDTreeTrainData(); virtual ~CvDTreeTrainData();
virtual void set_data( const CvMat* _train_data, int _tflag, virtual void set_data( const CvMat* _train_data, int _tflag,
const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _responses, const CvMat* _var_idx=0,
const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0,
@ -273,129 +186,102 @@ Decision tree training data and shared data for tree ensembles.
const CvDTreeParams& _params=CvDTreeParams(), const CvDTreeParams& _params=CvDTreeParams(),
bool _shared=false, bool _add_labels=false, bool _shared=false, bool _add_labels=false,
bool _update_data=false ); bool _update_data=false );
virtual void get_vectors( const CvMat* _subsample_idx, virtual void get_vectors( const CvMat* _subsample_idx,
float* values, uchar* missing, float* responses, float* values, uchar* missing, float* responses,
bool get_class_idx=false ); bool get_class_idx=false );
virtual CvDTreeNode* subsample_data( const CvMat* _subsample_idx ); virtual CvDTreeNode* subsample_data( const CvMat* _subsample_idx );
virtual void write_params( CvFileStorage* fs ); virtual void write_params( CvFileStorage* fs );
virtual void read_params( CvFileStorage* fs, CvFileNode* node ); virtual void read_params( CvFileStorage* fs, CvFileNode* node );
// release all the data // release all the data
virtual void clear(); virtual void clear();
int get_num_classes() const; int get_num_classes() const;
int get_var_type(int vi) const; int get_var_type(int vi) const;
int get_work_var_count() const; int get_work_var_count() const;
virtual int* get_class_labels( CvDTreeNode* n ); virtual int* get_class_labels( CvDTreeNode* n );
virtual float* get_ord_responses( CvDTreeNode* n ); virtual float* get_ord_responses( CvDTreeNode* n );
virtual int* get_labels( CvDTreeNode* n ); virtual int* get_labels( CvDTreeNode* n );
virtual int* get_cat_var_data( CvDTreeNode* n, int vi ); virtual int* get_cat_var_data( CvDTreeNode* n, int vi );
virtual CvPair32s32f* get_ord_var_data( CvDTreeNode* n, int vi ); virtual CvPair32s32f* get_ord_var_data( CvDTreeNode* n, int vi );
virtual int get_child_buf_idx( CvDTreeNode* n ); virtual int get_child_buf_idx( CvDTreeNode* n );
//////////////////////////////////// ////////////////////////////////////
virtual bool set_params( const CvDTreeParams& params ); virtual bool set_params( const CvDTreeParams& params );
virtual CvDTreeNode* new_node( CvDTreeNode* parent, int count, virtual CvDTreeNode* new_node( CvDTreeNode* parent, int count,
int storage_idx, int offset ); int storage_idx, int offset );
virtual CvDTreeSplit* new_split_ord( int vi, float cmp_val, virtual CvDTreeSplit* new_split_ord( int vi, float cmp_val,
int split_point, int inversed, float quality ); int split_point, int inversed, float quality );
virtual CvDTreeSplit* new_split_cat( int vi, float quality ); virtual CvDTreeSplit* new_split_cat( int vi, float quality );
virtual void free_node_data( CvDTreeNode* node ); virtual void free_node_data( CvDTreeNode* node );
virtual void free_train_data(); virtual void free_train_data();
virtual void free_node( CvDTreeNode* node ); virtual void free_node( CvDTreeNode* node );
int sample_count, var_all, var_count, max_c_count; int sample_count, var_all, var_count, max_c_count;
int ord_var_count, cat_var_count; int ord_var_count, cat_var_count;
bool have_labels, have_priors; bool have_labels, have_priors;
bool is_classifier; bool is_classifier;
int buf_count, buf_size; int buf_count, buf_size;
bool shared; bool shared;
CvMat* cat_count; CvMat* cat_count;
CvMat* cat_ofs; CvMat* cat_ofs;
CvMat* cat_map; CvMat* cat_map;
CvMat* counts; CvMat* counts;
CvMat* buf; CvMat* buf;
CvMat* direction; CvMat* direction;
CvMat* split_buf; CvMat* split_buf;
CvMat* var_idx; CvMat* var_idx;
CvMat* var_type; // i-th element = CvMat* var_type; // i-th element =
// k<0 - ordered // k<0 - ordered
// k>=0 - categorical, see k-th element of cat_* arrays // k>=0 - categorical, see k-th element of cat_* arrays
CvMat* priors; CvMat* priors;
CvDTreeParams params; CvDTreeParams params;
CvMemStorage* tree_storage; CvMemStorage* tree_storage;
CvMemStorage* temp_storage; CvMemStorage* temp_storage;
CvDTreeNode* data_root; CvDTreeNode* data_root;
CvSet* node_heap; CvSet* node_heap;
CvSet* split_heap; CvSet* split_heap;
CvSet* cv_heap; CvSet* cv_heap;
CvSet* nv_heap; CvSet* nv_heap;
CvRNG rng; CvRNG rng;
}; };
.. ..
This structure is mostly used internally for storing both standalone trees and tree ensembles efficiently. Basically, it contains 3 types of information: This structure is mostly used internally for storing both standalone trees and tree ensembles efficiently. Basically, it contains 3 types of information:
#. The training parameters, an instance of :ref:`CvDTreeParams`. #. The training parameters, an instance of :ref:`CvDTreeParams`.
#. The training data, preprocessed in order to find the best splits more efficiently. For tree ensembles this preprocessed data is reused by all the trees. Additionally, the training data characteristics that are shared by all trees in the ensemble are stored here: variable types, the number of classes, class label compression map etc. #. The training data, preprocessed in order to find the best splits more efficiently. For tree ensembles this preprocessed data is reused by all the trees. Additionally, the training data characteristics that are shared by all trees in the ensemble are stored here: variable types, the number of classes, class label compression map etc.
#. Buffers, memory storages for tree nodes, splits and other elements of the trees constructed. #. Buffers, memory storages for tree nodes, splits and other elements of the trees constructed.
There are 2 ways of using this structure. In simple cases (e.g. a standalone tree, or the ready-to-use "black box" tree ensemble from ML, like
:ref:`Random Trees`
or
:ref:`Boosting`
) there is no need to care or even to know about the structure - just construct the needed statistical model, train it and use it. The
``CvDTreeTrainData``
structure will be constructed and used internally. However, for custom tree algorithms, or another sophisticated cases, the structure may be constructed and used explicitly. The scheme is the following:
There are 2 ways of using this structure. In simple cases (e.g. a standalone tree, or the ready-to-use "black box" tree ensemble from ML, like
:ref:`Random Trees` or
:ref:`Boosting` ) there is no need to care or even to know about the structure - just construct the needed statistical model, train it and use it. The ``CvDTreeTrainData`` structure will be constructed and used internally. However, for custom tree algorithms, or another sophisticated cases, the structure may be constructed and used explicitly. The scheme is the following:
* *
The structure is initialized using the default constructor, followed by The structure is initialized using the default constructor, followed by ``set_data`` (or it is built using the full form of constructor). The parameter ``_shared`` must be set to ``true`` .
``set_data``
(or it is built using the full form of constructor). The parameter
``_shared``
must be set to
``true``
.
* *
One or more trees are trained using this data, see the special form of the method One or more trees are trained using this data, see the special form of the method ``CvDTree::train`` .
``CvDTree::train``
.
* *
Finally, the structure can be released only after all the trees using it are released. Finally, the structure can be released only after all the trees using it are released.
.. index:: CvDTree .. index:: CvDTree
@ -403,59 +289,47 @@ structure will be constructed and used internally. However, for custom tree algo
CvDTree CvDTree
------- -------
`id=0.802824162542 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTree>`__
.. ctype:: CvDTree .. ctype:: CvDTree
Decision tree. ::
Decision tree.
::
class CvDTree : public CvStatModel class CvDTree : public CvStatModel
{ {
public: public:
CvDTree(); CvDTree();
virtual ~CvDTree(); virtual ~CvDTree();
virtual bool train( const CvMat* _train_data, int _tflag, virtual bool train( const CvMat* _train_data, int _tflag,
const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _responses, const CvMat* _var_idx=0,
const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0,
const CvMat* _missing_mask=0, const CvMat* _missing_mask=0,
CvDTreeParams params=CvDTreeParams() ); CvDTreeParams params=CvDTreeParams() );
virtual bool train( CvDTreeTrainData* _train_data, virtual bool train( CvDTreeTrainData* _train_data,
const CvMat* _subsample_idx ); const CvMat* _subsample_idx );
virtual CvDTreeNode* predict( const CvMat* _sample, virtual CvDTreeNode* predict( const CvMat* _sample,
const CvMat* _missing_data_mask=0, const CvMat* _missing_data_mask=0,
bool raw_mode=false ) const; bool raw_mode=false ) const;
virtual const CvMat* get_var_importance(); virtual const CvMat* get_var_importance();
virtual void clear(); virtual void clear();
virtual void read( CvFileStorage* fs, CvFileNode* node ); virtual void read( CvFileStorage* fs, CvFileNode* node );
virtual void write( CvFileStorage* fs, const char* name ); virtual void write( CvFileStorage* fs, const char* name );
// special read & write methods for trees in the tree ensembles // special read & write methods for trees in the tree ensembles
virtual void read( CvFileStorage* fs, CvFileNode* node, virtual void read( CvFileStorage* fs, CvFileNode* node,
CvDTreeTrainData* data ); CvDTreeTrainData* data );
virtual void write( CvFileStorage* fs ); virtual void write( CvFileStorage* fs );
const CvDTreeNode* get_root() const; const CvDTreeNode* get_root() const;
int get_pruned_tree_idx() const; int get_pruned_tree_idx() const;
CvDTreeTrainData* get_data(); CvDTreeTrainData* get_data();
protected: protected:
virtual bool do_train( const CvMat* _subsample_idx ); virtual bool do_train( const CvMat* _subsample_idx );
virtual void try_split_node( CvDTreeNode* n ); virtual void try_split_node( CvDTreeNode* n );
virtual void split_node_data( CvDTreeNode* n ); virtual void split_node_data( CvDTreeNode* n );
virtual CvDTreeSplit* find_best_split( CvDTreeNode* n ); virtual CvDTreeSplit* find_best_split( CvDTreeNode* n );
@ -469,93 +343,52 @@ Decision tree.
virtual void complete_node_dir( CvDTreeNode* node ); virtual void complete_node_dir( CvDTreeNode* node );
virtual void cluster_categories( const int* vectors, int vector_count, virtual void cluster_categories( const int* vectors, int vector_count,
int var_count, int* sums, int k, int* cluster_labels ); int var_count, int* sums, int k, int* cluster_labels );
virtual void calc_node_value( CvDTreeNode* node ); virtual void calc_node_value( CvDTreeNode* node );
virtual void prune_cv(); virtual void prune_cv();
virtual double update_tree_rnc( int T, int fold ); virtual double update_tree_rnc( int T, int fold );
virtual int cut_tree( int T, int fold, double min_alpha ); virtual int cut_tree( int T, int fold, double min_alpha );
virtual void free_prune_data(bool cut_tree); virtual void free_prune_data(bool cut_tree);
virtual void free_tree(); virtual void free_tree();
virtual void write_node( CvFileStorage* fs, CvDTreeNode* node ); virtual void write_node( CvFileStorage* fs, CvDTreeNode* node );
virtual void write_split( CvFileStorage* fs, CvDTreeSplit* split ); virtual void write_split( CvFileStorage* fs, CvDTreeSplit* split );
virtual CvDTreeNode* read_node( CvFileStorage* fs, virtual CvDTreeNode* read_node( CvFileStorage* fs,
CvFileNode* node, CvFileNode* node,
CvDTreeNode* parent ); CvDTreeNode* parent );
virtual CvDTreeSplit* read_split( CvFileStorage* fs, CvFileNode* node ); virtual CvDTreeSplit* read_split( CvFileStorage* fs, CvFileNode* node );
virtual void write_tree_nodes( CvFileStorage* fs ); virtual void write_tree_nodes( CvFileStorage* fs );
virtual void read_tree_nodes( CvFileStorage* fs, CvFileNode* node ); virtual void read_tree_nodes( CvFileStorage* fs, CvFileNode* node );
CvDTreeNode* root; CvDTreeNode* root;
int pruned_tree_idx; int pruned_tree_idx;
CvMat* var_importance; CvMat* var_importance;
CvDTreeTrainData* data; CvDTreeTrainData* data;
}; };
.. ..
.. index:: CvDTree::train .. index:: CvDTree::train
.. _CvDTree::train: .. _CvDTree::train:
CvDTree::train CvDTree::train
-------------- --------------
`id=0.215158058664 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTree%3A%3Atrain>`__
.. cfunction:: bool CvDTree::train( const CvMat* _train_data, int _tflag, const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _missing_mask=0, CvDTreeParams params=CvDTreeParams() ) .. cfunction:: bool CvDTree::train( const CvMat* _train_data, int _tflag, const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _missing_mask=0, CvDTreeParams params=CvDTreeParams() )
.. cfunction:: bool CvDTree::train( CvDTreeTrainData* _train_data, const CvMat* _subsample_idx ) .. cfunction:: bool CvDTree::train( CvDTreeTrainData* _train_data, const CvMat* _subsample_idx )
Trains a decision tree. Trains a decision tree.
There are 2 ``train`` methods in ``CvDTree`` .
The first method follows the generic ``CvStatModel::train`` conventions, it is the most complete form. Both data layouts ( ``_tflag=CV_ROW_SAMPLE`` and ``_tflag=CV_COL_SAMPLE`` ) are supported, as well as sample and variable subsets, missing measurements, arbitrary combinations of input and output variable types etc. The last parameter contains all of the necessary training parameters, see the
:ref:`CvDTreeParams` description.
There are 2 The second method ``train`` is mostly used for building tree ensembles. It takes the pre-constructed
``train`` :ref:`CvDTreeTrainData` instance and the optional subset of training set. The indices in ``_subsample_idx`` are counted relatively to the ``_sample_idx`` , passed to ``CvDTreeTrainData`` constructor. For example, if ``_sample_idx=[1, 5, 7, 100]`` , then ``_subsample_idx=[0,3]`` means that the samples ``[1, 100]`` of the original training set are used.
methods in
``CvDTree``
.
The first method follows the generic
``CvStatModel::train``
conventions, it is the most complete form. Both data layouts (
``_tflag=CV_ROW_SAMPLE``
and
``_tflag=CV_COL_SAMPLE``
) are supported, as well as sample and variable subsets, missing measurements, arbitrary combinations of input and output variable types etc. The last parameter contains all of the necessary training parameters, see the
:ref:`CvDTreeParams`
description.
The second method
``train``
is mostly used for building tree ensembles. It takes the pre-constructed
:ref:`CvDTreeTrainData`
instance and the optional subset of training set. The indices in
``_subsample_idx``
are counted relatively to the
``_sample_idx``
, passed to
``CvDTreeTrainData``
constructor. For example, if
``_sample_idx=[1, 5, 7, 100]``
, then
``_subsample_idx=[0,3]``
means that the samples
``[1, 100]``
of the original training set are used.
.. index:: CvDTree::predict .. index:: CvDTree::predict
@ -563,44 +396,23 @@ of the original training set are used.
CvDTree::predict CvDTree::predict
---------------- ----------------
`id=0.366805937359 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvDTree%3A%3Apredict>`__
.. cfunction:: CvDTreeNode* CvDTree::predict( const CvMat* _sample, const CvMat* _missing_data_mask=0, bool raw_mode=false ) const .. cfunction:: CvDTreeNode* CvDTree::predict( const CvMat* _sample, const CvMat* _missing_data_mask=0, bool raw_mode=false ) const
Returns the leaf node of the decision tree corresponding to the input vector. Returns the leaf node of the decision tree corresponding to the input vector.
The method takes the feature vector and the optional missing measurement mask on input, traverses the decision tree and returns the reached leaf node on output. The prediction result, either the class label or the estimated function value, may be retrieved as the ``value`` field of the
:ref:`CvDTreeNode` structure, for example: dtree-
:math:`>` predict(sample,mask)-
:math:`>` value.
The last parameter is normally set to ``false`` , implying a regular
The method takes the feature vector and the optional missing measurement mask on input, traverses the decision tree and returns the reached leaf node on output. The prediction result, either the class label or the estimated function value, may be retrieved as the input. If it is ``true`` , the method assumes that all the values of
``value`` the discrete input variables have been already normalized to
field of the :math:`0` to
:ref:`CvDTreeNode` :math:`num\_of\_categories_i-1` ranges. (as the decision tree uses such
structure, for example: dtree-
:math:`>`
predict(sample,mask)-
:math:`>`
value.
The last parameter is normally set to
``false``
, implying a regular
input. If it is
``true``
, the method assumes that all the values of
the discrete input variables have been already normalized to
:math:`0`
to
:math:`num\_of\_categories_i-1`
ranges. (as the decision tree uses such
normalized representation internally). It is useful for faster prediction normalized representation internally). It is useful for faster prediction
with tree ensembles. For ordered input variables the flag is not used. with tree ensembles. For ordered input variables the flag is not used.
Example: Building A Tree for Classifying Mushrooms. See the Example: Building A Tree for Classifying Mushrooms. See the ``mushroom.cpp`` sample that demonstrates how to build and use the
``mushroom.cpp``
sample that demonstrates how to build and use the
decision tree. decision tree.

275
modules/ml/doc/expectation_maximization.rst
View File

@ -3,124 +3,75 @@ Expectation-Maximization
.. highlight:: cpp .. highlight:: cpp
The EM (Expectation-Maximization) algorithm estimates the parameters of the multivariate probability density function in the form of a Gaussian mixture distribution with a specified number of mixtures. The EM (Expectation-Maximization) algorithm estimates the parameters of the multivariate probability density function in the form of a Gaussian mixture distribution with a specified number of mixtures.
Consider the set of the feature vectors Consider the set of the feature vectors
:math:`x_1, x_2,...,x_{N}` :math:`x_1, x_2,...,x_{N}` : N vectors from a d-dimensional Euclidean space drawn from a Gaussian mixture:
: N vectors from a d-dimensional Euclidean space drawn from a Gaussian mixture:
.. math:: .. math::
p(x;a_k,S_k, \pi _k) = \sum _{k=1}^{m} \pi _kp_k(x), \quad \pi _k \geq 0, \quad \sum _{k=1}^{m} \pi _k=1, p(x;a_k,S_k, \pi _k) = \sum _{k=1}^{m} \pi _kp_k(x), \quad \pi _k \geq 0, \quad \sum _{k=1}^{m} \pi _k=1,
.. math:: .. math::
p_k(x)= \varphi (x;a_k,S_k)= \frac{1}{(2\pi)^{d/2}\mid{S_k}\mid^{1/2}} exp \left \{ - \frac{1}{2} (x-a_k)^TS_k^{-1}(x-a_k) \right \} , p_k(x)= \varphi (x;a_k,S_k)= \frac{1}{(2\pi)^{d/2}\mid{S_k}\mid^{1/2}} exp \left \{ - \frac{1}{2} (x-a_k)^TS_k^{-1}(x-a_k) \right \} ,
where
where :math:`m` is the number of mixtures,
:math:`m` :math:`p_k` is the normal distribution
is the number of mixtures, density with the mean
:math:`p_k` :math:`a_k` and covariance matrix
is the normal distribution :math:`S_k`,:math:`\pi_k` is the weight of the k-th mixture. Given the number of mixtures
density with the mean :math:`M` and the samples
:math:`a_k` :math:`x_i`,:math:`i=1..N` the algorithm finds the
and covariance matrix
:math:`S_k`
,
:math:`\pi_k`
is the weight of the k-th mixture. Given the number of mixtures
:math:`M`
and the samples
:math:`x_i`
,
:math:`i=1..N`
the algorithm finds the
maximum-likelihood estimates (MLE) of the all the mixture parameters, maximum-likelihood estimates (MLE) of the all the mixture parameters,
i.e. i.e.
:math:`a_k` :math:`a_k`,:math:`S_k` and
, :math:`\pi_k` :
:math:`S_k`
and
:math:`\pi_k`
:
.. math:: .. math::
L(x, \theta )=logp(x, \theta )= \sum _{i=1}^{N}log \left ( \sum _{k=1}^{m} \pi _kp_k(x) \right ) \to \max _{ \theta \in \Theta }, L(x, \theta )=logp(x, \theta )= \sum _{i=1}^{N}log \left ( \sum _{k=1}^{m} \pi _kp_k(x) \right ) \to \max _{ \theta \in \Theta },
.. math:: .. math::
\Theta = \left \{ (a_k,S_k, \pi _k): a_k \in \mathbbm{R} ^d,S_k=S_k^T>0,S_k \in \mathbbm{R} ^{d \times d}, \pi _k \geq 0, \sum _{k=1}^{m} \pi _k=1 \right \} . \Theta = \left \{ (a_k,S_k, \pi _k): a_k \in \mathbbm{R} ^d,S_k=S_k^T>0,S_k \in \mathbbm{R} ^{d \times d}, \pi _k \geq 0, \sum _{k=1}^{m} \pi _k=1 \right \} .
EM algorithm is an iterative procedure. Each iteration of it includes EM algorithm is an iterative procedure. Each iteration of it includes
two steps. At the first step (Expectation-step, or E-step), we find a two steps. At the first step (Expectation-step, or E-step), we find a
probability probability
:math:`p_{i,k}` :math:`p_{i,k}` (denoted
(denoted :math:`\alpha_{i,k}` in the formula below) of
:math:`\alpha_{i,k}` sample ``i`` to belong to mixture ``k`` using the currently
in the formula below) of
sample
``i``
to belong to mixture
``k``
using the currently
available mixture parameter estimates: available mixture parameter estimates:
.. math:: .. math::
\alpha _{ki} = \frac{\pi_k\varphi(x;a_k,S_k)}{\sum\limits_{j=1}^{m}\pi_j\varphi(x;a_j,S_j)} . \alpha _{ki} = \frac{\pi_k\varphi(x;a_k,S_k)}{\sum\limits_{j=1}^{m}\pi_j\varphi(x;a_j,S_j)} .
At the second step (Maximization-step, or M-step) the mixture parameter estimates are refined using the computed probabilities: At the second step (Maximization-step, or M-step) the mixture parameter estimates are refined using the computed probabilities:
.. math:: .. math::
\pi _k= \frac{1}{N} \sum _{i=1}^{N} \alpha _{ki}, \quad a_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}x_i}{\sum\limits_{i=1}^{N}\alpha_{ki}} , \quad S_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}(x_i-a_k)(x_i-a_k)^T}{\sum\limits_{i=1}^{N}\alpha_{ki}} , \pi _k= \frac{1}{N} \sum _{i=1}^{N} \alpha _{ki}, \quad a_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}x_i}{\sum\limits_{i=1}^{N}\alpha_{ki}} , \quad S_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}(x_i-a_k)(x_i-a_k)^T}{\sum\limits_{i=1}^{N}\alpha_{ki}} ,
Alternatively, the algorithm may start with the M-step when the initial values for
Alternatively, the algorithm may start with the M-step when the initial values for :math:`p_{i,k}` can be provided. Another alternative when
:math:`p_{i,k}` :math:`p_{i,k}` are unknown, is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
can be provided. Another alternative when :math:`p_{i,k}` . Often (and in ML) the
:math:`p_{i,k}` :ref:`KMeans2` algorithm is used for that purpose.
are unknown, is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
:math:`p_{i,k}`
. Often (and in ML) the
:ref:`KMeans2`
algorithm is used for that purpose.
One of the main that EM algorithm should deal with is the large number One of the main that EM algorithm should deal with is the large number
of parameters to estimate. The majority of the parameters sits in of parameters to estimate. The majority of the parameters sits in
covariance matrices, which are covariance matrices, which are
:math:`d \times d` :math:`d \times d` elements each
elements each (where
(where :math:`d` is the feature space dimensionality). However, in
:math:`d`
is the feature space dimensionality). However, in
many practical problems the covariance matrices are close to diagonal, many practical problems the covariance matrices are close to diagonal,
or even to or even to
:math:`\mu_k*I` :math:`\mu_k*I` , where
, where :math:`I` is identity matrix and
:math:`I` :math:`\mu_k` is mixture-dependent "scale" parameter. So a robust computation
is identity matrix and
:math:`\mu_k`
is mixture-dependent "scale" parameter. So a robust computation
scheme could be to start with the harder constraints on the covariance scheme could be to start with the harder constraints on the covariance
matrices and then use the estimated parameters as an input for a less matrices and then use the estimated parameters as an input for a less
constrained optimization problem (often a diagonal covariance matrix is constrained optimization problem (often a diagonal covariance matrix is
@ -128,13 +79,8 @@ already a good enough approximation).
**References:** **References:**
* *
Bilmes98 J. A. Bilmes. A Gentle Tutorial of the EM Algorithm and its Application to Parameter Estimation for Gaussian Mixture and Hidden Markov Models. Technical Report TR-97-021, International Computer Science Institute and Computer Science Division, University of California at Berkeley, April 1998. Bilmes98 J. A. Bilmes. A Gentle Tutorial of the EM Algorithm and its Application to Parameter Estimation for Gaussian Mixture and Hidden Markov Models. Technical Report TR-97-021, International Computer Science Institute and Computer Science Division, University of California at Berkeley, April 1998.
.. index:: CvEMParams .. index:: CvEMParams
@ -142,45 +88,33 @@ already a good enough approximation).
CvEMParams CvEMParams
---------- ----------
`id=0.432576013672 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvEMParams>`__
.. ctype:: CvEMParams .. ctype:: CvEMParams
Parameters of the EM algorithm. ::
Parameters of the EM algorithm.
::
struct CvEMParams struct CvEMParams
{ {
CvEMParams() : nclusters(10), cov_mat_type(CvEM::COV_MAT_DIAGONAL), CvEMParams() : nclusters(10), cov_mat_type(CvEM::COV_MAT_DIAGONAL),
start_step(CvEM::START_AUTO_STEP), probs(0), weights(0), means(0), start_step(CvEM::START_AUTO_STEP), probs(0), weights(0), means(0),
covs(0) covs(0)
{ {
term_crit=cvTermCriteria( CV_TERMCRIT_ITER+CV_TERMCRIT_EPS, term_crit=cvTermCriteria( CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,
100, FLT_EPSILON ); 100, FLT_EPSILON );
} }
CvEMParams( int _nclusters, int _cov_mat_type=1/*CvEM::COV_MAT_DIAGONAL*/, CvEMParams( int _nclusters, int _cov_mat_type=1/*CvEM::COV_MAT_DIAGONAL*/,
int _start_step=0/*CvEM::START_AUTO_STEP*/, int _start_step=0/*CvEM::START_AUTO_STEP*/,
CvTermCriteria _term_crit=cvTermCriteria( CvTermCriteria _term_crit=cvTermCriteria(
CV_TERMCRIT_ITER+CV_TERMCRIT_EPS, CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,
100, FLT_EPSILON), 100, FLT_EPSILON),
CvMat* _probs=0, CvMat* _weights=0, CvMat* _probs=0, CvMat* _weights=0,
CvMat* _means=0, CvMat** _covs=0 ) : CvMat* _means=0, CvMat** _covs=0 ) :
nclusters(_nclusters), cov_mat_type(_cov_mat_type), nclusters(_nclusters), cov_mat_type(_cov_mat_type),
start_step(_start_step), start_step(_start_step),
probs(_probs), weights(_weights), means(_means), covs(_covs), probs(_probs), weights(_weights), means(_means), covs(_covs),
term_crit(_term_crit) term_crit(_term_crit)
{} {}
int nclusters; int nclusters;
int cov_mat_type; int cov_mat_type;
int start_step; int start_step;
@ -190,64 +124,48 @@ Parameters of the EM algorithm.
const CvMat** covs; const CvMat** covs;
CvTermCriteria term_crit; CvTermCriteria term_crit;
}; };
.. ..
The structure has 2 constructors, the default one represents a rough rule-of-thumb, with another one it is possible to override a variety of parameters, from a single number of mixtures (the only essential problem-dependent parameter), to the initial values for the mixture parameters. The structure has 2 constructors, the default one represents a rough rule-of-thumb, with another one it is possible to override a variety of parameters, from a single number of mixtures (the only essential problem-dependent parameter), to the initial values for the mixture parameters.
.. index:: CvEM .. index:: CvEM
.. _CvEM: .. _CvEM:
CvEM CvEM
---- ----
`id=0.808344863567 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvEM>`__
.. ctype:: CvEM .. ctype:: CvEM
EM model. ::
EM model.
::
class CV_EXPORTS CvEM : public CvStatModel class CV_EXPORTS CvEM : public CvStatModel
{ {
public: public:
// Type of covariance matrices // Type of covariance matrices
enum { COV_MAT_SPHERICAL=0, COV_MAT_DIAGONAL=1, COV_MAT_GENERIC=2 }; enum { COV_MAT_SPHERICAL=0, COV_MAT_DIAGONAL=1, COV_MAT_GENERIC=2 };
// The initial step // The initial step
enum { START_E_STEP=1, START_M_STEP=2, START_AUTO_STEP=0 }; enum { START_E_STEP=1, START_M_STEP=2, START_AUTO_STEP=0 };
CvEM(); CvEM();
CvEM( const CvMat* samples, const CvMat* sample_idx=0, CvEM( const CvMat* samples, const CvMat* sample_idx=0,
CvEMParams params=CvEMParams(), CvMat* labels=0 ); CvEMParams params=CvEMParams(), CvMat* labels=0 );
virtual ~CvEM(); virtual ~CvEM();
virtual bool train( const CvMat* samples, const CvMat* sample_idx=0, virtual bool train( const CvMat* samples, const CvMat* sample_idx=0,
CvEMParams params=CvEMParams(), CvMat* labels=0 ); CvEMParams params=CvEMParams(), CvMat* labels=0 );
virtual float predict( const CvMat* sample, CvMat* probs ) const; virtual float predict( const CvMat* sample, CvMat* probs ) const;
virtual void clear(); virtual void clear();
int get_nclusters() const { return params.nclusters; } int get_nclusters() const { return params.nclusters; }
const CvMat* get_means() const { return means; } const CvMat* get_means() const { return means; }
const CvMat** get_covs() const { return covs; } const CvMat** get_covs() const { return covs; }
const CvMat* get_weights() const { return weights; } const CvMat* get_weights() const { return weights; }
const CvMat* get_probs() const { return probs; } const CvMat* get_probs() const { return probs; }
protected: protected:
virtual void set_params( const CvEMParams& params, virtual void set_params( const CvEMParams& params,
const CvVectors& train_data ); const CvVectors& train_data );
virtual void init_em( const CvVectors& train_data ); virtual void init_em( const CvVectors& train_data );
@ -258,77 +176,41 @@ EM model.
const CvMat* means ); const CvMat* means );
CvEMParams params; CvEMParams params;
double log_likelihood; double log_likelihood;
CvMat* means; CvMat* means;
CvMat** covs; CvMat** covs;
CvMat* weights; CvMat* weights;
CvMat* probs; CvMat* probs;
CvMat* log_weight_div_det; CvMat* log_weight_div_det;
CvMat* inv_eigen_values; CvMat* inv_eigen_values;
CvMat** cov_rotate_mats; CvMat** cov_rotate_mats;
}; };
.. ..
.. index:: CvEM::train .. index:: CvEM::train
.. _CvEM::train: .. _CvEM::train:
CvEM::train CvEM::train
----------- -----------
`id=0.340076585117 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvEM%3A%3Atrain>`__
.. cfunction:: void CvEM::train( const CvMat* samples, const CvMat* sample_idx=0, CvEMParams params=CvEMParams(), CvMat* labels=0 ) .. cfunction:: void CvEM::train( const CvMat* samples, const CvMat* sample_idx=0, CvEMParams params=CvEMParams(), CvMat* labels=0 )
Estimates the Gaussian mixture parameters from the sample set. Estimates the Gaussian mixture parameters from the sample set.
Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or the function values) on input. Instead, it computes the
:ref:`MLE` of the Gaussian mixture parameters from the input sample set, stores all the parameters inside the structure:
:math:`p_{i,k}` in ``probs``,:math:`a_k` in ``means`` :math:`S_k` in ``covs[k]``,:math:`\pi_k` in ``weights`` and optionally computes the output "class label" for each sample:
:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (i.e. indices of the most-probable mixture for each sample).
The trained model can be used further for prediction, just like any other classifier. The model trained is similar to the
:ref:`Bayes classifier` .
Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or the function values) on input. Instead, it computes the Example: Clustering random samples of multi-Gaussian distribution using EM ::
:ref:`MLE`
of the Gaussian mixture parameters from the input sample set, stores all the parameters inside the structure:
:math:`p_{i,k}`
in
``probs``
,
:math:`a_k`
in
``means``
:math:`S_k`
in
``covs[k]``
,
:math:`\pi_k`
in
``weights``
and optionally computes the output "class label" for each sample:
:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N`
(i.e. indices of the most-probable mixture for each sample).
The trained model can be used further for prediction, just like any other classifier. The model trained is similar to the
:ref:`Bayes classifier`
.
Example: Clustering random samples of multi-Gaussian distribution using EM
::
#include "ml.h" #include "ml.h"
#include "highgui.h" #include "highgui.h"
int main( int argc, char** argv ) int main( int argc, char** argv )
{ {
const int N = 4; const int N = 4;
@ -347,23 +229,23 @@ Example: Clustering random samples of multi-Gaussian distribution using EM
CvEM em_model; CvEM em_model;
CvEMParams params; CvEMParams params;
CvMat samples_part; CvMat samples_part;
cvReshape( samples, samples, 2, 0 ); cvReshape( samples, samples, 2, 0 );
for( i = 0; i < N; i++ ) for( i = 0; i < N; i++ )
{ {
CvScalar mean, sigma; CvScalar mean, sigma;
// form the training samples // form the training samples
cvGetRows( samples, &samples_part, i*nsamples/N, cvGetRows( samples, &samples_part, i*nsamples/N,
(i+1)*nsamples/N ); (i+1)*nsamples/N );
mean = cvScalar(((i mean = cvScalar(((i
((i/N1)+1.)*img->height/(N1+1)); ((i/N1)+1.)*img->height/(N1+1));
sigma = cvScalar(30,30); sigma = cvScalar(30,30);
cvRandArr( &rng_state, &samples_part, CV_RAND_NORMAL, cvRandArr( &rng_state, &samples_part, CV_RAND_NORMAL,
mean, sigma ); mean, sigma );
} }
cvReshape( samples, samples, 1, 0 ); cvReshape( samples, samples, 1, 0 );
// initialize model's parameters // initialize model's parameters
params.covs = NULL; params.covs = NULL;
params.means = NULL; params.means = NULL;
@ -375,13 +257,13 @@ Example: Clustering random samples of multi-Gaussian distribution using EM
params.term_crit.max_iter = 10; params.term_crit.max_iter = 10;
params.term_crit.epsilon = 0.1; params.term_crit.epsilon = 0.1;
params.term_crit.type = CV_TERMCRIT_ITER|CV_TERMCRIT_EPS; params.term_crit.type = CV_TERMCRIT_ITER|CV_TERMCRIT_EPS;
// cluster the data // cluster the data
em_model.train( samples, 0, params, labels ); em_model.train( samples, 0, params, labels );
#if 0 #if 0
// the piece of code shows how to repeatedly optimize the model // the piece of code shows how to repeatedly optimize the model
// with less-constrained parameters // with less-constrained parameters
//(COV_MAT_DIAGONAL instead of COV_MAT_SPHERICAL) //(COV_MAT_DIAGONAL instead of COV_MAT_SPHERICAL)
// when the output of the first stage is used as input for the second. // when the output of the first stage is used as input for the second.
CvEM em_model2; CvEM em_model2;
@ -390,9 +272,9 @@ Example: Clustering random samples of multi-Gaussian distribution using EM
params.means = em_model.get_means(); params.means = em_model.get_means();
params.covs = (const CvMat**)em_model.get_covs(); params.covs = (const CvMat**)em_model.get_covs();
params.weights = em_model.get_weights(); params.weights = em_model.get_weights();
em_model2.train( samples, 0, params, labels ); em_model2.train( samples, 0, params, labels );
// to use em_model2, replace em_model.predict() // to use em_model2, replace em_model.predict()
// with em_model2.predict() below // with em_model2.predict() below
#endif #endif
// classify every image pixel // classify every image pixel
@ -406,12 +288,12 @@ Example: Clustering random samples of multi-Gaussian distribution using EM
sample.data.fl[1] = (float)i; sample.data.fl[1] = (float)i;
int response = cvRound(em_model.predict( &sample, NULL )); int response = cvRound(em_model.predict( &sample, NULL ));
CvScalar c = colors[response]; CvScalar c = colors[response];
cvCircle( img, pt, 1, cvScalar(c.val[0]*0.75, cvCircle( img, pt, 1, cvScalar(c.val[0]*0.75,
c.val[1]*0.75,c.val[2]*0.75), CV_FILLED ); c.val[1]*0.75,c.val[2]*0.75), CV_FILLED );
} }
} }
//draw the clustered samples //draw the clustered samples
for( i = 0; i < nsamples; i++ ) for( i = 0; i < nsamples; i++ )
{ {
@ -420,17 +302,14 @@ Example: Clustering random samples of multi-Gaussian distribution using EM
pt.y = cvRound(samples->data.fl[i*2+1]); pt.y = cvRound(samples->data.fl[i*2+1]);
cvCircle( img, pt, 1, colors[labels->data.i[i]], CV_FILLED ); cvCircle( img, pt, 1, colors[labels->data.i[i]], CV_FILLED );
} }
cvNamedWindow( "EM-clustering result", 1 ); cvNamedWindow( "EM-clustering result", 1 );
cvShowImage( "EM-clustering result", img ); cvShowImage( "EM-clustering result", img );
cvWaitKey(0); cvWaitKey(0);
cvReleaseMat( &samples ); cvReleaseMat( &samples );
cvReleaseMat( &labels ); cvReleaseMat( &labels );
return 0; return 0;
} }
.. ..

142
modules/ml/doc/k_nearest_neighbors.rst
View File

@ -3,116 +3,64 @@ K Nearest Neighbors
.. highlight:: cpp .. highlight:: cpp
The algorithm caches all of the training samples, and predicts the response for a new sample by analyzing a certain number ( The algorithm caches all of the training samples, and predicts the response for a new sample by analyzing a certain number (
**K** **K**
) of the nearest neighbors of the sample (using voting, calculating weighted sum etc.) The method is sometimes referred to as "learning by example", because for prediction it looks for the feature vector with a known response that is closest to the given vector. ) of the nearest neighbors of the sample (using voting, calculating weighted sum etc.) The method is sometimes referred to as "learning by example", because for prediction it looks for the feature vector with a known response that is closest to the given vector.
.. index:: CvKNearest .. index:: CvKNearest
.. _CvKNearest: .. _CvKNearest:
CvKNearest CvKNearest
---------- ----------
`id=0.969498355265 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvKNearest>`__
.. ctype:: CvKNearest .. ctype:: CvKNearest
K Nearest Neighbors model. ::
K Nearest Neighbors model.
::
class CvKNearest : public CvStatModel class CvKNearest : public CvStatModel
{ {
public: public:
CvKNearest(); CvKNearest();
virtual ~CvKNearest(); virtual ~CvKNearest();
CvKNearest( const CvMat* _train_data, const CvMat* _responses, CvKNearest( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _sample_idx=0, bool _is_regression=false, int max_k=32 ); const CvMat* _sample_idx=0, bool _is_regression=false, int max_k=32 );
virtual bool train( const CvMat* _train_data, const CvMat* _responses, virtual bool train( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _sample_idx=0, bool is_regression=false, const CvMat* _sample_idx=0, bool is_regression=false,
int _max_k=32, bool _update_base=false ); int _max_k=32, bool _update_base=false );
virtual float find_nearest( const CvMat* _samples, int k, CvMat* results, virtual float find_nearest( const CvMat* _samples, int k, CvMat* results,
const float** neighbors=0, CvMat* neighbor_responses=0, CvMat* dist=0 ) const; const float** neighbors=0, CvMat* neighbor_responses=0, CvMat* dist=0 ) const;
virtual void clear(); virtual void clear();
int get_max_k() const; int get_max_k() const;
int get_var_count() const; int get_var_count() const;
int get_sample_count() const; int get_sample_count() const;
bool is_regression() const; bool is_regression() const;
protected: protected:
... ...
}; };
.. ..
.. index:: CvKNearest::train .. index:: CvKNearest::train
.. _CvKNearest::train: .. _CvKNearest::train:
CvKNearest::train CvKNearest::train
----------------- -----------------
`id=0.0998674771945 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvKNearest%3A%3Atrain>`__
.. cfunction:: bool CvKNearest::train( const CvMat* _train_data, const CvMat* _responses, const CvMat* _sample_idx=0, bool is_regression=false, int _max_k=32, bool _update_base=false ) .. cfunction:: bool CvKNearest::train( const CvMat* _train_data, const CvMat* _responses, const CvMat* _sample_idx=0, bool is_regression=false, int _max_k=32, bool _update_base=false )
Trains the model. Trains the model.
The method trains the K-Nearest model. It follows the conventions of generic ``train`` "method" with the following limitations: only CV_ROW_SAMPLE data layout is supported, the input variables are all ordered, the output variables can be either categorical ( ``is_regression=false`` ) or ordered ( ``is_regression=true`` ), variable subsets ( ``var_idx`` ) and missing measurements are not supported.
The parameter ``_max_k`` specifies the number of maximum neighbors that may be passed to the method ``find_nearest`` .
The method trains the K-Nearest model. It follows the conventions of generic The parameter ``_update_base`` specifies whether the model is trained from scratch
``train`` ( ``_update_base=false`` ), or it is updated using the new training data ( ``_update_base=true`` ). In the latter case the parameter ``_max_k`` must not be larger than the original value.
"method" with the following limitations: only CV
_
ROW
_
SAMPLE data layout is supported, the input variables are all ordered, the output variables can be either categorical (
``is_regression=false``
) or ordered (
``is_regression=true``
), variable subsets (
``var_idx``
) and missing measurements are not supported.
The parameter
``_max_k``
specifies the number of maximum neighbors that may be passed to the method
``find_nearest``
.
The parameter
``_update_base``
specifies whether the model is trained from scratch
(
``_update_base=false``
), or it is updated using the new training data (
``_update_base=true``
). In the latter case the parameter
``_max_k``
must not be larger than the original value.
.. index:: CvKNearest::find_nearest .. index:: CvKNearest::find_nearest
@ -120,58 +68,26 @@ must not be larger than the original value.
CvKNearest::find_nearest CvKNearest::find_nearest
------------------------ ------------------------
`id=0.654974872601 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvKNearest%3A%3Afind_nearest>`__
.. cfunction:: float CvKNearest::find_nearest( const CvMat* _samples, int k, CvMat* results=0, const float** neighbors=0, CvMat* neighbor_responses=0, CvMat* dist=0 ) const .. cfunction:: float CvKNearest::find_nearest( const CvMat* _samples, int k, CvMat* results=0, const float** neighbors=0, CvMat* neighbor_responses=0, CvMat* dist=0 ) const
Finds the neighbors for the input vectors. Finds the neighbors for the input vectors.
For each input vector (which are the rows of the matrix ``_samples`` ) the method finds the
For each input vector (which are the rows of the matrix
``_samples``
) the method finds the
:math:`\texttt{k} \le :math:`\texttt{k} \le
\texttt{get\_max\_k()}` \texttt{get\_max\_k()}` nearest neighbor. In the case of regression,
nearest neighbor. In the case of regression,
the predicted result will be a mean value of the particular vector's the predicted result will be a mean value of the particular vector's
neighbor responses. In the case of classification the class is determined neighbor responses. In the case of classification the class is determined
by voting. by voting.
For custom classification/regression prediction, the method can optionally return pointers to the neighbor vectors themselves ( For custom classification/regression prediction, the method can optionally return pointers to the neighbor vectors themselves ( ``neighbors`` , an array of ``k*_samples->rows`` pointers), their corresponding output values ( ``neighbor_responses`` , a vector of ``k*_samples->rows`` elements) and the distances from the input vectors to the neighbors ( ``dist`` , also a vector of ``k*_samples->rows`` elements).
``neighbors``
, an array of
``k*_samples->rows``
pointers), their corresponding output values (
``neighbor_responses``
, a vector of
``k*_samples->rows``
elements) and the distances from the input vectors to the neighbors (
``dist``
, also a vector of
``k*_samples->rows``
elements).
For each input vector the neighbors are sorted by their distances to the vector. For each input vector the neighbors are sorted by their distances to the vector.
If only a single input vector is passed, all output matrices are optional and the predicted value is returned by the method. If only a single input vector is passed, all output matrices are optional and the predicted value is returned by the method. ::
::
#include "ml.h" #include "ml.h"
#include "highgui.h" #include "highgui.h"
int main( int argc, char** argv ) int main( int argc, char** argv )
{ {
const int K = 10; const int K = 10;
@ -185,36 +101,36 @@ If only a single input vector is passed, all output matrices are optional and th
float _sample[2]; float _sample[2];
CvMat sample = cvMat( 1, 2, CV_32FC1, _sample ); CvMat sample = cvMat( 1, 2, CV_32FC1, _sample );
cvZero( img ); cvZero( img );
CvMat trainData1, trainData2, trainClasses1, trainClasses2; CvMat trainData1, trainData2, trainClasses1, trainClasses2;
// form the training samples // form the training samples
cvGetRows( trainData, &trainData1, 0, train_sample_count/2 ); cvGetRows( trainData, &trainData1, 0, train_sample_count/2 );
cvRandArr( &rng_state, &trainData1, CV_RAND_NORMAL, cvScalar(200,200), cvScalar(50,50) ); cvRandArr( &rng_state, &trainData1, CV_RAND_NORMAL, cvScalar(200,200), cvScalar(50,50) );
cvGetRows( trainData, &trainData2, train_sample_count/2, train_sample_count ); cvGetRows( trainData, &trainData2, train_sample_count/2, train_sample_count );
cvRandArr( &rng_state, &trainData2, CV_RAND_NORMAL, cvScalar(300,300), cvScalar(50,50) ); cvRandArr( &rng_state, &trainData2, CV_RAND_NORMAL, cvScalar(300,300), cvScalar(50,50) );
cvGetRows( trainClasses, &trainClasses1, 0, train_sample_count/2 ); cvGetRows( trainClasses, &trainClasses1, 0, train_sample_count/2 );
cvSet( &trainClasses1, cvScalar(1) ); cvSet( &trainClasses1, cvScalar(1) );
cvGetRows( trainClasses, &trainClasses2, train_sample_count/2, train_sample_count ); cvGetRows( trainClasses, &trainClasses2, train_sample_count/2, train_sample_count );
cvSet( &trainClasses2, cvScalar(2) ); cvSet( &trainClasses2, cvScalar(2) );
// learn classifier // learn classifier
CvKNearest knn( trainData, trainClasses, 0, false, K ); CvKNearest knn( trainData, trainClasses, 0, false, K );
CvMat* nearests = cvCreateMat( 1, K, CV_32FC1); CvMat* nearests = cvCreateMat( 1, K, CV_32FC1);
for( i = 0; i < img->height; i++ ) for( i = 0; i < img->height; i++ )
{ {
for( j = 0; j < img->width; j++ ) for( j = 0; j < img->width; j++ )
{ {
sample.data.fl[0] = (float)j; sample.data.fl[0] = (float)j;
sample.data.fl[1] = (float)i; sample.data.fl[1] = (float)i;
// estimates the response and get the neighbors' labels // estimates the response and get the neighbors' labels
response = knn.find_nearest(&sample,K,0,0,nearests,0); response = knn.find_nearest(&sample,K,0,0,nearests,0);
// compute the number of neighbors representing the majority // compute the number of neighbors representing the majority
for( k = 0, accuracy = 0; k < K; k++ ) for( k = 0, accuracy = 0; k < K; k++ )
{ {
@ -227,7 +143,7 @@ If only a single input vector is passed, all output matrices are optional and th
(accuracy > 5 ? CV_RGB(0,180,0) : CV_RGB(120,120,0)) ); (accuracy > 5 ? CV_RGB(0,180,0) : CV_RGB(120,120,0)) );
} }
} }
// display the original training samples // display the original training samples
for( i = 0; i < train_sample_count/2; i++ ) for( i = 0; i < train_sample_count/2; i++ )
{ {
@ -239,16 +155,14 @@ If only a single input vector is passed, all output matrices are optional and th
pt.y = cvRound(trainData2.data.fl[i*2+1]); pt.y = cvRound(trainData2.data.fl[i*2+1]);
cvCircle( img, pt, 2, CV_RGB(0,255,0), CV_FILLED ); cvCircle( img, pt, 2, CV_RGB(0,255,0), CV_FILLED );
} }
cvNamedWindow( "classifier result", 1 ); cvNamedWindow( "classifier result", 1 );
cvShowImage( "classifier result", img ); cvShowImage( "classifier result", img );
cvWaitKey(0); cvWaitKey(0);
cvReleaseMat( &trainClasses ); cvReleaseMat( &trainClasses );
cvReleaseMat( &trainData ); cvReleaseMat( &trainData );
return 0; return 0;
} }
.. ..

7
modules/ml/doc/ml.rst
View File

@ -1,12 +1,11 @@
**************** ********************
Machine Learning ml. Machine Learning
**************** ********************
The Machine Learning Library (MLL) is a set of classes and functions for statistical classification, regression and clustering of data. The Machine Learning Library (MLL) is a set of classes and functions for statistical classification, regression and clustering of data.
Most of the classification and regression algorithms are implemented as C++ classes. As the algorithms have different seta of features (like the ability to handle missing measurements, or categorical input variables etc.), there is a little common ground between the classes. This common ground is defined by the class `CvStatModel` that all the other ML classes are derived from. Most of the classification and regression algorithms are implemented as C++ classes. As the algorithms have different seta of features (like the ability to handle missing measurements, or categorical input variables etc.), there is a little common ground between the classes. This common ground is defined by the class `CvStatModel` that all the other ML classes are derived from.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

275
modules/ml/doc/neural_networks.rst
View File

@ -3,96 +3,53 @@ Neural Networks
.. highlight:: cpp .. highlight:: cpp
ML implements feed-forward artificial neural networks, more particularly, multi-layer perceptrons (MLP), the most commonly used type of neural networks. MLP consists of the input layer, output layer and one or more hidden layers. Each layer of MLP includes one or more neurons that are directionally linked with the neurons from the previous and the next layer. Here is an example of a 3-layer perceptron with 3 inputs, 2 outputs and the hidden layer including 5 neurons: ML implements feed-forward artificial neural networks, more particularly, multi-layer perceptrons (MLP), the most commonly used type of neural networks. MLP consists of the input layer, output layer and one or more hidden layers. Each layer of MLP includes one or more neurons that are directionally linked with the neurons from the previous and the next layer. Here is an example of a 3-layer perceptron with 3 inputs, 2 outputs and the hidden layer including 5 neurons:
.. image:: ../../pics/mlp_.png .. image:: ../../pics/mlp_.png
All the neurons in MLP are similar. Each of them has several input links (i.e. it takes the output values from several neurons in the previous layer on input) and several output links (i.e. it passes the response to several neurons in the next layer). The values retrieved from the previous layer are summed with certain weights, individual for each neuron, plus the bias term, and the sum is transformed using the activation function
:math:`f` that may be also different for different neurons. Here is the picture:
All the neurons in MLP are similar. Each of them has several input links (i.e. it takes the output values from several neurons in the previous layer on input) and several output links (i.e. it passes the response to several neurons in the next layer). The values retrieved from the previous layer are summed with certain weights, individual for each neuron, plus the bias term, and the sum is transformed using the activation function
:math:`f`
that may be also different for different neurons. Here is the picture:
.. image:: ../../pics/neuron_model.png .. image:: ../../pics/neuron_model.png
In other words, given the outputs
:math:`x_j` of the layer
In other words, given the outputs :math:`n` , the outputs
:math:`x_j` :math:`y_i` of the layer
of the layer :math:`n+1` are computed as:
:math:`n`
, the outputs
:math:`y_i`
of the layer
:math:`n+1`
are computed as:
.. math:: .. math::
u_i = \sum _j (w^{n+1}_{i,j}*x_j) + w^{n+1}_{i,bias} u_i = \sum _j (w^{n+1}_{i,j}*x_j) + w^{n+1}_{i,bias}
.. math:: .. math::
y_i = f(u_i) y_i = f(u_i)
Different activation functions may be used, ML implements 3 standard ones: Different activation functions may be used, ML implements 3 standard ones:
* *
Identity function ( Identity function ( ``CvANN_MLP::IDENTITY`` ):
``CvANN_MLP::IDENTITY``
):
:math:`f(x)=x` :math:`f(x)=x`
* *
Symmetrical sigmoid ( Symmetrical sigmoid ( ``CvANN_MLP::SIGMOID_SYM`` ):
``CvANN_MLP::SIGMOID_SYM`` :math:`f(x)=\beta*(1-e^{-\alpha x})/(1+e^{-\alpha x}` ), the default choice for MLP; the standard sigmoid with
): :math:`\beta =1, \alpha =1` is shown below:
:math:`f(x)=\beta*(1-e^{-\alpha x})/(1+e^{-\alpha x}`
), the default choice for MLP; the standard sigmoid with
:math:`\beta =1, \alpha =1`
is shown below:
.. image:: ../../pics/sigmoid_bipolar.png .. image:: ../../pics/sigmoid_bipolar.png
* *
Gaussian function ( Gaussian function ( ``CvANN_MLP::GAUSSIAN`` ):
``CvANN_MLP::GAUSSIAN`` :math:`f(x)=\beta e^{-\alpha x*x}` , not completely supported by the moment.
):
:math:`f(x)=\beta e^{-\alpha x*x}`
, not completely supported by the moment.
In ML all the neurons have the same activation functions, with the same free parameters ( In ML all the neurons have the same activation functions, with the same free parameters (
:math:`\alpha, \beta` :math:`\alpha, \beta` ) that are specified by user and are not altered by the training algorithms.
) that are specified by user and are not altered by the training algorithms.
So the whole trained network works as follows: It takes the feature vector on input, the vector size is equal to the size of the input layer, when the values are passed as input to the first hidden layer, the outputs of the hidden layer are computed using the weights and the activation functions and passed further downstream, until we compute the output layer. So the whole trained network works as follows: It takes the feature vector on input, the vector size is equal to the size of the input layer, when the values are passed as input to the first hidden layer, the outputs of the hidden layer are computed using the weights and the activation functions and passed further downstream, until we compute the output layer.
So, in order to compute the network one needs to know all the So, in order to compute the network one needs to know all the
weights weights
:math:`w^{n+1)}_{i,j}` :math:`w^{n+1)}_{i,j}` . The weights are computed by the training
. The weights are computed by the training
algorithm. The algorithm takes a training set: multiple input vectors algorithm. The algorithm takes a training set: multiple input vectors
with the corresponding output vectors, and iteratively adjusts the with the corresponding output vectors, and iteratively adjusts the
weights to try to make the network give the desired response on the weights to try to make the network give the desired response on the
@ -105,29 +62,16 @@ learned network will also "learn" the noise present in the training set,
so the error on the test set usually starts increasing after the network so the error on the test set usually starts increasing after the network
size reaches some limit. Besides, the larger networks are train much size reaches some limit. Besides, the larger networks are train much
longer than the smaller ones, so it is reasonable to preprocess the data longer than the smaller ones, so it is reasonable to preprocess the data
(using (using
:ref:`CalcPCA` :ref:`CalcPCA` or similar technique) and train a smaller network
or similar technique) and train a smaller network
on only the essential features. on only the essential features.
Another feature of the MLP's is their inability to handle categorical Another feature of the MLP's is their inability to handle categorical
data as is, however there is a workaround. If a certain feature in the data as is, however there is a workaround. If a certain feature in the
input or output (i.e. in the case of input or output (i.e. in the case of ``n`` -class classifier for
``n`` :math:`n>2` ) layer is categorical and can take
-class classifier for :math:`M>2` different values, it makes sense to represent it as binary tuple of ``M`` elements, where ``i`` -th element is 1 if and only if the
:math:`n>2` feature is equal to the ``i`` -th value out of ``M`` possible. It
) layer is categorical and can take
:math:`M>2`
different values, it makes sense to represent it as binary tuple of
``M``
elements, where
``i``
-th element is 1 if and only if the
feature is equal to the
``i``
-th value out of
``M``
possible. It
will increase the size of the input/output layer, but will speedup the will increase the size of the input/output layer, but will speedup the
training algorithm convergence and at the same time enable "fuzzy" values training algorithm convergence and at the same time enable "fuzzy" values
of such variables, i.e. a tuple of probabilities instead of a fixed value. of such variables, i.e. a tuple of probabilities instead of a fixed value.
@ -138,22 +82,15 @@ and the second (default one) is batch RPROP algorithm.
References: References:
* *
http://en.wikipedia.org/wiki/Backpropagation http://en.wikipedia.org/wiki/Backpropagation
. Wikipedia article about the back-propagation algorithm. . Wikipedia article about the back-propagation algorithm.
* *
Y. LeCun, L. Bottou, G.B. Orr and K.-R. Muller, "Efficient backprop", in Neural Networks---Tricks of the Trade, Springer Lecture Notes in Computer Sciences 1524, pp.5-50, 1998. Y. LeCun, L. Bottou, G.B. Orr and K.-R. Muller, "Efficient backprop", in Neural Networks---Tricks of the Trade, Springer Lecture Notes in Computer Sciences 1524, pp.5-50, 1998.
* *
M. Riedmiller and H. Braun, "A Direct Adaptive Method for Faster Backpropagation Learning: The RPROP Algorithm", Proc. ICNN, San Francisco (1993). M. Riedmiller and H. Braun, "A Direct Adaptive Method for Faster Backpropagation Learning: The RPROP Algorithm", Proc. ICNN, San Francisco (1993).
.. index:: CvANN_MLP_TrainParams .. index:: CvANN_MLP_TrainParams
@ -161,49 +98,31 @@ References:
CvANN_MLP_TrainParams CvANN_MLP_TrainParams
--------------------- ---------------------
`id=0.637270235159 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvANN_MLP_TrainParams>`__
.. ctype:: CvANN_MLP_TrainParams .. ctype:: CvANN_MLP_TrainParams
Parameters of the MLP training algorithm. ::
Parameters of the MLP training algorithm.
::
struct CvANN_MLP_TrainParams struct CvANN_MLP_TrainParams
{ {
CvANN_MLP_TrainParams(); CvANN_MLP_TrainParams();
CvANN_MLP_TrainParams( CvTermCriteria term_crit, int train_method, CvANN_MLP_TrainParams( CvTermCriteria term_crit, int train_method,
double param1, double param2=0 ); double param1, double param2=0 );
~CvANN_MLP_TrainParams(); ~CvANN_MLP_TrainParams();
enum { BACKPROP=0, RPROP=1 }; enum { BACKPROP=0, RPROP=1 };
CvTermCriteria term_crit; CvTermCriteria term_crit;
int train_method; int train_method;
// backpropagation parameters // backpropagation parameters
double bp_dw_scale, bp_moment_scale; double bp_dw_scale, bp_moment_scale;
// rprop parameters // rprop parameters
double rp_dw0, rp_dw_plus, rp_dw_minus, rp_dw_min, rp_dw_max; double rp_dw0, rp_dw_plus, rp_dw_minus, rp_dw_min, rp_dw_max;
}; };
.. ..
The structure has default constructor that initializes parameters for The structure has default constructor that initializes parameters for ``RPROP`` algorithm. There is also more advanced constructor to customize the parameters and/or choose backpropagation algorithm. Finally, the individual parameters can be adjusted after the structure is created.
``RPROP``
algorithm. There is also more advanced constructor to customize the parameters and/or choose backpropagation algorithm. Finally, the individual parameters can be adjusted after the structure is created.
.. index:: CvANN_MLP .. index:: CvANN_MLP
@ -211,22 +130,10 @@ algorithm. There is also more advanced constructor to customize the parameters a
CvANN_MLP CvANN_MLP
--------- ---------
`id=0.404391979594 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvANN_MLP>`__
.. ctype:: CvANN_MLP .. ctype:: CvANN_MLP
MLP model. ::
MLP model.
::
class CvANN_MLP : public CvStatModel class CvANN_MLP : public CvStatModel
{ {
public: public:
@ -234,52 +141,52 @@ MLP model.
CvANN_MLP( const CvMat* _layer_sizes, CvANN_MLP( const CvMat* _layer_sizes,
int _activ_func=SIGMOID_SYM, int _activ_func=SIGMOID_SYM,
double _f_param1=0, double _f_param2=0 ); double _f_param1=0, double _f_param2=0 );
virtual ~CvANN_MLP(); virtual ~CvANN_MLP();
virtual void create( const CvMat* _layer_sizes, virtual void create( const CvMat* _layer_sizes,
int _activ_func=SIGMOID_SYM, int _activ_func=SIGMOID_SYM,
double _f_param1=0, double _f_param2=0 ); double _f_param1=0, double _f_param2=0 );
virtual int train( const CvMat* _inputs, const CvMat* _outputs, virtual int train( const CvMat* _inputs, const CvMat* _outputs,
const CvMat* _sample_weights, const CvMat* _sample_weights,
const CvMat* _sample_idx=0, const CvMat* _sample_idx=0,
CvANN_MLP_TrainParams _params = CvANN_MLP_TrainParams(), CvANN_MLP_TrainParams _params = CvANN_MLP_TrainParams(),
int flags=0 ); int flags=0 );
virtual float predict( const CvMat* _inputs, virtual float predict( const CvMat* _inputs,
CvMat* _outputs ) const; CvMat* _outputs ) const;
virtual void clear(); virtual void clear();
// possible activation functions // possible activation functions
enum { IDENTITY = 0, SIGMOID_SYM = 1, GAUSSIAN = 2 }; enum { IDENTITY = 0, SIGMOID_SYM = 1, GAUSSIAN = 2 };
// available training flags // available training flags
enum { UPDATE_WEIGHTS = 1, NO_INPUT_SCALE = 2, NO_OUTPUT_SCALE = 4 }; enum { UPDATE_WEIGHTS = 1, NO_INPUT_SCALE = 2, NO_OUTPUT_SCALE = 4 };
virtual void read( CvFileStorage* fs, CvFileNode* node ); virtual void read( CvFileStorage* fs, CvFileNode* node );
virtual void write( CvFileStorage* storage, const char* name ); virtual void write( CvFileStorage* storage, const char* name );
int get_layer_count() { return layer_sizes ? layer_sizes->cols : 0; } int get_layer_count() { return layer_sizes ? layer_sizes->cols : 0; }
const CvMat* get_layer_sizes() { return layer_sizes; } const CvMat* get_layer_sizes() { return layer_sizes; }
protected: protected:
virtual bool prepare_to_train( const CvMat* _inputs, const CvMat* _outputs, virtual bool prepare_to_train( const CvMat* _inputs, const CvMat* _outputs,
const CvMat* _sample_weights, const CvMat* _sample_idx, const CvMat* _sample_weights, const CvMat* _sample_idx,
CvANN_MLP_TrainParams _params, CvANN_MLP_TrainParams _params,
CvVectors* _ivecs, CvVectors* _ovecs, double** _sw, int _flags ); CvVectors* _ivecs, CvVectors* _ovecs, double** _sw, int _flags );
// sequential random backpropagation // sequential random backpropagation
virtual int train_backprop( CvVectors _ivecs, CvVectors _ovecs, virtual int train_backprop( CvVectors _ivecs, CvVectors _ovecs,
const double* _sw ); const double* _sw );
// RPROP algorithm // RPROP algorithm
virtual int train_rprop( CvVectors _ivecs, CvVectors _ovecs, virtual int train_rprop( CvVectors _ivecs, CvVectors _ovecs,
const double* _sw ); const double* _sw );
virtual void calc_activ_func( CvMat* xf, const double* bias ) const; virtual void calc_activ_func( CvMat* xf, const double* bias ) const;
virtual void calc_activ_func_deriv( CvMat* xf, CvMat* deriv, virtual void calc_activ_func_deriv( CvMat* xf, CvMat* deriv,
const double* bias ) const; const double* bias ) const;
virtual void set_activ_func( int _activ_func=SIGMOID_SYM, virtual void set_activ_func( int _activ_func=SIGMOID_SYM,
double _f_param1=0, double _f_param2=0 ); double _f_param1=0, double _f_param2=0 );
@ -288,10 +195,10 @@ MLP model.
virtual void scale_output( const CvMat* _src, CvMat* _dst ) const; virtual void scale_output( const CvMat* _src, CvMat* _dst ) const;
virtual void calc_input_scale( const CvVectors* vecs, int flags ); virtual void calc_input_scale( const CvVectors* vecs, int flags );
virtual void calc_output_scale( const CvVectors* vecs, int flags ); virtual void calc_output_scale( const CvVectors* vecs, int flags );
virtual void write_params( CvFileStorage* fs ); virtual void write_params( CvFileStorage* fs );
virtual void read_params( CvFileStorage* fs, CvFileNode* node ); virtual void read_params( CvFileStorage* fs, CvFileNode* node );
CvMat* layer_sizes; CvMat* layer_sizes;
CvMat* wbuf; CvMat* wbuf;
CvMat* sample_weights; CvMat* sample_weights;
@ -303,15 +210,9 @@ MLP model.
CvANN_MLP_TrainParams params; CvANN_MLP_TrainParams params;
CvRNG rng; CvRNG rng;
}; };
.. ..
Unlike many other models in ML that are constructed and trained at once, in the MLP model these steps are separated. First, a network with the specified topology is created using the non-default constructor or the method Unlike many other models in ML that are constructed and trained at once, in the MLP model these steps are separated. First, a network with the specified topology is created using the non-default constructor or the method ``create`` . All the weights are set to zeros. Then the network is trained using the set of input and output vectors. The training procedure can be repeated more than once, i.e. the weights can be adjusted based on the new training data.
``create``
. All the weights are set to zeros. Then the network is trained using the set of input and output vectors. The training procedure can be repeated more than once, i.e. the weights can be adjusted based on the new training data.
.. index:: CvANN_MLP::create .. index:: CvANN_MLP::create
@ -319,81 +220,45 @@ Unlike many other models in ML that are constructed and trained at once, in the
CvANN_MLP::create CvANN_MLP::create
----------------- -----------------
`id=0.505267168137 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvANN_MLP%3A%3Acreate>`__
.. cfunction:: void CvANN_MLP::create( const CvMat* _layer_sizes, int _activ_func=SIGMOID_SYM, double _f_param1=0, double _f_param2=0 ) .. cfunction:: void CvANN_MLP::create( const CvMat* _layer_sizes, int _activ_func=SIGMOID_SYM, double _f_param1=0, double _f_param2=0 )
Constructs the MLP with the specified topology Constructs the MLP with the specified topology
:param _layer_sizes: The integer vector specifies the number of neurons in each layer including the input and output layers.
:param _activ_func: Specifies the activation function for each neuron; one of ``CvANN_MLP::IDENTITY`` , ``CvANN_MLP::SIGMOID_SYM`` and ``CvANN_MLP::GAUSSIAN`` .
:param _f_param1,_f_param2: Free parameters of the activation function, :math:`\alpha` and :math:`\beta` , respectively. See the formulas in the introduction section.
:param _layer_sizes: The integer vector specifies the number of neurons in each layer including the input and output layers.
:param _activ_func: Specifies the activation function for each neuron; one of ``CvANN_MLP::IDENTITY`` , ``CvANN_MLP::SIGMOID_SYM`` and ``CvANN_MLP::GAUSSIAN`` .
:param _f_param1,_f_param2: Free parameters of the activation function, :math:`\alpha` and :math:`\beta` , respectively. See the formulas in the introduction section.
The method creates a MLP network with the specified topology and assigns the same activation function to all the neurons. The method creates a MLP network with the specified topology and assigns the same activation function to all the neurons.
.. index:: CvANN_MLP::train .. index:: CvANN_MLP::train
.. _CvANN_MLP::train: .. _CvANN_MLP::train:
CvANN_MLP::train CvANN_MLP::train
---------------- ----------------
`id=0.561890021588 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvANN_MLP%3A%3Atrain>`__
.. cfunction:: int CvANN_MLP::train( const CvMat* _inputs, const CvMat* _outputs, const CvMat* _sample_weights, const CvMat* _sample_idx=0, CvANN_MLP_TrainParams _params = CvANN_MLP_TrainParams(), int flags=0 ) .. cfunction:: int CvANN_MLP::train( const CvMat* _inputs, const CvMat* _outputs, const CvMat* _sample_weights, const CvMat* _sample_idx=0, CvANN_MLP_TrainParams _params = CvANN_MLP_TrainParams(), int flags=0 )
Trains/updates MLP. Trains/updates MLP.
:param _inputs: A floating-point matrix of input vectors, one vector per row.
:param _outputs: A floating-point matrix of the corresponding output vectors, one vector per row.
:param _sample_weights: (RPROP only) The optional floating-point vector of weights for each sample. Some samples may be more important than others for training, and the user may want to raise the weight of certain classes to find the right balance between hit-rate and false-alarm rate etc.
:param _sample_idx: The optional integer vector indicating the samples (i.e. rows of ``_inputs`` and ``_outputs`` ) that are taken into account.
:param _params: The training params. See ``CvANN_MLP_TrainParams`` description.
:param _flags: The various parameters to control the training algorithm. May be a combination of the following:
* **UPDATE_WEIGHTS = 1** algorithm updates the network weights, rather than computes them from scratch (in the latter case the weights are initialized using *Nguyen-Widrow* algorithm).
* **NO_INPUT_SCALE** algorithm does not normalize the input vectors. If this flag is not set, the training algorithm normalizes each input feature independently, shifting its mean value to 0 and making the standard deviation =1. If the network is assumed to be updated frequently, the new training data could be much different from original one. In this case user should take care of proper normalization.
* **NO_OUTPUT_SCALE** algorithm does not normalize the output vectors. If the flag is not set, the training algorithm normalizes each output features independently, by transforming it to the certain range depending on the activation function used.
:param _inputs: A floating-point matrix of input vectors, one vector per row.
:param _outputs: A floating-point matrix of the corresponding output vectors, one vector per row.
:param _sample_weights: (RPROP only) The optional floating-point vector of weights for each sample. Some samples may be more important than others for training, and the user may want to raise the weight of certain classes to find the right balance between hit-rate and false-alarm rate etc.
:param _sample_idx: The optional integer vector indicating the samples (i.e. rows of ``_inputs`` and ``_outputs`` ) that are taken into account.
:param _params: The training params. See ``CvANN_MLP_TrainParams`` description.
:param _flags: The various parameters to control the training algorithm. May be a combination of the following:
* **UPDATE_WEIGHTS = 1** algorithm updates the network weights, rather than computes them from scratch (in the latter case the weights are initialized using *Nguyen-Widrow* algorithm).
* **NO_INPUT_SCALE** algorithm does not normalize the input vectors. If this flag is not set, the training algorithm normalizes each input feature independently, shifting its mean value to 0 and making the standard deviation =1. If the network is assumed to be updated frequently, the new training data could be much different from original one. In this case user should take care of proper normalization.
* **NO_OUTPUT_SCALE** algorithm does not normalize the output vectors. If the flag is not set, the training algorithm normalizes each output features independently, by transforming it to the certain range depending on the activation function used.
This method applies the specified training algorithm to compute/adjust the network weights. It returns the number of done iterations. This method applies the specified training algorithm to compute/adjust the network weights. It returns the number of done iterations.

73
modules/ml/doc/normal_bayes_classifier.rst
View File

@ -3,7 +3,6 @@ Normal Bayes Classifier
.. highlight:: cpp .. highlight:: cpp
This is a simple classification model assuming that feature vectors from each class are normally distributed (though, not necessarily independently distributed), so the whole data distribution function is assumed to be a Gaussian mixture, one component per class. Using the training data the algorithm estimates mean vectors and covariance matrices for every class, and then it uses them for prediction. This is a simple classification model assuming that feature vectors from each class are normally distributed (though, not necessarily independently distributed), so the whole data distribution function is assumed to be a Gaussian mixture, one component per class. Using the training data the algorithm estimates mean vectors and covariance matrices for every class, and then it uses them for prediction.
**[Fukunaga90] K. Fukunaga. Introduction to Statistical Pattern Recognition. second ed., New York: Academic Press, 1990.** **[Fukunaga90] K. Fukunaga. Introduction to Statistical Pattern Recognition. second ed., New York: Academic Press, 1990.**
@ -14,88 +13,48 @@ This is a simple classification model assuming that feature vectors from each cl
CvNormalBayesClassifier CvNormalBayesClassifier
----------------------- -----------------------
`id=0.110421013491 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvNormalBayesClassifier>`__
.. ctype:: CvNormalBayesClassifier .. ctype:: CvNormalBayesClassifier
Bayes classifier for normally distributed data. ::
Bayes classifier for normally distributed data.
::
class CvNormalBayesClassifier : public CvStatModel class CvNormalBayesClassifier : public CvStatModel
{ {
public: public:
CvNormalBayesClassifier(); CvNormalBayesClassifier();
virtual ~CvNormalBayesClassifier(); virtual ~CvNormalBayesClassifier();
CvNormalBayesClassifier( const CvMat* _train_data, const CvMat* _responses, CvNormalBayesClassifier( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _var_idx=0, const CvMat* _sample_idx=0 ); const CvMat* _var_idx=0, const CvMat* _sample_idx=0 );
virtual bool train( const CvMat* _train_data, const CvMat* _responses, virtual bool train( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _var_idx = 0, const CvMat* _sample_idx=0, bool update=false ); const CvMat* _var_idx = 0, const CvMat* _sample_idx=0, bool update=false );
virtual float predict( const CvMat* _samples, CvMat* results=0 ) const; virtual float predict( const CvMat* _samples, CvMat* results=0 ) const;
virtual void clear(); virtual void clear();
virtual void save( const char* filename, const char* name=0 ); virtual void save( const char* filename, const char* name=0 );
virtual void load( const char* filename, const char* name=0 ); virtual void load( const char* filename, const char* name=0 );
virtual void write( CvFileStorage* storage, const char* name ); virtual void write( CvFileStorage* storage, const char* name );
virtual void read( CvFileStorage* storage, CvFileNode* node ); virtual void read( CvFileStorage* storage, CvFileNode* node );
protected: protected:
... ...
}; };
.. ..
.. index:: CvNormalBayesClassifier::train .. index:: CvNormalBayesClassifier::train
.. _CvNormalBayesClassifier::train: .. _CvNormalBayesClassifier::train:
CvNormalBayesClassifier::train CvNormalBayesClassifier::train
------------------------------ ------------------------------
`id=0.746566750452 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvNormalBayesClassifier%3A%3Atrain>`__
.. cfunction:: bool CvNormalBayesClassifier::train( const CvMat* _train_data, const CvMat* _responses, const CvMat* _var_idx =0, const CvMat* _sample_idx=0, bool update=false ) .. cfunction:: bool CvNormalBayesClassifier::train( const CvMat* _train_data, const CvMat* _responses, const CvMat* _var_idx =0, const CvMat* _sample_idx=0, bool update=false )
Trains the model. Trains the model.
The method trains the Normal Bayes classifier. It follows the conventions of the generic ``train`` "method" with the following limitations: only CV_ROW_SAMPLE data layout is supported; the input variables are all ordered; the output variable is categorical (i.e. elements of ``_responses`` must be integer numbers, though the vector may have ``CV_32FC1`` type), and missing measurements are not supported.
In addition, there is an ``update`` flag that identifies whether the model should be trained from scratch ( ``update=false`` ) or should be updated using the new training data ( ``update=true`` ).
The method trains the Normal Bayes classifier. It follows the conventions of the generic
``train``
"method" with the following limitations: only CV
_
ROW
_
SAMPLE data layout is supported; the input variables are all ordered; the output variable is categorical (i.e. elements of
``_responses``
must be integer numbers, though the vector may have
``CV_32FC1``
type), and missing measurements are not supported.
In addition, there is an
``update``
flag that identifies whether the model should be trained from scratch (
``update=false``
) or should be updated using the new training data (
``update=true``
).
.. index:: CvNormalBayesClassifier::predict .. index:: CvNormalBayesClassifier::predict
@ -103,23 +62,9 @@ flag that identifies whether the model should be trained from scratch (
CvNormalBayesClassifier::predict CvNormalBayesClassifier::predict
-------------------------------- --------------------------------
`id=0.821415185096 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvNormalBayesClassifier%3A%3Apredict>`__
.. cfunction:: float CvNormalBayesClassifier::predict( const CvMat* samples, CvMat* results=0 ) const .. cfunction:: float CvNormalBayesClassifier::predict( const CvMat* samples, CvMat* results=0 ) const
Predicts the response for sample(s) Predicts the response for sample(s)
The method ``predict`` estimates the most probable classes for the input vectors. The input vectors (one or more) are stored as rows of the matrix ``samples`` . In the case of multiple input vectors, there should be one output vector ``results`` . The predicted class for a single input vector is returned by the method.
The method
``predict``
estimates the most probable classes for the input vectors. The input vectors (one or more) are stored as rows of the matrix
``samples``
. In the case of multiple input vectors, there should be one output vector
``results``
. The predicted class for a single input vector is returned by the method.

216
modules/ml/doc/random_trees.rst
View File

@ -3,69 +3,49 @@ Random Trees
.. highlight:: cpp .. highlight:: cpp
Random trees have been introduced by Leo Breiman and Adele Cutler:
Random trees have been introduced by Leo Breiman and Adele Cutler:
http://www.stat.berkeley.edu/users/breiman/RandomForests/ http://www.stat.berkeley.edu/users/breiman/RandomForests/
. The algorithm can deal with both classification and regression problems. Random trees is a collection (ensemble) of tree predictors that is called . The algorithm can deal with both classification and regression problems. Random trees is a collection (ensemble) of tree predictors that is called
**forest** **forest**
further in this section (the term has been also introduced by L. Breiman). The classification works as follows: the random trees classifier takes the input feature vector, classifies it with every tree in the forest, and outputs the class label that recieved the majority of "votes". In the case of regression the classifier response is the average of the responses over all the trees in the forest. further in this section (the term has been also introduced by L. Breiman). The classification works as follows: the random trees classifier takes the input feature vector, classifies it with every tree in the forest, and outputs the class label that recieved the majority of "votes". In the case of regression the classifier response is the average of the responses over all the trees in the forest.
All the trees are trained with the same parameters, but on the different training sets, which are generated from the original training set using the bootstrap procedure: for each training set we randomly select the same number of vectors as in the original set ( All the trees are trained with the same parameters, but on the different training sets, which are generated from the original training set using the bootstrap procedure: for each training set we randomly select the same number of vectors as in the original set ( ``=N`` ). The vectors are chosen with replacement. That is, some vectors will occur more than once and some will be absent. At each node of each tree trained not all the variables are used to find the best split, rather than a random subset of them. With each node a new subset is generated, however its size is fixed for all the nodes and all the trees. It is a training parameter, set to
``=N`` :math:`\sqrt{number\_of\_variables}` by default. None of the trees that are built are pruned.
). The vectors are chosen with replacement. That is, some vectors will occur more than once and some will be absent. At each node of each tree trained not all the variables are used to find the best split, rather than a random subset of them. With each node a new subset is generated, however its size is fixed for all the nodes and all the trees. It is a training parameter, set to
:math:`\sqrt{number\_of\_variables}`
by default. None of the trees that are built are pruned.
In random trees there is no need for any accuracy estimation procedures, such as cross-validation or bootstrap, or a separate test set to get an estimate of the training error. The error is estimated internally during the training. When the training set for the current tree is drawn by sampling with replacement, some vectors are left out (so-called In random trees there is no need for any accuracy estimation procedures, such as cross-validation or bootstrap, or a separate test set to get an estimate of the training error. The error is estimated internally during the training. When the training set for the current tree is drawn by sampling with replacement, some vectors are left out (so-called
*oob (out-of-bag) data* *oob (out-of-bag) data*
). The size of oob data is about ). The size of oob data is about ``N/3`` . The classification error is estimated by using this oob-data as following:
``N/3``
. The classification error is estimated by using this oob-data as following:
* *
Get a prediction for each vector, which is oob relatively to the i-th tree, using the very i-th tree. Get a prediction for each vector, which is oob relatively to the i-th tree, using the very i-th tree.
* *
After all the trees have been trained, for each vector that has ever been oob, find the class-"winner" for it (i.e. the class that has got the majority of votes in the trees, where the vector was oob) and compare it to the ground-truth response. After all the trees have been trained, for each vector that has ever been oob, find the class-"winner" for it (i.e. the class that has got the majority of votes in the trees, where the vector was oob) and compare it to the ground-truth response.
* *
Then the classification error estimate is computed as ratio of number of misclassified oob vectors to all the vectors in the original data. In the case of regression the oob-error is computed as the squared error for oob vectors difference divided by the total number of vectors. Then the classification error estimate is computed as ratio of number of misclassified oob vectors to all the vectors in the original data. In the case of regression the oob-error is computed as the squared error for oob vectors difference divided by the total number of vectors.
**References:** **References:**
* *
Machine Learning, Wald I, July 2002. Machine Learning, Wald I, July 2002.
http://stat-www.berkeley.edu/users/breiman/wald2002-1.pdf http://stat-www.berkeley.edu/users/breiman/wald2002-1.pdf
* *
Looking Inside the Black Box, Wald II, July 2002. Looking Inside the Black Box, Wald II, July 2002.
http://stat-www.berkeley.edu/users/breiman/wald2002-2.pdf http://stat-www.berkeley.edu/users/breiman/wald2002-2.pdf
* *
Software for the Masses, Wald III, July 2002. Software for the Masses, Wald III, July 2002.
http://stat-www.berkeley.edu/users/breiman/wald2002-3.pdf http://stat-www.berkeley.edu/users/breiman/wald2002-3.pdf
* *
And other articles from the web site And other articles from the web site
http://www.stat.berkeley.edu/users/breiman/RandomForests/cc_home.htm http://www.stat.berkeley.edu/users/breiman/RandomForests/cc_home.htm
. .
.. index:: CvRTParams .. index:: CvRTParams
@ -73,34 +53,22 @@ In random trees there is no need for any accuracy estimation procedures, such as
CvRTParams CvRTParams
---------- ----------
`id=0.971665272168 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvRTParams>`__
.. ctype:: CvRTParams .. ctype:: CvRTParams
Training Parameters of Random Trees. ::
Training Parameters of Random Trees.
::
struct CvRTParams : public CvDTreeParams struct CvRTParams : public CvDTreeParams
{ {
bool calc_var_importance; bool calc_var_importance;
int nactive_vars; int nactive_vars;
CvTermCriteria term_crit; CvTermCriteria term_crit;
CvRTParams() : CvDTreeParams( 5, 10, 0, false, 10, 0, false, false, 0 ), CvRTParams() : CvDTreeParams( 5, 10, 0, false, 10, 0, false, false, 0 ),
calc_var_importance(false), nactive_vars(0) calc_var_importance(false), nactive_vars(0)
{ {
term_crit = cvTermCriteria( CV_TERMCRIT_ITER+CV_TERMCRIT_EPS, 50, 0.1 ); term_crit = cvTermCriteria( CV_TERMCRIT_ITER+CV_TERMCRIT_EPS, 50, 0.1 );
} }
CvRTParams( int _max_depth, int _min_sample_count, CvRTParams( int _max_depth, int _min_sample_count,
float _regression_accuracy, bool _use_surrogates, float _regression_accuracy, bool _use_surrogates,
int _max_categories, const float* _priors, int _max_categories, const float* _priors,
@ -108,36 +76,20 @@ Training Parameters of Random Trees.
int _nactive_vars, int max_tree_count, int _nactive_vars, int max_tree_count,
float forest_accuracy, int termcrit_type ); float forest_accuracy, int termcrit_type );
}; };
.. ..
The set of training parameters for the forest is the superset of the training parameters for a single tree. However, Random trees do not need all the functionality/features of decision trees, most noticeably, the trees are not pruned, so the cross-validation parameters are not used. The set of training parameters for the forest is the superset of the training parameters for a single tree. However, Random trees do not need all the functionality/features of decision trees, most noticeably, the trees are not pruned, so the cross-validation parameters are not used.
.. index:: CvRTrees .. index:: CvRTrees
.. _CvRTrees: .. _CvRTrees:
CvRTrees CvRTrees
-------- --------
`id=0.485875932457 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvRTrees>`__
.. ctype:: CvRTrees .. ctype:: CvRTrees
Random Trees. ::
Random Trees.
::
class CvRTrees : public CvStatModel class CvRTrees : public CvStatModel
{ {
public: public:
@ -148,27 +100,27 @@ Random Trees.
const CvMat* _sample_idx=0, const CvMat* _var_type=0, const CvMat* _sample_idx=0, const CvMat* _var_type=0,
const CvMat* _missing_mask=0, const CvMat* _missing_mask=0,
CvRTParams params=CvRTParams() ); CvRTParams params=CvRTParams() );
virtual float predict( const CvMat* sample, const CvMat* missing = 0 ) virtual float predict( const CvMat* sample, const CvMat* missing = 0 )
const; const;
virtual void clear(); virtual void clear();
virtual const CvMat* get_var_importance(); virtual const CvMat* get_var_importance();
virtual float get_proximity( const CvMat* sample_1, const CvMat* sample_2 ) virtual float get_proximity( const CvMat* sample_1, const CvMat* sample_2 )
const; const;
virtual void read( CvFileStorage* fs, CvFileNode* node ); virtual void read( CvFileStorage* fs, CvFileNode* node );
virtual void write( CvFileStorage* fs, const char* name ); virtual void write( CvFileStorage* fs, const char* name );
CvMat* get_active_var_mask(); CvMat* get_active_var_mask();
CvRNG* get_rng(); CvRNG* get_rng();
int get_tree_count() const; int get_tree_count() const;
CvForestTree* get_tree(int i) const; CvForestTree* get_tree(int i) const;
protected: protected:
bool grow_forest( const CvTermCriteria term_crit ); bool grow_forest( const CvTermCriteria term_crit );
// array of the trees of the forest // array of the trees of the forest
CvForestTree** trees; CvForestTree** trees;
CvDTreeTrainData* data; CvDTreeTrainData* data;
@ -176,44 +128,20 @@ Random Trees.
int nclasses; int nclasses;
... ...
}; };
.. ..
.. index:: CvRTrees::train .. index:: CvRTrees::train
.. _CvRTrees::train: .. _CvRTrees::train:
CvRTrees::train CvRTrees::train
--------------- ---------------
`id=0.951910664821 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvRTrees%3A%3Atrain>`__
.. cfunction:: bool CvRTrees::train( const CvMat* train_data, int tflag, const CvMat* responses, const CvMat* comp_idx=0, const CvMat* sample_idx=0, const CvMat* var_type=0, const CvMat* missing_mask=0, CvRTParams params=CvRTParams() ) .. cfunction:: bool CvRTrees::train( const CvMat* train_data, int tflag, const CvMat* responses, const CvMat* comp_idx=0, const CvMat* sample_idx=0, const CvMat* var_type=0, const CvMat* missing_mask=0, CvRTParams params=CvRTParams() )
Trains the Random Trees model. Trains the Random Trees model.
The method ``CvRTrees::train`` is very similar to the first form of ``CvDTree::train`` () and follows the generic method ``CvStatModel::train`` conventions. All of the specific to the algorithm training parameters are passed as a
:ref:`CvRTParams` instance. The estimate of the training error ( ``oob-error`` ) is stored in the protected class member ``oob_error`` .
The method
``CvRTrees::train``
is very similar to the first form of
``CvDTree::train``
() and follows the generic method
``CvStatModel::train``
conventions. All of the specific to the algorithm training parameters are passed as a
:ref:`CvRTParams`
instance. The estimate of the training error (
``oob-error``
) is stored in the protected class member
``oob_error``
.
.. index:: CvRTrees::predict .. index:: CvRTrees::predict
@ -221,23 +149,11 @@ instance. The estimate of the training error (
CvRTrees::predict CvRTrees::predict
----------------- -----------------
`id=0.175799484956 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvRTrees%3A%3Apredict>`__
.. cfunction:: double CvRTrees::predict( const CvMat* sample, const CvMat* missing=0 ) const .. cfunction:: double CvRTrees::predict( const CvMat* sample, const CvMat* missing=0 ) const
Predicts the output for the input sample. Predicts the output for the input sample.
The input parameters of the prediction method are the same as in ``CvDTree::predict`` , but the return value type is different. This method returns the cumulative result from all the trees in the forest (the class that receives the majority of voices, or the mean of the regression function estimates).
The input parameters of the prediction method are the same as in
``CvDTree::predict``
, but the return value type is different. This method returns the cumulative result from all the trees in the forest (the class that receives the majority of voices, or the mean of the regression function estimates).
.. index:: CvRTrees::get_var_importance .. index:: CvRTrees::get_var_importance
@ -245,25 +161,11 @@ The input parameters of the prediction method are the same as in
CvRTrees::get_var_importance CvRTrees::get_var_importance
---------------------------- ----------------------------
`id=0.336660771362 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvRTrees%3A%3Aget_var_importance>`__
.. cfunction:: const CvMat* CvRTrees::get_var_importance() const .. cfunction:: const CvMat* CvRTrees::get_var_importance() const
Retrieves the variable importance array. Retrieves the variable importance array.
The method returns the variable importance vector, computed at the training stage when ``:ref:`CvRTParams`::calc_var_importance`` is set. If the training flag is not set, then the ``NULL`` pointer is returned. This is unlike decision trees, where variable importance can be computed anytime after the training.
The method returns the variable importance vector, computed at the training stage when
``:ref:`CvRTParams`::calc_var_importance``
is set. If the training flag is not set, then the
``NULL``
pointer is returned. This is unlike decision trees, where variable importance can be computed anytime after the training.
.. index:: CvRTrees::get_proximity .. index:: CvRTrees::get_proximity
@ -271,39 +173,23 @@ pointer is returned. This is unlike decision trees, where variable importance ca
CvRTrees::get_proximity CvRTrees::get_proximity
----------------------- -----------------------
`id=0.2120965436 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvRTrees%3A%3Aget_proximity>`__
.. cfunction:: float CvRTrees::get_proximity( const CvMat* sample_1, const CvMat* sample_2 ) const .. cfunction:: float CvRTrees::get_proximity( const CvMat* sample_1, const CvMat* sample_2 ) const
Retrieves the proximity measure between two training samples. Retrieves the proximity measure between two training samples.
The method returns proximity measure between any two samples (the ratio of the those trees in the ensemble, in which the samples fall into the same leaf node, to the total number of the trees). The method returns proximity measure between any two samples (the ratio of the those trees in the ensemble, in which the samples fall into the same leaf node, to the total number of the trees).
Example: Prediction of mushroom goodness using random trees classifier ::
Example: Prediction of mushroom goodness using random trees classifier
::
#include <float.h> #include <float.h>
#include <stdio.h> #include <stdio.h>
#include <ctype.h> #include <ctype.h>
#include "ml.h" #include "ml.h"
int main( void ) int main( void )
{ {
CvStatModel* cls = NULL; CvStatModel* cls = NULL;
CvFileStorage* storage = cvOpenFileStorage( "Mushroom.xml", CvFileStorage* storage = cvOpenFileStorage( "Mushroom.xml",
NULL,CV_STORAGE_READ ); NULL,CV_STORAGE_READ );
CvMat* data = (CvMat*)cvReadByName(storage, NULL, "sample", 0 ); CvMat* data = (CvMat*)cvReadByName(storage, NULL, "sample", 0 );
CvMat train_data, test_data; CvMat train_data, test_data;
@ -319,27 +205,27 @@ Example: Prediction of mushroom goodness using random trees classifier
const int ntrain_samples = 1000; const int ntrain_samples = 1000;
const int ntest_samples = 1000; const int ntest_samples = 1000;
const int nvars = 23; const int nvars = 23;
if(data == NULL || data->cols != nvars) if(data == NULL || data->cols != nvars)
{ {
puts("Error in source data"); puts("Error in source data");
return -1; return -1;
} }
cvGetSubRect( data, &train_data, cvRect(0, 0, nvars, ntrain_samples) ); cvGetSubRect( data, &train_data, cvRect(0, 0, nvars, ntrain_samples) );
cvGetSubRect( data, &test_data, cvRect(0, ntrain_samples, nvars, cvGetSubRect( data, &test_data, cvRect(0, ntrain_samples, nvars,
ntrain_samples + ntest_samples) ); ntrain_samples + ntest_samples) );
resp_col = 0; resp_col = 0;
cvGetCol( &train_data, &response, resp_col); cvGetCol( &train_data, &response, resp_col);
/* create missed variable matrix */ /* create missed variable matrix */
missed = cvCreateMat(train_data.rows, train_data.cols, CV_8UC1); missed = cvCreateMat(train_data.rows, train_data.cols, CV_8UC1);
for( i = 0; i < train_data.rows; i++ ) for( i = 0; i < train_data.rows; i++ )
for( j = 0; j < train_data.cols; j++ ) for( j = 0; j < train_data.cols; j++ )
CV_MAT_ELEM(*missed,uchar,i,j) CV_MAT_ELEM(*missed,uchar,i,j)
= (uchar)(CV_MAT_ELEM(train_data,float,i,j) < 0); = (uchar)(CV_MAT_ELEM(train_data,float,i,j) < 0);
/* create comp_idx vector */ /* create comp_idx vector */
comp_idx = cvCreateMat(1, train_data.cols-1, CV_32SC1); comp_idx = cvCreateMat(1, train_data.cols-1, CV_32SC1);
for( i = 0; i < train_data.cols; i++ ) for( i = 0; i < train_data.cols; i++ )
@ -347,7 +233,7 @@ Example: Prediction of mushroom goodness using random trees classifier
if(i<resp_col)CV_MAT_ELEM(*comp_idx,int,0,i) = i; if(i<resp_col)CV_MAT_ELEM(*comp_idx,int,0,i) = i;
if(i>resp_col)CV_MAT_ELEM(*comp_idx,int,0,i-1) = i; if(i>resp_col)CV_MAT_ELEM(*comp_idx,int,0,i-1) = i;
} }
/* create sample_idx vector */ /* create sample_idx vector */
sample_idx = cvCreateMat(1, train_data.rows, CV_32SC1); sample_idx = cvCreateMat(1, train_data.rows, CV_32SC1);
for( j = i = 0; i < train_data.rows; i++ ) for( j = i = 0; i < train_data.rows; i++ )
@ -357,11 +243,11 @@ Example: Prediction of mushroom goodness using random trees classifier
j++; j++;
} }
sample_idx->cols = j; sample_idx->cols = j;
/* create type mask */ /* create type mask */
type_mask = cvCreateMat(1, train_data.cols+1, CV_8UC1); type_mask = cvCreateMat(1, train_data.cols+1, CV_8UC1);
cvSet( type_mask, cvRealScalar(CV_VAR_CATEGORICAL), 0); cvSet( type_mask, cvRealScalar(CV_VAR_CATEGORICAL), 0);
// initialize training parameters // initialize training parameters
cvSetDefaultParamTreeClassifier((CvStatModelParams*)&cart_params); cvSetDefaultParamTreeClassifier((CvStatModelParams*)&cart_params);
cart_params.wrong_feature_as_unknown = 1; cart_params.wrong_feature_as_unknown = 1;
@ -369,16 +255,16 @@ Example: Prediction of mushroom goodness using random trees classifier
params.term_crit.max_iter = 50; params.term_crit.max_iter = 50;
params.term_crit.epsilon = 0.1; params.term_crit.epsilon = 0.1;
params.term_crit.type = CV_TERMCRIT_ITER|CV_TERMCRIT_EPS; params.term_crit.type = CV_TERMCRIT_ITER|CV_TERMCRIT_EPS;
puts("Random forest results"); puts("Random forest results");
cls = cvCreateRTreesClassifier( &train_data, cls = cvCreateRTreesClassifier( &train_data,
CV_ROW_SAMPLE, CV_ROW_SAMPLE,
&response, &response,
(CvStatModelParams*)& (CvStatModelParams*)&
params, params,
comp_idx, comp_idx,
sample_idx, sample_idx,
type_mask, type_mask,
missed ); missed );
if( cls ) if( cls )
{ {
@ -395,11 +281,11 @@ Example: Prediction of mushroom goodness using random trees classifier
total++; total++;
} }
} }
printf( "Test set error = printf( "Test set error =
} }
else else
puts("Error forest creation"); puts("Error forest creation");
cvReleaseMat(&missed); cvReleaseMat(&missed);
cvReleaseMat(&sample_idx); cvReleaseMat(&sample_idx);
cvReleaseMat(&comp_idx); cvReleaseMat(&comp_idx);
@ -409,7 +295,5 @@ Example: Prediction of mushroom goodness using random trees classifier
cvReleaseFileStorage(&storage); cvReleaseFileStorage(&storage);
return 0; return 0;
} }
.. ..

288
modules/ml/doc/statistical_models.rst
View File

@ -3,88 +3,56 @@ Statistical Models
.. highlight:: cpp .. highlight:: cpp
.. index:: CvStatModel .. index:: CvStatModel
.. _CvStatModel: .. _CvStatModel:
CvStatModel CvStatModel
----------- -----------
`id=0.709260507321 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel>`__
.. ctype:: CvStatModel .. ctype:: CvStatModel
Base class for the statistical models in ML. ::
Base class for the statistical models in ML.
::
class CvStatModel class CvStatModel
{ {
public: public:
/* CvStatModel(); */ /* CvStatModel(); */
/* CvStatModel( const CvMat* train_data ... ); */ /* CvStatModel( const CvMat* train_data ... ); */
virtual ~CvStatModel(); virtual ~CvStatModel();
virtual void clear()=0; virtual void clear()=0;
/* virtual bool train( const CvMat* train_data, [int tflag,] ..., const /* virtual bool train( const CvMat* train_data, [int tflag,] ..., const
CvMat* responses, ..., CvMat* responses, ...,
[const CvMat* var_idx,] ..., [const CvMat* sample_idx,] ... [const CvMat* var_idx,] ..., [const CvMat* sample_idx,] ...
[const CvMat* var_type,] ..., [const CvMat* missing_mask,] [const CvMat* var_type,] ..., [const CvMat* missing_mask,]
<misc_training_alg_params> ... )=0; <misc_training_alg_params> ... )=0;
*/ */
/* virtual float predict( const CvMat* sample ... ) const=0; */ /* virtual float predict( const CvMat* sample ... ) const=0; */
virtual void save( const char* filename, const char* name=0 )=0; virtual void save( const char* filename, const char* name=0 )=0;
virtual void load( const char* filename, const char* name=0 )=0; virtual void load( const char* filename, const char* name=0 )=0;
virtual void write( CvFileStorage* storage, const char* name )=0; virtual void write( CvFileStorage* storage, const char* name )=0;
virtual void read( CvFileStorage* storage, CvFileNode* node )=0; virtual void read( CvFileStorage* storage, CvFileNode* node )=0;
}; };
.. ..
In this declaration some methods are commented off. Actually, these are methods for which there is no unified API (with the exception of the default constructor), however, there are many similarities in the syntax and semantics that are briefly described below in this section, as if they are a part of the base class. In this declaration some methods are commented off. Actually, these are methods for which there is no unified API (with the exception of the default constructor), however, there are many similarities in the syntax and semantics that are briefly described below in this section, as if they are a part of the base class.
.. index:: CvStatModel::CvStatModel .. index:: CvStatModel::CvStatModel
.. _CvStatModel::CvStatModel: .. _CvStatModel::CvStatModel:
CvStatModel::CvStatModel CvStatModel::CvStatModel
------------------------ ------------------------
`id=0.362486770202 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3ACvStatModel>`__
.. cfunction:: CvStatModel::CvStatModel() .. cfunction:: CvStatModel::CvStatModel()
Default constructor. Default constructor.
Each statistical model class in ML has a default constructor without parameters. This constructor is useful for 2-stage model construction, when the default constructor is followed by ``train()`` or ``load()`` .
Each statistical model class in ML has a default constructor without parameters. This constructor is useful for 2-stage model construction, when the default constructor is followed by
``train()``
or
``load()``
.
.. index:: CvStatModel::CvStatModel(...) .. index:: CvStatModel::CvStatModel(...)
@ -92,23 +60,11 @@ or
CvStatModel::CvStatModel(...) CvStatModel::CvStatModel(...)
----------------------------- -----------------------------
`id=0.672522046035 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3ACvStatModel%28...%29>`__
.. cfunction:: CvStatModel::CvStatModel( const CvMat* train_data ... ) .. cfunction:: CvStatModel::CvStatModel( const CvMat* train_data ... )
Training constructor. Training constructor.
Most ML classes provide single-step construct and train constructors. This constructor is equivalent to the default constructor, followed by the ``train()`` method with the parameters that are passed to the constructor.
Most ML classes provide single-step construct and train constructors. This constructor is equivalent to the default constructor, followed by the
``train()``
method with the parameters that are passed to the constructor.
.. index:: CvStatModel::~CvStatModel .. index:: CvStatModel::~CvStatModel
@ -116,27 +72,12 @@ method with the parameters that are passed to the constructor.
CvStatModel::~CvStatModel CvStatModel::~CvStatModel
------------------------- -------------------------
`id=0.264685391089 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3A%7ECvStatModel>`__
.. cfunction:: CvStatModel::~CvStatModel() .. cfunction:: CvStatModel::~CvStatModel()
Virtual destructor. Virtual destructor.
The destructor of the base class is declared as virtual, so it is safe to write the following code: ::
The destructor of the base class is declared as virtual, so it is safe to write the following code:
::
CvStatModel* model; CvStatModel* model;
if( use_svm ) if( use_svm )
model = new CvSVM(... /* SVM params */); model = new CvSVM(... /* SVM params */);
@ -144,15 +85,9 @@ The destructor of the base class is declared as virtual, so it is safe to write
model = new CvDTree(... /* Decision tree params */); model = new CvDTree(... /* Decision tree params */);
... ...
delete model; delete model;
.. ..
Normally, the destructor of each derived class does nothing, but in this instance it calls the overridden method Normally, the destructor of each derived class does nothing, but in this instance it calls the overridden method ``clear()`` that deallocates all the memory.
``clear()``
that deallocates all the memory.
.. index:: CvStatModel::clear .. index:: CvStatModel::clear
@ -160,29 +95,11 @@ that deallocates all the memory.
CvStatModel::clear CvStatModel::clear
------------------ ------------------
`id=0.0232469661173 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Aclear>`__
.. cfunction:: void CvStatModel::clear() .. cfunction:: void CvStatModel::clear()
Deallocates memory and resets the model state. Deallocates memory and resets the model state.
The method ``clear`` does the same job as the destructor; it deallocates all the memory occupied by the class members. But the object itself is not destructed, and can be reused further. This method is called from the destructor, from the ``train`` methods of the derived classes, from the methods ``load()``,``read()`` or even explicitly by the user.
The method
``clear``
does the same job as the destructor; it deallocates all the memory occupied by the class members. But the object itself is not destructed, and can be reused further. This method is called from the destructor, from the
``train``
methods of the derived classes, from the methods
``load()``
,
``read()``
or even explicitly by the user.
.. index:: CvStatModel::save .. index:: CvStatModel::save
@ -190,25 +107,11 @@ or even explicitly by the user.
CvStatModel::save CvStatModel::save
----------------- -----------------
`id=0.852967404887 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Asave>`__
.. cfunction:: void CvStatModel::save( const char* filename, const char* name=0 ) .. cfunction:: void CvStatModel::save( const char* filename, const char* name=0 )
Saves the model to a file. Saves the model to a file.
The method ``save`` stores the complete model state to the specified XML or YAML file with the specified name or default name (that depends on the particular class). ``Data persistence`` functionality from CxCore is used.
The method
``save``
stores the complete model state to the specified XML or YAML file with the specified name or default name (that depends on the particular class).
``Data persistence``
functionality from CxCore is used.
.. index:: CvStatModel::load .. index:: CvStatModel::load
@ -216,55 +119,27 @@ functionality from CxCore is used.
CvStatModel::load CvStatModel::load
----------------- -----------------
`id=0.957875843108 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Aload>`__
.. cfunction:: void CvStatModel::load( const char* filename, const char* name=0 ) .. cfunction:: void CvStatModel::load( const char* filename, const char* name=0 )
Loads the model from a file. Loads the model from a file.
The method ``load`` loads the complete model state with the specified name (or default model-dependent name) from the specified XML or YAML file. The previous model state is cleared by ``clear()`` .
Note that the method is virtual, so any model can be loaded using this virtual method. However, unlike the C types of OpenCV that can be loaded using the generic
The method
``load``
loads the complete model state with the specified name (or default model-dependent name) from the specified XML or YAML file. The previous model state is cleared by
``clear()``
.
Note that the method is virtual, so any model can be loaded using this virtual method. However, unlike the C types of OpenCV that can be loaded using the generic
\ \
cross{cvLoad}, here the model type must be known, because an empty model must be constructed beforehand. This limitation will be removed in the later ML versions. cross{cvLoad}, here the model type must be known, because an empty model must be constructed beforehand. This limitation will be removed in the later ML versions.
.. index:: CvStatModel::write .. index:: CvStatModel::write
.. _CvStatModel::write: .. _CvStatModel::write:
CvStatModel::write CvStatModel::write
------------------ ------------------
`id=0.167242991674 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Awrite>`__
.. cfunction:: void CvStatModel::write( CvFileStorage* storage, const char* name ) .. cfunction:: void CvStatModel::write( CvFileStorage* storage, const char* name )
Writes the model to file storage. Writes the model to file storage.
The method ``write`` stores the complete model state to the file storage with the specified name or default name (that depends on the particular class). The method is called by ``save()`` .
The method
``write``
stores the complete model state to the file storage with the specified name or default name (that depends on the particular class). The method is called by
``save()``
.
.. index:: CvStatModel::read .. index:: CvStatModel::read
@ -272,29 +147,14 @@ stores the complete model state to the file storage with the specified name or d
CvStatModel::read CvStatModel::read
----------------- -----------------
`id=0.959831015705 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Aread>`__
.. cfunction:: void CvStatMode::read( CvFileStorage* storage, CvFileNode* node ) .. cfunction:: void CvStatMode::read( CvFileStorage* storage, CvFileNode* node )
Reads the model from file storage. Reads the model from file storage.
The method ``read`` restores the complete model state from the specified node of the file storage. The node must be located by the user using the function
:ref:`GetFileNodeByName` .
The previous model state is cleared by ``clear()`` .
The method
``read``
restores the complete model state from the specified node of the file storage. The node must be located by the user using the function
:ref:`GetFileNodeByName`
.
The previous model state is cleared by
``clear()``
.
.. index:: CvStatModel::train .. index:: CvStatModel::train
@ -302,95 +162,31 @@ The previous model state is cleared by
CvStatModel::train CvStatModel::train
------------------ ------------------
`id=0.616920786727 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Atrain>`__
.. cfunction:: bool CvStatMode::train( const CvMat* train_data, [int tflag,] ..., const CvMat* responses, ..., [const CvMat* var_idx,] ..., [const CvMat* sample_idx,] ... [const CvMat* var_type,] ..., [const CvMat* missing_mask,] <misc_training_alg_params> ... ) .. cfunction:: bool CvStatMode::train( const CvMat* train_data, [int tflag,] ..., const CvMat* responses, ..., [const CvMat* var_idx,] ..., [const CvMat* sample_idx,] ... [const CvMat* var_type,] ..., [const CvMat* missing_mask,] <misc_training_alg_params> ... )
Trains the model. Trains the model.
The method trains the statistical model using a set of input feature vectors and the corresponding output values (responses). Both input and output vectors/values are passed as matrices. By default the input feature vectors are stored as ``train_data`` rows, i.e. all the components (features) of a training vector are stored continuously. However, some algorithms can handle the transposed representation, when all values of each particular feature (component/input variable) over the whole input set are stored continuously. If both layouts are supported, the method includes ``tflag`` parameter that specifies the orientation:
* ``tflag=CV_ROW_SAMPLE`` means that the feature vectors are stored as rows,
The method trains the statistical model using a set of input feature vectors and the corresponding output values (responses). Both input and output vectors/values are passed as matrices. By default the input feature vectors are stored as * ``tflag=CV_COL_SAMPLE`` means that the feature vectors are stored as columns.
``train_data``
rows, i.e. all the components (features) of a training vector are stored continuously. However, some algorithms can handle the transposed representation, when all values of each particular feature (component/input variable) over the whole input set are stored continuously. If both layouts are supported, the method includes
``tflag``
parameter that specifies the orientation:
The ``train_data`` must have a ``CV_32FC1`` (32-bit floating-point, single-channel) format. Responses are usually stored in the 1d vector (a row or a column) of ``CV_32SC1`` (only in the classification problem) or ``CV_32FC1`` format, one value per input vector (although some algorithms, like various flavors of neural nets, take vector responses).
For classification problems the responses are discrete class labels; for regression problems the responses are values of the function to be approximated. Some algorithms can deal only with classification problems, some - only with regression problems, and some can deal with both problems. In the latter case the type of output variable is either passed as separate parameter, or as a last element of ``var_type`` vector:
* * ``CV_VAR_CATEGORICAL`` means that the output values are discrete class labels,
``tflag=CV_ROW_SAMPLE``
means that the feature vectors are stored as rows,
* * ``CV_VAR_ORDERED(=CV_VAR_NUMERICAL)`` means that the output values are ordered, i.e. 2 different values can be compared as numbers, and this is a regression problem
``tflag=CV_COL_SAMPLE``
means that the feature vectors are stored as columns.
The
``train_data``
must have a
``CV_32FC1``
(32-bit floating-point, single-channel) format. Responses are usually stored in the 1d vector (a row or a column) of
``CV_32SC1``
(only in the classification problem) or
``CV_32FC1``
format, one value per input vector (although some algorithms, like various flavors of neural nets, take vector responses).
For classification problems the responses are discrete class labels; for regression problems the responses are values of the function to be approximated. Some algorithms can deal only with classification problems, some - only with regression problems, and some can deal with both problems. In the latter case the type of output variable is either passed as separate parameter, or as a last element of The types of input variables can be also specified using ``var_type`` . Most algorithms can handle only ordered input variables.
``var_type``
vector:
Many models in the ML may be trained on a selected feature subset, and/or on a selected sample subset of the training set. To make it easier for the user, the method ``train`` usually includes ``var_idx`` and ``sample_idx`` parameters. The former identifies variables (features) of interest, and the latter identifies samples of interest. Both vectors are either integer ( ``CV_32SC1`` ) vectors, i.e. lists of 0-based indices, or 8-bit ( ``CV_8UC1`` ) masks of active variables/samples. The user may pass ``NULL`` pointers instead of either of the arguments, meaning that all of the variables/samples are used for training.
Additionally some algorithms can handle missing measurements, that is when certain features of certain training samples have unknown values (for example, they forgot to measure a temperature of patient A on Monday). The parameter ``missing_mask`` , an 8-bit matrix the same size as ``train_data`` , is used to mark the missed values (non-zero elements of the mask).
*
``CV_VAR_CATEGORICAL``
means that the output values are discrete class labels,
*
``CV_VAR_ORDERED(=CV_VAR_NUMERICAL)``
means that the output values are ordered, i.e. 2 different values can be compared as numbers, and this is a regression problem
The types of input variables can be also specified using
``var_type``
. Most algorithms can handle only ordered input variables.
Many models in the ML may be trained on a selected feature subset, and/or on a selected sample subset of the training set. To make it easier for the user, the method
``train``
usually includes
``var_idx``
and
``sample_idx``
parameters. The former identifies variables (features) of interest, and the latter identifies samples of interest. Both vectors are either integer (
``CV_32SC1``
) vectors, i.e. lists of 0-based indices, or 8-bit (
``CV_8UC1``
) masks of active variables/samples. The user may pass
``NULL``
pointers instead of either of the arguments, meaning that all of the variables/samples are used for training.
Additionally some algorithms can handle missing measurements, that is when certain features of certain training samples have unknown values (for example, they forgot to measure a temperature of patient A on Monday). The parameter
``missing_mask``
, an 8-bit matrix the same size as
``train_data``
, is used to mark the missed values (non-zero elements of the mask).
Usually, the previous model state is cleared by
``clear()``
before running the training procedure. However, some algorithms may optionally update the model state with the new training data, instead of resetting it.
Usually, the previous model state is cleared by ``clear()`` before running the training procedure. However, some algorithms may optionally update the model state with the new training data, instead of resetting it.
.. index:: CvStatModel::predict .. index:: CvStatModel::predict
@ -398,29 +194,11 @@ before running the training procedure. However, some algorithms may optionally u
CvStatModel::predict CvStatModel::predict
-------------------- --------------------
`id=0.404351209628 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvStatModel%3A%3Apredict>`__
.. cfunction:: float CvStatMode::predict( const CvMat* sample[, <prediction_params>] ) const .. cfunction:: float CvStatMode::predict( const CvMat* sample[, <prediction_params>] ) const
Predicts the response for the sample. Predicts the response for the sample.
The method is used to predict the response for a new sample. In the case of classification the method returns the class label, in the case of regression - the output function value. The input sample must have as many components as the ``train_data`` passed to ``train`` contains. If the ``var_idx`` parameter is passed to ``train`` , it is remembered and then is used to extract only the necessary components from the input sample in the method ``predict`` .
The method is used to predict the response for a new sample. In the case of classification the method returns the class label, in the case of regression - the output function value. The input sample must have as many components as the
``train_data``
passed to
``train``
contains. If the
``var_idx``
parameter is passed to
``train``
, it is remembered and then is used to extract only the necessary components from the input sample in the method
``predict``
.
The suffix "const" means that prediction does not affect the internal model state, so the method can be safely called from within different threads. The suffix "const" means that prediction does not affect the internal model state, so the method can be safely called from within different threads.

290
modules/ml/doc/support_vector_machines.rst
View File

@ -3,30 +3,23 @@ Support Vector Machines
.. highlight:: cpp .. highlight:: cpp
Originally, support vector machines (SVM) was a technique for building an optimal (in some sense) binary (2-class) classifier. Then the technique has been extended to regression and clustering problems. SVM is a partial case of kernel-based methods, it maps feature vectors into higher-dimensional space using some kernel function, and then it builds an optimal linear discriminating function in this space (or an optimal hyper-plane that fits into the training data, ...). in the case of SVM the kernel is not defined explicitly. Instead, a distance between any 2 points in the hyper-space needs to be defined. Originally, support vector machines (SVM) was a technique for building an optimal (in some sense) binary (2-class) classifier. Then the technique has been extended to regression and clustering problems. SVM is a partial case of kernel-based methods, it maps feature vectors into higher-dimensional space using some kernel function, and then it builds an optimal linear discriminating function in this space (or an optimal hyper-plane that fits into the training data, ...). in the case of SVM the kernel is not defined explicitly. Instead, a distance between any 2 points in the hyper-space needs to be defined.
The solution is optimal in a sense that the margin between the separating hyper-plane and the nearest feature vectors from the both classes (in the case of 2-class classifier) is maximal. The feature vectors that are the closest to the hyper-plane are called "support vectors", meaning that the position of other vectors does not affect the hyper-plane (the decision function). The solution is optimal in a sense that the margin between the separating hyper-plane and the nearest feature vectors from the both classes (in the case of 2-class classifier) is maximal. The feature vectors that are the closest to the hyper-plane are called "support vectors", meaning that the position of other vectors does not affect the hyper-plane (the decision function).
There are a lot of good references on SVM. Here are only a few ones to start with. There are a lot of good references on SVM. Here are only a few ones to start with.
* *
**[Burges98] C. Burges. "A tutorial on support vector machines for pattern recognition", Knowledge Discovery and Data Mining 2(2), 1998.** **[Burges98] C. Burges. "A tutorial on support vector machines for pattern recognition", Knowledge Discovery and Data Mining 2(2), 1998.**
(available online at (available online at
http://citeseer.ist.psu.edu/burges98tutorial.html http://citeseer.ist.psu.edu/burges98tutorial.html
). ).
* *
**LIBSVM - A Library for Support Vector Machines. By Chih-Chung Chang and Chih-Jen Lin** **LIBSVM - A Library for Support Vector Machines. By Chih-Chung Chang and Chih-Jen Lin**
( (
http://www.csie.ntu.edu.tw/~cjlin/libsvm/ http://www.csie.ntu.edu.tw/~cjlin/libsvm/
) )
.. index:: CvSVM .. index:: CvSVM
@ -34,45 +27,33 @@ There are a lot of good references on SVM. Here are only a few ones to start wit
CvSVM CvSVM
----- -----
`id=0.838668945864 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVM>`__
.. ctype:: CvSVM .. ctype:: CvSVM
Support Vector Machines. ::
Support Vector Machines.
::
class CvSVM : public CvStatModel class CvSVM : public CvStatModel
{ {
public: public:
// SVM type // SVM type
enum { C_SVC=100, NU_SVC=101, ONE_CLASS=102, EPS_SVR=103, NU_SVR=104 }; enum { C_SVC=100, NU_SVC=101, ONE_CLASS=102, EPS_SVR=103, NU_SVR=104 };
// SVM kernel type // SVM kernel type
enum { LINEAR=0, POLY=1, RBF=2, SIGMOID=3 }; enum { LINEAR=0, POLY=1, RBF=2, SIGMOID=3 };
// SVM params type // SVM params type
enum { C=0, GAMMA=1, P=2, NU=3, COEF=4, DEGREE=5 }; enum { C=0, GAMMA=1, P=2, NU=3, COEF=4, DEGREE=5 };
CvSVM(); CvSVM();
virtual ~CvSVM(); virtual ~CvSVM();
CvSVM( const CvMat* _train_data, const CvMat* _responses, CvSVM( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _var_idx=0, const CvMat* _sample_idx=0, const CvMat* _var_idx=0, const CvMat* _sample_idx=0,
CvSVMParams _params=CvSVMParams() ); CvSVMParams _params=CvSVMParams() );
virtual bool train( const CvMat* _train_data, const CvMat* _responses, virtual bool train( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _var_idx=0, const CvMat* _sample_idx=0, const CvMat* _var_idx=0, const CvMat* _sample_idx=0,
CvSVMParams _params=CvSVMParams() ); CvSVMParams _params=CvSVMParams() );
virtual bool train_auto( const CvMat* _train_data, const CvMat* _responses, virtual bool train_auto( const CvMat* _train_data, const CvMat* _responses,
const CvMat* _var_idx, const CvMat* _sample_idx, CvSVMParams _params, const CvMat* _var_idx, const CvMat* _sample_idx, CvSVMParams _params,
int k_fold = 10, int k_fold = 10,
@ -82,52 +63,37 @@ Support Vector Machines.
CvParamGrid nu_grid = get_default_grid(CvSVM::NU), CvParamGrid nu_grid = get_default_grid(CvSVM::NU),
CvParamGrid coef_grid = get_default_grid(CvSVM::COEF), CvParamGrid coef_grid = get_default_grid(CvSVM::COEF),
CvParamGrid degree_grid = get_default_grid(CvSVM::DEGREE) ); CvParamGrid degree_grid = get_default_grid(CvSVM::DEGREE) );
virtual float predict( const CvMat* _sample ) const; virtual float predict( const CvMat* _sample ) const;
virtual int get_support_vector_count() const; virtual int get_support_vector_count() const;
virtual const float* get_support_vector(int i) const; virtual const float* get_support_vector(int i) const;
virtual CvSVMParams get_params() const { return params; }; virtual CvSVMParams get_params() const { return params; };
virtual void clear(); virtual void clear();
static CvParamGrid get_default_grid( int param_id ); static CvParamGrid get_default_grid( int param_id );
virtual void save( const char* filename, const char* name=0 ); virtual void save( const char* filename, const char* name=0 );
virtual void load( const char* filename, const char* name=0 ); virtual void load( const char* filename, const char* name=0 );
virtual void write( CvFileStorage* storage, const char* name ); virtual void write( CvFileStorage* storage, const char* name );
virtual void read( CvFileStorage* storage, CvFileNode* node ); virtual void read( CvFileStorage* storage, CvFileNode* node );
int get_var_count() const { return var_idx ? var_idx->cols : var_all; } int get_var_count() const { return var_idx ? var_idx->cols : var_all; }
protected: protected:
... ...
}; };
.. ..
.. index:: CvSVMParams .. index:: CvSVMParams
.. _CvSVMParams: .. _CvSVMParams:
CvSVMParams CvSVMParams
----------- -----------
`id=0.577929883484 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVMParams>`__
.. ctype:: CvSVMParams .. ctype:: CvSVMParams
SVM training parameters. ::
SVM training parameters.
::
struct CvSVMParams struct CvSVMParams
{ {
CvSVMParams(); CvSVMParams();
@ -135,29 +101,23 @@ SVM training parameters.
double _degree, double _gamma, double _coef0, double _degree, double _gamma, double _coef0,
double _C, double _nu, double _p, double _C, double _nu, double _p,
CvMat* _class_weights, CvTermCriteria _term_crit ); CvMat* _class_weights, CvTermCriteria _term_crit );
int svm_type; int svm_type;
int kernel_type; int kernel_type;
double degree; // for poly double degree; // for poly
double gamma; // for poly/rbf/sigmoid double gamma; // for poly/rbf/sigmoid
double coef0; // for poly/sigmoid double coef0; // for poly/sigmoid
double C; // for CV_SVM_C_SVC, CV_SVM_EPS_SVR and CV_SVM_NU_SVR double C; // for CV_SVM_C_SVC, CV_SVM_EPS_SVR and CV_SVM_NU_SVR
double nu; // for CV_SVM_NU_SVC, CV_SVM_ONE_CLASS, and CV_SVM_NU_SVR double nu; // for CV_SVM_NU_SVC, CV_SVM_ONE_CLASS, and CV_SVM_NU_SVR
double p; // for CV_SVM_EPS_SVR double p; // for CV_SVM_EPS_SVR
CvMat* class_weights; // for CV_SVM_C_SVC CvMat* class_weights; // for CV_SVM_C_SVC
CvTermCriteria term_crit; // termination criteria CvTermCriteria term_crit; // termination criteria
}; };
.. ..
The structure must be initialized and passed to the training method of The structure must be initialized and passed to the training method of
:ref:`CvSVM` :ref:`CvSVM` .
.
.. index:: CvSVM::train .. index:: CvSVM::train
@ -165,41 +125,14 @@ The structure must be initialized and passed to the training method of
CvSVM::train CvSVM::train
------------ ------------
`id=0.720656682385 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVM%3A%3Atrain>`__
.. cfunction:: bool CvSVM::train( const CvMat* _train_data, const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _sample_idx=0, CvSVMParams _params=CvSVMParams() ) .. cfunction:: bool CvSVM::train( const CvMat* _train_data, const CvMat* _responses, const CvMat* _var_idx=0, const CvMat* _sample_idx=0, CvSVMParams _params=CvSVMParams() )
Trains SVM. Trains SVM.
The method trains the SVM model. It follows the conventions of the generic ``train`` "method" with the following limitations: only the CV_ROW_SAMPLE data layout is supported, the input variables are all ordered, the output variables can be either categorical ( ``_params.svm_type=CvSVM::C_SVC`` or ``_params.svm_type=CvSVM::NU_SVC`` ), or ordered ( ``_params.svm_type=CvSVM::EPS_SVR`` or ``_params.svm_type=CvSVM::NU_SVR`` ), or not required at all ( ``_params.svm_type=CvSVM::ONE_CLASS`` ), missing measurements are not supported.
All the other parameters are gathered in
The method trains the SVM model. It follows the conventions of the generic :ref:`CvSVMParams` structure.
``train``
"method" with the following limitations: only the CV
_
ROW
_
SAMPLE data layout is supported, the input variables are all ordered, the output variables can be either categorical (
``_params.svm_type=CvSVM::C_SVC``
or
``_params.svm_type=CvSVM::NU_SVC``
), or ordered (
``_params.svm_type=CvSVM::EPS_SVR``
or
``_params.svm_type=CvSVM::NU_SVR``
), or not required at all (
``_params.svm_type=CvSVM::ONE_CLASS``
), missing measurements are not supported.
All the other parameters are gathered in
:ref:`CvSVMParams`
structure.
.. index:: CvSVM::train_auto .. index:: CvSVM::train_auto
@ -207,119 +140,41 @@ structure.
CvSVM::train_auto CvSVM::train_auto
----------------- -----------------
`id=0.63289997524 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVM%3A%3Atrain_auto>`__
.. cfunction:: train_auto( const CvMat* _train_data, const CvMat* _responses, const CvMat* _var_idx, const CvMat* _sample_idx, CvSVMParams params, int k_fold = 10, CvParamGrid C_grid = get_default_grid(CvSVM::C), CvParamGrid gamma_grid = get_default_grid(CvSVM::GAMMA), CvParamGrid p_grid = get_default_grid(CvSVM::P), CvParamGrid nu_grid = get_default_grid(CvSVM::NU), CvParamGrid coef_grid = get_default_grid(CvSVM::COEF), CvParamGrid degree_grid = get_default_grid(CvSVM::DEGREE) ) .. cfunction:: train_auto( const CvMat* _train_data, const CvMat* _responses, const CvMat* _var_idx, const CvMat* _sample_idx, CvSVMParams params, int k_fold = 10, CvParamGrid C_grid = get_default_grid(CvSVM::C), CvParamGrid gamma_grid = get_default_grid(CvSVM::GAMMA), CvParamGrid p_grid = get_default_grid(CvSVM::P), CvParamGrid nu_grid = get_default_grid(CvSVM::NU), CvParamGrid coef_grid = get_default_grid(CvSVM::COEF), CvParamGrid degree_grid = get_default_grid(CvSVM::DEGREE) )
Trains SVM with optimal parameters. Trains SVM with optimal parameters.
:param k_fold: Cross-validation parameter. The training set is divided into ``k_fold`` subsets, one subset being used to train the model, the others forming the test set. So, the SVM algorithm is executed ``k_fold`` times.
:param k_fold: Cross-validation parameter. The training set is divided into ``k_fold`` subsets, one subset being used to train the model, the others forming the test set. So, the SVM algorithm is executed ``k_fold`` times.
The method trains the SVM model automatically by choosing the optimal The method trains the SVM model automatically by choosing the optimal
parameters parameters ``C``,``gamma``,``p``,``nu``,``coef0``,``degree`` from
``C`` :ref:`CvSVMParams` . By optimal
,
``gamma``
,
``p``
,
``nu``
,
``coef0``
,
``degree``
from
:ref:`CvSVMParams`
. By optimal
one means that the cross-validation estimate of the test set error one means that the cross-validation estimate of the test set error
is minimal. The parameters are iterated by a logarithmic grid, for is minimal. The parameters are iterated by a logarithmic grid, for
example, the parameter example, the parameter ``gamma`` takes the values in the set
``gamma`` (
takes the values in the set :math:`min`,:math:`min*step`,:math:`min*{step}^2` , ...
( :math:`min*{step}^n` )
:math:`min` where
, :math:`min` is ``gamma_grid.min_val``,:math:`step` is ``gamma_grid.step`` , and
:math:`min*step` :math:`n` is the maximal index such, that
,
:math:`min*{step}^2`
, ...
:math:`min*{step}^n`
)
where
:math:`min`
is
``gamma_grid.min_val``
,
:math:`step`
is
``gamma_grid.step``
, and
:math:`n`
is the maximal index such, that
.. math:: .. math::
\texttt{gamma\_grid.min\_val} * \texttt{gamma\_grid.step} ^n < \texttt{gamma\_grid.max\_val} \texttt{gamma\_grid.min\_val} * \texttt{gamma\_grid.step} ^n < \texttt{gamma\_grid.max\_val}
So ``step`` must always be greater than 1.
So If there is no need in optimization in some parameter, the according grid step should be set to any value less or equal to 1. For example, to avoid optimization in ``gamma`` one should set ``gamma_grid.step = 0``,``gamma_grid.min_val``,``gamma_grid.max_val`` being arbitrary numbers. In this case, the value ``params.gamma`` will be taken for ``gamma`` .
``step``
must always be greater than 1.
If there is no need in optimization in some parameter, the according grid step should be set to any value less or equal to 1. For example, to avoid optimization in
``gamma``
one should set
``gamma_grid.step = 0``
,
``gamma_grid.min_val``
,
``gamma_grid.max_val``
being arbitrary numbers. In this case, the value
``params.gamma``
will be taken for
``gamma``
.
And, finally, if the optimization in some parameter is required, but And, finally, if the optimization in some parameter is required, but
there is no idea of the corresponding grid, one may call the function there is no idea of the corresponding grid, one may call the function ``CvSVM::get_default_grid`` . In
``CvSVM::get_default_grid`` order to generate a grid, say, for ``gamma`` , call ``CvSVM::get_default_grid(CvSVM::GAMMA)`` .
. In
order to generate a grid, say, for
``gamma``
, call
``CvSVM::get_default_grid(CvSVM::GAMMA)``
.
This function works for the case of classification
(
``params.svm_type=CvSVM::C_SVC``
or
``params.svm_type=CvSVM::NU_SVC``
)
as well as for the regression
(
``params.svm_type=CvSVM::EPS_SVR``
or
``params.svm_type=CvSVM::NU_SVR``
). If
``params.svm_type=CvSVM::ONE_CLASS``
, no optimization is made and the usual SVM with specified in
``params``
parameters is executed.
This function works for the case of classification
( ``params.svm_type=CvSVM::C_SVC`` or ``params.svm_type=CvSVM::NU_SVC`` )
as well as for the regression
( ``params.svm_type=CvSVM::EPS_SVR`` or ``params.svm_type=CvSVM::NU_SVR`` ). If ``params.svm_type=CvSVM::ONE_CLASS`` , no optimization is made and the usual SVM with specified in ``params`` parameters is executed.
.. index:: CvSVM::get_default_grid .. index:: CvSVM::get_default_grid
@ -327,45 +182,28 @@ parameters is executed.
CvSVM::get_default_grid CvSVM::get_default_grid
----------------------- -----------------------
`id=0.647625940741 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVM%3A%3Aget_default_grid>`__
.. cfunction:: CvParamGrid CvSVM::get_default_grid( int param_id ) .. cfunction:: CvParamGrid CvSVM::get_default_grid( int param_id )
Generates a grid for the SVM parameters. Generates a grid for the SVM parameters.
:param param_id: Must be one of the following:
* **CvSVM::C**
* **CvSVM::GAMMA**
* **CvSVM::P**
* **CvSVM::NU**
:param param_id: Must be one of the following:
* **CvSVM::C**
* **CvSVM::GAMMA**
* **CvSVM::P**
* **CvSVM::NU**
* **CvSVM::COEF**
* **CvSVM::DEGREE**
.
The grid will be generated for the parameter with this ID.
The function generates a grid for the specified parameter of the SVM algorithm. The grid may be passed to the function
``CvSVM::train_auto``
.
* **CvSVM::COEF**
* **CvSVM::DEGREE**
.
The grid will be generated for the parameter with this ID.
The function generates a grid for the specified parameter of the SVM algorithm. The grid may be passed to the function ``CvSVM::train_auto`` .
.. index:: CvSVM::get_params .. index:: CvSVM::get_params
@ -373,23 +211,11 @@ The function generates a grid for the specified parameter of the SVM algorithm.
CvSVM::get_params CvSVM::get_params
----------------- -----------------
`id=0.179013680104 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVM%3A%3Aget_params>`__
.. cfunction:: CvSVMParams CvSVM::get_params() const .. cfunction:: CvSVMParams CvSVM::get_params() const
Returns the current SVM parameters. Returns the current SVM parameters.
This function may be used to get the optimal parameters that were obtained while automatically training ``CvSVM::train_auto`` .
This function may be used to get the optimal parameters that were obtained while automatically training
``CvSVM::train_auto``
.
.. index:: CvSVM::get_support_vector* .. index:: CvSVM::get_support_vector*
@ -397,21 +223,11 @@ This function may be used to get the optimal parameters that were obtained while
CvSVM::get_support_vector* CvSVM::get_support_vector*
-------------------------- --------------------------
`id=0.988886411952 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/ml/CvSVM%3A%3Aget_support_vector%2A>`__
.. cfunction:: int CvSVM::get_support_vector_count() const .. cfunction:: int CvSVM::get_support_vector_count() const
.. cfunction:: const float* CvSVM::get_support_vector(int i) const .. cfunction:: const float* CvSVM::get_support_vector(int i) const
Retrieves the number of support vectors and the particular vector. Retrieves the number of support vectors and the particular vector.
The methods can be used to retrieve the set of support vectors. The methods can be used to retrieve the set of support vectors.

371
modules/objdetect/doc/cascade_classification.rst
View File

@ -3,245 +3,117 @@ Cascade Classification
.. highlight:: cpp .. highlight:: cpp
.. index:: FeatureEvaluator .. index:: FeatureEvaluator
.. _FeatureEvaluator: .. _FeatureEvaluator:
FeatureEvaluator FeatureEvaluator
---------------- ----------------
`id=0.360131889668 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator>`__
.. ctype:: FeatureEvaluator .. ctype:: FeatureEvaluator
Base class for computing feature values in cascade classifiers. ::
Base class for computing feature values in cascade classifiers.
::
class CV_EXPORTS FeatureEvaluator class CV_EXPORTS FeatureEvaluator
{ {
public: public:
enum { HAAR = 0, LBP = 1 }; // supported feature types enum { HAAR = 0, LBP = 1 }; // supported feature types
virtual ~FeatureEvaluator(); // destructor virtual ~FeatureEvaluator(); // destructor
virtual bool read(const FileNode& node); virtual bool read(const FileNode& node);
virtual Ptr<FeatureEvaluator> clone() const; virtual Ptr<FeatureEvaluator> clone() const;
virtual int getFeatureType() const; virtual int getFeatureType() const;
virtual bool setImage(const Mat& img, Size origWinSize); virtual bool setImage(const Mat& img, Size origWinSize);
virtual bool setWindow(Point p); virtual bool setWindow(Point p);
virtual double calcOrd(int featureIdx) const; virtual double calcOrd(int featureIdx) const;
virtual int calcCat(int featureIdx) const; virtual int calcCat(int featureIdx) const;
static Ptr<FeatureEvaluator> create(int type); static Ptr<FeatureEvaluator> create(int type);
}; };
.. ..
.. index:: FeatureEvaluator::read .. index:: FeatureEvaluator::read
cv::FeatureEvaluator::read cv::FeatureEvaluator::read
-------------------------- --------------------------
`id=0.201865718724 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3Aread>`__
.. cfunction:: bool FeatureEvaluator::read(const FileNode\& node) .. cfunction:: bool FeatureEvaluator::read(const FileNode\& node)
Reads parameters of the features from a FileStorage node. Reads parameters of the features from a FileStorage node.
:param node: File node from which the feature parameters are read.
:param node: File node from which the feature parameters are read.
.. index:: FeatureEvaluator::clone .. index:: FeatureEvaluator::clone
cv::FeatureEvaluator::clone cv::FeatureEvaluator::clone
--------------------------- ---------------------------
`id=0.296896128079 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3Aclone>`__
.. cfunction:: Ptr<FeatureEvaluator> FeatureEvaluator::clone() const .. cfunction:: Ptr<FeatureEvaluator> FeatureEvaluator::clone() const
Returns a full copy of the feature evaluator. Returns a full copy of the feature evaluator.
.. index:: FeatureEvaluator::getFeatureType .. index:: FeatureEvaluator::getFeatureType
cv::FeatureEvaluator::getFeatureType cv::FeatureEvaluator::getFeatureType
------------------------------------ ------------------------------------
`id=0.0597446379803 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3AgetFeatureType>`__
.. cfunction:: int FeatureEvaluator::getFeatureType() const .. cfunction:: int FeatureEvaluator::getFeatureType() const
Returns the feature type (HAAR or LBP for now). Returns the feature type (HAAR or LBP for now).
.. index:: FeatureEvaluator::setImage .. index:: FeatureEvaluator::setImage
cv::FeatureEvaluator::setImage cv::FeatureEvaluator::setImage
------------------------------ ------------------------------
`id=0.203782054077 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3AsetImage>`__
.. cfunction:: bool FeatureEvaluator::setImage(const Mat\& img, Size origWinSize) .. cfunction:: bool FeatureEvaluator::setImage(const Mat\& img, Size origWinSize)
Sets the image in which to compute the features. Sets the image in which to compute the features.
:param img: Matrix of type ``CV_8UC1`` containing the image in which to compute the features.
:param origWinSize: Size of training images.
:param img: Matrix of type ``CV_8UC1`` containing the image in which to compute the features.
:param origWinSize: Size of training images.
.. index:: FeatureEvaluator::setWindow .. index:: FeatureEvaluator::setWindow
cv::FeatureEvaluator::setWindow cv::FeatureEvaluator::setWindow
------------------------------- -------------------------------
`id=0.403436827824 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3AsetWindow>`__
:func:`CascadeClassifier::runAt` :func:`CascadeClassifier::runAt`
.. cfunction:: bool FeatureEvaluator::setWindow(Point p) .. cfunction:: bool FeatureEvaluator::setWindow(Point p)
Sets window in the current image in which the features will be computed (called by ). Sets window in the current image in which the features will be computed (called by ).
:param p: The upper left point of window in which the features will be computed. Size of the window is equal to size of training images.
:param p: The upper left point of window in which the features will be computed. Size of the window is equal to size of training images.
.. index:: FeatureEvaluator::calcOrd .. index:: FeatureEvaluator::calcOrd
cv::FeatureEvaluator::calcOrd cv::FeatureEvaluator::calcOrd
----------------------------- -----------------------------
`id=0.549815479033 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3AcalcOrd>`__
.. cfunction:: double FeatureEvaluator::calcOrd(int featureIdx) const .. cfunction:: double FeatureEvaluator::calcOrd(int featureIdx) const
Computes value of an ordered (numerical) feature. Computes value of an ordered (numerical) feature.
:param featureIdx: Index of feature whose value will be computed.
:param featureIdx: Index of feature whose value will be computed.
Returns computed value of ordered feature. Returns computed value of ordered feature.
.. index:: FeatureEvaluator::calcCat .. index:: FeatureEvaluator::calcCat
cv::FeatureEvaluator::calcCat cv::FeatureEvaluator::calcCat
----------------------------- -----------------------------
`id=0.581631081759 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3AcalcCat>`__
.. cfunction:: int FeatureEvaluator::calcCat(int featureIdx) const .. cfunction:: int FeatureEvaluator::calcCat(int featureIdx) const
Computes value of a categorical feature. Computes value of a categorical feature.
:param featureIdx: Index of feature whose value will be computed.
:param featureIdx: Index of feature whose value will be computed.
Returns computed label of categorical feature, i.e. value from [0,... (number of categories - 1)]. Returns computed label of categorical feature, i.e. value from [0,... (number of categories - 1)].
.. index:: FeatureEvaluator::create .. index:: FeatureEvaluator::create
cv::FeatureEvaluator::create cv::FeatureEvaluator::create
---------------------------- ----------------------------
`id=0.415170878436 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/FeatureEvaluator%3A%3Acreate>`__
.. cfunction:: static Ptr<FeatureEvaluator> FeatureEvaluator::create(int type) .. cfunction:: static Ptr<FeatureEvaluator> FeatureEvaluator::create(int type)
Constructs feature evaluator. Constructs feature evaluator.
:param type: Type of features evaluated by cascade (HAAR or LBP for now).
:param type: Type of features evaluated by cascade (HAAR or LBP for now).
.. index:: CascadeClassifier .. index:: CascadeClassifier
@ -249,40 +121,28 @@ cv::FeatureEvaluator::create
CascadeClassifier CascadeClassifier
----------------- -----------------
`id=0.173067043388 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier>`__
.. ctype:: CascadeClassifier .. ctype:: CascadeClassifier
The cascade classifier class for object detection. ::
The cascade classifier class for object detection.
::
class CascadeClassifier class CascadeClassifier
{ {
public: public:
// structure for storing tree node // structure for storing tree node
struct CV_EXPORTS DTreeNode struct CV_EXPORTS DTreeNode
{ {
int featureIdx; // feature index on which is a split int featureIdx; // feature index on which is a split
float threshold; // split threshold of ordered features only float threshold; // split threshold of ordered features only
int left; // left child index in the tree nodes array int left; // left child index in the tree nodes array
int right; // right child index in the tree nodes array int right; // right child index in the tree nodes array
}; };
// structure for storing desision tree // structure for storing desision tree
struct CV_EXPORTS DTree struct CV_EXPORTS DTree
{ {
int nodeCount; // nodes count int nodeCount; // nodes count
}; };
// structure for storing cascade stage (BOOST only for now) // structure for storing cascade stage (BOOST only for now)
struct CV_EXPORTS Stage struct CV_EXPORTS Stage
{ {
@ -290,275 +150,146 @@ The cascade classifier class for object detection.
int ntrees; // number of trees int ntrees; // number of trees
float threshold; // treshold of stage sum float threshold; // treshold of stage sum
}; };
enum { BOOST = 0 }; // supported stage types enum { BOOST = 0 }; // supported stage types
// mode of detection (see parameter flags in function HaarDetectObjects) // mode of detection (see parameter flags in function HaarDetectObjects)
enum { DO_CANNY_PRUNING = CV_HAAR_DO_CANNY_PRUNING, enum { DO_CANNY_PRUNING = CV_HAAR_DO_CANNY_PRUNING,
SCALE_IMAGE = CV_HAAR_SCALE_IMAGE, SCALE_IMAGE = CV_HAAR_SCALE_IMAGE,
FIND_BIGGEST_OBJECT = CV_HAAR_FIND_BIGGEST_OBJECT, FIND_BIGGEST_OBJECT = CV_HAAR_FIND_BIGGEST_OBJECT,
DO_ROUGH_SEARCH = CV_HAAR_DO_ROUGH_SEARCH }; DO_ROUGH_SEARCH = CV_HAAR_DO_ROUGH_SEARCH };
CascadeClassifier(); // default constructor CascadeClassifier(); // default constructor
CascadeClassifier(const string& filename); CascadeClassifier(const string& filename);
~CascadeClassifier(); // destructor ~CascadeClassifier(); // destructor
bool empty() const; bool empty() const;
bool load(const string& filename); bool load(const string& filename);
bool read(const FileNode& node); bool read(const FileNode& node);
void detectMultiScale( const Mat& image, vector<Rect>& objects, void detectMultiScale( const Mat& image, vector<Rect>& objects,
double scaleFactor=1.1, int minNeighbors=3, double scaleFactor=1.1, int minNeighbors=3,
int flags=0, Size minSize=Size()); int flags=0, Size minSize=Size());
bool setImage( Ptr<FeatureEvaluator>&, const Mat& ); bool setImage( Ptr<FeatureEvaluator>&, const Mat& );
int runAt( Ptr<FeatureEvaluator>&, Point ); int runAt( Ptr<FeatureEvaluator>&, Point );
bool is_stump_based; // true, if the trees are stumps bool is_stump_based; // true, if the trees are stumps
int stageType; // stage type (BOOST only for now) int stageType; // stage type (BOOST only for now)
int featureType; // feature type (HAAR or LBP for now) int featureType; // feature type (HAAR or LBP for now)
int ncategories; // number of categories (for categorical features only) int ncategories; // number of categories (for categorical features only)
Size origWinSize; // size of training images Size origWinSize; // size of training images
vector<Stage> stages; // vector of stages (BOOST for now) vector<Stage> stages; // vector of stages (BOOST for now)
vector<DTree> classifiers; // vector of decision trees vector<DTree> classifiers; // vector of decision trees
vector<DTreeNode> nodes; // vector of tree nodes vector<DTreeNode> nodes; // vector of tree nodes
vector<float> leaves; // vector of leaf values vector<float> leaves; // vector of leaf values
vector<int> subsets; // subsets of split by categorical feature vector<int> subsets; // subsets of split by categorical feature
Ptr<FeatureEvaluator> feval; // pointer to feature evaluator Ptr<FeatureEvaluator> feval; // pointer to feature evaluator
Ptr<CvHaarClassifierCascade> oldCascade; // pointer to old cascade Ptr<CvHaarClassifierCascade> oldCascade; // pointer to old cascade
}; };
.. ..
.. index:: CascadeClassifier::CascadeClassifier .. index:: CascadeClassifier::CascadeClassifier
cv::CascadeClassifier::CascadeClassifier cv::CascadeClassifier::CascadeClassifier
---------------------------------------- ----------------------------------------
`id=0.751407128029 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3ACascadeClassifier>`__
.. cfunction:: CascadeClassifier::CascadeClassifier(const string\& filename) .. cfunction:: CascadeClassifier::CascadeClassifier(const string\& filename)
Loads the classifier from file. Loads the classifier from file.
:param filename: Name of file from which classifier will be load.
:param filename: Name of file from which classifier will be load.
.. index:: CascadeClassifier::empty .. index:: CascadeClassifier::empty
cv::CascadeClassifier::empty cv::CascadeClassifier::empty
---------------------------- ----------------------------
`id=0.907371026536 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3Aempty>`__
.. cfunction:: bool CascadeClassifier::empty() const .. cfunction:: bool CascadeClassifier::empty() const
Checks if the classifier has been loaded or not. Checks if the classifier has been loaded or not.
.. index:: CascadeClassifier::load .. index:: CascadeClassifier::load
cv::CascadeClassifier::load cv::CascadeClassifier::load
--------------------------- ---------------------------
`id=0.689328093704 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3Aload>`__
.. cfunction:: bool CascadeClassifier::load(const string\& filename) .. cfunction:: bool CascadeClassifier::load(const string\& filename)
Loads the classifier from file. The previous content is destroyed. Loads the classifier from file. The previous content is destroyed.
:param filename: Name of file from which classifier will be load. File may contain as old haar classifier (trained by haartraining application) or new cascade classifier (trained traincascade application).
:param filename: Name of file from which classifier will be load. File may contain as old haar classifier (trained by haartraining application) or new cascade classifier (trained traincascade application).
.. index:: CascadeClassifier::read .. index:: CascadeClassifier::read
cv::CascadeClassifier::read cv::CascadeClassifier::read
--------------------------- ---------------------------
`id=0.21698114693 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3Aread>`__
.. cfunction:: bool CascadeClassifier::read(const FileNode\& node) .. cfunction:: bool CascadeClassifier::read(const FileNode\& node)
Reads the classifier from a FileStorage node. File may contain a new cascade classifier (trained traincascade application) only. Reads the classifier from a FileStorage node. File may contain a new cascade classifier (trained traincascade application) only.
.. index:: CascadeClassifier::detectMultiScale .. index:: CascadeClassifier::detectMultiScale
cv::CascadeClassifier::detectMultiScale cv::CascadeClassifier::detectMultiScale
--------------------------------------- ---------------------------------------
`id=0.0317051017457 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3AdetectMultiScale>`__
.. cfunction:: void CascadeClassifier::detectMultiScale( const Mat\& image, vector<Rect>\& objects, double scaleFactor=1.1, int minNeighbors=3, int flags=0, Size minSize=Size()) .. cfunction:: void CascadeClassifier::detectMultiScale( const Mat\& image, vector<Rect>\& objects, double scaleFactor=1.1, int minNeighbors=3, int flags=0, Size minSize=Size())
Detects objects of different sizes in the input image. The detected objects are returned as a list of rectangles. Detects objects of different sizes in the input image. The detected objects are returned as a list of rectangles.
:param image: Matrix of type ``CV_8U`` containing the image in which to detect objects.
:param objects: Vector of rectangles such that each rectangle contains the detected object.
:param scaleFactor: Specifies how much the image size is reduced at each image scale.
:param minNeighbors: Speficifes how many neighbors should each candiate rectangle have to retain it.
:param flags: This parameter is not used for new cascade and have the same meaning for old cascade as in function cvHaarDetectObjects.
:param image: Matrix of type ``CV_8U`` containing the image in which to detect objects.
:param minSize: The minimum possible object size. Objects smaller than that are ignored.
:param objects: Vector of rectangles such that each rectangle contains the detected object.
:param scaleFactor: Specifies how much the image size is reduced at each image scale.
:param minNeighbors: Speficifes how many neighbors should each candiate rectangle have to retain it.
:param flags: This parameter is not used for new cascade and have the same meaning for old cascade as in function cvHaarDetectObjects.
:param minSize: The minimum possible object size. Objects smaller than that are ignored.
.. index:: CascadeClassifier::setImage .. index:: CascadeClassifier::setImage
cv::CascadeClassifier::setImage cv::CascadeClassifier::setImage
------------------------------- -------------------------------
`id=0.632605719384 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3AsetImage>`__
.. cfunction:: bool CascadeClassifier::setImage( Ptr<FeatureEvaluator>\& feval, const Mat\& image ) .. cfunction:: bool CascadeClassifier::setImage( Ptr<FeatureEvaluator>\& feval, const Mat\& image )
Sets the image for detection (called by detectMultiScale at each image level). Sets the image for detection (called by detectMultiScale at each image level).
:param feval: Pointer to feature evaluator which is used for computing features.
:param image: Matrix of type ``CV_8UC1`` containing the image in which to compute the features.
:param feval: Pointer to feature evaluator which is used for computing features.
:param image: Matrix of type ``CV_8UC1`` containing the image in which to compute the features.
.. index:: CascadeClassifier::runAt .. index:: CascadeClassifier::runAt
cv::CascadeClassifier::runAt cv::CascadeClassifier::runAt
---------------------------- ----------------------------
`id=0.159942031477 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/CascadeClassifier%3A%3ArunAt>`__
.. cfunction:: int CascadeClassifier::runAt( Ptr<FeatureEvaluator>\& feval, Point pt ) .. cfunction:: int CascadeClassifier::runAt( Ptr<FeatureEvaluator>\& feval, Point pt )
Runs the detector at the specified point (the image that the detector is working with should be set by setImage). Runs the detector at the specified point (the image that the detector is working with should be set by setImage).
:param feval: Feature evaluator which is used for computing features.
:param pt: The upper left point of window in which the features will be computed. Size of the window is equal to size of training images.
:param feval: Feature evaluator which is used for computing features.
:param pt: The upper left point of window in which the features will be computed. Size of the window is equal to size of training images.
Returns: Returns:
1 - if cascade classifier detects object in the given location. 1 - if cascade classifier detects object in the given location.
-si - otherwise. si is an index of stage which first predicted that given window is a background image. -si - otherwise. si is an index of stage which first predicted that given window is a background image.
.. index:: groupRectangles .. index:: groupRectangles
cv::groupRectangles cv::groupRectangles
------------------- -------------------
`id=0.226659440065 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/objdetect/groupRectangles>`__
.. cfunction:: void groupRectangles(vector<Rect>\& rectList, int groupThreshold, double eps=0.2) .. cfunction:: void groupRectangles(vector<Rect>\& rectList, int groupThreshold, double eps=0.2)
Groups the object candidate rectangles Groups the object candidate rectangles
:param rectList: The input/output vector of rectangles. On output there will be retained and grouped rectangles
:param groupThreshold: The minimum possible number of rectangles, minus 1, in a group of rectangles to retain it.
:param eps: The relative difference between sides of the rectangles to merge them into a group
The function is a wrapper for a generic function
:func:`partition` . It clusters all the input rectangles using the rectangle equivalence criteria, that combines rectangles that have similar sizes and similar locations (the similarity is defined by ``eps`` ). When ``eps=0`` , no clustering is done at all. If
:param rectList: The input/output vector of rectangles. On output there will be retained and grouped rectangles :math:`\texttt{eps}\rightarrow +\inf` , all the rectangles will be put in one cluster. Then, the small clusters, containing less than or equal to ``groupThreshold`` rectangles, will be rejected. In each other cluster the average rectangle will be computed and put into the output rectangle list.
:param groupThreshold: The minimum possible number of rectangles, minus 1, in a group of rectangles to retain it.
:param eps: The relative difference between sides of the rectangles to merge them into a group
The function is a wrapper for a generic function
:func:`partition`
. It clusters all the input rectangles using the rectangle equivalence criteria, that combines rectangles that have similar sizes and similar locations (the similarity is defined by
``eps``
). When
``eps=0``
, no clustering is done at all. If
:math:`\texttt{eps}\rightarrow +\inf`
, all the rectangles will be put in one cluster. Then, the small clusters, containing less than or equal to
``groupThreshold``
rectangles, will be rejected. In each other cluster the average rectangle will be computed and put into the output rectangle list.

6
modules/objdetect/doc/objdetect.rst
View File

@ -1,6 +1,6 @@
**************** ***************************
Object Detection objdetect. Object Detection
**************** ***************************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

399
modules/video/doc/motion_analysis_and_object_tracking.rst
View File

@ -3,405 +3,199 @@ Motion Analysis and Object Tracking
.. highlight:: cpp .. highlight:: cpp
.. index:: calcOpticalFlowPyrLK .. index:: calcOpticalFlowPyrLK
cv::calcOpticalFlowPyrLK cv::calcOpticalFlowPyrLK
------------------------ ------------------------
`id=0.801764538588 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/calcOpticalFlowPyrLK>`__
.. cfunction:: void calcOpticalFlowPyrLK( const Mat\& prevImg, const Mat\& nextImg, const vector<Point2f>\& prevPts, vector<Point2f>\& nextPts, vector<uchar>\& status, vector<float>\& err, Size winSize=Size(15,15), int maxLevel=3, TermCriteria criteria=TermCriteria( TermCriteria::COUNT+TermCriteria::EPS, 30, 0.01), double derivLambda=0.5, int flags=0 ) .. cfunction:: void calcOpticalFlowPyrLK( const Mat\& prevImg, const Mat\& nextImg, const vector<Point2f>\& prevPts, vector<Point2f>\& nextPts, vector<uchar>\& status, vector<float>\& err, Size winSize=Size(15,15), int maxLevel=3, TermCriteria criteria=TermCriteria( TermCriteria::COUNT+TermCriteria::EPS, 30, 0.01), double derivLambda=0.5, int flags=0 )
Calculates the optical flow for a sparse feature set using the iterative Lucas-Kanade method with pyramids Calculates the optical flow for a sparse feature set using the iterative Lucas-Kanade method with pyramids
:param prevImg: The first 8-bit single-channel or 3-channel input image
:param nextImg: The second input image of the same size and the same type as ``prevImg``
:param prevPts: Vector of points for which the flow needs to be found
:param nextPts: The output vector of points containing the calculated new positions of the input features in the second image
:param status: The output status vector. Each element of the vector is set to 1 if the flow for the corresponding features has been found, 0 otherwise
:param err: The output vector that will contain the difference between patches around the original and moved points
:param prevImg: The first 8-bit single-channel or 3-channel input image
:param winSize: Size of the search window at each pyramid level
:param nextImg: The second input image of the same size and the same type as ``prevImg`` :param maxLevel: 0-based maximal pyramid level number. If 0, pyramids are not used (single level), if 1, two levels are used etc.
:param criteria: Specifies the termination criteria of the iterative search algorithm (after the specified maximum number of iterations ``criteria.maxCount`` or when the search window moves by less than ``criteria.epsilon``
:param prevPts: Vector of points for which the flow needs to be found :param derivLambda: The relative weight of the spatial image derivatives impact to the optical flow estimation. If ``derivLambda=0`` , only the image intensity is used, if ``derivLambda=1`` , only derivatives are used. Any other values between 0 and 1 means that both derivatives and the image intensity are used (in the corresponding proportions).
:param flags: The operation flags:
:param nextPts: The output vector of points containing the calculated new positions of the input features in the second image
* **OPTFLOW_USE_INITIAL_FLOW** use initial estimations stored in ``nextPts`` . If the flag is not set, then initially :math:`\texttt{nextPts}\leftarrow\texttt{prevPts}`
The function implements the sparse iterative version of the Lucas-Kanade optical flow in pyramids, see
:param status: The output status vector. Each element of the vector is set to 1 if the flow for the corresponding features has been found, 0 otherwise
:param err: The output vector that will contain the difference between patches around the original and moved points
:param winSize: Size of the search window at each pyramid level
:param maxLevel: 0-based maximal pyramid level number. If 0, pyramids are not used (single level), if 1, two levels are used etc.
:param criteria: Specifies the termination criteria of the iterative search algorithm (after the specified maximum number of iterations ``criteria.maxCount`` or when the search window moves by less than ``criteria.epsilon``
:param derivLambda: The relative weight of the spatial image derivatives impact to the optical flow estimation. If ``derivLambda=0`` , only the image intensity is used, if ``derivLambda=1`` , only derivatives are used. Any other values between 0 and 1 means that both derivatives and the image intensity are used (in the corresponding proportions).
:param flags: The operation flags:
* **OPTFLOW_USE_INITIAL_FLOW** use initial estimations stored in ``nextPts`` . If the flag is not set, then initially :math:`\texttt{nextPts}\leftarrow\texttt{prevPts}`
The function implements the sparse iterative version of the Lucas-Kanade optical flow in pyramids, see
Bouguet00 Bouguet00
. .
.. index:: calcOpticalFlowFarneback .. index:: calcOpticalFlowFarneback
cv::calcOpticalFlowFarneback cv::calcOpticalFlowFarneback
---------------------------- ----------------------------
`id=0.147581673853 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/calcOpticalFlowFarneback>`__
.. cfunction:: void calcOpticalFlowFarneback( const Mat\& prevImg, const Mat\& nextImg, Mat\& flow, double pyrScale, int levels, int winsize, int iterations, int polyN, double polySigma, int flags ) .. cfunction:: void calcOpticalFlowFarneback( const Mat\& prevImg, const Mat\& nextImg, Mat\& flow, double pyrScale, int levels, int winsize, int iterations, int polyN, double polySigma, int flags )
Computes dense optical flow using Gunnar Farneback's algorithm Computes dense optical flow using Gunnar Farneback's algorithm
:param prevImg: The first 8-bit single-channel input image
:param nextImg: The second input image of the same size and the same type as ``prevImg``
:param flow: The computed flow image; will have the same size as ``prevImg`` and type ``CV_32FC2``
:param pyrScale: Specifies the image scale (<1) to build the pyramids for each image. ``pyrScale=0.5`` means the classical pyramid, where each next layer is twice smaller than the previous
:param levels: The number of pyramid layers, including the initial image. ``levels=1`` means that no extra layers are created and only the original images are used
:param winsize: The averaging window size; The larger values increase the algorithm robustness to image noise and give more chances for fast motion detection, but yield more blurred motion field
:param iterations: The number of iterations the algorithm does at each pyramid level
:param prevImg: The first 8-bit single-channel input image
:param nextImg: The second input image of the same size and the same type as ``prevImg``
:param flow: The computed flow image; will have the same size as ``prevImg`` and type ``CV_32FC2``
:param pyrScale: Specifies the image scale (<1) to build the pyramids for each image. ``pyrScale=0.5`` means the classical pyramid, where each next layer is twice smaller than the previous
:param levels: The number of pyramid layers, including the initial image. ``levels=1`` means that no extra layers are created and only the original images are used
:param winsize: The averaging window size; The larger values increase the algorithm robustness to image noise and give more chances for fast motion detection, but yield more blurred motion field
:param iterations: The number of iterations the algorithm does at each pyramid level
:param polyN: Size of the pixel neighborhood used to find polynomial expansion in each pixel. The larger values mean that the image will be approximated with smoother surfaces, yielding more robust algorithm and more blurred motion field. Typically, ``polyN`` =5 or 7
:param polySigma: Standard deviation of the Gaussian that is used to smooth derivatives that are used as a basis for the polynomial expansion. For ``polyN=5`` you can set ``polySigma=1.1`` , for ``polyN=7`` a good value would be ``polySigma=1.5``
:param flags: The operation flags; can be a combination of the following:
* **OPTFLOW_USE_INITIAL_FLOW** Use the input ``flow`` as the initial flow approximation
* **OPTFLOW_FARNEBACK_GAUSSIAN** Use a Gaussian :math:`\texttt{winsize}\times\texttt{winsize}` filter instead of box filter of the same size for optical flow estimation. Usually, this option gives more accurate flow than with a box filter, at the cost of lower speed (and normally ``winsize`` for a Gaussian window should be set to a larger value to achieve the same level of robustness)
The function finds optical flow for each
``prevImg``
pixel using the alorithm so that
:param polyN: Size of the pixel neighborhood used to find polynomial expansion in each pixel. The larger values mean that the image will be approximated with smoother surfaces, yielding more robust algorithm and more blurred motion field. Typically, ``polyN`` =5 or 7
:param polySigma: Standard deviation of the Gaussian that is used to smooth derivatives that are used as a basis for the polynomial expansion. For ``polyN=5`` you can set ``polySigma=1.1`` , for ``polyN=7`` a good value would be ``polySigma=1.5``
:param flags: The operation flags; can be a combination of the following:
* **OPTFLOW_USE_INITIAL_FLOW** Use the input ``flow`` as the initial flow approximation
* **OPTFLOW_FARNEBACK_GAUSSIAN** Use a Gaussian :math:`\texttt{winsize}\times\texttt{winsize}` filter instead of box filter of the same size for optical flow estimation. Usually, this option gives more accurate flow than with a box filter, at the cost of lower speed (and normally ``winsize`` for a Gaussian window should be set to a larger value to achieve the same level of robustness)
The function finds optical flow for each ``prevImg`` pixel using the alorithm so that
.. math:: .. math::
\texttt{prevImg} (x,y) \sim \texttt{nextImg} ( \texttt{flow} (x,y)[0], \texttt{flow} (x,y)[1]) \texttt{prevImg} (x,y) \sim \texttt{nextImg} ( \texttt{flow} (x,y)[0], \texttt{flow} (x,y)[1])
.. index:: updateMotionHistory .. index:: updateMotionHistory
cv::updateMotionHistory cv::updateMotionHistory
----------------------- -----------------------
`id=0.684725809289 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/updateMotionHistory>`__
.. cfunction:: void updateMotionHistory( const Mat\& silhouette, Mat\& mhi, double timestamp, double duration ) .. cfunction:: void updateMotionHistory( const Mat\& silhouette, Mat\& mhi, double timestamp, double duration )
Updates the motion history image by a moving silhouette. Updates the motion history image by a moving silhouette.
:param silhouette: Silhouette mask that has non-zero pixels where the motion occurs
:param mhi: Motion history image, that is updated by the function (single-channel, 32-bit floating-point)
:param timestamp: Current time in milliseconds or other units
:param duration: Maximal duration of the motion track in the same units as ``timestamp``
:param silhouette: Silhouette mask that has non-zero pixels where the motion occurs
:param mhi: Motion history image, that is updated by the function (single-channel, 32-bit floating-point)
:param timestamp: Current time in milliseconds or other units
:param duration: Maximal duration of the motion track in the same units as ``timestamp``
The function updates the motion history image as following: The function updates the motion history image as following:
.. math:: .. math::
\texttt{mhi} (x,y)= \forkthree{\texttt{timestamp}}{if $\texttt{silhouette}(x,y) \ne 0$}{0}{if $\texttt{silhouette}(x,y) = 0$ and $\texttt{mhi} < (\texttt{timestamp} - \texttt{duration})$}{\texttt{mhi}(x,y)}{otherwise} \texttt{mhi} (x,y)= \forkthree{\texttt{timestamp}}{if $\texttt{silhouette}(x,y) \ne 0$}{0}{if $\texttt{silhouette}(x,y) = 0$ and $\texttt{mhi} < (\texttt{timestamp} - \texttt{duration})$}{\texttt{mhi}(x,y)}{otherwise}
That is, MHI pixels where motion occurs are set to the current ``timestamp`` , while the pixels where motion happened last time a long time ago are cleared.
That is, MHI pixels where motion occurs are set to the current The function, together with
``timestamp`` :func:`calcMotionGradient` and
, while the pixels where motion happened last time a long time ago are cleared. :func:`calcGlobalOrientation` , implements the motion templates technique, described in
The function, together with
:func:`calcMotionGradient`
and
:func:`calcGlobalOrientation`
, implements the motion templates technique, described in
Davis97 Davis97
and and
Bradski00 Bradski00
. .
See also the OpenCV sample See also the OpenCV sample ``motempl.c`` that demonstrates the use of all the motion template functions.
``motempl.c``
that demonstrates the use of all the motion template functions.
.. index:: calcMotionGradient .. index:: calcMotionGradient
cv::calcMotionGradient cv::calcMotionGradient
---------------------- ----------------------
`id=0.911487015982 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/calcMotionGradient>`__
.. cfunction:: void calcMotionGradient( const Mat\& mhi, Mat\& mask, Mat\& orientation, double delta1, double delta2, int apertureSize=3 ) .. cfunction:: void calcMotionGradient( const Mat\& mhi, Mat\& mask, Mat\& orientation, double delta1, double delta2, int apertureSize=3 )
Calculates the gradient orientation of a motion history image. Calculates the gradient orientation of a motion history image.
:param mhi: Motion history single-channel floating-point image
:param mask: The output mask image; will have the type ``CV_8UC1`` and the same size as ``mhi`` . Its non-zero elements will mark pixels where the motion gradient data is correct
:param orientation: The output motion gradient orientation image; will have the same type and the same size as ``mhi`` . Each pixel of it will the motion orientation in degrees, from 0 to 360.
:param delta1, delta2: The minimal and maximal allowed difference between ``mhi`` values within a pixel neighorhood. That is, the function finds the minimum ( :math:`m(x,y)` ) and maximum ( :math:`M(x,y)` ) ``mhi`` values over :math:`3 \times 3` neighborhood of each pixel and marks the motion orientation at :math:`(x, y)` as valid only if
:param mhi: Motion history single-channel floating-point image
:param mask: The output mask image; will have the type ``CV_8UC1`` and the same size as ``mhi`` . Its non-zero elements will mark pixels where the motion gradient data is correct
:param orientation: The output motion gradient orientation image; will have the same type and the same size as ``mhi`` . Each pixel of it will the motion orientation in degrees, from 0 to 360.
:param delta1, delta2: The minimal and maximal allowed difference between ``mhi`` values within a pixel neighorhood. That is, the function finds the minimum ( :math:`m(x,y)` ) and maximum ( :math:`M(x,y)` ) ``mhi`` values over :math:`3 \times 3` neighborhood of each pixel and marks the motion orientation at :math:`(x, y)` as valid only if
.. math:: .. math::
\min ( \texttt{delta1} , \texttt{delta2} ) \le M(x,y)-m(x,y) \le \max ( \texttt{delta1} , \texttt{delta2} ).
:param apertureSize: The aperture size of :func:`Sobel` operator
The function calculates the gradient orientation at each pixel
:math:`(x, y)`
as:
\min ( \texttt{delta1} , \texttt{delta2} ) \le M(x,y)-m(x,y) \le \max ( \texttt{delta1} , \texttt{delta2} ).
:param apertureSize: The aperture size of :func:`Sobel` operator
The function calculates the gradient orientation at each pixel
:math:`(x, y)` as:
.. math:: .. math::
\texttt{orientation} (x,y)= \arctan{\frac{d\texttt{mhi}/dy}{d\texttt{mhi}/dx}} \texttt{orientation} (x,y)= \arctan{\frac{d\texttt{mhi}/dy}{d\texttt{mhi}/dx}}
(in fact,
:func:`fastArctan`
and
:func:`phase`
are used, so that the computed angle is measured in degrees and covers the full range 0..360). Also, the
``mask``
is filled to indicate pixels where the computed angle is valid.
(in fact,
:func:`fastArctan` and
:func:`phase` are used, so that the computed angle is measured in degrees and covers the full range 0..360). Also, the ``mask`` is filled to indicate pixels where the computed angle is valid.
.. index:: calcGlobalOrientation .. index:: calcGlobalOrientation
cv::calcGlobalOrientation cv::calcGlobalOrientation
------------------------- -------------------------
`id=0.785441857219 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/calcGlobalOrientation>`__
.. cfunction:: double calcGlobalOrientation( const Mat\& orientation, const Mat\& mask, const Mat\& mhi, double timestamp, double duration ) .. cfunction:: double calcGlobalOrientation( const Mat\& orientation, const Mat\& mask, const Mat\& mhi, double timestamp, double duration )
Calculates the global motion orientation in some selected region. Calculates the global motion orientation in some selected region.
:param orientation: Motion gradient orientation image, calculated by the function :func:`calcMotionGradient`
:param mask: Mask image. It may be a conjunction of a valid gradient mask, also calculated by :func:`calcMotionGradient` , and the mask of the region, whose direction needs to be calculated
:param mhi: The motion history image, calculated by :func:`updateMotionHistory`
:param timestamp: The timestamp passed to :func:`updateMotionHistory`
:param duration: Maximal duration of motion track in milliseconds, passed to :func:`updateMotionHistory`
:param orientation: Motion gradient orientation image, calculated by the function :func:`calcMotionGradient`
:param mask: Mask image. It may be a conjunction of a valid gradient mask, also calculated by :func:`calcMotionGradient` , and the mask of the region, whose direction needs to be calculated
:param mhi: The motion history image, calculated by :func:`updateMotionHistory`
:param timestamp: The timestamp passed to :func:`updateMotionHistory`
:param duration: Maximal duration of motion track in milliseconds, passed to :func:`updateMotionHistory`
The function calculates the average The function calculates the average
motion direction in the selected region and returns the angle between motion direction in the selected region and returns the angle between
0 degrees and 360 degrees. The average direction is computed from 0 degrees and 360 degrees. The average direction is computed from
the weighted orientation histogram, where a recent motion has larger the weighted orientation histogram, where a recent motion has larger
weight and the motion occurred in the past has smaller weight, as recorded in weight and the motion occurred in the past has smaller weight, as recorded in ``mhi`` .
``mhi``
.
.. index:: CamShift .. index:: CamShift
cv::CamShift cv::CamShift
------------ ------------
`id=0.364212510583 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/CamShift>`__
.. cfunction:: RotatedRect CamShift( const Mat\& probImage, Rect\& window, TermCriteria criteria ) .. cfunction:: RotatedRect CamShift( const Mat\& probImage, Rect\& window, TermCriteria criteria )
Finds the object center, size, and orientation Finds the object center, size, and orientation
:param probImage: Back projection of the object histogram; see :func:`calcBackProject`
:param window: Initial search window
:param criteria: Stop criteria for the underlying :func:`meanShift`
:param probImage: Back projection of the object histogram; see :func:`calcBackProject`
:param window: Initial search window
:param criteria: Stop criteria for the underlying :func:`meanShift`
The function implements the CAMSHIFT object tracking algrorithm The function implements the CAMSHIFT object tracking algrorithm
Bradski98 Bradski98
. .
First, it finds an object center using First, it finds an object center using
:func:`meanShift` :func:`meanShift` and then adjust the window size and finds the optimal rotation. The function returns the rotated rectangle structure that includes the object position, size and the orientation. The next position of the search window can be obtained with ``RotatedRect::boundingRect()`` .
and then adjust the window size and finds the optimal rotation. The function returns the rotated rectangle structure that includes the object position, size and the orientation. The next position of the search window can be obtained with
``RotatedRect::boundingRect()``
.
See the OpenCV sample
``camshiftdemo.c``
that tracks colored objects.
See the OpenCV sample ``camshiftdemo.c`` that tracks colored objects.
.. index:: meanShift .. index:: meanShift
cv::meanShift cv::meanShift
------------- -------------
`id=0.437046716762 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/meanShift>`__
.. cfunction:: int meanShift( const Mat\& probImage, Rect\& window, TermCriteria criteria ) .. cfunction:: int meanShift( const Mat\& probImage, Rect\& window, TermCriteria criteria )
Finds the object on a back projection image. Finds the object on a back projection image.
:param probImage: Back projection of the object histogram; see :func:`calcBackProject`
:param window: Initial search window
:param criteria: The stop criteria for the iterative search algorithm
The function implements iterative object search algorithm. It takes the object back projection on input and the initial position. The mass center in ``window`` of the back projection image is computed and the search window center shifts to the mass center. The procedure is repeated until the specified number of iterations ``criteria.maxCount`` is done or until the window center shifts by less than ``criteria.epsilon`` . The algorithm is used inside
:func:`CamShift` and, unlike
:func:`CamShift` , the search window size or orientation do not change during the search. You can simply pass the output of
:param probImage: Back projection of the object histogram; see :func:`calcBackProject` :func:`calcBackProject` to this function, but better results can be obtained if you pre-filter the back projection and remove the noise (e.g. by retrieving connected components with
:func:`findContours` , throwing away contours with small area (
:func:`contourArea` ) and rendering the remaining contours with
:param window: Initial search window :func:`drawContours` )
:param criteria: The stop criteria for the iterative search algorithm
The function implements iterative object search algorithm. It takes the object back projection on input and the initial position. The mass center in
``window``
of the back projection image is computed and the search window center shifts to the mass center. The procedure is repeated until the specified number of iterations
``criteria.maxCount``
is done or until the window center shifts by less than
``criteria.epsilon``
. The algorithm is used inside
:func:`CamShift`
and, unlike
:func:`CamShift`
, the search window size or orientation do not change during the search. You can simply pass the output of
:func:`calcBackProject`
to this function, but better results can be obtained if you pre-filter the back projection and remove the noise (e.g. by retrieving connected components with
:func:`findContours`
, throwing away contours with small area (
:func:`contourArea`
) and rendering the remaining contours with
:func:`drawContours`
)
.. index:: KalmanFilter .. index:: KalmanFilter
@ -409,22 +203,10 @@ to this function, but better results can be obtained if you pre-filter the back
KalmanFilter KalmanFilter
------------ ------------
`id=0.4483617174 Comments from the Wiki <http://opencv.willowgarage.com/wiki/documentation/cpp/video/KalmanFilter>`__
.. ctype:: KalmanFilter .. ctype:: KalmanFilter
Kalman filter class ::
Kalman filter class
::
class KalmanFilter class KalmanFilter
{ {
public: public:
@ -434,9 +216,9 @@ Kalman filter class
// predicts statePre from statePost // predicts statePre from statePost
const Mat& predict(const Mat& control=Mat()); const Mat& predict(const Mat& control=Mat());
// corrects statePre based on the input measurement vector // corrects statePre based on the input measurement vector
// and stores the result to statePost. // and stores the result to statePost.
const Mat& correct(const Mat& measurement); const Mat& correct(const Mat& measurement);
Mat statePre; // predicted state (x'(k)): Mat statePre; // predicted state (x'(k)):
// x(k)=A*x(k-1)+B*u(k) // x(k)=A*x(k-1)+B*u(k)
Mat statePost; // corrected state (x(k)): Mat statePost; // corrected state (x(k)):
@ -455,17 +237,8 @@ Kalman filter class
// P(k)=(I-K(k)*H)*P'(k) // P(k)=(I-K(k)*H)*P'(k)
... ...
}; };
.. ..
The class implements standard Kalman filter The class implements standard Kalman filter
http://en.wikipedia.org/wiki/Kalman_filter http://en.wikipedia.org/wiki/Kalman_filter
. However, you can modify . However, you can modify ``transitionMatrix``,``controlMatrix`` and ``measurementMatrix`` to get the extended Kalman filter functionality. See the OpenCV sample ``kalman.c``
``transitionMatrix``
,
``controlMatrix``
and
``measurementMatrix``
to get the extended Kalman filter functionality. See the OpenCV sample
``kalman.c``

6
modules/video/doc/video.rst
View File

@ -1,6 +1,6 @@
************** *********************
Video Analysis video. Video Analysis
************** *********************
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2