Finds the camera intrinsic and extrinsic parameters from several views of a calibration pattern.
Finds the camera intrinsic and extrinsic parameters from several views of a calibration pattern.
...
@@ -118,13 +121,13 @@ cv::calibrateCamera
...
@@ -118,13 +121,13 @@ cv::calibrateCamera
:param distCoeffs: The output vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5 or 8 elements
:param distCoeffs: The output vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5 or 8 elements
:param rvecs: The output vector of rotation vectors (see :ref:`Rodrigues2` ), estimated for each pattern view. That is, each k-th rotation vector together with the corresponding k-th translation vector (see the next output parameter description) brings the calibration pattern from the model coordinate space (in which object points are specified) to the world coordinate space, i.e. real position of the calibration pattern in the k-th pattern view (k=0.. *M* -1)
:param rvecs: The output vector of rotation vectors (see :ref:`Rodrigues` ), estimated for each pattern view. That is, each k-th rotation vector together with the corresponding k-th translation vector (see the next output parameter description) brings the calibration pattern from the model coordinate space (in which object points are specified) to the world coordinate space, i.e. real position of the calibration pattern in the k-th pattern view (k=0.. *M* -1)
:param tvecs: The output vector of translation vectors, estimated for each pattern view.
:param tvecs: The output vector of translation vectors, estimated for each pattern view.
:param flags: Different flags, may be 0 or combination of the following values:
:param flags: Different flags, may be 0 or combination of the following values:
* **CV_CALIB_USE_INTRINSIC_GUESS** ``cameraMatrix`` contains the valid initial values of ``fx, fy, cx, cy`` that are optimized further. Otherwise, ``(cx, cy)`` is initially set to the image center ( ``imageSize`` is used here), and focal distances are computed in some least-squares fashion. Note, that if intrinsic parameters are known, there is no need to use this function just to estimate the extrinsic parameters. Use :ref:`FindExtrinsicCameraParams2` instead.
* **CV_CALIB_USE_INTRINSIC_GUESS** ``cameraMatrix`` contains the valid initial values of ``fx, fy, cx, cy`` that are optimized further. Otherwise, ``(cx, cy)`` is initially set to the image center ( ``imageSize`` is used here), and focal distances are computed in some least-squares fashion. Note, that if intrinsic parameters are known, there is no need to use this function just to estimate the extrinsic parameters. Use :ref:`solvePnP` instead.
* **CV_CALIB_FIX_PRINCIPAL_POINT** The principal point is not changed during the global optimization, it stays at the center or at the other location specified when ``CV_CALIB_USE_INTRINSIC_GUESS`` is set too.
* **CV_CALIB_FIX_PRINCIPAL_POINT** The principal point is not changed during the global optimization, it stays at the center or at the other location specified when ``CV_CALIB_USE_INTRINSIC_GUESS`` is set too.
...
@@ -144,7 +147,7 @@ object with known geometry and easily detectable feature points.
...
@@ -144,7 +147,7 @@ object with known geometry and easily detectable feature points.
Such an object is called a calibration rig or calibration pattern,
Such an object is called a calibration rig or calibration pattern,
and OpenCV has built-in support for a chessboard as a calibration
and OpenCV has built-in support for a chessboard as a calibration
of intrinsic parameters (when ``CV_CALIB_USE_INTRINSIC_GUESS`` is not set) is only implemented for planar calibration patterns
of intrinsic parameters (when ``CV_CALIB_USE_INTRINSIC_GUESS`` is not set) is only implemented for planar calibration patterns
(where z-coordinates of the object points must be all 0's). 3D
(where z-coordinates of the object points must be all 0's). 3D
calibration rigs can also be used as long as initial ``cameraMatrix`` is provided.
calibration rigs can also be used as long as initial ``cameraMatrix`` is provided.
...
@@ -156,10 +159,9 @@ The algorithm does the following:
...
@@ -156,10 +159,9 @@ The algorithm does the following:
#.
#.
The initial camera pose is estimated as if the intrinsic parameters have been already known. This is done using
The initial camera pose is estimated as if the intrinsic parameters have been already known. This is done using
:ref:`FindExtrinsicCameraParams2`
:ref:`solvePnP`
#.
#.
After that the global Levenberg-Marquardt optimization algorithm is run to minimize the reprojection error, i.e. the total sum of squared distances between the observed feature points ``imagePoints`` and the projected (using the current estimates for camera parameters and the poses) object points ``objectPoints`` ; see
After that the global Levenberg-Marquardt optimization algorithm is run to minimize the reprojection error, i.e. the total sum of squared distances between the observed feature points ``imagePoints`` and the projected (using the current estimates for camera parameters and the poses) object points ``objectPoints``; see :ref:`projectPoints` .
:ref:`ProjectPoints2` .
The function returns the final re-projection error.
The function returns the final re-projection error.
Note: if you're using a non-square (=non-NxN) grid and
Note: if you're using a non-square (=non-NxN) grid and
...
@@ -172,16 +174,20 @@ bad values (i.e. zero distortion coefficients, an image center very far from
...
@@ -172,16 +174,20 @@ bad values (i.e. zero distortion coefficients, an image center very far from
:param whichImage: Index of the image (1 or 2) that contains the ``points``
:param whichImage: Index of the image (1 or 2) that contains the ``points``
:param F: The fundamental matrix that can be estimated using :ref:`FindFundamentalMat` or :ref:`StereoRectify` .
:param F: The fundamental matrix that can be estimated using :ref:`findFundamentalMat` or :ref:`StereoRectify` .
:param lines: The output vector of the corresponding to the points epipolar lines in the other image. Each line :math:`ax + by + c=0` is encoded by 3 numbers :math:`(a, b, c)`
:param lines: The output vector of the corresponding to the points epipolar lines in the other image. Each line :math:`ax + by + c=0` is encoded by 3 numbers :math:`(a, b, c)`
...
@@ -256,7 +266,7 @@ For every point in one of the two images of a stereo-pair the function finds the
...
@@ -256,7 +266,7 @@ For every point in one of the two images of a stereo-pair the function finds the
corresponding epipolar line in the other image.
corresponding epipolar line in the other image.
From the fundamental matrix definition (see
From the fundamental matrix definition (see
:ref:`FindFundamentalMat` ),
:ref:`findFundamentalMat` ),
line
line
:math:`l^{(2)}_i` in the second image for the point
:math:`l^{(2)}_i` in the second image for the point
:math:`p^{(1)}_i` in the first image (i.e. when ``whichImage=1`` ) is computed as:
:math:`p^{(1)}_i` in the first image (i.e. when ``whichImage=1`` ) is computed as:
...
@@ -277,8 +287,11 @@ Line coefficients are defined up to a scale. They are normalized, such that
...
@@ -277,8 +287,11 @@ Line coefficients are defined up to a scale. They are normalized, such that
:param image: The destination image; it must be an 8-bit color image
:param image: The destination image; it must be an 8-bit color image
:param patternSize: The number of inner corners per chessboard row and column. (patternSize = cv::Size(points _ per _ row,points _ per _ column) = cv::Size(rows,columns) )
:param patternSize: The number of inner corners per chessboard row and column. (patternSize = cv::Size(points_per_row,points_per_column) = cv::Size(rows,columns) )
:param corners: The array of corners detected, this should be the output from findChessboardCorners wrapped in a cv::Mat().
:param corners: The array of corners detected, this should be the output from findChessboardCorners wrapped in a cv::Mat().
...
@@ -351,16 +368,18 @@ The function draws the individual chessboard corners detected as red circles if
...
@@ -351,16 +368,18 @@ The function draws the individual chessboard corners detected as red circles if
:param cameraMatrix: The input camera matrix :math:`A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}`
:param cameraMatrix: The input camera matrix :math:`A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}`
:param distCoeffs: The input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5 or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
:param distCoeffs: The input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5 or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
:param rvec: The output rotation vector (see :ref:`Rodrigues2` ) that (together with ``tvec`` ) brings points from the model coordinate system to the camera coordinate system
:param rvec: The output rotation vector (see :ref:`Rodrigues` ) that (together with ``tvec`` ) brings points from the model coordinate system to the camera coordinate system
:param tvec: The output translation vector
:param tvec: The output translation vector
:param useExtrinsicGuess: If true (1), the function will use the provided ``rvec`` and ``tvec`` as the initial approximations of the rotation and translation vectors, respectively, and will further optimize them.
:param useExtrinsicGuess: If true (1), the function will use the provided ``rvec`` and ``tvec`` as the initial approximations of the rotation and translation vectors, respectively, and will further optimize them.
The function estimates the object pose given a set of object points, their corresponding image projections, as well as the camera matrix and the distortion coefficients. This function finds such a pose that minimizes reprojection error, i.e. the sum of squared distances between the observed projections ``imagePoints`` and the projected (using
The function estimates the object pose given a set of object points, their corresponding image projections, as well as the camera matrix and the distortion coefficients. This function finds such a pose that minimizes reprojection error, i.e. the sum of squared distances between the observed projections ``imagePoints`` and the projected (using
Finds the object pose from the 3D-2D point correspondences
Finds the object pose from the 3D-2D point correspondences
...
@@ -490,9 +515,10 @@ cv::solvePnPRansac
...
@@ -490,9 +515,10 @@ cv::solvePnPRansac
:param imagePoints: The array of corresponding image points, 2xN or Nx2 1-channel or 1xN or Nx1 2-channel, where N is the number of points. Can also pass ``vector<Point2f>`` here.
:param imagePoints: The array of corresponding image points, 2xN or Nx2 1-channel or 1xN or Nx1 2-channel, where N is the number of points. Can also pass ``vector<Point2f>`` here.
:param cameraMatrix: The input camera matrix :math:`A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}`
:param cameraMatrix: The input camera matrix :math:`A = \vecthreethree{fx}{0}{cx}{0}{fy}{cy}{0}{0}{1}`
:param distCoeffs: The input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5 or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
:param distCoeffs: The input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5 or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
:param rvec: The output rotation vector (see :ref:`Rodrigues2` ) that (together with ``tvec`` ) brings points from the model coordinate system to the camera coordinate system
:param rvec: The output rotation vector (see :ref:`Rodrigues` ) that (together with ``tvec`` ) brings points from the model coordinate system to the camera coordinate system
:param tvec: The output translation vector
:param tvec: The output translation vector
...
@@ -507,11 +533,13 @@ cv::solvePnPRansac
...
@@ -507,11 +533,13 @@ cv::solvePnPRansac
:param inliers: The output vector that contained indices of inliers in objectPoints and imagePoints
:param inliers: The output vector that contained indices of inliers in objectPoints and imagePoints
The function estimates the object pose given a set of object points, their corresponding image projections, as well as the camera matrix and the distortion coefficients. This function finds such a pose that minimizes reprojection error, i.e. the sum of squared distances between the observed projections ``imagePoints`` and the projected (using
The function estimates the object pose given a set of object points, their corresponding image projections, as well as the camera matrix and the distortion coefficients. This function finds such a pose that minimizes reprojection error, i.e. the sum of squared distances between the observed projections ``imagePoints`` and the projected (using
:ref:`ProjectPoints2` ) ``objectPoints`` . Through the use of RANSAC function is resistant to outliers.
:ref:`projectPoints` ) ``objectPoints``. Through the use of RANSAC the function is resistant to outliers.
.. index:: findFundamentalMat
.. index:: findFundamentalMat
cv::findFundamentalMat
.. _findFundamentalMat:
findFundamentalMat
----------------------
----------------------
.. c:function:: Mat findFundamentalMat( const Mat& points1, const Mat& points2, vector<uchar>& status, int method=FM_RANSAC, double param1=3., double param2=0.99 )
.. c:function:: Mat findFundamentalMat( const Mat& points1, const Mat& points2, vector<uchar>& status, int method=FM_RANSAC, double param1=3., double param2=0.99 )
...
@@ -572,7 +600,9 @@ corresponding to the specified points. It can also be passed to
...
@@ -572,7 +600,9 @@ corresponding to the specified points. It can also be passed to
.. index:: findHomography
.. index:: findHomography
cv::findHomography
.. _findHomography:
findHomography
------------------
------------------
.. c:function:: Mat findHomography( const Mat& srcPoints, const Mat& dstPoints, Mat& status, int method=0, double ransacReprojThreshold=3 )
.. c:function:: Mat findHomography( const Mat& srcPoints, const Mat& dstPoints, Mat& status, int method=0, double ransacReprojThreshold=3 )
:param objectPoints: The array of object points, 3xN or Nx3 1-channel or 1xN or Nx1 3-channel (or ``vector<Point3f>`` ) , where N is the number of points in the view
:param objectPoints: The array of object points, 3xN or Nx3 1-channel or 1xN or Nx1 3-channel (or ``vector<Point3f>`` ) , where N is the number of points in the view
:param rvec: The rotation vector, see :ref:`Rodrigues2`
:param rvec: The rotation vector, see :ref:`Rodrigues`
:param tvec: The translation vector
:param tvec: The translation vector
...
@@ -841,8 +885,7 @@ of partial derivatives of image points coordinates (as functions of all the
...
@@ -841,8 +885,7 @@ of partial derivatives of image points coordinates (as functions of all the
input parameters) with respect to the particular parameters, intrinsic and/or
input parameters) with respect to the particular parameters, intrinsic and/or
extrinsic. The jacobians are used during the global optimization
extrinsic. The jacobians are used during the global optimization
in
in
:ref:`CalibrateCamera2`,:ref:`FindExtrinsicCameraParams2` and
:ref:`calibrateCamera`, :ref:`solvePnP` and :ref:`stereoCalibrate` . The
:ref:`StereoCalibrate` . The
function itself can also used to compute re-projection error given the
function itself can also used to compute re-projection error given the
current intrinsic and extrinsic parameters.
current intrinsic and extrinsic parameters.
...
@@ -850,7 +893,9 @@ Note, that by setting ``rvec=tvec=(0,0,0)`` , or by setting ``cameraMatrix`` to
...
@@ -850,7 +893,9 @@ Note, that by setting ``rvec=tvec=(0,0,0)`` , or by setting ``cameraMatrix`` to
:param Q: The :math:`4 \times 4` perspective transformation matrix that can be obtained with :ref:`StereoRectify`
:param Q: The :math:`4 \times 4` perspective transformation matrix that can be obtained with :ref:`StereoRectify`
:param handleMissingValues: If true, when the pixels with the minimal disparity (that corresponds to the outliers; see :ref:`FindStereoCorrespondenceBM` ) will be transformed to 3D points with some very large Z value (currently set to 10000)
:param handleMissingValues: If true, when the pixels with the minimal disparity (that corresponds to the outliers; see :ref:`StereoBM::operator ()` ) will be transformed to 3D points with some very large Z value (currently set to 10000)
The function transforms 1-channel disparity map to 3-channel image representing a 3D surface. That is, for each pixel ``(x,y)`` and the corresponding disparity ``d=disparity(x,y)`` it computes:
The function transforms 1-channel disparity map to 3-channel image representing a 3D surface. That is, for each pixel ``(x,y)`` and the corresponding disparity ``d=disparity(x,y)`` it computes:
...
@@ -879,7 +924,9 @@ The matrix ``Q`` can be arbitrary
...
@@ -879,7 +924,9 @@ The matrix ``Q`` can be arbitrary
Computes disparity using BM algorithm for a rectified stereo pair
:param left: The left image, 8-bit single-channel or 3-channel.
:param right: The right image of the same size and the same type as the left one.
:param disp: The output disparity map. It will have the same size as the input images. When ``disptype==CV_16S``, the map will be 16-bit signed single-channel image, containing scaled by 16 disparity values, so that to get the floating-point disparity map, you will need to divide each ``disp`` element by 16. Otherwise, it will be floating-point disparity map.
:param disptype: The type of the output disparity map, ``CV_16S`` (default) or ``CV_32F``.
The method executes BM algorithm on a rectified stereo pair. See ``stereo_match.cpp`` OpenCV sample on how to prepare the images and call the method. Note that the method is not constant, thus you should not use the same ``StereoBM`` instance from within different threads simultaneously.
.. index:: StereoSGBM
.. index:: StereoSGBM
...
@@ -980,6 +1051,7 @@ The class is a C++ wrapper for and the associated functions. In particular, ``St
...
@@ -980,6 +1051,7 @@ The class is a C++ wrapper for and the associated functions. In particular, ``St
StereoSGBM
StereoSGBM
----------
----------
.. c:type:: StereoSGBM
.. c:type:: StereoSGBM
The class for computing stereo correspondence using semi-global block matching algorithm. ::
The class for computing stereo correspondence using semi-global block matching algorithm. ::
...
@@ -1010,30 +1082,21 @@ The class for computing stereo correspondence using semi-global block matching a
...
@@ -1010,30 +1082,21 @@ The class for computing stereo correspondence using semi-global block matching a
...
...
};
};
The class implements modified H. Hirschmuller algorithm
The class implements modified H. Hirschmuller algorithm HH08. The main differences between the implemented algorithm and the original one are:
HH08
. The main differences between the implemented algorithm and the original one are:
*
* by default the algorithm is single-pass, i.e. instead of 8 directions we only consider 5. Set ``fullDP=true`` to run the full variant of the algorithm (which could consume *a lot* of memory)
by default the algorithm is single-pass, i.e. instead of 8 directions we only consider 5. Set ``fullDP=true`` to run the full variant of the algorithm (which could consume
*a lot*
of memory)
*
* the algorithm matches blocks, not individual pixels (though, by setting ``SADWindowSize=1`` the blocks are reduced to single pixels)
the algorithm matches blocks, not individual pixels (though, by setting ``SADWindowSize=1`` the blocks are reduced to single pixels)
*
* mutual information cost function is not implemented. Instead, we use a simpler Birchfield-Tomasi sub-pixel metric from BT96, though the color images are supported as well.
mutual information cost function is not implemented. Instead, we use a simpler Birchfield-Tomasi sub-pixel metric from
BT96
, though the color images are supported as well.
*
* we include some pre- and post- processing steps from K. Konolige algorithm :ref:`StereoBM::operator ()` , such as pre-filtering (``CV_STEREO_BM_XSOBEL`` type) and post-filtering (uniqueness check, quadratic interpolation and speckle filtering)
we include some pre- and post- processing steps from K. Konolige algorithm
:ref:`FindStereoCorrespondceBM` , such as pre-filtering ( ``CV_STEREO_BM_XSOBEL`` type) and post-filtering (uniqueness check, quadratic interpolation and speckle filtering)
.. index:: StereoSGBM::StereoSGBM
.. index:: StereoSGBM::StereoSGBM
cv::StereoSGBM::StereoSGBM
.. _StereoSGBM::StereoSGBM:
StereoSGBM::StereoSGBM
--------------------------
--------------------------
.. c:function:: StereoSGBM::StereoSGBM()
.. c:function:: StereoSGBM::StereoSGBM()
...
@@ -1065,10 +1128,12 @@ The first constructor initializes ``StereoSGBM`` with all the default parameters
...
@@ -1065,10 +1128,12 @@ The first constructor initializes ``StereoSGBM`` with all the default parameters
* **CV_CALIB_RATIONAL_MODEL** Enable coefficients k4, k5 and k6. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the rational model and return 8 coefficients. If the flag is not set, the function will compute and return only 5 distortion coefficients.
* **CV_CALIB_RATIONAL_MODEL** Enable coefficients k4, k5 and k6. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the rational model and return 8 coefficients. If the flag is not set, the function will compute and return only 5 distortion coefficients.
The function estimates transformation between the 2 cameras making a stereo pair. If we have a stereo camera, where the relative position and orientation of the 2 cameras is fixed, and if we computed poses of an object relative to the fist camera and to the second camera, (R1, T1) and (R2, T2), respectively (that can be done with
The function estimates transformation between the 2 cameras making a stereo pair. If we have a stereo camera, where the relative position and orientation of the 2 cameras is fixed, and if we computed poses of an object relative to the fist camera and to the second camera, (R1, T1) and (R2, T2), respectively (that can be done with
:ref:`FindExtrinsicCameraParams2` ), obviously, those poses will relate to each other, i.e. given (
:ref:`solvePnP` ), obviously, those poses will relate to each other, i.e. given (
:math:`R_1`,:math:`T_1` ) it should be possible to compute (
:math:`R_1`,:math:`T_1` ) it should be possible to compute (
:math:`R_2`,:math:`T_2` ) - we only need to know the position and orientation of the 2nd camera relative to the 1st camera. That's what the described function does. It computes (
:math:`R_2`,:math:`T_2` ) - we only need to know the position and orientation of the 2nd camera relative to the 1st camera. That's what the described function does. It computes (
:math:`R`,:math:`T` ) such that:
:math:`R`,:math:`T` ) such that:
...
@@ -1160,15 +1227,15 @@ where
...
@@ -1160,15 +1227,15 @@ where
F = cameraMatrix2^{-T} E cameraMatrix1^{-1}
F = cameraMatrix2^{-T} E cameraMatrix1^{-1}
Besides the stereo-related information, the function can also perform full calibration of each of the 2 cameras. However, because of the high dimensionality of the parameter space and noise in the input data the function can diverge from the correct solution. Thus, if intrinsic parameters can be estimated with high accuracy for each of the cameras individually (e.g. using
Besides the stereo-related information, the function can also perform full calibration of each of the 2 cameras. However, because of the high dimensionality of the parameter space and noise in the input data the function can diverge from the correct solution. Thus, if intrinsic parameters can be estimated with high accuracy for each of the cameras individually (e.g. using
:ref:`CalibrateCamera2` ), it is recommended to do so and then pass ``CV_CALIB_FIX_INTRINSIC`` flag to the function along with the computed intrinsic parameters. Otherwise, if all the parameters are estimated at once, it makes sense to restrict some parameters, e.g. pass ``CV_CALIB_SAME_FOCAL_LENGTH`` and ``CV_CALIB_ZERO_TANGENT_DIST`` flags, which are usually reasonable assumptions.
:ref:`calibrateCamera` ), it is recommended to do so and then pass ``CV_CALIB_FIX_INTRINSIC`` flag to the function along with the computed intrinsic parameters. Otherwise, if all the parameters are estimated at once, it makes sense to restrict some parameters, e.g. pass ``CV_CALIB_SAME_FOCAL_LENGTH`` and ``CV_CALIB_ZERO_TANGENT_DIST`` flags, which are usually reasonable assumptions.
Similarly to
Similarly to :ref:`calibrateCamera` , the function minimizes the total re-projection error for all the points in all the available views from both cameras. The function returns the final value of the re-projection error.
:ref:`CalibrateCamera2` , the function minimizes the total re-projection error for all the points in all the available views from both cameras.
The function returns the final value of the re-projection error.
Computes rectification transform for uncalibrated stereo camera.
Computes rectification transform for uncalibrated stereo camera.
:param points1, points2: The 2 arrays of corresponding 2D points. The same formats as in :ref:`FindFundamentalMat` are supported
:param points1, points2: The 2 arrays of corresponding 2D points. The same formats as in :ref:`findFundamentalMat` are supported
:param F: The input fundamental matrix. It can be computed from the same set of point pairs using :ref:`FindFundamentalMat` .
:param F: The input fundamental matrix. It can be computed from the same set of point pairs using :ref:`findFundamentalMat` .
:param imageSize: Size of the image.
:param imageSize: Size of the image.
...
@@ -1266,13 +1335,15 @@ Hartley99
...
@@ -1266,13 +1335,15 @@ Hartley99
.
.
Note that while the algorithm does not need to know the intrinsic parameters of the cameras, it heavily depends on the epipolar geometry. Therefore, if the camera lenses have significant distortion, it would better be corrected before computing the fundamental matrix and calling this function. For example, distortion coefficients can be estimated for each head of stereo camera separately by using
Note that while the algorithm does not need to know the intrinsic parameters of the cameras, it heavily depends on the epipolar geometry. Therefore, if the camera lenses have significant distortion, it would better be corrected before computing the fundamental matrix and calling this function. For example, distortion coefficients can be estimated for each head of stereo camera separately by using
:ref:`CalibrateCamera2` and then the images can be corrected using
:ref:`calibrateCamera` and then the images can be corrected using
:ref:`Undistort2` , or just the point coordinates can be corrected with
:ref:`undistort` , or just the point coordinates can be corrected with
:param P: The new camera matrix (3x3) or the new projection matrix (3x4). ``P1`` or ``P2`` , computed by :func:`StereoRectify` can be passed here. If the matrix is empty, the identity new camera matrix is used
:param P: The new camera matrix (3x3) or the new projection matrix (3x4). ``P1`` or ``P2`` , computed by :func:`StereoRectify` can be passed here. If the matrix is empty, the identity new camera matrix is used
The function is similar to
The function is similar to
:ref:`Undistort2` and
:ref:`undistort` and
:ref:`InitUndistortRectifyMap` , but it operates on a sparse set of points instead of a raster image. Also the function does some kind of reverse transformation to
:ref:`initUndistortRectifyMap` , but it operates on a sparse set of points instead of a raster image. Also the function does some kind of reverse transformation to
:ref:`ProjectPoints2` (in the case of 3D object it will not reconstruct its 3D coordinates, of course; but for a planar object it will, up to a translation vector, if the proper ``R`` is specified). ::
:ref:`projectPoints` (in the case of 3D object it will not reconstruct its 3D coordinates, of course; but for a planar object it will, up to a translation vector, if the proper ``R`` is specified). ::
// (u,v) is the input point, (u', v') is the output point
// (u,v) is the input point, (u', v') is the output point
@@ -32,9 +34,8 @@ Template "traits" class for other OpenCV primitive data types ::
...
@@ -32,9 +34,8 @@ Template "traits" class for other OpenCV primitive data types ::
};
};
};
};
The template class ``DataType`` is 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. If you are familiar with OpenCV
The template class ``DataType`` is 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 a form ``CV_<bit-depth>{U|S|F}C<number_of_channels>``, for example, ``uchar`` ~ ``CV_8UC1``, 3-element floating-point tuple ~ ``CV_32FC3`` etc. A universal OpenCV structure, which is able to store a single instance of such primitive data type is
:ref:`CvMat` 's type notation, CV_8U ... CV_32FC3, CV_64FC2 etc., then a primitive type can be defined as a type for which you can give a unique identifier in a form ``CV_<bit-depth>{U|S|F}C<number_of_channels>`` . A universal OpenCV structure able to store a single instance of such primitive data type is
:ref:`Vec`. Multiple instances of such a type can be stored to a ``std::vector``,``Mat``,``Mat_``,``SparseMat``,``SparseMat_`` or any other container that is able to store
:ref:`Vec` . Multiple instances of such a type can be stored to a ``std::vector``,``Mat``,``Mat_``,``SparseMat``,``SparseMat_`` or any other container that is able to store
:ref:`Vec` instances.
:ref:`Vec` instances.
The class ``DataType`` is basically used to provide some 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's not ``DataType`` itself that is used, but its specialized versions, such as: ::
The class ``DataType`` is basically used to provide some 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's not ``DataType`` itself that is used, but its specialized versions, such as: ::
...
@@ -205,8 +206,7 @@ Template class for specfying image or rectangle size. ::
...
@@ -205,8 +206,7 @@ Template class for specfying image or rectangle size. ::
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
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
:ref:`CvSize` and
``CvSize`` and ``CvSize2D32f`` . The same set of arithmetic and comparison operations as for ``Point_`` is available.
:ref:`CvSize2D32f` . The same set of arithmetic and comparison operations as for ``Point_`` is available.
OpenCV defines the following type aliases: ::
OpenCV defines the following type aliases: ::
...
@@ -267,7 +267,7 @@ Another assumption OpenCV usually makes is that the top and left boundary of the
...
@@ -267,7 +267,7 @@ Another assumption OpenCV usually makes is that the top and left boundary of the
y \leq pt.y < y+height
y \leq pt.y < y+height
And virtually every loop over an image
And virtually every loop over an image
:ref:`ROI` in OpenCV (where ROI is specified by ``Rect_<int>`` ) is implemented as: ::
ROI in OpenCV (where ROI is specified by ``Rect_<int>`` ) is implemented as: ::
for(int y = roi.y; y < roi.y + rect.height; y++)
for(int y = roi.y; y < roi.y + rect.height; y++)
for(int x = roi.x; x < roi.x + rect.width; x++)
for(int x = roi.x; x < roi.x + rect.width; x++)
...
@@ -309,6 +309,8 @@ For user convenience, the following type alias is available: ::
...
@@ -309,6 +309,8 @@ For user convenience, the following type alias is available: ::
typedef Rect_<int> Rect;
typedef Rect_<int> Rect;
.. _RotatedRect:
RotatedRect
RotatedRect
-----------
-----------
...
@@ -336,8 +338,7 @@ Possibly rotated rectangle ::
...
@@ -336,8 +338,7 @@ Possibly rotated rectangle ::
};
};
The class ``RotatedRect`` replaces the old
The class ``RotatedRect`` replaces the old ``CvBox2D`` and fully compatible with it.
:ref:`CvBox2D` and fully compatible with it.
TermCriteria
TermCriteria
------------
------------
...
@@ -368,8 +369,9 @@ Termination criteria for iterative algorithms ::
...
@@ -368,8 +369,9 @@ Termination criteria for iterative algorithms ::
};
};
The class ``TermCriteria`` replaces the old
The class ``TermCriteria`` replaces the old ``CvTermCriteria`` and fully compatible with it.
:ref:`CvTermCriteria` and fully compatible with it.
.. _Matx:
Matx
Matx
----
----
...
@@ -419,6 +421,8 @@ The class represents small matrices, which type and size are known at compile ti
...
@@ -419,6 +421,8 @@ The class represents small matrices, which type and size are known at compile ti
cout << sum(Mat(m*m.t())) << endl;
cout << sum(Mat(m*m.t())) << endl;
.. _Vec:
Vec
Vec
---
---
...
@@ -456,7 +460,7 @@ Template class for short numerical vectors ::
...
@@ -456,7 +460,7 @@ Template class for short numerical vectors ::
typedef Vec<double, 4> Vec4d;
typedef Vec<double, 4> Vec4d;
typedef Vec<double, 6> Vec6d;
typedef Vec<double, 6> Vec6d;
``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 :ref:`CvScalar` or :ref:`Scalar`. The elements of ``Vec`` are accessed using ``operator[]``. All the expected vector operations are implemented too:
``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}` (plus the corresponding augmenting operations; note that these operations apply
:math:`\texttt{v1} = \texttt{v2} \pm \texttt{v3}`, :math:`\texttt{v1} = \texttt{v2} * \alpha`, :math:`\texttt{v1} = \alpha * \texttt{v2}` (plus the corresponding augmenting operations; note that these operations apply
...
@@ -466,6 +470,8 @@ Template class for short numerical vectors ::
...
@@ -466,6 +470,8 @@ Template class for short numerical vectors ::
The class ``Vec`` is commonly used to describe pixel types of multi-channel arrays, see ``Mat_`` description.
The class ``Vec`` is commonly used to describe pixel types of multi-channel arrays, see ``Mat_`` description.
.. _Scalar:
Scalar\_
Scalar\_
--------
--------
...
@@ -491,7 +497,9 @@ Scalar\_
...
@@ -491,7 +497,9 @@ Scalar\_
The template class ``Scalar_`` and it's double-precision instantiation ``Scalar`` represent 4-element vector. Being derived from ``Vec<_Tp, 4>`` , they can be used as typical 4-element vectors, but in addition they can be converted to/from ``CvScalar`` . The type ``Scalar`` is widely used in OpenCV for passing pixel values and it is a drop-in replacement for
The template class ``Scalar_`` and it's double-precision instantiation ``Scalar`` represent 4-element vector. Being derived from ``Vec<_Tp, 4>`` , they can be used as typical 4-element vectors, but in addition they can be converted to/from ``CvScalar`` . The type ``Scalar`` is widely used in OpenCV for passing pixel values and it is a drop-in replacement for
:ref:`CvScalar` that was used for the same purpose in the earlier versions of OpenCV.
``CvScalar`` that was used for the same purpose in the earlier versions of OpenCV.
.. _Range:
Range
Range
-----
-----
...
@@ -530,6 +538,8 @@ The static method ``Range::all()`` returns some special variable that means "the
...
@@ -530,6 +538,8 @@ The static method ``Range::all()`` returns some special variable that means "the
}
}
.. _Ptr:
Ptr
Ptr
---
---
...
@@ -619,6 +629,8 @@ However, if the object is deallocated in a different way, then the specialized m
...
@@ -619,6 +629,8 @@ However, if the object is deallocated in a different way, then the specialized m
: The reference increment/decrement operations are implemented as atomic operations, and therefore it is normally safe to use the classes in multi-threaded applications. The same is true for
: The reference increment/decrement operations are implemented as atomic operations, and therefore it is normally safe to use the classes in multi-threaded applications. The same is true for
:ref:`Mat` and other C++ OpenCV classes that operate on the reference counters.
:ref:`Mat` and other C++ OpenCV classes that operate on the reference counters.
.. _Mat:
Mat
Mat
---
---
...
@@ -675,6 +687,7 @@ That is, the data layout in ``Mat`` is fully compatible with ``CvMat``,``IplImag
...
@@ -675,6 +687,7 @@ That is, the data layout in ``Mat`` is fully compatible with ``CvMat``,``IplImag
There are many different ways to create ``Mat`` object. Here are the some popular ones:
There are many different ways to create ``Mat`` object. Here are the some popular ones:
*
*
using ``create(nrows, ncols, type)`` method or
using ``create(nrows, ncols, type)`` method or
the similar constructor ``Mat(nrows, ncols, type[, fillValue])`` constructor.
the similar constructor ``Mat(nrows, ncols, type[, fillValue])`` constructor.
A new array of the specified size and specifed type will be allocated. ``type`` has the same meaning as in
A new array of the specified size and specifed type will be allocated. ``type`` has the same meaning as in
...
@@ -695,6 +708,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -695,6 +708,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
or type are different from the specified.
or type are different from the specified.
*
*
similarly to above, you can create a multi-dimensional array:
similarly to above, you can create a multi-dimensional array:
::
::
...
@@ -708,6 +722,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -708,6 +722,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
note that it is pass number of dimensions =1 to the ``Mat`` constructor, but the created array will be 2-dimensional, with the number of columns set to 1. That's why ``Mat::dims`` is always >= 2 (can also be 0 when the array is empty)
note that it is pass number of dimensions =1 to the ``Mat`` constructor, but the created array will be 2-dimensional, with the number of columns set to 1. That's why ``Mat::dims`` is always >= 2 (can also be 0 when the array is empty)
*
*
by using a copy constructor or assignment operator, where on the right side it can
by using a copy constructor or assignment operator, where on the right side it can
be a array or expression, see below. Again, as noted in the introduction,
be a array or expression, see below. Again, as noted in the introduction,
array assignment is O(1) operation because it only copies the header
array assignment is O(1) operation because it only copies the header
...
@@ -715,6 +730,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -715,6 +730,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
(a.k.a. deep) copy of the array when you need it.
(a.k.a. deep) copy of the array when you need it.
*
*
by constructing a header for a part of another array. It can be a single row, single column,
by constructing a header for a part of another array. It can be a single row, single column,
several rows, several columns, rectangular region in the array (called a minor in algebra) or
several rows, several columns, rectangular region in the array (called a minor in algebra) or
a diagonal. Such operations are also O(1), because the new header will reference the same data.
a diagonal. Such operations are also O(1), because the new header will reference the same data.
...
@@ -760,6 +776,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -760,6 +776,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
of the extracted sub-matrices.
of the extracted sub-matrices.
*
*
by making a header for user-allocated-data. It can be useful for
by making a header for user-allocated-data. It can be useful for
#.
#.
...
@@ -787,7 +804,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -787,7 +804,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
..
..
partial yet very common cases of this "user-allocated data" case are conversions from :ref:`CvMat` and :ref:`IplImage` to ``Mat``. For this purpose there are special constructors taking pointers to ``CvMat`` or ``IplImage`` and the optional flag indicating whether to copy the data or not.
partial yet very common cases of this "user-allocated data" case are conversions from ``CvMat`` and ``IplImage`` to ``Mat``. For this purpose there are special constructors taking pointers to ``CvMat`` or ``IplImage`` and the optional flag indicating whether to copy the data or not.
Backward conversion from ``Mat`` to ``CvMat`` or ``IplImage`` is provided via cast operators ``Mat::operator CvMat() const`` an ``Mat::operator IplImage()``. The operators do *not* copy the data.
Backward conversion from ``Mat`` to ``CvMat`` or ``IplImage`` is provided via cast operators ``Mat::operator CvMat() const`` an ``Mat::operator IplImage()``. The operators do *not* copy the data.
...
@@ -802,6 +819,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -802,6 +819,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
..
..
*
*
by using MATLAB-style array initializers, ``zeros(), ones(), eye()`` , e.g.:
by using MATLAB-style array initializers, ``zeros(), ones(), eye()`` , e.g.:
::
::
...
@@ -812,6 +830,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
...
@@ -812,6 +830,7 @@ There are many different ways to create ``Mat`` object. Here are the some popula
..
..
*
*
by using comma-separated initializer:
by using comma-separated initializer:
::
::
...
@@ -878,6 +897,8 @@ Finally, there are STL-style iterators that are smart enough to skip gaps betwee
...
@@ -878,6 +897,8 @@ Finally, there are STL-style iterators that are smart enough to skip gaps betwee
The matrix iterators are random-access iterators, so they can be passed to any STL algorithm, including ``std::sort()`` .
The matrix iterators are random-access iterators, so they can be passed to any STL algorithm, including ``std::sort()`` .
.. _MatrixExpressions:
Matrix Expressions
Matrix Expressions
------------------
------------------
...
@@ -933,6 +954,8 @@ Below is the formal description of the ``Mat`` methods.
...
@@ -933,6 +954,8 @@ Below is the formal description of the ``Mat`` methods.
.. index:: Mat::Mat
.. index:: Mat::Mat
.. _Mat::Mat:
Mat::Mat
Mat::Mat
------------
------------
.. c:function:: (1) Mat::Mat()
.. c:function:: (1) Mat::Mat()
...
@@ -941,39 +964,39 @@ Mat::Mat
...
@@ -941,39 +964,39 @@ Mat::Mat
.. c:function:: (3) Mat::Mat(Size size, int type)
.. c:function:: (3) Mat::Mat(Size size, int type)
.. c:function:: (4) Mat::Mat(int rows, int cols, int type, const Scalar\& s)
.. c:function:: (4) Mat::Mat(int rows, int cols, int type, const Scalar& s)
.. c:function:: (5) Mat::Mat(Size size, int type, const Scalar\& s)
.. c:function:: (5) Mat::Mat(Size size, int type, const Scalar& s)
.. c:function:: (6) Mat::Mat(const Mat\& m)
.. c:function:: (6) Mat::Mat(const Mat& m)
.. c:function:: (7) Mat::Mat(int rows, int cols, int type, void* data, size_t step=AUTO_STEP)
.. c:function:: (7) Mat::Mat(int rows, int cols, int type, void* data, size_t step=AUTO_STEP)
.. c:function:: (20) Mat::Mat(const Mat\& m, const Range* ranges)
.. c:function:: (20) Mat::Mat(const Mat& m, const Range* ranges)
Various array constructors
Various array constructors
...
@@ -1013,7 +1036,7 @@ Mat::Mat
...
@@ -1013,7 +1036,7 @@ Mat::Mat
.
.
:param expr: Matrix expression. See :ref:`Matrix Expressions` .
:param expr: Matrix expression. See :ref:`MatrixExpressions`.
These are various constructors that form a matrix. As noticed in the
These are various constructors that form a matrix. As noticed in the
, often the default constructor is enough, and the proper matrix will be allocated by an OpenCV function. The constructed matrix can further be assigned to another matrix or matrix expression, in which case the old content is dereferenced, or be allocated with
, often the default constructor is enough, and the proper matrix will be allocated by an OpenCV function. The constructed matrix can further be assigned to another matrix or matrix expression, in which case the old content is dereferenced, or be allocated with
...
@@ -1021,9 +1044,9 @@ These are various constructors that form a matrix. As noticed in the
...
@@ -1021,9 +1044,9 @@ These are various constructors that form a matrix. As noticed in the
.. index:: Mat::Mat
.. index:: Mat::Mat
Mat::Mat
Mat::~Mat
------------
------------
.. c:function:: Mat::\textasciitilde Mat()
.. cpp:function:: Mat::~Mat()
Matrix destructor
Matrix destructor
...
@@ -1034,11 +1057,11 @@ The matrix destructor calls
...
@@ -1034,11 +1057,11 @@ The matrix destructor calls
Mat::operator =
Mat::operator =
-------------------
-------------------
.. c:function:: Mat\& Mat::operator = (const Mat\& m)
.. cpp:function:: Mat& Mat::operator = (const Mat& m)
The class is used for implementation of unary, binary and, generally, n-ary element-wise operations on multi-dimensional arrays. Some of the arguments of n-ary function may be continuous arrays, some may be not. It is possible to use conventional
The class is used for implementation of unary, binary and, generally, n-ary element-wise operations on multi-dimensional arrays. Some of the arguments of n-ary function may be continuous arrays, some may be not. It is possible to use conventional
:ref:`MatIterator` 's for each array, but it can be a big overhead to increment all of the iterators after each small operations. That's where ``NAryMatIterator`` can be used. Using it, you can iterate though several matrices simultaneously as long as they have the same geometry (dimensionality and all the dimension sizes are the same). On each iteration ``it.planes[0]``,``it.planes[1]`` , ... will be the slices of the corresponding matrices.
``MatIterator`` 's for each array, but it can be a big overhead to increment all of the iterators after each small operations. That's where ``NAryMatIterator`` can be used. Using it, you can iterate though several matrices simultaneously as long as they have the same geometry (dimensionality and all the dimension sizes are the same). On each iteration ``it.planes[0]``,``it.planes[1]`` , ... will be the slices of the corresponding matrices.
Here is an example of how you can compute a normalized and thresholded 3D color histogram: ::
Here is an example of how you can compute a normalized and thresholded 3D color histogram: ::
...
@@ -2057,6 +2153,8 @@ Here is an example of how you can compute a normalized and thresholded 3D color
...
@@ -2057,6 +2153,8 @@ Here is an example of how you can compute a normalized and thresholded 3D color
}
}
.. _SparseMat:
SparseMat
SparseMat
---------
---------
...
@@ -2278,9 +2376,7 @@ The class ``SparseMat`` represents multi-dimensional sparse numerical arrays. Su
...
@@ -2278,9 +2376,7 @@ The class ``SparseMat`` represents multi-dimensional sparse numerical arrays. Su
..
..
#.
#.
sparse matrix iterators. Like
sparse matrix iterators. They are similar to ``MatIterator``, but different from :ref:`NAryMatIterator`. That is, the iteration loop is familiar to STL users:
:ref:`Mat` iterators and unlike
:ref:`MatND` iterators, the sparse matrix iterators are STL-style, that is, the iteration loop is familiar to C++ users:
::
::
...
@@ -2362,7 +2458,6 @@ Template sparse n-dimensional array class derived from
...
@@ -2362,7 +2458,6 @@ Template sparse n-dimensional array class derived from
SparseMat_& operator = (const SparseMat& m);
SparseMat_& operator = (const SparseMat& m);
SparseMat_& operator = (const SparseMat_& m);
SparseMat_& operator = (const SparseMat_& m);
SparseMat_& operator = (const Mat& m);
SparseMat_& operator = (const Mat& m);
SparseMat_& operator = (const MatND& m);
// equivalent to the correspoding parent class methods
// equivalent to the correspoding parent class methods
OpenCV (Open Source Computer Vision Library: http://opencv.willowgarage.com/wiki/) is open-source BSD-licensed library that includes several hundreds computer vision algorithms. It is very popular in the Computer Vision community. Some people call it “de-facto standard” API. The document aims to specify the stable parts of the library, as well as some abstract interfaces for high-level interfaces, with the final goal to make it an official standard.
OpenCV (Open Source Computer Vision Library: http://opencv.willowgarage.com/wiki/) is open-source BSD-licensed library that includes several hundreds computer vision algorithms. The document describes the so-called OpenCV 2.x API, which is essentially a C++ API, as opposite to the C-based OpenCV 1.x API. The latter is described in opencv1x.pdf.
API specifications in the document use the standard C++ (http://www.open-std.org/jtc1/sc22/wg21/) and the standard C++ library.
OpenCV has a modular structure (i.e. package includes several shared or static libraries). The modules are:
The current OpenCV implementation has a modular structure (i.e. the binary package includes several shared or static libraries), where we have:
* **core** - the compact module defining basic data structures, including the dense multi-dimensional array ``Mat``, and basic functions, used by all other modules.
* **core** - the compact module defining basic data structures, including the dense multi-dimensional array ``Mat``, and basic functions, used by all other modules.
* **imgproc** - image processing module that includes linear and non-linear image filtering, geometrical image transformations (resize, affine and perspective warping, generic table-based remap), color space conversion, histograms etc.
* **imgproc** - image processing module that includes linear and non-linear image filtering, geometrical image transformations (resize, affine and perspective warping, generic table-based remap), color space conversion, histograms etc.
...
@@ -18,9 +16,7 @@ The current OpenCV implementation has a modular structure (i.e. the binary packa
...
@@ -18,9 +16,7 @@ The current OpenCV implementation has a modular structure (i.e. the binary packa
* **gpu** - GPU-accelerated algorithms from different OpenCV modules.
* **gpu** - GPU-accelerated algorithms from different OpenCV modules.
* ... some other helper modules, such as FLANN and Google test wrappers, Python bindings etc.
* ... some other helper modules, such as FLANN and Google test wrappers, Python bindings etc.
Although the alternative implementations of the proposed standard may be structured differently, the proposed standard draft is organized by the functionality groups that reflect the decomposition of the library by modules.
The further chapters of the document describe functionality of each module. But first, let's make an overview of the common API concepts, used thoroughly in the library.
Below are the other main concepts of the OpenCV API, implied everywhere in the document.
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. in the case of multi-channel arrays each channel is processed independently.
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. in the case of multi-channel arrays each channel is processed independently.
@@ -315,15 +303,16 @@ The functions ``bitwise_xor`` compute per-element bit-wise logical "exclusive or
...
@@ -315,15 +303,16 @@ The functions ``bitwise_xor`` compute per-element bit-wise logical "exclusive or
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. in the case of multi-channel arrays each channel is processed independently.
In the case of floating-point arrays their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. in the case of multi-channel arrays each channel is processed independently.
See also:,,
.. index:: calcCovarMatrix
.. index:: calcCovarMatrix
.. _calcCovarMatrix:
calcCovarMatrix
calcCovarMatrix
-------------------
---------------
.. c:function:: void calcCovarMatrix( const Mat* samples, int nsamples, Mat\& covar, Mat\& mean, int flags, int ctype=CV_64F)
.. c:function:: void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean, int flags, int ctype=CV_64F)
.. c:function:: void calcCovarMatrix( const Mat\& samples, Mat\& covar, Mat\& mean, int flags, int ctype=CV_64F)
.. c:function:: void calcCovarMatrix( const Mat& samples, Mat& covar, Mat& mean, int flags, int ctype=CV_64F)
Scales, computes absolute values and converts the result to 8-bit.
Scales, computes absolute values and converts the result to 8-bit.
...
@@ -528,11 +526,12 @@ See also:
...
@@ -528,11 +526,12 @@ See also:
.. index:: countNonZero
.. index:: countNonZero
.. _countNonZero:
countNonZero
countNonZero
----------------
------------
.. c:function:: int countNonZero( const Mat\& mtx )
.. c:function:: int countNonZero( const MatND\& mtx )
.. c:function:: int countNonZero( const Mat& mtx )
Counts non-zero array elements.
Counts non-zero array elements.
...
@@ -549,8 +548,11 @@ See also:
...
@@ -549,8 +548,11 @@ See also:
.. index:: cubeRoot
.. index:: cubeRoot
.. _cubeRoot:
cubeRoot
cubeRoot
------------
--------
.. c:function:: float cubeRoot(float val)
.. c:function:: float cubeRoot(float val)
Computes cube root of the argument
Computes cube root of the argument
...
@@ -562,13 +564,16 @@ and :math:`\pm\infty` are not handled. The accuracy approaches the maximum possi
...
@@ -562,13 +564,16 @@ and :math:`\pm\infty` are not handled. The accuracy approaches the maximum possi
.. index:: cvarrToMat
.. index:: cvarrToMat
.. _cvarrToMat:
cvarrToMat
cvarrToMat
--------------
----------
.. c:function:: Mat cvarrToMat(const CvArr* src, bool copyData=false, bool allowND=true, int coiMode=0)
.. c:function:: Mat cvarrToMat(const CvArr* src, bool copyData=false, bool allowND=true, int coiMode=0)
Converts CvMat, IplImage or CvMatND to Mat.
Converts ``CvMat``, ``IplImage`` or ``CvMatND`` to ``Mat``.
:param src: The source ``CvMat`` , ``IplImage`` or ``CvMatND``
:param src: The source ``CvMat``, ``IplImage`` or ``CvMatND``
:param copyData: When it is false (default value), no data is copied, only the new header is created. In this case the original array should not be deallocated while the new matrix header is used. The the parameter is true, all the data is copied, then user may deallocate the original array right after the conversion
:param copyData: When it is false (default value), no data is copied, only the new header is created. In this case the original array should not be deallocated while the new matrix header is used. The the parameter is true, all the data is copied, then user may deallocate the original array right after the conversion
...
@@ -580,16 +585,14 @@ cvarrToMat
...
@@ -580,16 +585,14 @@ cvarrToMat
* If ``coiMode=1`` , the function will never report an error; instead it returns the header to the whole original image and user will have to check and process COI manually, see :func:`extractImageCOI` .
* If ``coiMode=1`` , the function will never report an error; instead it returns the header to the whole original image and user will have to check and process COI manually, see :func:`extractImageCOI` .
The function ``cvarrToMat`` converts
The function ``cvarrToMat`` converts ``CvMat``, ``IplImage`` or ``CvMatND`` header to
:ref:`CvMat`,:ref:`IplImage` or
:ref:`CvMatND` header to
:func:`Mat` header, and optionally duplicates the underlying data. The constructed header is returned by the function.
:func:`Mat` header, and optionally duplicates the underlying data. The constructed header is returned by the function.
When ``copyData=false`` , the conversion is done really fast (in O(1) time) and the newly created matrix header will have ``refcount=0`` , which means that no reference counting is done for the matrix data, and user has to preserve the data until the new header is destructed. Otherwise, when ``copyData=true`` , the new buffer will be allocated and managed as if you created a new matrix from scratch and copy the data there. That is, ``cvarrToMat(src, true) :math:`\sim` cvarrToMat(src, false).clone()`` (assuming that COI is not set). The function provides uniform way of supporting
When ``copyData=false`` , the conversion is done really fast (in O(1) time) and the newly created matrix header will have ``refcount=0`` , which means that no reference counting is done for the matrix data, and user has to preserve the data until the new header is destructed. Otherwise, when ``copyData=true`` , the new buffer will be allocated and managed as if you created a new matrix from scratch and copy the data there. That is, ``cvarrToMat(src, true) :math:`\sim` cvarrToMat(src, false).clone()`` (assuming that COI is not set). The function provides uniform way of supporting
:ref:`CvArr` paradigm in the code that is migrated to use new-style data structures internally. The reverse transformation, from
``CvArr`` paradigm in the code that is migrated to use new-style data structures internally. The reverse transformation, from
:func:`Mat` to
:func:`Mat` to
:ref:`CvMat` or
``CvMat`` or
:ref:`IplImage` can be done by simple assignment: ::
``IplImage`` can be done by simple assignment: ::
CvMat* A = cvCreateMat(10, 10, CV_32F);
CvMat* A = cvCreateMat(10, 10, CV_32F);
cvSetIdentity(A);
cvSetIdentity(A);
...
@@ -606,12 +609,12 @@ When ``copyData=false`` , the conversion is done really fast (in O(1) time) and
...
@@ -606,12 +609,12 @@ When ``copyData=false`` , the conversion is done really fast (in O(1) time) and
Normally, the function is used to convert an old-style 2D array (
Normally, the function is used to convert an old-style 2D array (
:ref:`CvMat` or
``CvMat`` or
:ref:`IplImage` ) to ``Mat`` , however, the function can also take
``IplImage`` ) to ``Mat`` , however, the function can also take
:ref:`CvMatND` on input and create
``CvMatND`` on input and create
:func:`Mat` for it, if it's possible. And for ``CvMatND A`` it is possible if and only if ``A.dim[i].size*A.dim.step[i] == A.dim.step[i-1]`` for all or for all but one ``i, 0 < i < A.dims`` . That is, the matrix data should be continuous or it should be representable as a sequence of continuous matrices. By using this function in this way, you can process
:func:`Mat` for it, if it's possible. And for ``CvMatND A`` it is possible if and only if ``A.dim[i].size*A.dim.step[i] == A.dim.step[i-1]`` for all or for all but one ``i, 0 < i < A.dims`` . That is, the matrix data should be continuous or it should be representable as a sequence of continuous matrices. By using this function in this way, you can process
:ref:`CvMatND` using arbitrary element-wise function. But for more complex operations, such as filtering functions, it will not work, and you need to convert
``CvMatND`` using arbitrary element-wise function. But for more complex operations, such as filtering functions, it will not work, and you need to convert
:ref:`CvMatND` to
``CvMatND`` to
:func:`MatND` using the corresponding constructor of the latter.
:func:`MatND` using the corresponding constructor of the latter.
The last parameter, ``coiMode`` , specifies how to react on an image with COI set: by default it's 0, and then the function reports an error when an image with COI comes in. And ``coiMode=1`` means that no error is signaled - user has to check COI presence and handle it manually. The modern structures, such as
The last parameter, ``coiMode`` , specifies how to react on an image with COI set: by default it's 0, and then the function reports an error when an image with COI comes in. And ``coiMode=1`` means that no error is signaled - user has to check COI presence and handle it manually. The modern structures, such as
...
@@ -627,9 +630,11 @@ See also:
...
@@ -627,9 +630,11 @@ See also:
.. index:: dct
.. index:: dct
.. _dct:
dct
dct
-------
-------
.. c:function:: void dct(const Mat\& src, Mat\& dst, int flags=0)
.. c:function:: void dct(const Mat& src, Mat& dst, int flags=0)
Performs a forward or inverse discrete cosine transform of 1D or 2D array
Performs a forward or inverse discrete cosine transform of 1D or 2D array
...
@@ -715,9 +720,12 @@ See also:
...
@@ -715,9 +720,12 @@ See also:
.. index:: dft
.. index:: dft
.. _dft:
dft
dft
-------
---
.. c:function:: void dft(const Mat\& src, Mat\& dst, int flags=0, int nonzeroRows=0)
.. c:function:: void dft(const Mat& src, Mat& dst, int flags=0, int nonzeroRows=0)
Performs a forward or inverse Discrete Fourier transform of 1D or 2D floating-point array.
Performs a forward or inverse Discrete Fourier transform of 1D or 2D floating-point array.
...
@@ -779,23 +787,17 @@ in the case of 1D transform of real vector, the output will look as the first ro
...
@@ -779,23 +787,17 @@ in the case of 1D transform of real vector, the output will look as the first ro
So, the function chooses the operation mode depending on the flags and size of the input array:
So, the function chooses the operation mode depending on the flags and size of the input array:
*
* if ``DFT_ROWS`` is set or the input array has single row or single column then the function performs 1D forward or inverse transform (of each row of a matrix when ``DFT_ROWS`` is set, otherwise it will be 2D transform.
if ``DFT_ROWS`` is set or the input array has single row or single column then the function performs 1D forward or inverse transform (of each row of a matrix when ``DFT_ROWS`` is set, otherwise it will be 2D transform.
*
* if input array is real and ``DFT_INVERSE`` is not set, the function does forward 1D or 2D transform:
if input array is real and ``DFT_INVERSE`` is not set, the function does forward 1D or 2D transform:
*
* when ``DFT_COMPLEX_OUTPUT`` is set then the output will be complex matrix of the same size as input.
when ``DFT_COMPLEX_OUTPUT`` is set then the output will be complex matrix of the same size as input.
*
* otherwise the output will be a real matrix of the same size as input. in the case of 2D transform it will use the packed format as shown above; in the case of single 1D transform it will look as the first row of the above matrix; in the case of multiple 1D transforms (when using ``DCT_ROWS`` flag) each row of the output matrix will look like the first row of the above matrix.
otherwise the output will be a real matrix of the same size as input. in the case of 2D transform it will use the packed format as shown above; in the case of single 1D transform it will look as the first row of the above matrix; in the case of multiple 1D transforms (when using ``DCT_ROWS`` flag) each row of the output matrix will look like the first row of the above matrix.
*
* otherwise, if the input array is complex and either ``DFT_INVERSE`` or ``DFT_REAL_OUTPUT`` are not set then the output will be a complex array of the same size as input and the function will perform the forward or inverse 1D or 2D transform of the whole input array or each row of the input array independently, depending on the flags ``DFT_INVERSE`` and ``DFT_ROWS``.
otherwise, if the input array is complex and either ``DFT_INVERSE`` or ``DFT_REAL_OUTPUT`` are not set then the output will be a complex array of the same size as input and the function will perform the forward or inverse 1D or 2D transform of the whole input array or each row of the input array independently, depending on the flags ``DFT_INVERSE`` and ``DFT_ROWS`` .
*
* otherwise, i.e. when ``DFT_INVERSE`` is set, the input array is real, or it is complex but ``DFT_REAL_OUTPUT`` is set, the output will be a real array of the same size as input, and the function will perform 1D or 2D inverse transformation of the whole input array or each individual row, depending on the flags ``DFT_INVERSE`` and ``DFT_ROWS``.
otherwise, i.e. when ``DFT_INVERSE`` is set, the input array is real, or it is complex but ``DFT_REAL_OUTPUT`` is set, the output will be a real array of the same size as input, and the function will perform 1D or 2D inverse transformation of the whole input array or each individual row, depending on the flags ``DFT_INVERSE`` and ``DFT_ROWS`` .
The scaling is done after the transformation if ``DFT_SCALE`` is set.
The scaling is done after the transformation if ``DFT_SCALE`` is set.
@@ -2404,9 +2558,12 @@ The function ``randShuffle`` shuffles the specified 1D array by randomly choosin
...
@@ -2404,9 +2558,12 @@ The function ``randShuffle`` shuffles the specified 1D array by randomly choosin
.. index:: reduce
.. index:: reduce
.. _reduce:
reduce
reduce
----------
------
.. c:function:: void reduce(const Mat\& mtx, Mat\& vec, int dim, int reduceOp, int dtype=-1)
.. c:function:: void reduce(const Mat& mtx, Mat& vec, int dim, int reduceOp, int dtype=-1)
Reduces a matrix to a vector
Reduces a matrix to a vector
...
@@ -2430,16 +2587,18 @@ reduce
...
@@ -2430,16 +2587,18 @@ reduce
The function ``reduce`` reduces 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 an raster image. In the 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.
The function ``reduce`` reduces 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 an raster image. In the 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:
See also: :func:`repeat`
:func:`repeat`
.. index:: repeat
.. index:: repeat
.. _repeat:
repeat
repeat
----------
------
.. c:function:: void repeat(const Mat\& src, int ny, int nx, Mat\& dst)
.. c:function:: Mat repeat(const Mat\& src, int ny, int nx)
.. c:function:: void repeat(const Mat& src, int ny, int nx, Mat& dst)
.. c:function:: Mat repeat(const Mat& src, int ny, int nx)
Fill the destination array with repeated copies of the source array.
Fill the destination array with repeated copies of the source array.
.. c:function:: Mat imread( const string\& filename, int flags=1 )
.. c:function:: Mat imread( const string\& filename, int flags=1 )
...
@@ -61,34 +67,19 @@ imread
...
@@ -61,34 +67,19 @@ imread
The function ``imread`` loads an image from the specified file and returns it. If the image can not be read (because of missing file, improper permissions, unsupported or invalid format), the function returns empty matrix ( ``Mat::data==NULL`` ).Currently, the following file formats are supported:
The function ``imread`` loads an image from the specified file and returns it. If the image can not be read (because of missing file, improper permissions, unsupported or invalid format), the function returns empty matrix ( ``Mat::data==NULL`` ).Currently, the following file formats are supported:
*
* Windows bitmaps - ``*.bmp, *.dib`` (always supported)
Windows bitmaps - ``*.bmp, *.dib`` (always supported)
*
* JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see **Note2**)
JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see
**Note2**
)
*
* JPEG 2000 files - ``*.jp2`` (see **Note2**)
JPEG 2000 files - ``*.jp2`` (see
**Note2**
)
*
* Portable Network Graphics - ``*.png`` (see **Note2**)
Portable Network Graphics - ``*.png`` (see
**Note2**
)
*
* Portable image format - ``*.pbm, *.pgm, *.ppm`` (always supported)
Portable image format - ``*.pbm, *.pgm, *.ppm`` (always supported)
*
* Sun rasters - ``*.sr, *.ras`` (always supported)
Sun rasters - ``*.sr, *.ras`` (always supported)
*
* TIFF files - ``*.tiff, *.tif`` (see **Note2**)
TIFF files - ``*.tiff, *.tif`` (see
**Note2**
)
**Note1**
**Note1**
: The function determines type of the image by the content, not by the file extension.
: The function determines type of the image by the content, not by the file extension.
...
@@ -100,6 +91,8 @@ On Linux, BSD flavors and other Unix-like open-source operating systems OpenCV l
...
@@ -100,6 +91,8 @@ On Linux, BSD flavors and other Unix-like open-source operating systems OpenCV l
@@ -84,9 +88,11 @@ The function ``imshow`` displays the image in the specified window. If the windo
...
@@ -84,9 +88,11 @@ The function ``imshow`` displays the image in the specified window. If the windo
.. index:: namedWindow
.. index:: namedWindow
.. _namedWindow:
namedWindow
namedWindow
---------------
---------------
.. c:function:: void namedWindow( const string\& winname, int flags )
.. c:function:: void namedWindow( const string& winname, int flags )
Creates a window.
Creates a window.
...
@@ -104,7 +110,7 @@ qt-specific details:
...
@@ -104,7 +110,7 @@ qt-specific details:
* **flags** Flags of the window. Currently the supported flags are:
* **flags** Flags of the window. Currently the supported flags are:
* **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` let the user resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window's size to fit the displayed image (see :ref:`ShowImage` ), and the user can not change the window size manually.
* **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` let the user resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window's size to fit the displayed image (see :ref:`imshow` ), and the user can not change the window size manually.
* **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjust the image without respect the its ration, whereas ``CV_WINDOW_KEEPRATIO`` keep the image's ratio.
* **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjust the image without respect the its ration, whereas ``CV_WINDOW_KEEPRATIO`` keep the image's ratio.
@@ -7,7 +9,7 @@ A common machine learning task is supervised learning. In supervised learning, t
...
@@ -7,7 +9,7 @@ A common machine learning task is supervised learning. In supervised learning, t
:math:`y` . Predicting the qualitative output is called classification, while predicting the quantitative output is called regression.
:math:`y` . Predicting the qualitative output is called classification, while predicting the quantitative output is called regression.
Boosting is a powerful learning concept, which provide a solution to the supervised classification learning task. It combines the performance of many "weak" classifiers to produce a powerful 'committee'
Boosting is a powerful learning concept, which provide a solution to the supervised classification learning task. It combines the performance of many "weak" classifiers to produce a powerful 'committee'
:ref:`HTF01` . A weak classifier is only required to be better than chance, and thus can be very simple and computationally inexpensive. Many of them smartly combined, however, results in a strong classifier, which often outperforms most 'monolithic' strong classifiers such as SVMs and Neural Networks.
:ref:`[HTF01] <HTF01>` . A weak classifier is only required to be better than chance, and thus can be very simple and computationally inexpensive. Many of them smartly combined, however, results in a strong classifier, which often outperforms most 'monolithic' strong classifiers such as SVMs and Neural Networks.
Decision trees are the most popular weak classifiers used in boosting schemes. Often the simplest decision trees with only a single split node per tree (called stumps) are sufficient.
Decision trees are the most popular weak classifiers used in boosting schemes. Often the simplest decision trees with only a single split node per tree (called stumps) are sufficient.
...
@@ -20,7 +22,7 @@ The boosted model is based on
...
@@ -20,7 +22,7 @@ The boosted model is based on
:math:`K` -component vector. Each component encodes a feature relevant for the learning task at hand. The desired two-class output is encoded as -1 and +1.
:math:`K` -component vector. Each component encodes a feature relevant for the learning task at hand. The desired two-class output is encoded as -1 and +1.
Different variants of boosting are known such as Discrete Adaboost, Real AdaBoost, LogitBoost, and Gentle AdaBoost
Different variants of boosting are known such as Discrete Adaboost, Real AdaBoost, LogitBoost, and Gentle AdaBoost
:ref:`FHT98` . All of them are very similar in their overall structure. Therefore, we will look only at the standard two-class Discrete AdaBoost algorithm as shown in the box below. Each sample is initially assigned the same weight (step 2). Next a weak classifier
:ref:`[FHT98] <FHT98>` . All of them are very similar in their overall structure. Therefore, we will look only at the standard two-class Discrete AdaBoost algorithm as shown in the box below. Each sample is initially assigned the same weight (step 2). Next a weak classifier
:math:`f_{m(x)}` is trained on the weighted training data (step 3a). Its weighted training error and scaling factor
:math:`f_{m(x)}` is trained on the weighted training data (step 3a). Its weighted training error and scaling factor
:math:`c_m` is computed (step 3b). The weights are increased for training samples, which have been misclassified (step 3c). All weights are then normalized, and the process of finding the next weak classifier continues for another
:math:`c_m` is computed (step 3b). The weights are increased for training samples, which have been misclassified (step 3c). All weights are then normalized, and the process of finding the next weak classifier continues for another
:math:`M` -1 times. The final classifier
:math:`M` -1 times. The final classifier
...
@@ -65,15 +67,20 @@ As well as the classical boosting methods, the current implementation supports 2
...
@@ -65,15 +67,20 @@ As well as the classical boosting methods, the current implementation supports 2
:math:`>` 2 classes there is the
:math:`>` 2 classes there is the
**AdaBoost.MH**
**AdaBoost.MH**
algorithm, described in
algorithm, described in
:ref:`FHT98` , that reduces the problem to the 2-class problem, yet with a much larger training set.
:ref:`[FHT98] <FHT98>` , that reduces the problem to the 2-class problem, yet with a much larger training set.
In order to reduce computation time for boosted models without substantially losing accuracy, the influence trimming technique may be employed. As the training algorithm proceeds and the number of trees in the ensemble is increased, a larger number of the training samples are classified correctly and with increasing confidence, thereby those samples receive smaller weights on the subsequent iterations. Examples with very low relative weight have small impact on training of the weak classifier. Thus such examples may be excluded during the weak classifier training without having much effect on the induced classifier. This process is controlled with the weight_trim_rate parameter. Only examples with the summary fraction weight_trim_rate of the total weight mass are used in the weak classifier training. Note that the weights for
In order to reduce computation time for boosted models without substantially losing accuracy, the influence trimming technique may be employed. As the training algorithm proceeds and the number of trees in the ensemble is increased, a larger number of the training samples are classified correctly and with increasing confidence, thereby those samples receive smaller weights on the subsequent iterations. Examples with very low relative weight have small impact on training of the weak classifier. Thus such examples may be excluded during the weak classifier training without having much effect on the induced classifier. This process is controlled with the weight_trim_rate parameter. Only examples with the summary fraction weight_trim_rate of the total weight mass are used in the weak classifier training. Note that the weights for
**all**
**all**
training examples are recomputed at each training iteration. Examples deleted at a particular iteration may be used again for learning some of the weak classifiers further
training examples are recomputed at each training iteration. Examples deleted at a particular iteration may be used again for learning some of the weak classifiers further
:ref:`FHT98` .
:ref:`[FHT98] <FHT98>` .
.. _HTF01:
[HTF01] Hastie, T., Tibshirani, R., Friedman, J. H. The Elements of Statistical Learning: Data Mining, Inference, and Prediction. Springer Series in Statistics. 2001.**
.. _FHT98:
**[HTF01] Hastie, T., Tibshirani, R., Friedman, J. H. The Elements of Statistical Learning: Data Mining, Inference, and Prediction. Springer Series in Statistics. 2001.**
[FHT98] Friedman, J. H., Hastie, T. and Tibshirani, R. Additive Logistic Regression: a Statistical View of Boosting. Technical Report, Dept. of Statistics, Stanford University, 1998.**
**[FHT98] Friedman, J. H., Hastie, T. and Tibshirani, R. Additive Logistic Regression: a Statistical View of Boosting. Technical Report, Dept. of Statistics, Stanford University, 1998.**
@@ -57,7 +57,7 @@ Alternatively, the algorithm may start with the M-step when the initial values f
...
@@ -57,7 +57,7 @@ Alternatively, the algorithm may start with the M-step when the initial values f
:math:`p_{i,k}` can be provided. Another alternative when
:math:`p_{i,k}` can be provided. Another alternative when
:math:`p_{i,k}` are unknown, is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
:math:`p_{i,k}` are unknown, is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
:math:`p_{i,k}` . Often (and in ML) the
:math:`p_{i,k}` . Often (and in ML) the
:ref:`KMeans2` algorithm is used for that purpose.
:ref:`kmeans` algorithm is used for that purpose.
One of the main that EM algorithm should deal with is the large number
One of the main that EM algorithm should deal with is the large number
of parameters to estimate. The majority of the parameters sits in
of parameters to estimate. The majority of the parameters sits in
...
@@ -197,12 +197,12 @@ CvEM::train
...
@@ -197,12 +197,12 @@ CvEM::train
Estimates the Gaussian mixture parameters from the sample set.
Estimates the Gaussian mixture parameters from the sample set.
Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or the function values) on input. Instead, it computes the
Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or the function values) on input. Instead, it computes the
:ref:`MLE` of the Gaussian mixture parameters from the input sample set, stores all the parameters inside the structure:
*Maximum Likelihood Estimate* of the Gaussian mixture parameters from the input sample set, stores all the parameters inside the structure:
:math:`p_{i,k}` in ``probs``,:math:`a_k` in ``means`` :math:`S_k` in ``covs[k]``,:math:`\pi_k` in ``weights`` and optionally computes the output "class label" for each sample:
:math:`p_{i,k}` in ``probs``,:math:`a_k` in ``means`` :math:`S_k` in ``covs[k]``,:math:`\pi_k` in ``weights`` and optionally computes the output "class label" for each sample:
:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (i.e. indices of the most-probable mixture for each sample).
:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (i.e. indices of the most-probable mixture for each sample).
The trained model can be used further for prediction, just like any other classifier. The model trained is similar to the
The trained model can be used further for prediction, just like any other classifier. The model trained is similar to the
:ref:`Bayes classifier`.
:ref:`Bayes classifier`.
Example: Clustering random samples of multi-Gaussian distribution using EM ::
Example: Clustering random samples of multi-Gaussian distribution using EM ::
This is a simple classification model assuming that feature vectors from each class are normally distributed (though, not necessarily independently distributed), so the whole data distribution function is assumed to be a Gaussian mixture, one component per class. Using the training data the algorithm estimates mean vectors and covariance matrices for every class, and then it uses them for prediction.
This is a simple classification model assuming that feature vectors from each class are normally distributed (though, not necessarily independently distributed), so the whole data distribution function is assumed to be a Gaussian mixture, one component per class. Using the training data the algorithm estimates mean vectors and covariance matrices for every class, and then it uses them for prediction.
**[Fukunaga90] K. Fukunaga. Introduction to Statistical Pattern Recognition. second ed., New York: Academic Press, 1990.**
**[Fukunaga90] K. Fukunaga. Introduction to Statistical Pattern Recognition. second ed., New York: Academic Press, 1990.**
