Skip to content

O
opencv
Commit bb8198ab authored by Vadim Pisarevsky's avatar Vadim Pisarevsky
Browse files
Options

continued cleaning up the docs and fixing hyperlinks (".. index:: <name>" and… 

continued cleaning up the docs and fixing hyperlinks (".. index:: <name>" and ".. _<name>:" are not needed anymore)
parent 6cc33614
Hide whitespace changes
Inline Side-by-side
Showing with 574 additions and 1132 deletions
modules/calib3d/doc/camera_calibration_and_3d_reconstruction.rst
View file @ bb8198ab
......@@ -103,8 +103,6 @@ The functions below use the above model to do the following:
.. index:: calibrateCamera
.. _calibrateCamera:
calibrateCamera
---------------
......@@ -186,8 +184,6 @@ See Also:
.. index:: calibrationMatrixValues
.. _calibrationMatrixValues:
calibrationMatrixValues
-----------------------
.. cpp:function:: void calibrationMatrixValues( InputArray cameraMatrix, Size imageSize, double apertureWidth, double apertureHeight, double& fovx, double& fovy, double& focalLength, Point2d& principalPoint, double& aspectRatio )
......@@ -216,8 +212,6 @@ The function computes various useful camera characteristics from the previously
.. index:: composeRT
.. _composeRT:
composeRT
-------------
......@@ -253,8 +247,6 @@ The functions are used inside :ref:`stereoCalibrate` but can also be used in you
.. index:: computeCorrespondEpilines
.. _computeCorrespondEpilines:
computeCorrespondEpilines
-----------------------------
.. cpp:function:: void computeCorrespondEpilines( InputArray points, int whichImage, InputArray F, OutputArray lines )
......@@ -374,8 +366,6 @@ The function is based on
.. index:: drawChessboardCorners
.. _drawChessboardCorners:
drawChessboardCorners
-------------------------
.. cpp:function:: void drawChessboardCorners( InputOutputArray image, Size patternSize, InputArray corners, bool patternWasFound )
......@@ -384,18 +374,16 @@ drawChessboardCorners
:param image: Destination image. It must be an 8-bit color image.
:param patternSize: Number of inner corners per a chessboard row and column. ``(patternSize = cv::Size(points_per_row,points_per_column) = cv::Size(rows,columns) )``
:param patternSize: Number of inner corners per a chessboard row and column ``(patternSize = cv::Size(points_per_row,points_per_column))``
:param corners: Array of detected corners. This should be an output from ``findChessboardCorners`` wrapped in ``cv::Mat()`` .
:param corners: Array of detected corners, the output of ``findChessboardCorners``.
:param patternWasFound: Parameter indicating whether the complete board was found or not. The return value :ref:`FindChessboardCorners` may be passed here.
:param patternWasFound: Parameter indicating whether the complete board was found or not. The return value of :cpp:func:`findChessboardCorners` should be passed here.
The function draws individual chessboard corners detected either as red circles if the board was not found, or as colored corners connected with lines if the board was found.
.. index:: findChessboardCorners
.. _findChessboardCorners:
findChessboardCorners
-------------------------
.. cpp:function:: bool findChessboardCorners( InputArray image, Size patternSize, OutputArray corners, int flags=CV_CALIB_CB_ADAPTIVE_THRESH+CV_CALIB_CB_NORMALIZE_IMAGE )
......@@ -454,8 +442,6 @@ The function requires white space (like a square-thick border, the wider the bet
.. index:: findCirclesGrid
.. _findCirclesGrid:
findCirclesGrid
-------------------
.. cpp:function:: bool findCirclesGrid( InputArray image, Size patternSize, OutputArray centers, int flags=CALIB_CB_SYMMETRIC_GRID, const Ptr<FeatureDetector> &blobDetector = new SimpleBlobDetector() )
......@@ -501,8 +487,6 @@ The function requires white space (like a square-thick border, the wider the bet
.. index:: solvePnP
.. _solvePnP:
solvePnP
------------
.. cpp:function:: void solvePnP( InputArray objectPoints, InputArray imagePoints, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess=false )
......@@ -528,8 +512,6 @@ The function estimates the object pose given a set of object points, their corre
.. index:: solvePnPRansac
.. _solvePnPRansac:
solvePnPRansac
------------------
......@@ -564,8 +546,6 @@ The function estimates an object pose given a set of object points, their corres
.. index:: findFundamentalMat
.. _findFundamentalMat:
findFundamentalMat
----------------------
.. cpp:function:: Mat findFundamentalMat( InputArray points1, InputArray points2, int method=FM_RANSAC, double param1=3., double param2=0.99, OutputArray mask=noArray() )
......@@ -755,8 +735,6 @@ the optimal new camera matrix based on the free scaling parameter. By varying t
.. index:: initCameraMatrix2D
.. _initCameraMatrix2D:
initCameraMatrix2D
----------------------
.. cpp:function:: Mat initCameraMatrix2D( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints, Size imageSize, double aspectRatio=1.)
......@@ -776,8 +754,6 @@ Currently, the function only supports planar calibration patterns, which are pat
.. index:: matMulDeriv
.. _matMulDeriv:
matMulDeriv
---------------
......@@ -799,8 +775,6 @@ The function computes partial derivatives of the elements of the matrix product
.. index:: projectPoints
.. _projectPoints:
projectPoints
-----------------
......@@ -843,8 +817,6 @@ By setting ``rvec=tvec=(0,0,0)`` or by setting ``cameraMatrix`` to a 3x3 identi
.. index:: reprojectImageTo3D
.. _reprojectImageTo3D:
reprojectImageTo3D
----------------------
......@@ -903,8 +875,6 @@ that could be used in OpenGL.
.. index:: Rodrigues
.. _Rodrigues:
Rodrigues
-------------
.. cpp:function:: void Rodrigues(InputArray src, OutputArray dst, OutputArray jacobian=noArray())
......@@ -936,8 +906,6 @@ used in the global 3D geometry optimization procedures like
.. index:: StereoBM
.. _StereoBM:
StereoBM
--------
.. c:type:: StereoBM
......@@ -973,8 +941,6 @@ The class is a C++ wrapper for the associated functions. In particular, ``Stereo
.. index:: StereoBM::operator ()
.. _StereoBM::operator ():
StereoBM::operator ()
-----------------------
......@@ -995,8 +961,6 @@ The method executes the BM algorithm on a rectified stereo pair. See the ``stere
.. index:: StereoSGBM
.. _StereoSGBM:
StereoSGBM
----------
......@@ -1042,8 +1006,6 @@ The class implements the modified H. Hirschmuller algorithm HH08 that differs fr
.. index:: StereoSGBM::StereoSGBM
.. _StereoSGBM::StereoSGBM:
StereoSGBM::StereoSGBM
--------------------------
.. cpp:function:: StereoSGBM::StereoSGBM()
......@@ -1076,8 +1038,6 @@ The first constructor initializes ``StereoSGBM`` with all the default parameters
.. index:: StereoSGBM::operator ()
.. _StereoSGBM::operator ():
StereoSGBM::operator ()
-----------------------
......@@ -1099,8 +1059,6 @@ The method is not constant, so you should not use the same ``StereoSGBM`` instan
.. index:: stereoCalibrate
.. _stereoCalibrate:
stereoCalibrate
-------------------
.. cpp:function:: double stereoCalibrate( InputArrayOfArrays objectPoints, InputArrayOfArrays imagePoints1, InputArrayOfArrays imagePoints2, InputOutputArray cameraMatrix1, InputOutputArray distCoeffs1, InputOutputArray cameraMatrix2, InputOutputArray distCoeffs2, Size imageSize, OutputArray R, OutputArray T, OutputArray E, OutputArray F, TermCriteria term_crit = TermCriteria(TermCriteria::COUNT+ TermCriteria::EPS, 30, 1e-6), int flags=CALIB_FIX_INTRINSIC )
......@@ -1265,8 +1223,6 @@ See below the screenshot from the ``stereo_calib.cpp`` sample. Some red horizont
.. index:: stereoRectifyUncalibrated
.. _stereoRectifyUncalibrated:
stereoRectifyUncalibrated
-----------------------------
.. cpp:function:: bool stereoRectifyUncalibrated( InputArray points1, InputArray points2, InputArray F, Size imgSize, OutputArray H1, OutputArray H2, double threshold=5 )
......
modules/core/doc/basic_structures.rst
View file @ bb8198ab
......@@ -3,42 +3,12 @@ Basic Structures
.. highlight:: cpp
.. index:: _DataType
.. _DataType:
DataType
--------
.. cpp:class:: DataType
Template "trait" class for other OpenCV primitive data types ::
template<typename _Tp> class DataType
{
// value_type is always a synonym to _Tp.
typedef _Tp value_type;
// intermediate type used for operations on _Tp.
// it is int for uchar, signed char, unsigned short, signed short, and int,
// float for float, double for double, ...
typedef <...> work_type;
// in the case of multi-channel data, it is the data type of each channel
typedef <...> channel_type;
enum
{
// CV_8U ... CV_64F
depth = DataDepth<channel_type>::value,
// 1 ...
channels = <...>,
// '1u', '4i', '3f', '2d' etc.
fmt=<...>,
// CV_8UC3, CV_32FC2 ...
type = CV_MAKETYPE(depth, channels)
};
};
The template class ``DataType`` is a descriptive class for OpenCV primitive data types and other types that comply with the following definition. A primitive OpenCV data type is one of ``unsigned char``, ``bool``, ``signed char``, ``unsigned short``, ``signed short``, ``int``, ``float``, ``double`` or a tuple of values of one of these types, where all the values in the tuple have the same type. Any primitive type from the list can be defined by an identifier in the form ``CV_<bit-depth>{U|S|F}C(<number_of_channels>)``, for example: ``uchar`` ~ ``CV_8UC1``, 3-element floating-point tuple ~ ``CV_32FC3``, and so on. A universal OpenCV structure that is able to store a single instance of such a primitive data type is
- Template "trait" class for other OpenCV primitive data types. A primitive OpenCV data type is one of ``unsigned char``, ``bool``, ``signed char``, ``unsigned short``, ``signed short``, ``int``, ``float``, ``double`` or a tuple of values of one of these types, where all the values in the tuple have the same type. Any primitive type from the list can be defined by an identifier in the form ``CV_<bit-depth>{U|S|F}C(<number_of_channels>)``, for example: ``uchar`` ~ ``CV_8UC1``, 3-element floating-point tuple ~ ``CV_32FC3``, and so on. A universal OpenCV structure that is able to store a single instance of such a primitive data type is
:ref:`Vec`. Multiple instances of such a type can be stored in a ``std::vector``, ``Mat``, ``Mat_``, ``SparseMat``, ``SparseMat_``, or any other container that is able to store ``Vec`` instances.
The ``DataType`` class is basically used to provide a description of such primitive data types without adding any fields or methods to the corresponding classes (and it is actually impossible to add anything to primitive C/C++ data types). This technique is known in C++ as class traits. It is not ``DataType`` itself that is used but its specialized versions, such as: ::
......@@ -75,44 +45,12 @@ The main purpose of this class is to convert compilation-time type information t
So, such traits are used to tell OpenCV which data type you are working with, even if such a type is not native to OpenCV. For example, the matrix ``B`` intialization above is compiled because OpenCV defines the proper specialized template class ``DataType<complex<_Tp> >`` . This mechanism is also useful (and used in OpenCV this way) for generic algorithms implementations.
.. index:: Point\_
Point\_
-------
.. cpp:class:: Point_
Template class for 2D points ::
template<typename _Tp> class Point_
{
public:
typedef _Tp value_type;
Point_();
Point_(_Tp _x, _Tp _y);
Point_(const Point_& pt);
Point_(const CvPoint& pt);
Point_(const CvPoint2D32f& pt);
Point_(const Size_<_Tp>& sz);
Point_(const Vec<_Tp, 2>& v);
Point_& operator = (const Point_& pt);
template<typename _Tp2> operator Point_<_Tp2>() const;
operator CvPoint() const;
operator CvPoint2D32f() const;
operator Vec<_Tp, 2>() const;
// computes dot-product (this->x*pt.x + this->y*pt.y)
_Tp dot(const Point_& pt) const;
// computes dot-product using double-precision arithmetics
double ddot(const Point_& pt) const;
// returns true if the point is inside the rectangle "r".
bool inside(const Rect_<_Tp>& r) const;
_Tp x, y;
};
The class represents a 2D point specified by its coordinates
Template class for 2D points, specified by its coordinates
:math:`x` and
:math:`y` .
An instance of the class is interchangeable with C structures, ``CvPoint`` and ``CvPoint2D32f`` . There is also a cast operator to convert point coordinates to the specified type. The conversion from floating-point coordinates to integer coordinates is done by rounding. Commonly, the conversion uses this
......@@ -142,39 +80,12 @@ Example: ::
Point pt = (a + b)*10.f;
cout << pt.x << ", " << pt.y << endl;
.. index:: Point3\_
Point3\_
--------
.. cpp:class:: Point3_
Template class for 3D points ::
template<typename _Tp> class Point3_
{
public:
typedef _Tp value_type;
Point3_();
Point3_(_Tp _x, _Tp _y, _Tp _z);
Point3_(const Point3_& pt);
explicit Point3_(const Point_<_Tp>& pt);
Point3_(const CvPoint3D32f& pt);
Point3_(const Vec<_Tp, 3>& v);
Point3_& operator = (const Point3_& pt);
template<typename _Tp2> operator Point3_<_Tp2>() const;
operator CvPoint3D32f() const;
operator Vec<_Tp, 3>() const;
_Tp dot(const Point3_& pt) const;
double ddot(const Point3_& pt) const;
_Tp x, y, z;
};
The class represents a 3D point specified by its coordinates
Template class for 3D points, specified by its coordinates
:math:`x`,
:math:`y` and
:math:`z` .
......@@ -186,40 +97,12 @@ The following ``Point3_<>`` aliases are available: ::
typedef Point3_<float> Point3f;
typedef Point3_<double> Point3d;
.. index:: Size\_
Size\_
------
.. cpp:class:: Size_
Template class for specfying an image or rectangle size ::
template<typename _Tp> class Size_
{
public:
typedef _Tp value_type;
Size_();
Size_(_Tp _width, _Tp _height);
Size_(const Size_& sz);
Size_(const CvSize& sz);
Size_(const CvSize2D32f& sz);
Size_(const Point_<_Tp>& pt);
Size_& operator = (const Size_& sz);
_Tp area() const;
operator Size_<int>() const;
operator Size_<float>() const;
operator Size_<double>() const;
operator CvSize() const;
operator CvSize2D32f() const;
_Tp width, height;
};
The class ``Size_`` is similar to ``Point_`` except that the two members are called ``width`` and ``height`` instead of ``x`` and ``y`` . The structure can be converted to and from the old OpenCV structures
Template class for specfying size of an image or rectangle. The class includes two members are called ``width`` and ``height``. The structure can be converted to and from the old OpenCV structures
``CvSize`` and ``CvSize2D32f`` . The same set of arithmetic and comparison operations as for ``Point_`` is available.
OpenCV defines the following ``Size_<>`` aliases: ::
......@@ -228,56 +111,15 @@ OpenCV defines the following ``Size_<>`` aliases: ::
typedef Size2i Size;
typedef Size_<float> Size2f;
.. index:: Rect\_
Rect\_
------
.. cpp:class:: Rect_
Template class for 2D rectangles ::
template<typename _Tp> class Rect_
{
public:
typedef _Tp value_type;
Rect_();
Rect_(_Tp _x, _Tp _y, _Tp _width, _Tp _height);
Rect_(const Rect_& r);
Rect_(const CvRect& r);
// (x, y) <- org, (width, height) <- sz
Rect_(const Point_<_Tp>& org, const Size_<_Tp>& sz);
// (x, y) <- min(pt1, pt2), (width, height) <- max(pt1, pt2) - (x, y)
Rect_(const Point_<_Tp>& pt1, const Point_<_Tp>& pt2);
Rect_& operator = ( const Rect_& r );
// returns Point_<_Tp>(x, y)
Point_<_Tp> tl() const;
// returns Point_<_Tp>(x+width, y+height)
Point_<_Tp> br() const;
// returns Size_<_Tp>(width, height)
Size_<_Tp> size() const;
// returns width*height
_Tp area() const;
operator Rect_<int>() const;
operator Rect_<float>() const;
operator Rect_<double>() const;
operator CvRect() const;
// x <= pt.x && pt.x < x + width &&
// y <= pt.y && pt.y < y + height ? true : false
bool contains(const Point_<_Tp>& pt) const;
_Tp x, y, width, height;
};
The rectangle is described with the following parameters:
Template class for 2D rectangles, described by the following parameters::
* Coordinates of the top-left corner. This is a default interpretation of ``Rect_::x`` and ``Rect_::y`` in OpenCV. Though, in your algorithms you may count ``x`` and ``y`` from the bottom-left corner.
* Rectangle width and height.
* Coordinates of the top-left corner. This is a default interpretation of ``Rect_::x`` and ``Rect_::y`` in OpenCV. Though, in your algorithms you may count ``x`` and ``y`` from the bottom-left corner.
* Rectangle width and height.
OpenCV typically assumes that the top and left boundary of the rectangle are inclusive, while the right and bottom boundaries are not. For example, the method ``Rect_::contains`` returns ``true`` if
......@@ -328,100 +170,30 @@ For your convenience, the ``Rect_<>`` alias is available: ::
typedef Rect_<int> Rect;
.. index:: _RotatedRect
.. _RotatedRect:
RotatedRect
-----------
.. cpp:class:: RotatedRect
Template class for rotated rectangles ::
class RotatedRect
{
public:
// constructors
RotatedRect();
RotatedRect(const Point2f& _center, const Size2f& _size, float _angle);
RotatedRect(const CvBox2D& box);
// returns minimal up-right rectangle that contains the rotated rectangle
Rect boundingRect() const;
// backward conversion to CvBox2D
operator CvBox2D() const;
// mass center of the rectangle
Point2f center;
// size
Size2f size;
// rotation angle in degrees
float angle;
};
Template class for rotated rectangles that are specified by the center, size and the rotation angle in degrees.
The class ``RotatedRect`` replaces the old ``CvBox2D`` and is fully compatible with it.
.. index:: TermCriteria
TermCriteria
------------
.. cpp:class:: TermCriteria
Template class defining termination criteria for iterative algorithms ::
class TermCriteria
{
public:
enum { COUNT=1, MAX_ITER=COUNT, EPS=2 };
// constructors
TermCriteria();
// type can be MAX_ITER, EPS or MAX_ITER+EPS.
// type = MAX_ITER means that only the number of iterations does matter;
// type = EPS means that only the required precision (epsilon) does matter
// (though, most algorithms limit the number of iterations anyway)
// type = MAX_ITER + EPS means that algorithm stops when
// either the specified number of iterations is made,
// or when the specified accuracy is achieved - whatever happens first.
TermCriteria(int _type, int _maxCount, double _epsilon);
TermCriteria(const CvTermCriteria& criteria);
operator CvTermCriteria() const;
int type;
int maxCount;
double epsilon;
};
The class ``TermCriteria`` replaces the old ``CvTermCriteria`` and is fully compatible with it.
.. index:: Matx
.. _Matx:
Template class defining termination criteria for iterative algorithms
Matx
----
.. cpp:class:: Matx
Template class for small matrices ::
template<typename T, int m, int n> class Matx
{
public:
typedef T value_type;
enum { depth = DataDepth<T>::value, channels = m*n,
type = CV_MAKETYPE(depth, channels) };
// various methods
...
Tp val[m*n];
};
Template class for small matrices, whose type and size are known at compilation time.: ::
template<typename _Tp, int m, int n> class Matx {...};
typedef Matx<float, 1, 2> Matx12f;
typedef Matx<double, 1, 2> Matx12d;
...
......@@ -439,10 +211,8 @@ Template class for small matrices ::
...
typedef Matx<float, 6, 6> Matx66f;
typedef Matx<double, 6, 6> Matx66d;
The class represents small matrices whose type and size are known at compilation time. If you need a more flexible type, use
:cpp:class:`Mat` . The elements of the matrix ``M`` are accessible using the ``M(i,j)`` notation. Most of the common matrix operations (see also
If you need a more flexible type, use :cpp:class:`Mat` . The elements of the matrix ``M`` are accessible using the ``M(i,j)`` notation. Most of the common matrix operations (see also
:ref:`MatrixExpressions` ) are available. To do an operation on ``Matx`` that is not implemented, you can easily convert the matrix to
:cpp:class:`Mat` and backwards. ::
......@@ -451,27 +221,16 @@ The class represents small matrices whose type and size are known at compilation
7, 8, 9);
cout << sum(Mat(m*m.t())) << endl;
.. index:: Vec
.. _Vec:
Vec
---
.. cpp:class:: Vec
Template class for short numerical vectors ::
template<typename T, int cn> class Vec : public Matx<T, cn, 1>
{
public:
typedef T value_type;
enum { depth = DataDepth<T>::value, channels = cn,
type = CV_MAKETYPE(depth, channels) };
// various methods ...
};
Template class for short numerical vectors, a partial case of :cpp:class:`Matx`: ::
template<typename _Tp, int n> class Vec : public Matx<_Tp, n, 1> {...};
typedef Vec<uchar, 2> Vec2b;
typedef Vec<uchar, 3> Vec3b;
typedef Vec<uchar, 4> Vec4b;
......@@ -493,79 +252,51 @@ Template class for short numerical vectors ::
typedef Vec<double, 3> Vec3d;
typedef Vec<double, 4> Vec4d;
typedef Vec<double, 6> Vec6d;
It is possible to convert ``Vec<T,2>`` to/from ``Point_``, ``Vec<T,3>`` to/from ``Point3_`` , and ``Vec<T,4>`` to ``CvScalar`` or :ref:`Scalar`. The elements of ``Vec`` are accessed using ``operator[]``.
``Vec`` is a partial case of ``Matx`` . It is possible to convert ``Vec<T,2>`` to/from ``Point_``, ``Vec<T,3>`` to/from ``Point3_`` , and ``Vec<T,4>`` to ``CvScalar`` or :ref:`Scalar`. The elements of ``Vec`` are accessed using ``operator[]``. All the expected vector operations are implemented too:
*
:math:`\texttt{v1} = \texttt{v2} \pm \texttt{v3}`, :math:`\texttt{v1} = \texttt{v2} * \alpha`, :math:`\texttt{v1} = \alpha * \texttt{v2}` in addition to the corresponding augmenting operations. Note that these operations apply
to each computed vector component.
* ``v1 == v2, v1 != v2`` * ``norm(v1)`` (:math:`L_2`-norm)
The ``Vec`` class is commonly used to describe pixel types of multi-channel arrays. See
:ref:`Mat_` for details.
All the expected vector operations are implemented too:
.. index:: Scalar
* ``v1 = v2 + v3``
* ``v1 = v2 - v3``
* ``v1 = v2 * scale``
* ``v1 = scale * v2``
* ``v1 = -v2``
* ``v1 += v2`` and other augmenting operations.
* ``v1 == v2, v1 != v2``
* ``norm(v1)`` (euclidean norm)
.. _Scalar:
The ``Vec`` class is commonly used to describe pixel types of multi-channel arrays. See :cpp:class:`Mat` for details.
Scalar\_
--------
.. cpp:class:: Scalar_
Template class for a 4-element vector ::
template<typename _Tp> class Scalar_ : public Vec<_Tp, 4>
{
public:
Scalar_();
Scalar_(_Tp v0, _Tp v1, _Tp v2=0, _Tp v3=0);
Scalar_(const CvScalar& s);
Scalar_(_Tp v0);
static Scalar_<_Tp> all(_Tp v0);
operator CvScalar() const;
template<typename T2> operator Scalar_<T2>() const;
Scalar_<_Tp> mul(const Scalar_<_Tp>& t, double scale=1 ) const;
template<typename T2> void convertTo(T2* buf, int channels, int unroll_to=0) const;
};
Template class for a 4-element vector, derived from Vec ::
template<typename _Tp> class Scalar_ : public Vec<_Tp, 4> { ... };
typedef Scalar_<double> Scalar;
The template class ``Scalar_`` and its double-precision instantiation ``Scalar`` represent a 4-element vector. Being derived from ``Vec<_Tp, 4>`` , they can be used as typical 4-element vectors. In addition, they can be converted to/from ``CvScalar`` . The type ``Scalar`` is widely used in OpenCV for passing pixel values. It is a drop-in replacement for
``CvScalar`` that was used for the same purpose in the earlier versions of OpenCV.
.. index:: Range
.. _Range:
Being derived from ``Vec<_Tp, 4>`` , ``Scalar_`` and ``Scalar`` can be used just as typical 4-element vectors. In addition, they can be converted to/from ``CvScalar`` . The type ``Scalar`` is widely used in OpenCV for passing pixel values.
Range
-----
.. cpp:class:: Range
Template class specifying a continuous subsequence (slice) of a sequence ::
Template class specifying a continuous subsequence (slice) of a sequence. ::
class Range
{
public:
Range();
Range(int _start, int _end);
Range(const CvSlice& slice);
int size() const;
bool empty() const;
static Range all();
operator CvSlice() const;
...
int start, end;
};
The class is used to specify a row or a column span in a matrix (
:ref:`Mat` ) and for many other purposes. ``Range(a,b)`` is basically the same as ``a:b`` in Matlab or ``a..b`` in Python. As in Python, ``start`` is an inclusive left boundary of the range and ``end`` is an exclusive right boundary of the range. Such a half-opened interval is usually denoted as
:cpp:class:`Mat` ) and for many other purposes. ``Range(a,b)`` is basically the same as ``a:b`` in Matlab or ``a..b`` in Python. As in Python, ``start`` is an inclusive left boundary of the range and ``end`` is an exclusive right boundary of the range. Such a half-opened interval is usually denoted as
:math:`[start,end)` .
The static method ``Range::all()`` returns a special variable that means "the whole sequence" or "the whole range", just like " ``:`` " in Matlab or " ``...`` " in Python. All the methods and functions in OpenCV that take ``Range`` support this special ``Range::all()`` value. But, of course, in case of your own custom processing, you will probably have to check and handle it explicitly: ::
......@@ -581,10 +312,6 @@ The static method ``Range::all()`` returns a special variable that means "the wh
}
.. index:: Ptr
.. _Ptr:
Ptr
---
......@@ -1870,10 +1597,6 @@ Mat::type
The method returns a matrix element type. This is an id, compatible with the ``CvMat`` type system, like ``CV_16SC3`` or 16-bit signed 3-channel array, and so on.
.. index:: Mat::depth
.. _Mat::depth:
Mat::depth
--------------
.. cpp:function:: int Mat::depth() const
......@@ -1896,10 +1619,6 @@ The method returns the matrix element depth id (the type of each individual chan
* ``CV_64F`` - 64-bit floating-point numbers ( ``-DBL_MAX..DBL_MAX, INF, NAN`` )
.. index:: Mat::channels
.. _Mat::channels:
Mat::channels
-----------------
.. cpp:function:: int Mat::channels() const
......@@ -1908,10 +1627,6 @@ Mat::channels
The method returns the number of matrix channels.
.. index:: Mat::step1
.. _Mat::step1:
Mat::step1
--------------
.. cpp:function:: size_t Mat::step1() const
......@@ -1921,8 +1636,6 @@ Mat::step1
The method returns a matrix step divided by
:cpp:func:`Mat::elemSize1()` . It can be useful to quickly access an arbitrary matrix element.
.. index:: Mat::size
Mat::size
-------------
.. cpp:function:: Size Mat::size() const
......@@ -1931,10 +1644,6 @@ Mat::size
The method returns a matrix size: ``Size(cols, rows)`` .
.. index:: Mat::empty
.. _Mat::empty:
Mat::empty
--------------
.. cpp:function:: bool Mat::empty() const
......@@ -1943,10 +1652,6 @@ Mat::empty
The method returns ``true`` if ``Mat::total()`` is 0 or if ``Mat::data`` is NULL. Because of ``pop_back()`` and ``resize()`` methods ``M.total() == 0`` does not imply that ``M.data == NULL`` .
.. index:: Mat::ptr
.. _Mat::ptr:
Mat::ptr
------------
.. cpp:function:: uchar* Mat::ptr(int i=0)
......@@ -1964,10 +1669,6 @@ Mat::ptr
The methods return ``uchar*`` or typed pointer to the specified matrix row. See the sample in
:cpp:func:`Mat::isContinuous` () to know how to use these methods.
.. index:: Mat::at
.. _Mat::at:
Mat::at
-----------
.. cpp:function:: template<typename T> T& Mat::at(int i) const
......@@ -2010,10 +1711,6 @@ Here is an example of initialization of a Hilbert matrix: ::
H.at<double>(i,j)=1./(i+j+1);
.. index:: Mat::begin
.. _Mat::begin:
Mat::begin
--------------
.. cpp:function:: template<typename _Tp> MatIterator_<_Tp> Mat::begin() template<typename _Tp> MatConstIterator_<_Tp> Mat::begin() const
......@@ -2052,10 +1749,6 @@ The methods return the matrix read-only or read-write iterators. The use of matr
}
.. index:: Mat::end
.. _Mat::end:
Mat::end
------------
.. cpp:function:: template<typename _Tp> MatIterator_<_Tp> Mat::end()
......@@ -2114,8 +1807,6 @@ To use ``Mat_`` for multi-channel images/matrices, pass ``Vec`` as a ``Mat_`` pa
img(i,j)[2] ^= (uchar)(i ^ j);
.. _NAryMatIterator:
NAryMatIterator
---------------
......@@ -2186,8 +1877,6 @@ Here is an example of how you can compute a normalized and thresholded 3D color
}
.. index:: SparseMat
SparseMat
---------
......@@ -2469,8 +2158,6 @@ The class ``SparseMat`` represents multi-dimensional sparse numerical arrays. Su
..
.. index:: SparseMat\_
SparseMat\_
-----------
......
modules/core/doc/operations_on_arrays.rst
View file @ bb8198ab
......@@ -3,7 +3,14 @@ Operations on Arrays
.. highlight:: cpp
.. index:: abs
.. list-table:: **Arithmetical Operations**
* -
-
* - :cpp:funcx:`abs` (src)
- Computes an absolute value of each matrix element.
* - :cpp:funcx:`absdiff` (src1, src2, dst)
- Computes the per-element absolute difference between 2 arrays or between an array and a scalar.
abs
---
......@@ -22,12 +29,10 @@ abs
* ``C = Mat_<Vec<uchar,n> >(abs(A*alpha + beta))`` is equivalent to ``convertScaleAbs(A, C, alpha, beta)``
The output matrix has the same size and the same type as the input one (except for the last case, where ``C`` will be ``depth=CV_8U`` ).
The output matrix has the same size and the same type as the input one (except for the last case, where ``C`` will be ``depth=CV_8U`` ).
See Also: :ref:`MatrixExpressions`,
:cpp:func:`absdiff`
.. seealso:: :ref:`MatrixExpressions`, :cpp:func:`absdiff`
.. index:: absdiff
absdiff
-----------
......@@ -40,30 +45,28 @@ absdiff
:param src2: The second input array or a scalar.
:param dst: The destination array. It will have the same size and type as ``src1`` (or ``src2``).
The function ``absdiff`` computes:
The function ``absdiff`` computes:
#. absolute difference between two arrays when they have the same size and type:
#. absolute difference between two arrays when they have the same size and type:
.. math::
\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)
.. math::
\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)
#. absolute difference between an array and a scalar, when the second array is constructed from ``Scalar`` or has as many elements as the number of channels in ``src1``:
#. absolute difference between an array and a scalar, when the second array is constructed from ``Scalar`` or has as many elements as the number of channels in ``src1``:
.. math::
\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)
.. math::
\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)
#. or absolute difference between a scalar and an array, when the first array is constructed from ``Scalar`` or has as many elements as the number of channels in ``src2``:
#. or absolute difference between a scalar and an array, when the first array is constructed from ``Scalar`` or has as many elements as the number of channels in ``src2``:
.. math::
\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)
.. math::
\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)
where ``I`` is a multi-dimensional index of array elements.
In case of multi-channel arrays, each channel is processed independently.
where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
See Also: :cpp:func:`abs`
.. seealso:: :cpp:func:`abs`
.. index:: add
add
-------
......@@ -113,14 +116,15 @@ The first function in the list above can be replaced with matrix expressions: ::
The input arrays and the destination array can all have the same or different depths. For example, you can add 16-bit unsigned array to 8-bit signed array and store the sum as 32-bit floating-point array. Depth of the output array is determined by ``dtype`` parameter. In the 2nd and 3rd cases above, as well as in the first case, when ``src1.depth() == src2.depth()``, ``dtype`` can be set to the default ``-1``. In this case the output array will have the same depth as the input array, be it ``src1``, ``src2`` or both.
See Also:
:cpp:func:`subtract`,
:cpp:func:`addWeighted`,
:cpp:func:`scaleAdd`,
:cpp:func:`convertScale`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`subtract`,
:cpp:func:`addWeighted`,
:cpp:func:`scaleAdd`,
:cpp:func:`convertScale`,
:ref:`MatrixExpressions`
.. index:: addWeighted
addWeighted
---------------
......@@ -155,14 +159,15 @@ The function can be replaced with a matrix expression: ::
dst = src1*alpha + src2*beta + gamma;
See Also:
:cpp:func:`add`,
:cpp:func:`subtract`,
:cpp:func:`scaleAdd`,
:cpp:func:`convertScale`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`add`,
:cpp:func:`subtract`,
:cpp:func:`scaleAdd`,
:cpp:func:`convertScale`,
:ref:`MatrixExpressions`
.. index:: bitwise_and
bitwise_and
-----------
......@@ -204,7 +209,7 @@ The function computes the per-element bit-wise logical conjunction:
In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the 2nd and 3rd cases above, the scalar is first converted to the array type.
.. index:: bitwise_not
bitwise_not
-----------
......@@ -226,7 +231,7 @@ The function computes per-element bit-wise inversion of the source array:
In case of a floating-point source array, its machine-specific bit representation (usually IEEE754-compliant) is used for the operation. In case of multi-channel arrays, each channel is processed independently.
.. index:: bitwise_or
bitwise_or
----------
......@@ -269,7 +274,7 @@ The function computes the per-element bit-wise logical disjunction:
In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the 2nd and 3rd cases above, the scalar is first converted to the array type.
.. index:: bitwise_xor
bitwise_xor
-----------
......@@ -312,7 +317,7 @@ The function computes the per-element bit-wise logical "exclusive-or" operation:
In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the 2nd and 3rd cases above, the scalar is first converted to the array type.
.. index:: calcCovarMatrix
calcCovarMatrix
---------------
......@@ -339,7 +344,7 @@ calcCovarMatrix
\texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...]^T \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...],
The covariance matrix will be :math:`\texttt{nsamples} \times \texttt{nsamples}` . Such an unusual covariance matrix is used for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of the "scrambled" covariance matrix.
The covariance matrix will be ``nsamples x nsamples``. Such an unusual covariance matrix is used for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of the "scrambled" covariance matrix.
* **CV_COVAR_NORMAL** The output covariance matrix is calculated as:
......@@ -359,12 +364,13 @@ calcCovarMatrix
The functions ``calcCovarMatrix`` calculate the covariance matrix and, optionally, the mean vector of the set of input vectors.
See Also:
:cpp:func:`PCA`,
:cpp:func:`mulTransposed`,
:cpp:func:`Mahalanobis`
.. seealso::
:cpp:class:`PCA`,
:cpp:func:`mulTransposed`,
:cpp:func:`Mahalanobis`
.. index:: cartToPolar
cartToPolar
-----------
......@@ -379,7 +385,7 @@ cartToPolar
:param magnitude: The destination array of magnitudes of the same size and type as ``x`` .
:param angle: The destination array of angles of the same size and type as ``x`` . The angles are measured in radians :math:`(0` to :math:`2 \pi )` or in degrees (0 to 360 degrees).
:param angle: The destination array of angles of the same size and type as ``x`` . The angles are measured in radians (from 0 to 2*Pi) or in degrees (0 to 360 degrees).
:param angleInDegrees: The flag indicating whether the angles are measured in radians, which is a default mode, or in degrees.
......@@ -389,10 +395,9 @@ The function ``cartToPolar`` calculates either the magnitude, angle, or both for
\begin{array}{l} \texttt{magnitude} (I)= \sqrt{\texttt{x}(I)^2+\texttt{y}(I)^2} , \\ \texttt{angle} (I)= \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))[ \cdot180 / \pi ] \end{array}
The angles are calculated with
:math:`\sim\,0.3^\circ` accuracy. For the point (0,0) , the angle is set to 0.
The angles are calculated with accuracy about 0.3 degrees. For the point (0,0) the angle is set to 0.
.. index:: checkRange
checkRange
----------
......@@ -412,11 +417,11 @@ checkRange
:param maxVal: The exclusive upper boundary of valid values range.
The functions ``checkRange`` check that every array element is neither NaN nor
:math:`\pm \infty` . When ``minVal < -DBL_MAX`` and ``maxVal < DBL_MAX`` , the functions also check that each value is between ``minVal`` and ``maxVal`` . In case of multi-channel arrays, each channel is processed independently.
infinite. When ``minVal < -DBL_MAX`` and ``maxVal < DBL_MAX`` , the functions also check that each value is between ``minVal`` and ``maxVal`` . In case of multi-channel arrays, each channel is processed independently.
If some values are out of range, position of the first outlier is stored in ``pos`` (when
:math:`\texttt{pos}\ne0` ). Then, the functions either return false (when ``quiet=true`` ) or throw an exception.
``pos != NULL``). Then, the functions either return false (when ``quiet=true`` ) or throw an exception.
.. index:: compare
compare
-------
......@@ -473,14 +478,15 @@ The comparison operations can be replaced with the equivalent matrix expressions
...
See Also:
:cpp:func:`checkRange`,
:cpp:func:`min`,
:cpp:func:`max`,
:cpp:func:`threshold`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`checkRange`,
:cpp:func:`min`,
:cpp:func:`max`,
:cpp:func:`threshold`,
:ref:`MatrixExpressions`
.. index:: completeSymm
completeSymm
------------
......@@ -503,10 +509,12 @@ The function ``completeSymm`` copies the lower half of a square matrix to its an
:math:`\texttt{mtx}_{ij}=\texttt{mtx}_{ji}` for
:math:`i < j` if ``lowerToUpper=true``
See Also: :cpp:func:`flip`,
:cpp:func:`transpose`
.. seealso::
:cpp:func:`flip`,
:cpp:func:`transpose`
.. index:: convertScaleAbs
convertScaleAbs
---------------
......@@ -540,11 +548,12 @@ In case of multi-channel arrays, the function processes each channel independent
// but it will allocate a temporary matrix
See Also:
:cpp:func:`Mat::convertTo`,
:cpp:func:`abs`
.. seealso::
:cpp:func:`Mat::convertTo`,
:cpp:func:`abs`
.. index:: countNonZero
countNonZero
------------
......@@ -561,14 +570,15 @@ The function returns the number of non-zero elements in ``mtx`` :
\sum _{I: \; \texttt{mtx} (I) \ne0 } 1
See Also:
:cpp:func:`mean`,
:cpp:func:`meanStdDev`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`,
:cpp:func:`calcCovarMatrix`
.. seealso::
:cpp:func:`mean`,
:cpp:func:`meanStdDev`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`,
:cpp:func:`calcCovarMatrix`
.. index:: cubeRoot
cubeRoot
--------
......@@ -579,10 +589,9 @@ cubeRoot
:param val: A function argument.
The function ``cubeRoot`` computes :math:`\sqrt[3]{\texttt{val}}`. Negative arguments are handled correctly. *NaN*
and :math:`\pm\infty` are not handled. The accuracy approaches the maximum possible accuracy for single-precision data.
The function ``cubeRoot`` computes :math:`\sqrt[3]{\texttt{val}}`. Negative arguments are handled correctly. NaN and Inf are not handled. The accuracy approaches the maximum possible accuracy for single-precision data.
.. index:: cvarrToMat
cvarrToMat
----------
......@@ -640,15 +649,14 @@ The last parameter, ``coiMode`` , specifies how to deal with an image with COI s
:cpp:func:`mixChannel` or
:cpp:func:`insertImageCOI` , respectively).
See Also:
:c:func:`cvGetImage`,
:c:func:`cvGetMat`,
:c:func:`cvGetMatND`,
:cpp:func:`extractImageCOI`,
:cpp:func:`insertImageCOI`,
:cpp:func:`mixChannels`
.. seealso::
.. index:: dct
:c:func:`cvGetImage`,
:c:func:`cvGetMat`,
:c:func:`cvGetMatND`,
:cpp:func:`extractImageCOI`,
:cpp:func:`insertImageCOI`,
:cpp:func:`mixChannels`
dct
-------
......@@ -668,54 +676,56 @@ dct
The function ``dct`` performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D floating-point array:
* Forward Cosine transform of a 1D vector of
:math:`N` elements:
*
Forward Cosine transform of a 1D vector of ``N`` elements:
.. math::
.. math::
Y = C^{(N)} \cdot X
Y = C^{(N)} \cdot X
where
where
.. math::
.. math::
C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )
C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )
and
:math:`\alpha_0=1`,:math:`\alpha_j=2` for
:math:`j > 0` .
and
:math:`\alpha_0=1`, :math:`\alpha_j=2` for *j > 0*.
* Inverse Cosine transform of a 1D vector of N elements:
*
Inverse Cosine transform of a 1D vector of ``N`` elements:
.. math::
.. math::
X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y
X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y
(since
:math:`C^{(N)}` is an orthogonal matrix,
:math:`C^{(N)} \cdot \left(C^{(N)}\right)^T = I` )
(since
:math:`C^{(N)}` is an orthogonal matrix,
:math:`C^{(N)} \cdot \left(C^{(N)}\right)^T = I` )
* Forward Cosine transform of 2D
:math:`M \times N` matrix:
*
Forward 2D Cosine transform of ``M x N`` matrix:
.. math::
.. math::
Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T
Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T
*
Inverse 2D Cosine transform of ``M x N`` matrix:
* Inverse Cosine transform of a 2D vector of
:math:`M \times N` elements:
.. math::
.. math::
X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}
X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}
The function chooses the mode of operation by looking at the flags and size of the input array:
*
If ``(flags & DCT_INVERSE) == 0`` , the function does a forward 1D or 2D transform. Otherwise, it is an inverse 1D or 2D transform.
If ``(flags & DCT_INVERSE) == 0`` , the function does a forward 1D or 2D transform. Otherwise, it is an inverse 1D or 2D transform.
*
If ``(flags & DCT_ROWS) :math:`\ne` 0`` , the function performs a 1D transform of each row.
If ``(flags & DCT_ROWS) != 0`` , the function performs a 1D transform of each row.
*
If the array is a single column or a single row, the function performs a 1D transform.
......@@ -723,23 +733,19 @@ The function chooses the mode of operation by looking at the flags and size of t
*
If none of the above is true, the function performs a 2D transform.
**Note**
:
Currently ``dct`` supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you can pad the array when necessary.
.. note::
Currently ``dct`` supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you can pad the array when necessary.
Also, the function performance depends very much, and not monotonically, on the array size (see
:cpp:func:`getOptimalDFTSize` ). In the current implementation DCT of a vector of size ``N`` is computed via DFT of a vector of size ``N/2`` . Thus, the optimal DCT size
:math:`\texttt{N}^*\geq\texttt{N}` can be computed as: ::
Also, the function performance depends very much, and not monotonically, on the array size (see
:cpp:func:`getOptimalDFTSize` ). In the current implementation DCT of a vector of size ``N`` is computed via DFT of a vector of size ``N/2`` . Thus, the optimal DCT size ``N1 >= N`` can be computed as: ::
size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
N1 = getOptimalDCTSize(N);
.. seealso:: :cpp:func:`dft` , :cpp:func:`getOptimalDFTSize` , :cpp:func:`idct`
See Also:
:cpp:func:`dft`,
:cpp:func:`getOptimalDFTSize`,
:cpp:func:`idct`
.. index:: dft
dft
---
......@@ -763,40 +769,48 @@ dft
* **DFT_REAL_OUTPUT** Perform an inverse transformation of 1D or 2D complex array. The result is normally a complex array of the same size. However, if the source array has conjugate-complex symmetry (for example, it is a result of forward transformation with ``DFT_COMPLEX_OUTPUT`` flag), the output is a real array. While the function itself does not check whether the input is symmetrical or not, you can pass the flag and then the function will assume the symmetry and produce the real output array. Note that when the input is packed into a real array and inverse transformation is executed, the function treats the input as a packed complex-conjugate symmetrical array. So, the output will also be a real array.
:param nonzeroRows: When the parameter :math:`\ne 0` , the function assumes that only the first ``nonzeroRows`` rows of the input array ( ``DFT_INVERSE`` is not set) or only the first ``nonzeroRows`` of the output array ( ``DFT_INVERSE`` is set) contain non-zeros. Thus, the function can handle the rest of the rows more efficiently and save some time. This technique is very useful for computing array cross-correlation or convolution using DFT.
:param nonzeroRows: When the parameter is not zero, the function assumes that only the first ``nonzeroRows`` rows of the input array ( ``DFT_INVERSE`` is not set) or only the first ``nonzeroRows`` of the output array ( ``DFT_INVERSE`` is set) contain non-zeros. Thus, the function can handle the rest of the rows more efficiently and save some time. This technique is very useful for computing array cross-correlation or convolution using DFT.
Forward Fourier transform of 1D vector of N elements:
.. math::
The function performs one of the following:
Y = F^{(N)} \cdot X,
*
Forward Fourier transform of 1D vector of ``N`` elements:
where
:math:`F^{(N)}_{jk}=\exp(-2\pi i j k/N)` and
:math:`i=\sqrt{-1}` Inverse Fourier transform of 1D vector of N elements:
.. math::
.. math::
Y = F^{(N)} \cdot X,
\begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array}
where
:math:`F^{(N)}_{jk}=\exp(-2\pi i j k/N)` and
:math:`i=\sqrt{-1}`
*
Inverse Fourier transform of 1D vector of ``N`` elements:
where
:math:`F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T` Forward Fourier transform of 2D vector of
:math:`M \times N` elements:
.. math::
.. math::
\begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array}
Y = F^{(M)} \cdot X \cdot F^{(N)}
where
:math:`F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T`
Inverse Fourier transform of 2D vector of
:math:`M \times N` elements:
*
Forward 2D Fourier transform of ``M x N`` matrix:
.. math::
.. math::
\begin{array}{l} X'= \left (F^{(M)} \right )^* \cdot Y \cdot \left (F^{(N)} \right )^* \\ X = \frac{1}{M \cdot N} \cdot X' \end{array}
Y = F^{(M)} \cdot X \cdot F^{(N)}
In case of real (single-channel) data, the packed format is called
*CCS*
(complex-conjugate-symmetrical). It was borrowed from IPL and used to represent the result of a forward Fourier transform or input for an inverse Fourier transform:
*
Inverse 2D Fourier transform of ``M x N`` matrix:
.. math::
\begin{array}{l} X'= \left (F^{(M)} \right )^* \cdot Y \cdot \left (F^{(N)} \right )^* \\ X = \frac{1}{M \cdot N} \cdot X' \end{array}
In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input spectrum of the inverse Fourier transform can be represented in a packed format called *CCS* (complex-conjugate-symmetrical). It was borrowed from IPL (Intel Image Processing Library). Here is how 2D *CCS* spectrum looks:
.. math::
......@@ -820,9 +834,7 @@ So, the function chooses an operation mode depending on the flags and size of th
If ``DFT_SCALE`` is set, the scaling is done after the transformation.
Unlike
:cpp:func:`dct` , the function supports arrays of arbitrary size. But only those arrays are processed efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the current implementation). Such an efficient DFT size can be computed using the
:cpp:func:`getOptimalDFTSize` method.
Unlike :cpp:func:`dct` , the function supports arrays of arbitrary size. But only those arrays are processed efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the current implementation). Such an efficient DFT size can be computed using the :cpp:func:`getOptimalDFTSize` method.
Here is a sample illustrating how to compute a DFT-based convolution of two 2D real arrays: ::
......@@ -870,27 +882,19 @@ Here is a sample illustrating how to compute a DFT-based convolution of two 2D r
To optimize this sample, consider the following approaches:
*
Since :math:`\texttt{nonzeroRows} \ne 0` is passed to the forward transform calls and since ``A`` / ``B`` is copied to the top-left corners of ``tempA`` / ``tempB`` , respectively, it is not necessary to clear the whole ``tempA`` and ``tempB`` . It is only necessary to clear the ``tempA.cols - A.cols`` ( ``tempB.cols - B.cols`` ) rightmost columns of the matrices.
Since ``nonzeroRows != 0`` is passed to the forward transform calls and since ``A`` and ``B`` are copied to the top-left corners of ``tempA`` and ``tempB``, respectively, it is not necessary to clear the whole ``tempA`` and ``tempB``. It is only necessary to clear the ``tempA.cols - A.cols`` ( ``tempB.cols - B.cols``) rightmost columns of the matrices.
* This DFT-based convolution does not have to be applied to the whole big arrays, especially if ``B`` is significantly smaller than ``A`` or vice versa. Instead, you can compute convolution by parts. To do this, you need to split the destination array ``C`` into multiple tiles. For each tile, estimate which parts of ``A`` and ``B`` are required to compute convolution in this tile. If the tiles in ``C`` are too small, the speed will decrease a lot because of repeated work. In the ultimate case, when each tile in ``C`` is a single pixel, the algorithm becomes equivalent to the naive convolution algorithm. If the tiles are too big, the temporary arrays ``tempA`` and ``tempB`` become too big and there is also a slowdown because of bad cache locality. So, there is an optimal tile size somewhere in the middle.
*
This DFT-based convolution does not have to be applied to the whole big arrays, especially if ``B`` is significantly smaller than ``A`` or vice versa. Instead, you can compute convolution by parts. To do this, you need to split the destination array ``C`` into multiple tiles. For each tile, estimate which parts of ``A`` and ``B`` are required to compute convolution in this tile. If the tiles in ``C`` are too small, the speed will decrease a lot because of repeated work. In the ultimate case, when each tile in ``C`` is a single pixel, the algorithm becomes equivalent to the naive convolution algorithm. If the tiles are too big, the temporary arrays ``tempA`` and ``tempB`` become too big and there is also a slowdown because of bad cache locality. So, there is an optimal tile size somewhere in the middle.
*
If different tiles in ``C`` can be computed in parallel and, thus, the convolution is done by parts, the loop can be threaded.
All of the above improvements have been implemented in :cpp:func:`matchTemplate` and :cpp:func:`filter2D` . Therefore, by using them, you can get the performance even better than with the above theoretically optimal implementation. Though, those two functions actually compute cross-correlation, not convolution, so you need to "flip" the kernel or the image around the center using :cpp:func:`flip` .
All of the above improvements have been implemented in :cpp:func:`matchTemplate` and :cpp:func:`filter2D` . Therefore, by using them, you can get the performance even better than with the above theoretically optimal implementation. Though, those two functions actually compute cross-correlation, not convolution, so you need to "flip" the second convolution operand ``B`` vertically and horizontally using :cpp:func:`flip` .
.. seealso:: :cpp:func:`dct` , :cpp:func:`getOptimalDFTSize` , :cpp:func:`mulSpectrums`, :cpp:func:`filter2D` , :cpp:func:`matchTemplate` , :cpp:func:`flip` , :cpp:func:`cartToPolar` , :cpp:func:`magnitude` , :cpp:func:`phase`
See Also:
:cpp:func:`dct`,
:cpp:func:`getOptimalDFTSize`,
:cpp:func:`mulSpectrums`,
:cpp:func:`filter2D`,
:cpp:func:`matchTemplate`,
:cpp:func:`flip`,
:cpp:func:`cartToPolar`,
:cpp:func:`magnitude`,
:cpp:func:`phase`
.. index:: divide
divide
----------
......@@ -924,13 +928,14 @@ or a scalar by array, when there is no ``src1`` :
When ``src2(I)`` is zero, ``dst(I)`` will also be zero. Different channels of multi-channel arrays are processed independently.
See Also:
:cpp:func:`multiply`,
:cpp:func:`add`,
:cpp:func:`subtract`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`multiply`,
:cpp:func:`add`,
:cpp:func:`subtract`,
:ref:`MatrixExpressions`
.. index:: determinant
determinant
-----------
......@@ -946,14 +951,15 @@ the direct method is used. For larger matrices, the function uses LU factorizati
For symmetric positively-determined matrices, it is also possible to use :cpp:func:`eigen` decomposition to compute the determinant.
See Also:
:cpp:func:`trace`,
:cpp:func:`invert`,
:cpp:func:`solve`,
:cpp:func:`eigen`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`trace`,
:cpp:func:`invert`,
:cpp:func:`solve`,
:cpp:func:`eigen`,
:ref:`MatrixExpressions`
.. index:: eigen
eigen
-----
......@@ -964,7 +970,7 @@ eigen
Computes eigenvalues and eigenvectors of a symmetric matrix.
:param src: The input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type, square size and be symmetric: :math:`\texttt{src}^T=\texttt{src}`
:param src: The input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type, square size and be symmetrical (``src`` :sup:`T` == ``src``).
:param eigenvalues: The output vector of eigenvalues of the same type as ``src`` . The eigenvalues are stored in the descending order.
......@@ -978,11 +984,9 @@ The functions ``eigen`` compute just eigenvalues, or eigenvalues and eigenvector
src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
See Also:
:cpp:func:`completeSymm`,
:cpp:func:`PCA`
.. seealso:: :cpp:func:`completeSymm` , :cpp:class:`PCA`
.. index:: exp
exp
---
......@@ -1001,21 +1005,11 @@ The function ``exp`` calculates the exponent of every element of the input array
\texttt{dst} [I] = e^{ \texttt{src} }(I)
The maximum relative error is about
:math:`7 \times 10^{-6}` for single-precision and less than
:math:`10^{-10}` for double-precision. Currently, the function converts denormalized values to zeros on output. Special values (NaN,
:math:`\pm \infty` ) are not handled.
The maximum relative error is about ``7e-6`` for single-precision input and less than ``1e-10`` for double-precision input. Currently, the function converts denormalized values to zeros on output. Special values (NaN, Inf) are not handled.
.. seealso:: :cpp:func:`log` , :cpp:func:`cartToPolar` , :cpp:func:`polarToCart` , :cpp:func:`phase` , :cpp:func:`pow` , :cpp:func:`sqrt` , :cpp:func:`magnitude`
See Also:
:cpp:func:`log`,
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`,
:cpp:func:`phase`,
:cpp:func:`pow`,
:cpp:func:`sqrt`,
:cpp:func:`magnitude`
.. index:: extractImageCOI
extractImageCOI
---------------
......@@ -1036,15 +1030,9 @@ To extract a channel from a new-style matrix, use
:cpp:func:`mixChannels` or
:cpp:func:`split` .
See Also:
:cpp:func:`mixChannels`,
:cpp:func:`split`,
:cpp:func:`merge`,
:cpp:func:`cvarrToMat`,
:c:func:`cvSetImageCOI`,
:c:func:`cvGetImageCOI`
.. seealso:: :cpp:func:`mixChannels` , :cpp:func:`split` , :cpp:func:`merge` , :cpp:func:`cvarrToMat` , :c:func:`cvSetImageCOI` , :c:func:`cvGetImageCOI`
.. index:: fastAtan2
fastAtan2
---------
......@@ -1057,12 +1045,9 @@ fastAtan2
:param y: y-coordinate of the vector.
The function ``fastAtan2`` calculates the full-range angle of an input 2D vector. The angle is measured in degrees and varies from
:math:`0^\circ` to
:math:`360^\circ` . The accuracy is about
:math:`0.3^\circ` .
The function ``fastAtan2`` calculates the full-range angle of an input 2D vector. The angle is measured in degrees and varies from 0 to 360 degrees. The accuracy is about 0.3 degrees.
.. index:: flip
flip
--------
......@@ -1087,27 +1072,20 @@ The function ``flip`` flips the array in one of three different ways (row and co
The example scenarios of using the function are the following:
*
Vertical flipping of the image (
:math:`\texttt{flipCode} = 0` ) to switch between top-left and bottom-left image origin. This is a typical operation in video processing on Microsoft Windows* OS.
Vertical flipping of the image (``flipCode == 0``) to switch between top-left and bottom-left image origin. This is a typical operation in video processing on Microsoft Windows* OS.
*
Horizontal flipping of the image with the subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (
:math:`\texttt{flipCode} > 0` ).
Horizontal flipping of the image with the subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (``flipCode > 0``).
*
Simultaneous horizontal and vertical flipping of the image with the subsequent shift and absolute difference calculation to check for a central symmetry (
:math:`\texttt{flipCode} < 0` ).
Simultaneous horizontal and vertical flipping of the image with the subsequent shift and absolute difference calculation to check for a central symmetry (``flipCode < 0``).
*
Reversing the order of 1D point arrays (
:math:`\texttt{flipCode} > 0` or
:math:`\texttt{flipCode} = 0` ).
Reversing the order of point arrays (``flipCode > 0`` or ``flipCode == 0``).
.. seealso:: :cpp:func:`transpose` , :cpp:func:`repeat` , :cpp:func:`completeSymm`
See Also: :cpp:func:`transpose`,
:cpp:func:`repeat`,
:cpp:func:`completeSymm`
.. index:: gemm
gemm
----
......@@ -1145,12 +1123,9 @@ The function can be replaced with a matrix expression. For example, the above ca
dst = alpha*src1.t()*src2 + beta*src3.t();
See Also:
:cpp:func:`mulTransposed`,
:cpp:func:`transform`,
:ref:`MatrixExpressions`
.. seealso:: :cpp:func:`mulTransposed` , :cpp:func:`transform` , :ref:`MatrixExpressions`
.. index:: getConvertElem
getConvertElem
--------------
......@@ -1181,11 +1156,9 @@ getConvertElem
The functions ``getConvertElem`` and ``getConvertScaleElem`` return pointers to the functions for converting individual pixels from one type to another. While the main function purpose is to convert single pixels (actually, for converting sparse matrices from one type to another), you can use them to convert the whole row of a dense matrix or the whole matrix at once, by setting ``cn = matrix.cols*matrix.rows*matrix.channels()`` if the matrix data is continuous.
See Also:
:cpp:func:`Mat::convertTo`,
:cpp:func:`SparseMat::convertTo`
.. seealso:: :cpp:func:`Mat::convertTo` , :cpp:func:`SparseMat::convertTo`
.. index:: getOptimalDFTSize
getOptimalDFTSize
-----------------
......@@ -1199,23 +1172,15 @@ getOptimalDFTSize
DFT performance is not a monotonic function of a vector size. Therefore, when you compute convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to pad the input data with zeros to get a bit larger array that can be transformed much faster than the original one.
Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process. Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5*5*3*2*2) are also processed quite efficiently.
The function ``getOptimalDFTSize`` returns the minimum number ``N`` that is greater than or equal to ``vecsize`` so that the DFT
of a vector of size ``N`` can be computed efficiently. In the current implementation
:math:`N=2^p \times 3^q \times 5^r` , for some
:math:`p`,:math:`q`,:math:`r` .
The function ``getOptimalDFTSize`` returns the minimum number ``N`` that is greater than or equal to ``vecsize`` so that the DFT of a vector of size ``N`` can be computed efficiently. In the current implementation ``N`` = 2 :sup:`p` * 3 :sup:`q` * 5 :sup:`r` for some integer ``p``, ``q``, ``r``.
The function returns a negative number if ``vecsize`` is too large (very close to ``INT_MAX`` ).
While the function cannot be used directly to estimate the optimal vector size for DCT transform (since the current DCT implementation supports only even-size vectors), it can be easily computed as ``getOptimalDFTSize((vecsize+1)/2)*2`` .
While the function cannot be used directly to estimate the optimal vector size for DCT transform (since the current DCT implementation supports only even-size vectors), it can be easily computed as ``getOptimalDFTSize((vecsize+1)/2)*2``.
.. seealso:: :cpp:func:`dft` , :cpp:func:`dct` , :cpp:func:`idft` , :cpp:func:`idct` , :cpp:func:`mulSpectrums`
See Also:
:cpp:func:`dft`,
:cpp:func:`dct`,
:cpp:func:`idft`,
:cpp:func:`idct`,
:cpp:func:`mulSpectrums`
.. index:: idct
idct
----
......@@ -1232,12 +1197,14 @@ idct
``idct(src, dst, flags)`` is equivalent to ``dct(src, dst, flags | DCT_INVERSE)``.
See Also: :cpp:func:`dct`,
:cpp:func:`dft`,
:cpp:func:`idft`,
:cpp:func:`getOptimalDFTSize`
.. seealso::
:cpp:func:`dct`,
:cpp:func:`dft`,
:cpp:func:`idft`,
:cpp:func:`getOptimalDFTSize`
.. index:: idft
idft
----
......@@ -1257,18 +1224,18 @@ idft
``idft(src, dst, flags)`` is equivalent to ``dct(src, dst, flags | DFT_INVERSE)`` .
See :cpp:func:`dft` for details.
**Note**:
None of ``dft`` and ``idft`` scale the result by default.
Thus, you should pass ``DFT_SCALE`` to one of ``dft`` or ``idft`` explicitly to make these transforms mutually inverse.
.. note:: None of ``dft`` and ``idft`` scale the result by default. Thus, you should pass ``DFT_SCALE`` to one of ``dft`` or ``idft`` explicitly to make these transforms mutually inverse.
.. seealso::
:cpp:func:`dft`,
:cpp:func:`dct`,
:cpp:func:`idct`,
:cpp:func:`mulSpectrums`,
:cpp:func:`getOptimalDFTSize`
See Also: :cpp:func:`dft`,
:cpp:func:`dct`,
:cpp:func:`idct`,
:cpp:func:`mulSpectrums`,
:cpp:func:`getOptimalDFTSize`
.. index:: inRange
inRange
-------
......@@ -1305,7 +1272,7 @@ The function checks the range as follows:
When the lower and/or upper bounary parameters are scalars, the indexes ``(I)`` at ``lowerb`` and ``upperb`` in the above formulas should be omitted.
.. index:: invert
invert
------
......@@ -1327,8 +1294,7 @@ invert
* **DECOMP_CHOLESKY** Cholesky decomposion. The matrix must be symmetrical and positively defined.
The function ``invert`` inverts the matrix ``src`` and stores the result in ``dst`` .
When the matrix ``src`` is singular or non-square, the function computes the pseudo-inverse matrix (the ``dst`` matrix) so that
:math:`\|\texttt{src} \cdot \texttt{dst} - I\|` is minimal.
When the matrix ``src`` is singular or non-square, the function computes the pseudo-inverse matrix (the ``dst`` matrix) so that ``norm(src*dst - I)`` is minimal, where I is an identity matrix.
In case of the ``DECOMP_LU`` method, the function returns the ``src`` determinant ( ``src`` must be square). If it is 0, the matrix is not inverted and ``dst`` is filled with zeros.
......@@ -1336,11 +1302,12 @@ In case of the ``DECOMP_SVD`` method, the function returns the inverse condition
Similarly to ``DECOMP_LU`` , the method ``DECOMP_CHOLESKY`` works only with non-singular square matrices that should also be symmetrical and positively defined. In this case, the function stores the inverted matrix in ``dst`` and returns non-zero. Otherwise, it returns 0.
See Also:
:cpp:func:`solve`,
:cpp:class:`SVD`
.. seealso::
:cpp:func:`solve`,
:cpp:class:`SVD`
.. index:: log
log
---
......@@ -1360,21 +1327,19 @@ The function ``log`` calculates the natural logarithm of the absolute value of e
\texttt{dst} (I) = \fork{\log |\texttt{src}(I)|}{if $\texttt{src}(I) \ne 0$ }{\texttt{C}}{otherwise}
where ``C`` is a large negative number (about -700 in the current implementation).
The maximum relative error is about
:math:`7 \times 10^{-6}` for single-precision input and less than
:math:`10^{-10}` for double-precision input. Special values (NaN,
:math:`\pm \infty` ) are not handled.
See Also:
:cpp:func:`exp`,
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`,
:cpp:func:`phase`,
:cpp:func:`pow`,
:cpp:func:`sqrt`,
:cpp:func:`magnitude`
.. index:: LUT
The maximum relative error is about ``7e-6`` for single-precision input and less than ``1e-10`` for double-precision input. Special values (NaN, Inf) are not handled.
.. seealso::
:cpp:func:`exp`,
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`,
:cpp:func:`phase`,
:cpp:func:`pow`,
:cpp:func:`sqrt`,
:cpp:func:`magnitude`
LUT
---
......@@ -1401,11 +1366,12 @@ where
d = \fork{0}{if \texttt{src} has depth \texttt{CV\_8U}}{128}{if \texttt{src} has depth \texttt{CV\_8S}}
See Also:
:cpp:func:`convertScaleAbs`,
:cpp:func:`Mat::convertTo`
.. seealso::
:cpp:func:`convertScaleAbs`,
:cpp:func:`Mat::convertTo`
.. index:: magnitude
magnitude
---------
......@@ -1426,13 +1392,14 @@ The function ``magnitude`` calculates the magnitude of 2D vectors formed from th
\texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}
See Also:
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`,
:cpp:func:`phase`,
:cpp:func:`sqrt`
.. seealso::
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`,
:cpp:func:`phase`,
:cpp:func:`sqrt`
.. index:: Mahalanobis
Mahalanobis
-----------
......@@ -1457,7 +1424,7 @@ The covariance matrix may be calculated using the
:cpp:func:`calcCovarMatrix` function and then inverted using the
:cpp:func:`invert` function (preferably using the ``DECOMP_SVD`` method, as the most accurate).
.. index:: max
max
---
......@@ -1501,14 +1468,14 @@ In the second variant, when the source array is multi-channel, each channel is c
The first 3 variants of the function listed above are actually a part of
:ref:`MatrixExpressions` . They return an expression object that can be further either transformed/ assigned to a matrix, or passed to a function, and so on.
See Also:
:cpp:func:`min`,
:cpp:func:`compare`,
:cpp:func:`inRange`,
:cpp:func:`minMaxLoc`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`min`,
:cpp:func:`compare`,
:cpp:func:`inRange`,
:cpp:func:`minMaxLoc`,
:ref:`MatrixExpressions`
.. index:: mean
mean
----
......@@ -1529,13 +1496,14 @@ The functions ``mean`` compute mean value ``M`` of array elements, independently
When all the mask elements are 0's, the functions return ``Scalar::all(0)`` .
See Also:
:cpp:func:`countNonZero`,
:cpp:func:`meanStdDev`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`
.. seealso::
:cpp:func:`countNonZero`,
:cpp:func:`meanStdDev`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`
.. index:: meanStdDev
meanStdDev
----------
......@@ -1559,20 +1527,18 @@ The functions ``meanStdDev`` compute the mean and the standard deviation ``M`` o
\begin{array}{l} N = \sum _{I, \texttt{mask} (I) \ne 0} 1 \\ \texttt{mean} _c = \frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \texttt{src} (I)_c}{N} \\ \texttt{stddev} _c = \sqrt{\sum_{ I: \; \texttt{mask}(I) \ne 0} \left ( \texttt{src} (I)_c - \texttt{mean} _c \right )^2} \end{array}
When all the mask elements are 0's, the functions return ``mean=stddev=Scalar::all(0)`` .
**Note**:
The computed standard deviation is only the diagonal of the complete normalized covariance matrix. If the full matrix is needed, you can reshape the multi-channel array
:math:`M \times N` to the single-channel array
:math:`M*N \times \texttt{mtx.channels}()` (only possible when the matrix is continuous) and then pass the matrix to
:cpp:func:`calcCovarMatrix` .
See Also:
:cpp:func:`countNonZero`,
:cpp:func:`mean`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`,
:cpp:func:`calcCovarMatrix`
.. note:: The computed standard deviation is only the diagonal of the complete normalized covariance matrix. If the full matrix is needed, you can reshape the multi-channel array ``M x N`` to the single-channel array ``M*N x mtx.channels()`` (only possible when the matrix is continuous) and then pass the matrix to :cpp:func:`calcCovarMatrix` .
.. seealso::
:cpp:func:`countNonZero`,
:cpp:func:`mean`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`,
:cpp:func:`calcCovarMatrix`
.. index:: merge
merge
-----
......@@ -1595,12 +1561,13 @@ The function
:cpp:func:`split` does the reverse operation. If you need to shuffle channels in some other advanced way, use
:cpp:func:`mixChannels` .
See Also:
:cpp:func:`mixChannels`,
:cpp:func:`split`,
:cpp:func:`reshape`
.. seealso::
:cpp:func:`mixChannels`,
:cpp:func:`split`,
:cpp:func:`reshape`
.. index:: min
min
---
......@@ -1644,14 +1611,15 @@ In the second variant, when the source array is multi-channel, each channel is c
The first three variants of the function listed above are actually a part of
:ref:`MatrixExpressions` . They return the expression object that can be further either transformed/assigned to a matrix, or passed to a function, and so on.
See Also:
:cpp:func:`max`,
:cpp:func:`compare`,
:cpp:func:`inRange`,
:cpp:func:`minMaxLoc`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`max`,
:cpp:func:`compare`,
:cpp:func:`inRange`,
:cpp:func:`minMaxLoc`,
:ref:`MatrixExpressions`
.. index:: minMaxLoc
minMaxLoc
---------
......@@ -1689,17 +1657,18 @@ The functions do not work with multi-channel arrays. If you need to find minimum
In case of a sparse matrix, the minimum is found among non-zero elements only.
See Also:
:cpp:func:`max`,
:cpp:func:`min`,
:cpp:func:`compare`,
:cpp:func:`inRange`,
:cpp:func:`extractImageCOI`,
:cpp:func:`mixChannels`,
:cpp:func:`split`,
:cpp:func:`reshape`
.. seealso::
:cpp:func:`max`,
:cpp:func:`min`,
:cpp:func:`compare`,
:cpp:func:`inRange`,
:cpp:func:`extractImageCOI`,
:cpp:func:`mixChannels`,
:cpp:func:`split`,
:cpp:func:`reshape`
.. index:: mixChannels
mixChannels
-----------
......@@ -1741,17 +1710,15 @@ As an example, this code splits a 4-channel RGBA image into a 3-channel BGR (wit
mixChannels( &rgba, 1, out, 2, from_to, 4 );
**Note**
.. note:: Unlike many other new-style C++ functions in OpenCV (see the introduction section and :cpp:func:`Mat::create` ), ``mixChannels`` requires the destination arrays to be pre-allocated before calling the function.
.. seealso::
Unlike many other new-style C++ functions in OpenCV (see the introduction section and
:cpp:func:`Mat::create` ), ``mixChannels`` requires the destination arrays to be pre-allocated before calling the function.
:cpp:func:`split`,
:cpp:func:`merge`,
:cpp:func:`cvtColor`
See Also:
:cpp:func:`split`,
:cpp:func:`merge`,
:cpp:func:`cvtColor`
.. index:: mulSpectrums
mulSpectrums
------------
......@@ -1777,7 +1744,7 @@ The function, together with
:cpp:func:`idft` , may be used to calculate convolution (pass ``conj=false`` ) or correlation (pass ``conj=false`` ) of two arrays rapidly. When the arrays are complex, they are simply multiplied (per element) with an optional conjugation of the second-array elements. When the arrays are real, they are assumed to be CCS-packed (see
:cpp:func:`dft` for details).
.. index:: multiply
multiply
--------
......@@ -1807,19 +1774,20 @@ There is also
For a not-per-element matrix product, see
:cpp:func:`gemm` .
See Also:
:cpp:func:`add`,
:cpp:func:`substract`,
:cpp:func:`divide`,
:ref:`MatrixExpressions`,
:cpp:func:`scaleAdd`,
:cpp:func:`addWeighted`,
:cpp:func:`accumulate`,
:cpp:func:`accumulateProduct`,
:cpp:func:`accumulateSquare`,
:cpp:func:`Mat::convertTo`
.. seealso::
:cpp:func:`add`,
:cpp:func:`substract`,
:cpp:func:`divide`,
:ref:`MatrixExpressions`,
:cpp:func:`scaleAdd`,
:cpp:func:`addWeighted`,
:cpp:func:`accumulate`,
:cpp:func:`accumulateProduct`,
:cpp:func:`accumulateSquare`,
:cpp:func:`Mat::convertTo`
.. index:: mulTransposed
mulTransposed
-------------
......@@ -1852,17 +1820,16 @@ if ``aTa=true`` , and
\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T
otherwise. The function is used to compute the covariance matrix. With zero delta, it can be used as a faster substitute for general matrix product
:math:`A*B` when
:math:`B=A^T` .
otherwise. The function is used to compute the covariance matrix. With zero delta, it can be used as a faster substitute for general matrix product ``A*B`` when ``B=A'``
.. seealso::
:cpp:func:`calcCovarMatrix`,
:cpp:func:`gemm`,
:cpp:func:`repeat`,
:cpp:func:`reduce`
See Also:
:cpp:func:`calcCovarMatrix`,
:cpp:func:`gemm`,
:cpp:func:`repeat`,
:cpp:func:`reduce`
.. index:: norm
norm
----
......@@ -1913,7 +1880,7 @@ When the ``mask`` parameter is specified and it is not empty, the norm is comput
A multi-channel source arrays are treated as a single-channel, that is, the results for all channels are combined.
.. index:: normalize
normalize
---------
......@@ -1940,65 +1907,43 @@ normalize
The functions ``normalize`` scale and shift the source array elements, so that
.. math::
*
.. math::
\| \texttt{dst} \| _{L_p}= \texttt{alpha}
\| \texttt{dst} \| _{L_p}= \texttt{alpha}
(where
:math:`p=\infty` , 1 or 2) when ``normType=NORM_INF``,``NORM_L1`` or ``NORM_L2``,or so that
(where p=Inf, 1 or 2) when ``normType=NORM_INF``,``NORM_L1`` or ``NORM_L2``, respectively,
.. math::
*
or so that
.. math::
\min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}
\min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}
when ``normType=NORM_MINMAX`` (for dense arrays only).
when ``normType=NORM_MINMAX`` (for dense arrays only).
The optional mask specifies a sub-array to be normalized. This means that the norm or min-n-max are computed over the sub-array, and then this sub-array is modified to be normalized. If you want to only use the mask to compute the norm or min-max but modify the whole array, you can use
:cpp:func:`norm` and
:cpp:func:`Mat::convertScale` /
:cpp:func:`Mat::convertTo`
In case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this, the range transformation for sparse matrices is not allowed, since it can shift the zero level.
See Also:
:cpp:func:`norm`,
:cpp:func:`Mat::convertScale`,
:cpp:func:`SparseMat::convertScale`
.. seealso::
:cpp:func:`norm`,
:cpp:func:`Mat::convertTo`,
:cpp:func:`SparseMat::convertTo`
.. index:: PCA
PCA
---
.. cpp:class:: PCA
Class for Principal Component Analysis ::
for Principal Component Analysis.
class PCA
{
public:
// default constructor
PCA();
// computes PCA for a set of vectors stored as data rows or columns.
PCA(InputArray data, InputArray mean, int flags, int maxComponents=0);
// computes PCA for a set of vectors stored as data rows or columns
PCA& operator()(InputArray data, InputArray mean, int flags, int maxComponents=0);
// projects vector into the principal components space
Mat project(InputArray vec) const;
void project(InputArray vec, OutputArray result) const;
// reconstructs the vector from its PC projection
Mat backProject(InputArray vec) const;
void backProject(InputArray vec, OutputArray result) const;
// eigenvectors of the PC space, stored as the matrix rows
Mat eigenvectors;
// the corresponding eigenvalues; not used for PCA compression/decompression
Mat eigenvalues;
// mean vector, subtracted from the projected vector
// or added to the reconstructed vector
Mat mean;
};
The class ``PCA`` is used to compute a special basis for a set of vectors. The basis will consist of eigenvectors of the covariance matrix computed from the input set of vectors. The class ``PCA`` can also transform vectors to/from the new coordinate space defined by the basis. Usually, in this new coordinate system, each vector from the original set (and any linear combination of such vectors) can be quite accurately approximated by taking just the first few its components, corresponding to the eigenvectors of the largest eigenvalues of the covariance matrix. Geometrically it means that you compute a projection of the vector to a subspace formed by a few eigenvectors corresponding to the dominant eigenvalues of the covariation matrix. And usually such a projection is very close to the original vector. That is, you can represent the original vector from a high-dimensional space with a much shorter vector consisting of the projected vector's coordinates in the subspace. Such a transformation is also known as Karhunen-Loeve Transform, or KLT. See
The class is used to compute a special basis for a set of vectors. The basis will consist of eigenvectors of the covariance matrix computed from the input set of vectors. The class ``PCA`` can also transform vectors to/from the new coordinate space defined by the basis. Usually, in this new coordinate system, each vector from the original set (and any linear combination of such vectors) can be quite accurately approximated by taking just the first few its components, corresponding to the eigenvectors of the largest eigenvalues of the covariance matrix. Geometrically it means that you compute a projection of the vector to a subspace formed by a few eigenvectors corresponding to the dominant eigenvalues of the covariation matrix. And usually such a projection is very close to the original vector. That is, you can represent the original vector from a high-dimensional space with a much shorter vector consisting of the projected vector's coordinates in the subspace. Such a transformation is also known as Karhunen-Loeve Transform, or KLT. See
http://en.wikipedia.org/wiki/Principal\_component\_analysis
The sample below is the function that takes two matrices. The first one stores the set of vectors (a row per vector) that is used to compute PCA. The second one stores another "test" set of vectors (a row per vector) that are first compressed with PCA, then reconstructed back, and then the reconstruction error norm is computed and printed for each vector. ::
......@@ -2037,14 +1982,15 @@ The sample below is the function that takes two matrices. The first one stores t
}
See Also:
:cpp:func:`calcCovarMatrix`,
:cpp:func:`mulTransposed`,
:cpp:class:`SVD`,
:cpp:func:`dft`,
:cpp:func:`dct`
.. seealso::
:cpp:func:`calcCovarMatrix`,
:cpp:func:`mulTransposed`,
:cpp:class:`SVD`,
:cpp:func:`dft`,
:cpp:func:`dct`
.. index:: PCA::PCA
PCA::PCA
------------
......@@ -2069,7 +2015,7 @@ PCA::PCA
The default constructor initializes empty PCA structure. The second constructor initializes the structure and calls
:cpp:func:`PCA::operator ()` .
.. index:: PCA::operator ()
PCA::operator ()
----------------
......@@ -2094,7 +2040,7 @@ The operator performs PCA of the supplied dataset. It is safe to reuse the same
The computed eigenvalues are sorted from the largest to the smallest and the corresponding eigenvectors are stored as ``PCA::eigenvectors`` rows.
.. index:: PCA::project
PCA::project
------------
......@@ -2111,7 +2057,7 @@ PCA::project
The methods project one or more vectors to the principal component subspace, where each vector projection is represented by coefficients in the principal component basis. The first form of the method returns the matrix that the second form writes to the result. So the first form can be used as a part of expression while the second form can be more efficient in a processing loop.
.. index:: PCA::backProject
PCA::backProject
----------------
......@@ -2129,7 +2075,7 @@ PCA::backProject
The methods are inverse operations to
:cpp:func:`PCA::project` . They take PC coordinates of projected vectors and reconstruct the original vectors. Of course, unless all the principal components have been retained, the reconstructed vectors are different from the originals. But typically, the difference is small if the number of components is large enough (but still much smaller than the original vector dimensionality). As a result, PCA is used.
.. index:: perspectiveTransform
perspectiveTransform
--------------------
......@@ -2141,7 +2087,7 @@ perspectiveTransform
:param dst: Destination array of the same size and type as ``src`` .
:param mtx: :math:`3\times 3` or :math:`4 \times 4` transformation matrix.
:param mtx: ``3x3`` or ``4x4`` floating-point transformation matrix.
The function ``perspectiveTransform`` transforms every element of ``src``by treating it as a 2D or 3D vector, in the following way:
......@@ -2161,23 +2107,18 @@ and
w = \fork{w'}{if $w' \ne 0$}{\infty}{otherwise}
Here a 3D vector transformation is shown. In case of a 2D vector transformation, the
:math:`z` component is omitted.
Here a 3D vector transformation is shown. In case of a 2D vector transformation, the ``z`` component is omitted.
.. note:: The function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use :cpp:func:`warpPerspective` . If you have an inverse problem, that is, you want to compute the most probable perspective transformation out of several pairs of corresponding points, you can use :cpp:func:`getPerspectiveTransform` or :cpp:func:`findHomography` .
**Note**:
.. seealso::
The function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use
:cpp:func:`warpPerspective` . If you have an inverse task, that is, you want to compute the most probable perspective transformation out of several pairs of corresponding points, you can use
:cpp:func:`getPerspectiveTransform` or
:cpp:func:`findHomography` .
:cpp:func:`transform`,
:cpp:func:`warpPerspective`,
:cpp:func:`getPerspectiveTransform`,
:cpp:func:`findHomography`
See Also:
:cpp:func:`transform`,
:cpp:func:`warpPerspective`,
:cpp:func:`getPerspectiveTransform`,
:cpp:func:`findHomography`
.. index:: phase
phase
-----
......@@ -2200,13 +2141,8 @@ The function ``phase`` computes the rotation angle of each 2D vector that is for
\texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))
The angle estimation accuracy is
:math:`\sim\,0.3^\circ` , when ``x(I)=y(I)=0`` , the corresponding ``angle`` (I) is set to
:math:`0` .
The angle estimation accuracy is about 0.3 degrees. When ``x(I)=y(I)=0`` , the corresponding ``angle(I)`` is set to 0.
See Also:
.. index:: polarToCart
polarToCart
-----------
......@@ -2231,19 +2167,19 @@ The function ``polarToCart`` computes the Cartesian coordinates of each 2D vecto
\begin{array}{l} \texttt{x} (I) = \texttt{magnitude} (I) \cos ( \texttt{angle} (I)) \\ \texttt{y} (I) = \texttt{magnitude} (I) \sin ( \texttt{angle} (I)) \\ \end{array}
The relative accuracy of the estimated coordinates is
:math:`\sim\,10^{-6}` .
The relative accuracy of the estimated coordinates is about ``1e-6``.
.. seealso::
:cpp:func:`cartToPolar`,
:cpp:func:`magnitude`,
:cpp:func:`phase`,
:cpp:func:`exp`,
:cpp:func:`log`,
:cpp:func:`pow`,
:cpp:func:`sqrt`
See Also:
:cpp:func:`cartToPolar`,
:cpp:func:`magnitude`,
:cpp:func:`phase`,
:cpp:func:`exp`,
:cpp:func:`log`,
:cpp:func:`pow`,
:cpp:func:`sqrt`
.. index:: pow
pow
---
......@@ -2273,69 +2209,28 @@ That is, for a non-integer power exponent, the absolute values of input array el
For some values of ``p`` , such as integer values, 0.5 and -0.5, specialized faster algorithms are used.
See Also:
:cpp:func:`sqrt`,
:cpp:func:`exp`,
:cpp:func:`log`,
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`
.. seealso::
:cpp:func:`sqrt`,
:cpp:func:`exp`,
:cpp:func:`log`,
:cpp:func:`cartToPolar`,
:cpp:func:`polarToCart`
.. index:: RNG
RNG
---
.. cpp:class: RNG
Random number generator class ::
class CV_EXPORTS RNG
{
public:
enum { UNIFORM=0, NORMAL=1 };
// constructors
RNG();
RNG(uint64 state);
// returns a 32-bit unsigned random number
unsigned next();
// return random numbers of the specified type
operator uchar();
operator schar();
operator ushort();
operator short();
operator unsigned();
// returns a random integer sampled uniformly from [0, N).
unsigned operator()(unsigned N);
unsigned operator()();
operator int();
operator float();
operator double();
// returns a random number sampled uniformly from [a, b) range
int uniform(int a, int b);
float uniform(float a, float b);
double uniform(double a, double b);
// returns the Gaussian random number with zero mean.
double gaussian(double sigma);
// fills thec array with random numbers sampled from the specified distribution
void fill( Mat& mat, int distType, const Scalar& a, const Scalar& b );
// internal state of the RNG (could change in the future)
uint64 state;
};
The class ``RNG`` implements the random number generator. It encapsulates the RNG state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia (
- Random number generator. It encapsulates the state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia (
http://en.wikipedia.org/wiki/Multiply-with-carry
). Gaussian-distribution random numbers are generated using the Ziggurat algorithm (
http://en.wikipedia.org/wiki/Ziggurat_algorithm
), introduced by G. Marsaglia and W. W. Tsang.
.. index:: RNG::RNG
RNG::RNG
------------
......@@ -2349,7 +2244,7 @@ RNG::RNG
These are the RNG constructors. The first form sets the state to some pre-defined value, equal to ``2**32-1`` in the current implementation. The second form sets the state to the specified value. If you passed ``state=0`` , the constructor uses the above default value instead to avoid the singular random number sequence, consisting of all zeros.
.. index:: RNG::next
RNG::next
-------------
......@@ -2359,7 +2254,7 @@ RNG::next
The method updates the state using the MWC algorithm and returns the next 32-bit random number.
.. index:: RNG::operator T
RNG::operator T
---------------
......@@ -2374,6 +2269,8 @@ RNG::operator T
.. cpp:function:: RNG::operator int()
.. cpp:function:: RNG::operator unsigned()
.. cpp:function:: RNG::operator float()
.. cpp:function:: RNG::operator double()
......@@ -2382,7 +2279,7 @@ RNG::operator T
Each of the methods updates the state using the MWC algorithm and returns the next random number of the specified type. In case of integer types, the returned number is from the available value range for the specified type. In case of floating-point types, the returned value is from ``[0,1)`` range.
.. index:: RNG::operator ()
RNG::operator ()
--------------------
......@@ -2397,7 +2294,7 @@ RNG::operator ()
The methods transform the state using the MWC algorithm and return the next random number. The first form is equivalent to
:cpp:func:`RNG::next` . The second form returns the random number modulo ``N`` , which means that the result is in the range ``[0, N)`` .
.. index:: RNG::uniform
RNG::uniform
----------------
......@@ -2436,7 +2333,7 @@ The methods transform the state using the MWC algorithm and return the next unif
The compiler does not take into account the type of the variable to which you assign the result of ``RNG::uniform`` . The only thing that matters to the compiler is the type of ``a`` and ``b`` parameters. So, if you want a floating-point random number, but the range boundaries are integer numbers, either put dots in the end, if they are constants, or use explicit type cast operators, as in the ``a1`` initialization above.
.. index:: RNG::gaussian
RNG::gaussian
-----------------
......@@ -2448,7 +2345,7 @@ RNG::gaussian
The method transforms the state using the MWC algorithm and returns the next random number from the Gaussian distribution ``N(0,sigma)`` . That is, the mean value of the returned random numbers is zero and the standard deviation is the specified ``sigma`` .
.. index:: RNG::fill
RNG::fill
-------------
......@@ -2464,11 +2361,7 @@ RNG::fill
:param b: The second distribution parameter. In case of the uniform distribution, this is a non-inclusive upper boundary. In case of the normal distribution, this is a standard deviation (diagonal of the standard deviation matrix or the full standard deviation matrix).
Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In case of multiple-channel images, every channel is filled independently, which means that RNG cannot generate samples from the multi-dimensional Gaussian distribution with non-diagonal covariation matrix directly. To do that, first, generate matrix from the distribution
:math:`N(0, I_n)` (Gaussian distribution with zero mean and identity covariation matrix) and then transform it using
:cpp:func:`transform` and the specific covariation matrix.
.. index:: randu
Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In case of multiple-channel images, every channel is filled independently, which means that RNG cannot generate samples from the multi-dimensional Gaussian distribution with non-diagonal covariation matrix directly. To do that, the method generates samples from multi-dimensional standard Gaussian distribution with zero mean and identity covariation matrix, and then transforms them using :cpp:func:`transform` to get samples from the specified Gaussian distribution.
randu
-----
......@@ -2486,7 +2379,7 @@ randu
:param high: Exclusive upper boundary of the generated random numbers.
The template functions ``randu`` generate and return the next uniformly-distributed random value of the specified type. ``randu<int>()`` is an equivalent to ``(int)theRNG();`` , and so on. See
:cpp:func:`RNG` description.
:cpp:class:`RNG` description.
The second non-template variant of the function fills the matrix ``mtx`` with uniformly-distributed random numbers from the specified range:
......@@ -2494,12 +2387,13 @@ The second non-template variant of the function fills the matrix ``mtx`` with un
\texttt{low} _c \leq \texttt{mtx} (I)_c < \texttt{high} _c
See Also:
:cpp:func:`RNG`,
:cpp:func:`randn`,
:cpp:func:`theRNG`
.. seealso::
:cpp:class:`RNG`,
:cpp:func:`randn`,
:cpp:func:`theRNG`
.. index:: randn
randn
-----
......@@ -2516,11 +2410,12 @@ randn
The function ``randn`` fills the matrix ``mtx`` with normally distributed random numbers with the specified mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the value range of the destination array data type.
See Also:
:cpp:func:`RNG`,
:cpp:func:`randu`
.. seealso::
:cpp:class:`RNG`,
:cpp:func:`randu`
.. index:: randShuffle
randShuffle
-----------
......@@ -2537,11 +2432,12 @@ randShuffle
The function ``randShuffle`` shuffles the specified 1D array by randomly choosing pairs of elements and swapping them. The number of such swap operations will be ``mtx.rows*mtx.cols*iterFactor`` .
See Also:
:cpp:func:`RNG`,
:cpp:func:`sort`
.. seealso::
:cpp:class:`RNG`,
:cpp:func:`sort`
.. index:: reduce
reduce
------
......@@ -2570,9 +2466,9 @@ reduce
The function ``reduce`` reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of ``CV_REDUCE_SUM`` and ``CV_REDUCE_AVG`` , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
See Also: :cpp:func:`repeat`
.. seealso:: :cpp:func:`repeat`
.. index:: repeat
repeat
------
......@@ -2601,30 +2497,17 @@ The functions
The second variant of the function is more convenient to use with
:ref:`MatrixExpressions` .
See Also:
:cpp:func:`reduce`,
:ref:`MatrixExpressions`
.. seealso::
.. index:: saturate_cast
:cpp:func:`reduce`,
:ref:`MatrixExpressions`
saturate_cast
-------------
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(unsigned char v)
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(signed char v)
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(unsigned short v)
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(signed short v)
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(int v)
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(unsigned int v)
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(float v)
saturate_cast
-------------
.. cpp:function:: template<typename _Tp> inline _Tp saturate_cast(double v)
.. cpp:function:: template<...> _Tp saturate_cast(_Tp2 v)
Template function for accurate conversion from one primitive type to another.
......@@ -2635,21 +2518,21 @@ The functions ``saturate_cast`` resemble the standard C++ cast operations, such
uchar a = saturate_cast<uchar>(-100); // a = 0 (UCHAR_MIN)
short b = saturate_cast<short>(33333.33333); // b = 32767 (SHRT_MAX)
Such clipping is done when the target type is ``unsigned char`` , ``signed char`` , ``unsigned short`` or ``signed short`` . For 32-bit integers, no clipping is done.
When the parameter is a floating-point value and the target type is an integer (8-, 16- or 32-bit), the floating-point value is first rounded to the nearest integer and then clipped if needed (when the target type is 8- or 16-bit).
This operation is used in the simplest or most complex image processing functions in OpenCV.
See Also:
:cpp:func:`add`,
:cpp:func:`subtract`,
:cpp:func:`multiply`,
:cpp:func:`divide`,
:cpp:func:`Mat::convertTo`
.. seealso::
:cpp:func:`add`,
:cpp:func:`subtract`,
:cpp:func:`multiply`,
:cpp:func:`divide`,
:cpp:func:`Mat::convertTo`
.. index:: scaleAdd
scaleAdd
--------
......@@ -2679,15 +2562,16 @@ The function can also be emulated with a matrix expression, for example: ::
A.row(0) = A.row(1)*2 + A.row(2);
See Also:
:cpp:func:`add`,
:cpp:func:`addWeighted`,
:cpp:func:`subtract`,
:cpp:func:`Mat::dot`,
:cpp:func:`Mat::convertTo`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`add`,
:cpp:func:`addWeighted`,
:cpp:func:`subtract`,
:cpp:func:`Mat::dot`,
:cpp:func:`Mat::convertTo`,
:ref:`MatrixExpressions`
.. index:: setIdentity
setIdentity
-----------
......@@ -2713,14 +2597,15 @@ The function can also be emulated using the matrix initializers and the matrix e
// A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
See Also:
:cpp:func:`Mat::zeros`,
:cpp:func:`Mat::ones`,
:ref:`MatrixExpressions`,
:cpp:func:`Mat::setTo`,
:cpp:func:`Mat::operator=`
.. seealso::
:cpp:func:`Mat::zeros`,
:cpp:func:`Mat::ones`,
:ref:`MatrixExpressions`,
:cpp:func:`Mat::setTo`,
:cpp:func:`Mat::operator=`
.. index:: solve
solve
-----
......@@ -2758,18 +2643,15 @@ The function ``solve`` solves a linear system or least-squares problem (the latt
If ``DECOMP_LU`` or ``DECOMP_CHOLESKY`` method is used, the function returns 1 if ``src1`` (or
:math:`\texttt{src1}^T\texttt{src1}` ) is non-singular. Otherwise, it returns 0. In the latter case, ``dst`` is not valid. Other methods find a pseudo-solution in case of a singular left-hand side part.
**Note**
.. note:: If you want to find a unity-norm solution of an under-defined singular system :math:`\texttt{src1}\cdot\texttt{dst}=0` , the function ``solve`` will not do the work. Use :cpp:func:`SVD::solveZ` instead.
If you want to find a unity-norm solution of an under-defined singular system
:math:`\texttt{src1}\cdot\texttt{dst}=0` , the function ``solve`` will not do the work. Use
:cpp:func:`SVD::solveZ` instead.
.. seealso::
:cpp:func:`invert`,
:cpp:class:`SVD`,
:cpp:func:`eigen`
See Also:
:cpp:func:`invert`,
:cpp:class:`SVD`,
:cpp:func:`eigen`
.. index:: solveCubic
solveCubic
--------------
......@@ -2797,7 +2679,7 @@ or (if ``coeffs`` is a 3-element vector):
The roots are stored in the ``roots`` array.
.. index:: solvePoly
solvePoly
---------
......@@ -2818,7 +2700,7 @@ The function ``solvePoly`` finds real and complex roots of a polynomial equation
\texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0
.. index:: sort
sort
----
......@@ -2843,11 +2725,12 @@ sort
The function ``sort`` sorts each matrix row or each matrix column in ascending or descending order. So you should pass two operation flags to get desirable behaviour. If you want to sort matrix rows or columns lexicographically, you can use STL ``std::sort`` generic function with the proper comparison predicate.
See Also:
:cpp:func:`sortIdx`,
:cpp:func:`randShuffle`
.. seealso::
:cpp:func:`sortIdx`,
:cpp:func:`randShuffle`
.. index:: sortIdx
sortIdx
-------
......@@ -2879,11 +2762,12 @@ The function ``sortIdx`` sorts each matrix row or each matrix column in the asce
// [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
See Also:
:cpp:func:`sort`,
:cpp:func:`randShuffle`
.. seealso::
:cpp:func:`sort`,
:cpp:func:`randShuffle`
.. index:: split
split
-----
......@@ -2907,12 +2791,13 @@ The functions ``split`` split a multi-channel array into separate single-channel
If you need to extract a single channel or do some other sophisticated channel permutation, use
:cpp:func:`mixChannels` .
See Also:
:cpp:func:`merge`,
:cpp:func:`mixChannels`,
:cpp:func:`cvtColor`
.. seealso::
:cpp:func:`merge`,
:cpp:func:`mixChannels`,
:cpp:func:`cvtColor`
.. index:: sqrt
sqrt
----
......@@ -2927,11 +2812,12 @@ sqrt
The functions ``sqrt`` calculate a square root of each source array element. In case of multi-channel arrays, each channel is processed independently. The accuracy is approximately the same as of the built-in ``std::sqrt`` .
See Also:
:cpp:func:`pow`,
:cpp:func:`magnitude`
.. seealso::
:cpp:func:`pow`,
:cpp:func:`magnitude`
.. index:: subtract
subtract
--------
......@@ -2982,56 +2868,32 @@ The first function in the list above can be replaced with matrix expressions: ::
The input arrays and the destination array can all have the same or different depths. For example, you can subtract to 8-bit unsigned arrays and store the difference in 16-bit signed array. Depth of the output array is determined by ``dtype`` parameter. In the 2nd and 3rd cases above, as well as in the first case, when ``src1.depth() == src2.depth()``, ``dtype`` can be set to the default ``-1``. In this case the output array will have the same depth as the input array, be it ``src1``, ``src2`` or both.
See Also:
:cpp:func:`add`,
:cpp:func:`addWeighted`,
:cpp:func:`scaleAdd`,
:cpp:func:`convertScale`,
:ref:`MatrixExpressions`
.. seealso::
:cpp:func:`add`,
:cpp:func:`addWeighted`,
:cpp:func:`scaleAdd`,
:cpp:func:`convertScale`,
:ref:`MatrixExpressions`
.. index:: SVD
SVD
---
.. cpp:class:: SVD
Class for computing Singular Value Decomposition ::
for computing Singular Value Decomposition of a floating-point matrix. The Singular Value Decomposition is used to solve least-square problems, under-determined linear systems, invert matrices, compute condition numbers, and so on.
class SVD
{
public:
enum { MODIFY_A=1, NO_UV=2, FULL_UV=4 };
// default empty constructor
SVD();
// decomposes A into u, w and vt: A = u*w*vt;
// u and vt are orthogonal, w is diagonal
SVD( const Mat& A, int flags=0 );
// decomposes A into u, w and vt.
SVD& operator ()( const Mat& A, int flags=0 );
// finds vector x, norm(x)=1, so that A*x = 0,
// where A is a singular matrix
static void solveZ( const Mat& A, OutputArray x );
// does back-subsitution:
// x = vt.t()*inv(w)*u.t()*rhs ~ inv(A)*rhs
void backSubst( const Mat& rhs, OutputArray x ) const;
Mat u; // the left orthogonal matrix
Mat w; // vector of singular values
Mat vt; // the right orthogonal matrix
};
The class ``SVD`` is used to compute Singular Value Decomposition of a floating-point matrix. The Singular Value Decomposition is used to solve least-square problems, under-determined linear systems, invert matrices, compute condition numbers, and so on.
For a bit faster operation, you can pass ``flags=SVD::MODIFY_A|...`` to modify the decomposed matrix when it is not necessary to preserve it. If you want to compute a condition number of a matrix or an absolute value of its determinant, you do not need ``u`` and ``vt`` . You can pass ``flags=SVD::NO_UV|...`` . Another flag ``FULL_UV`` indicates that full-size ``u`` and ``vt`` must be computed, which is not necessary most of the time.
See Also:
:cpp:func:`invert`,
:cpp:func:`solve`,
:cpp:func:`eigen`,
:cpp:func:`determinant`
.. seealso::
:cpp:func:`invert`,
:cpp:func:`solve`,
:cpp:func:`eigen`,
:cpp:func:`determinant`
.. index:: SVD::SVD
SVD::SVD
--------
......@@ -3055,7 +2917,7 @@ SVD::SVD
The first constructor initializes an empty ``SVD`` structure. The second constructor initializes an empty ``SVD`` structure and then calls
:cpp:func:`SVD::operator ()` .
.. index:: SVD::operator ()
SVD::operator ()
----------------
......@@ -3077,7 +2939,7 @@ SVD::operator ()
The operator performs the singular value decomposition of the supplied matrix. The ``u``,``vt`` , and the vector of singular values ``w`` are stored in the structure. The same ``SVD`` structure can be reused many times with different matrices. Each time, if needed, the previous ``u``,``vt`` , and ``w`` are reclaimed and the new matrices are created, which is all handled by
:cpp:func:`Mat::create` .
.. index:: SVD::solveZ
SVD::solveZ
-----------
......@@ -3090,16 +2952,14 @@ SVD::solveZ
:param x: Found solution.
The method finds a unit-length solution
**x**
of the under-determined system
:math:`A x = 0` . Theory says that such a system has an infinite number of solutions, so the algorithm finds a unit-length solution as the right singular vector corresponding to the smallest singular value (which should be 0). In practice, because of round errors and limited floating-point accuracy, the input matrix can appear to be close-to-singular rather than just singular. So, strictly speaking, the algorithm solves the following problem:
The method finds a unit-length solution ``x`` of a singular linear system
``A*x = 0``. Depending on the rank of ``A``, there can be no solutions, a single solution or an infinite number of solutions. In general, the algorithm solves the following problem:
.. math::
x^* = \arg \min _{x: \| x \| =1} \| A \cdot x \|
.. index:: SVD::backSubst
SVD::backSubst
--------------
......@@ -3108,7 +2968,7 @@ SVD::backSubst
Performs a singular value back substitution.
:param rhs: Right-hand side of a linear system :math:`\texttt{A} \texttt{x} = \texttt{rhs}` to be solved, where ``A`` is the matrix passed to :cpp:func:`SVD::SVD` or :cpp:func:`SVD::operator ()` .
:param rhs: Right-hand side of a linear system ``A*x = rhs`` to be solved, where ``A`` has been previously decomposed using :cpp:func:`SVD::SVD` or :cpp:func:`SVD::operator ()` .
:param x: Found solution of the system.
......@@ -3120,12 +2980,9 @@ The method computes a back substitution for the specified right-hand side:
Using this technique you can either get a very accurate solution of the convenient linear system, or the best (in the least-squares terms) pseudo-solution of an overdetermined linear system.
**Note**
.. note:: Explicit SVD with the further back substitution only makes sense if you need to solve many linear systems with the same left-hand side (for example, ``A`` ). If all you need is to solve a single system (possibly with multiple ``rhs`` immediately available), simply call :cpp:func:`solve` add pass ``DECOMP_SVD`` there. It does absolutely the same thing.
Explicit SVD with the further back substitution only makes sense if you need to solve many linear systems with the same left-hand side (for example, ``A`` ). If all you need is to solve a single system (possibly with multiple ``rhs`` immediately available), simply call
:cpp:func:`solve` add pass ``DECOMP_SVD`` there. It does absolutely the same thing.
.. index:: sum
sum
---
......@@ -3138,15 +2995,16 @@ sum
The functions ``sum`` calculate and return the sum of array elements, independently for each channel.
See Also:
:cpp:func:`countNonZero`,
:cpp:func:`mean`,
:cpp:func:`meanStdDev`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`,
:cpp:func:`reduce`
.. seealso::
:cpp:func:`countNonZero`,
:cpp:func:`mean`,
:cpp:func:`meanStdDev`,
:cpp:func:`norm`,
:cpp:func:`minMaxLoc`,
:cpp:func:`reduce`
.. index:: theRNG
theRNG
------
......@@ -3159,12 +3017,13 @@ The function ``theRNG`` returns the default random number generator. For each th
:cpp:func:`randu` or
:cpp:func:`randn` instead. But if you are going to generate many random numbers inside a loop, it is much faster to use this function to retrieve the generator and then use ``RNG::operator _Tp()`` .
See Also:
:cpp:func:`RNG`,
:cpp:func:`randu`,
:cpp:func:`randn`
.. seealso::
:cpp:class:`RNG`,
:cpp:func:`randu`,
:cpp:func:`randn`
.. index:: trace
trace
-----
......@@ -3181,7 +3040,7 @@ The function ``trace`` returns the sum of the diagonal elements of the matrix ``
\mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)
.. index:: transform
transform
---------
......@@ -3211,24 +3070,22 @@ The function ``transform`` performs the matrix transformation of every element o
(when ``mtx.cols=src.channels()+1`` )
Every element of the ``N`` -channel array ``src`` is interpreted as ``N`` -element vector that is transformed using
the
:math:`\texttt{M} \times \texttt{N}` or
:math:`\texttt{M} \times \texttt{N+1}` matrix ``mtx``
the ``M x N`` or ``M x (N+1)`` matrix ``mtx``
to ``M``-element vector - the corresponding element of the destination array ``dst`` .
The function may be used for geometrical transformation of
:math:`N` -dimensional
points, arbitrary linear color space transformation (such as various kinds of RGB
:math:`\rightarrow` YUV transforms), shuffling the image channels, and so forth.
``N`` -dimensional
points, arbitrary linear color space transformation (such as various kinds of RGB to YUV transforms), shuffling the image channels, and so forth.
.. seealso::
:cpp:func:`perspectiveTransform`,
:cpp:func:`getAffineTransform`,
:cpp:func:`estimateRigidTransform`,
:cpp:func:`warpAffine`,
:cpp:func:`warpPerspective`
See Also:
:cpp:func:`perspectiveTransform`,
:cpp:func:`getAffineTransform`,
:cpp:func:`estimateRigidTransform`,
:cpp:func:`warpAffine`,
:cpp:func:`warpPerspective`
.. index:: transpose
transpose
---------
......@@ -3247,6 +3104,4 @@ The function :cpp:func:`transpose` transposes the matrix ``src`` :
\texttt{dst} (i,j) = \texttt{src} (j,i)
**Note**:
No complex conjugation is done in case of a complex matrix. It it should be done separately if needed.
.. note:: No complex conjugation is done in case of a complex matrix. It it should be done separately if needed.
modules/ml/doc/boosting.rst
View file @ bb8198ab
......@@ -43,21 +43,21 @@ Different variants of boosting are known as Discrete Adaboost, Real AdaBoost, Lo
:math:`m` =
:math:`1,2,...,M` :
##.
#.
Fit the classifier
:math:`f_m(x) \in{-1,1}` , using weights
:math:`w_i` on the training data.
##.
#.
Compute
:math:`err_m = E_w [1_{(y =\neq f_m(x))}], c_m = log((1 - err_m)/err_m)` .
##.
#.
Set
: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
:math:`\Sigma i w_i = 1` .
##.
#.
Output the classifier sign
:math:`[\Sigma m = 1M c_m f_m(x)]` .
......@@ -153,67 +153,11 @@ In case of LogitBoost and Gentle AdaBoost, each weak predictor is a regression t
.. index:: CvBoost
.. _CvBoost:
CvBoost
-------
.. c:type:: CvBoost
Boosted tree classifier ::
class CvBoost : public CvStatModel
{
public:
// Boosting type
enum { DISCRETE=0, REAL=1, LOGIT=2, GENTLE=3 };
// Splitting criteria
enum { DEFAULT=0, GINI=1, MISCLASS=3, SQERR=4 };
CvBoost();
virtual ~CvBoost();
CvBoost( const Mat& _train_data, int _tflag,
const Mat& _responses, const Mat& _var_idx=0,
const Mat& _sample_idx=0, const Mat& _var_type=0,
const Mat& _missing_mask=0,
CvBoostParams params=CvBoostParams() );
virtual bool train( const Mat& _train_data, int _tflag,
const Mat& _responses, const Mat& _var_idx=0,
const Mat& _sample_idx=0, const Mat& _var_type=0,
const Mat& _missing_mask=0,
CvBoostParams params=CvBoostParams(),
bool update=false );
virtual float predict( const Mat& _sample, const Mat& _missing=0,
Mat& weak_responses=0, CvSlice slice=CV_WHOLE_SEQ,
bool raw_mode=false ) const;
virtual void prune( CvSlice slice );
virtual void clear();
virtual void write( CvFileStorage* storage, const char* name );
virtual void read( CvFileStorage* storage, CvFileNode* node );
CvSeq* get_weak_predictors();
const CvBoostParams& get_params() const;
...
protected:
virtual bool set_params( const CvBoostParams& _params );
virtual void update_weights( CvBoostTree* tree );
virtual void trim_weights();
virtual void write_params( CvFileStorage* fs );
virtual void read_params( CvFileStorage* fs, CvFileNode* node );
CvDTreeTrainData* data;
CvBoostParams params;
CvSeq* weak;
...
};
.. cpp:class:: CvBoost
Boosted tree classifier, derived from :cpp:class:`CvStatModel`
.. index:: CvBoost::train
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment