Project 3D points to the image plane given intrinsic and extrinsic parameters
*
Compute extrinsic parameters given intrinsic parameters, a few 3D points and their projections.
*
Estimate intrinsic and extrinsic camera parameters from several views of a known calibration pattern (i.e. every view is described by several 3D-2D point correspondences).
:param objectPoints:The vector of vectors of points on the calibration pattern in its coordinate system, one vector per view. If the same calibration pattern is shown in each view and it's fully visible then all the vectors will be the same, although it is possible to use partially occluded patterns, or even different patterns in different views - then the vectors will be different. The points are 3D, but since they are in the pattern coordinate system, then if the rig is planar, it may have sense to put the model to the XY coordinate plane, so that Z-coordinate of each input object point is 0
:param imagePoints:The vector of vectors of the object point projections on the calibration pattern views, one vector per a view. The projections must be in the same order as the corresponding object points.
:param cameraMatrix:The output 3x3 floating-point camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` . If ``CV_CALIB_USE_INTRINSIC_GUESS`` and/or ``CV_CALIB_FIX_ASPECT_RATIO`` are specified, some or all of ``fx, fy, cx, cy`` must be initialized before calling the function
: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 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:
***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_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_ASPECT_RATIO** The functions considers only ``fy`` as a free parameter, the ratio ``fx/fy`` stays the same as in the input ``cameraMatrix`` . When ``CV_CALIB_USE_INTRINSIC_GUESS`` is not set, the actual input values of ``fx`` and ``fy`` are ignored, only their ratio is computed and used further.
***CV_CALIB_ZERO_TANGENT_DIST** Tangential distortion coefficients :math:`(p_1, p_2)` will be set to zeros and stay zero.
***CV_CALIB_FIX_K1,...,CV_CALIB_FIX_K6** Do not change the corresponding radial distortion coefficient during the optimization. If ``CV_CALIB_USE_INTRINSIC_GUESS`` is set, the coefficient from the supplied ``distCoeffs`` matrix is used, otherwise it is set to 0.
***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.
First, it computes the initial intrinsic parameters (the option only available for planar calibration patterns) or reads them from the input parameters. The distortion coefficients are all set to zeros initially (unless some of ``CV_CALIB_FIX_K?`` are specified).
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
Also, the functions can compute the derivatives of the output vectors w.r.t the input vectors (see
:func:`matMulDeriv` ).
The functions are used inside
:func:`stereoCalibrate` but can also be used in your own code where Levenberg-Marquardt or another gradient-based solver is used to optimize a function that contains matrix multiplication.
: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)`
If the output array dimensionality is larger, an extra 1 is appended to each point. Otherwise, the input array is simply copied (with optional transposition) to the output.
: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) )
The function draws the individual chessboard corners detected as red circles if the board was not found or as colored corners connected with lines if the board was found.
***CV_CALIB_CB_ADAPTIVE_THRESH** use adaptive thresholding to convert the image to black and white, rather than a fixed threshold level (computed from the average image brightness).
***CV_CALIB_CB_FILTER_QUADS** use additional criteria (like contour area, perimeter, square-like shape) to filter out false quads that are extracted at the contour retrieval stage.
***CALIB_CB_FAST_CHECK** Runs a fast check on the image that looks for chessboard corners, and shortcuts the call if none are found. This can drastically speed up the call in the degenerate condition when
the function requires some white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environment (otherwise if there is no border and the background is dark, the outer black squares could not be segmented properly and so the square grouping and ordering algorithm will fail).
the function requires some white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environment.
:param objectPoints:The array of object points in the object coordinate space, 3xN or Nx3 1-channel, or 1xN or Nx1 3-channel, where N is the number of points. Can also pass ``vector<Point3f>`` 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 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 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
***CV_FM_7POINT** for a 7-point algorithm. :math:`N = 7`
***CV_FM_8POINT** for an 8-point algorithm. :math:`N \ge 8`
***CV_FM_RANSAC** for the RANSAC algorithm. :math:`N \ge 8`
***CV_FM_LMEDS** for the LMedS algorithm. :math:`N \ge 8`
:param param1:The parameter is used for RANSAC. It is the maximum distance from point to epipolar line in pixels, beyond which the point is considered an outlier and is not used for computing the final fundamental matrix. It can be set to something like 1-3, depending on the accuracy of the point localization, image resolution and the image noise
:param param2:The parameter is used for RANSAC or LMedS methods only. It specifies the desirable level of confidence (probability) that the estimated matrix is correct
:param status:The output array of N elements, every element of which is set to 0 for outliers and to 1 for the other points. The array is computed only in RANSAC and LMedS methods. For other methods it is set to all 1's
then the point :math:`i` is considered an outlier. If ``srcPoints`` and ``dstPoints`` are measured in pixels, it usually makes sense to set this parameter somewhere in the range 1 to 10.
The function returns the camera matrix that is either an exact copy of the input ``cameraMatrix`` (when ``centerPrinicipalPoint=false`` ), or the modified one (when ``centerPrincipalPoint`` =true).
By default, the undistortion functions in OpenCV (see ``initUndistortRectifyMap``,``undistort`` ) do not move the principal point. However, when you work with stereo, it's important to move the principal points in both views to the same y-coordinate (which is required by most of stereo correspondence algorithms), and maybe to the same x-coordinate too. So you can form the new camera matrix for each view, where the principal points will be at the center.
: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 alpha:The free scaling parameter between 0 (when all the pixels in the undistorted image will be valid) and 1 (when all the source image pixels will be retained in the undistorted image); see :ref:`StereoRectify`
:param newCameraMatrix:The output new camera matrix.
:param validPixROI:The optional output rectangle that will outline all-good-pixels region in the undistorted image. See ``roi1, roi2`` description in :ref:`StereoRectify`
The function computes
and returns
the optimal new camera matrix based on the free scaling parameter. By varying this parameter the user may retrieve only sensible pixels ``alpha=0`` , keep all the original image pixels if there is valuable information in the corners ``alpha=1`` , or get something in between. When ``alpha>0`` , the undistortion result will likely have some black pixels corresponding to "virtual" pixels outside of the captured distorted image. The original camera matrix, distortion coefficients, the computed new camera matrix and the ``newImageSize`` should be passed to
:ref:`InitUndistortRectifyMap` to produce the maps for
:param aspectRatio:If it is zero or negative, both :math:`f_x` and :math:`f_y` are estimated independently. Otherwise :math:`f_x = f_y * \texttt{aspectRatio}`
:param cameraMatrix:The input camera matrix :math:`A=\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{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 R:The optional rectification transformation in object space (3x3 matrix). ``R1`` or ``R2`` , computed by :ref:`StereoRectify` can be passed here. If the matrix is empty , the identity transformation is assumed
The function computes the joint undistortion+rectification transformation and represents the result in the form of maps for
:ref:`Remap` . The undistorted image will look like the original, as if it was captured with a camera with camera matrix ``=newCameraMatrix`` and zero distortion. In the case of monocular camera ``newCameraMatrix`` is usually equal to ``cameraMatrix`` , or it can be computed by
:ref:`GetOptimalNewCameraMatrix` for a better control over scaling. In the case of stereo camera ``newCameraMatrix`` is normally set to ``P1`` or ``P2`` computed by
Also, this new camera will be oriented differently in the coordinate space, according to ``R`` . That, for example, helps to align two heads of a stereo camera so that the epipolar lines on both images become horizontal and have the same y- coordinate (in the case of horizontally aligned stereo camera).
The function actually builds the maps for the inverse mapping algorithm that is used by
:ref:`Remap` . That is, for each pixel
:math:`(u, v)` in the destination (corrected and rectified) image the function computes the corresponding coordinates in the source image (i.e. in the original image from camera). The process is the following:
In the case of a stereo camera this function is called twice, once for each camera head, after
:ref:`StereoRectify` , which in its turn is called after
:ref:`StereoCalibrate` . But if the stereo camera was not calibrated, it is still possible to compute the rectification transformations directly from the fundamental matrix using
:ref:`StereoRectifyUncalibrated` . For each camera the function computes homography ``H`` as the rectification transformation in pixel domain, not a rotation matrix ``R`` in 3D space. The ``R`` can be computed from ``H`` as
: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 tvec:The translation vector
:param cameraMatrix:The camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{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.
Note, that by setting ``rvec=tvec=(0,0,0)`` , or by setting ``cameraMatrix`` to 3x3 identity matrix, or by passing zero distortion coefficients, you can get various useful partial cases of the function, i.e. you can compute the distorted coordinates for a sparse set of points, or apply a perspective transformation (and also compute the derivatives) in the ideal zero-distortion setup etc.
: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)
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:
:param jacobian:Optional output Jacobian matrix, 3x9 or 9x3 - partial derivatives of the output array components with respect to the input array components
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
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)
..cfunction:: StereoSGBM::StereoSGBM( int minDisparity, int numDisparities, int SADWindowSize, int P1=0, int P2=0, int disp12MaxDiff=0, int preFilterCap=0, int uniquenessRatio=0, int speckleWindowSize=0, int speckleRange=0, bool fullDP=false)
:param minDisparity:The minimum possible disparity value. Normally it is 0, but sometimes rectification algorithms can shift images, so this parameter needs to be adjusted accordingly
:param numDisparities:This is maximum disparity minus minimum disparity. Always greater than 0. In the current implementation this parameter must be divisible by 16.
:param P1, P2:Parameters that control disparity smoothness. The larger the values, the smoother the disparity. ``P1`` is the penalty on the disparity change by plus or minus 1 between neighbor pixels. ``P2`` is the penalty on the disparity change by more than 1 between neighbor pixels. The algorithm requires ``P2 > P1`` . See ``stereo_match.cpp`` sample where some reasonably good ``P1`` and ``P2`` values are shown (like ``8*number_of_image_channels*SADWindowSize*SADWindowSize`` and ``32*number_of_image_channels*SADWindowSize*SADWindowSize`` , respectively).
:param disp12MaxDiff:Maximum allowed difference (in integer pixel units) in the left-right disparity check. Set it to non-positive value to disable the check.
:param preFilterCap:Truncation value for the prefiltered image pixels. The algorithm first computes x-derivative at each pixel and clips its value by ``[-preFilterCap, preFilterCap]`` interval. The result values are passed to the Birchfield-Tomasi pixel cost function.
:param uniquenessRatio:The margin in percents by which the best (minimum) computed cost function value should "win" the second best value to consider the found match correct. Normally, some value within 5-15 range is good enough
:param speckleWindowSize:Maximum size of smooth disparity regions to consider them noise speckles and invdalidate. Set it to 0 to disable speckle filtering. Otherwise, set it somewhere in 50-200 range.
:param speckleRange:Maximum disparity variation within each connected component. If you do speckle filtering, set it to some positive value, multiple of 16. Normally, 16 or 32 is good enough.
:param fullDP:Set it to ``true`` to run full-scale 2-pass dynamic programming algorithm. It will consume O(W*H*numDisparities) bytes, which is large for 640x480 stereo and huge for HD-size pictures. By default this is ``false``
The first constructor initializes ``StereoSGBM`` with all the default parameters (so actually one will only have to set ``StereoSGBM::numberOfDisparities`` at minimum). The second constructor allows you to set each parameter to a custom value.
:param disp:The output disparity map. It will be 16-bit signed single-channel image of the same size as the input images. It will contain scaled by 16 disparity values, so that to get the floating-point disparity map, you will need to divide each ``disp`` element by 16.
The method executes SGBM 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 ``StereoSGBM`` instance from within different threads simultaneously.
:param objectPoints:The vector of vectors of points on the calibration pattern in its coordinate system, one vector per view. If the same calibration pattern is shown in each view and it's fully visible then all the vectors will be the same, although it is possible to use partially occluded patterns, or even different patterns in different views - then the vectors will be different. The points are 3D, but since they are in the pattern coordinate system, then if the rig is planar, it may have sense to put the model to the XY coordinate plane, so that Z-coordinate of each input object point is 0
:param imagePoints1:The vector of vectors of the object point projections on the calibration pattern views from the 1st camera, one vector per a view. The projections must be in the same order as the corresponding object points.
:param imagePoints2:The vector of vectors of the object point projections on the calibration pattern views from the 2nd camera, one vector per a view. The projections must be in the same order as the corresponding object points.
:param cameraMatrix1:The input/output first camera matrix: :math:`\vecthreethree{f_x^{(j)}}{0}{c_x^{(j)}}{0}{f_y^{(j)}}{c_y^{(j)}}{0}{0}{1}` , :math:`j = 0,\, 1` . If any of ``CV_CALIB_USE_INTRINSIC_GUESS`` , ``CV_CALIB_FIX_ASPECT_RATIO`` , ``CV_CALIB_FIX_INTRINSIC`` or ``CV_CALIB_FIX_FOCAL_LENGTH`` are specified, some or all of the matrices' components must be initialized; see the flags description
:param distCoeffs:The input/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. On output vector length depends on the flags.
***CV_CALIB_USE_INTRINSIC_GUESS** The flag allows the function to optimize some or all of the intrinsic parameters, depending on the other flags, but the initial values are provided by the user.
***CV_CALIB_FIX_K1,...,CV_CALIB_FIX_K6** Do not change the corresponding radial distortion coefficient during the optimization. If ``CV_CALIB_USE_INTRINSIC_GUESS`` is set, the coefficient from the supplied ``distCoeffs`` matrix is used, otherwise it is set to 0.
***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
:ref:`FindExtrinsicCameraParams2` ), 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_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 (
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.
Similarly to
:ref:`CalibrateCamera2` , the function minimizes the total re-projection error for all the points in all the available views from both cameras.
:param distCoeffs:The input vectors 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 each. If the vectors are NULL/empty, the zero distortion coefficients are assumed.
:param flags:The operation flags; may be 0 or ``CV_CALIB_ZERO_DISPARITY`` . If the flag is set, the function makes the principal points of each camera have the same pixel coordinates in the rectified views. And if the flag is not set, the function may still shift the images in horizontal or vertical direction (depending on the orientation of epipolar lines) in order to maximize the useful image area.
:param alpha:The free scaling parameter. If it is -1 or absent , the functions performs some default scaling. Otherwise the parameter should be between 0 and 1. ``alpha=0`` means that the rectified images will be zoomed and shifted so that only valid pixels are visible (i.e. there will be no black areas after rectification). ``alpha=1`` means that the rectified image will be decimated and shifted so that all the pixels from the original images from the cameras are retained in the rectified images, i.e. no source image pixels are lost. Obviously, any intermediate value yields some intermediate result between those two extreme cases.
:param newImageSize:The new image resolution after rectification. The same size should be passed to :ref:`InitUndistortRectifyMap` , see the ``stereo_calib.cpp`` sample in OpenCV samples directory. By default, i.e. when (0,0) is passed, it is set to the original ``imageSize`` . Setting it to larger value can help you to preserve details in the original image, especially when there is big radial distortion.
:param roi1, roi2:The optional output rectangles inside the rectified images where all the pixels are valid. If ``alpha=0`` , the ROIs will cover the whole images, otherwise they likely be smaller, see the picture below
The function computes the rotation matrices for each camera that (virtually) make both camera image planes the same plane. Consequently, that makes all the epipolar lines parallel and thus simplifies the dense stereo correspondence problem. On input the function takes the matrices computed by
:func:`stereoCalibrate` and on output it gives 2 rotation matrices and also 2 projection matrices in the new coordinates. The 2 cases are distinguished by the function are:
Horizontal stereo, when 1st and 2nd camera views are shifted relative to each other mainly along the x axis (with possible small vertical shift). Then in the rectified images the corresponding epipolar lines in left and right cameras will be horizontal and have the same y-coordinate. P1 and P2 will look as:
Vertical stereo, when 1st and 2nd camera views are shifted relative to each other mainly in vertical direction (and probably a bit in the horizontal direction too). Then the epipolar lines in the rectified images will be vertical and have the same x coordinate. P2 and P2 will look as:
Below is the screenshot from ``stereo_calib.cpp`` sample. Some red horizontal lines, as you can see, pass through the corresponding image regions, i.e. the images are well rectified (which is what most stereo correspondence algorithms rely on). The green rectangles are ``roi1`` and ``roi2`` - indeed, their interior are all valid pixels.
:param threshold:The optional threshold used to filter out the outliers. If the parameter is greater than zero, then all the point pairs that do not comply the epipolar geometry well enough (that is, the points for which :math:`|\texttt{points2[i]}^T*\texttt{F}*\texttt{points1[i]}|>\texttt{threshold}` ) are rejected prior to computing the homographies.
The function computes the rectification transformations without knowing intrinsic parameters of the cameras and their relative position in space, hence the suffix "Uncalibrated". Another related difference from
:ref:`StereoRectify` is that the function outputs not the rectification transformations in the object (3D) space, but the planar perspective transformations, encoded by the homography matrices ``H1`` and ``H2`` . The function implements the algorithm
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:`Undistort2` , or just the point coordinates can be corrected with
:param dst:The output (corrected) image; will have the same size and the same type as ``src``
:param cameraMatrix:The input camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{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 newCameraMatrix:Camera matrix of the distorted image. By default it is the same as ``cameraMatrix`` , but you may additionally scale and shift the result by using some different matrix
:param cameraMatrix:The camera matrix :math:`\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{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 R:The rectification transformation in object space (3x3 matrix). ``R1`` or ``R2`` , computed by :func:`StereoRectify` can be passed here. If the matrix is empty, the identity transformation 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
: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). ::
// (u,v) is the input point, (u', v') is the output point
// camera_matrix=[fx 0 cx; 0 fy cy; 0 0 1]
// P=[fx' 0 cx' tx; 0 fy' cy' ty; 0 0 1 tz]
x" = (u - cx)/fx
y" = (v - cy)/fy
(x',y') = undistort(x",y",dist_coeffs)
[X,Y,W]T = R*[x' y' 1]T
x = X/W, y = Y/W
u' = x*fx' + cx'
v' = y*fy' + cy',
..
where undistort() is approximate iterative algorithm that estimates the normalized original point coordinates out of the normalized distorted point coordinates ("normalized" means that the coordinates do not depend on the camera matrix).
