Skip to content
opencv-wasm

undistortPoints

geometryfunctionOpenCV 5.0.0
import { undistortPoints } from '@banou/opencv-wasm'

Use after await initOpenCV(). See the initialization and named imports guide.

Computes the ideal point coordinates from the observed point coordinates.

The function is similar to #undistort and #initUndistortRectifyMap but it operates on a sparse set of points instead of a raster image. Also the function performs a reverse transformation to #projectPoints. In case of a 3D object, it does not reconstruct its 3D coordinates, but for a planar object, it does, up to a translation vector, if the proper R is specified.

For each observed point coordinate (u, v) the function computes:


\begin{array}{l}
x^{"}  \leftarrow (u - c_x)/f_x  \\
y^{"}  \leftarrow (v - c_y)/f_y  \\
(x',y') = undistort(x^{"},y^{"}, \texttt{distCoeffs}) \\
{[X\,Y\,W]} ^T  \leftarrow R*[x' \, y' \, 1]^T  \\
x  \leftarrow X/W  \\
y  \leftarrow Y/W  \\
\text{only performed if P is specified:} \\
u'  \leftarrow x {f'}_x + {c'}_x  \\
v'  \leftarrow y {f'}_y + {c'}_y
\end{array}

where undistort is an 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).

The function can be used for both a stereo camera head or a monocular camera (when R is empty).

Note: Coordinate Systems:

  • Input (src): Points are expected in pixel coordinates of the distorted image, i.e., coordinates (u, v) measured in pixels from the top-left corner of the image.
  • Output (dst): The coordinate system of output points depends on parameter P:
    • If P is provided (not empty): Output points are in pixel coordinates of the rectified/undistorted image plane, using the camera matrix P.
    • If P is empty or identity: Output points are in normalized camera coordinates (also called "normalized image coordinates"), which are dimensionless coordinates (x, y) in the camera's focal plane, related to pixel coordinates by: x = (u - c_x) / f_x and y = (v - c_y) / f_y. These normalized coordinates are independent of the camera's intrinsic parameters and are useful for 3D reconstruction or epipolar geometry.
undistortPoints(src: Mat, dst: Mat, cameraMatrix: Mat, distCoeffs: Mat, R: Mat, P: Mat, criteria: TermCriteria): void;
4 available overloads
undistortPoints(src: Mat, dst: Mat, cameraMatrix: Mat, distCoeffs: Mat): void;
undistortPoints(src: Mat, dst: Mat, cameraMatrix: Mat, distCoeffs: Mat, R: Mat): void;
undistortPoints(src: Mat, dst: Mat, cameraMatrix: Mat, distCoeffs: Mat, R: Mat, P: Mat): void;
undistortPoints(src: Mat, dst: Mat, cameraMatrix: Mat, distCoeffs: Mat, R: Mat, P: Mat, criteria: TermCriteria): void;
src

Observed point coordinates in pixel coordinates of the distorted image, 2xN/Nx2 1-channel or 1xN/Nx1 2-channel (CV_32FC2 or CV_64FC2) (or vector<Point2f> ).

dst

Output destination, filled by the native operation. Output ideal point coordinates (1xN/Nx1 2-channel or vector<Point2f> ) after undistortion and reverse perspective transformation. If matrix P is identity or omitted, dst will contain normalized point coordinates.

cameraMatrix

Camera matrix \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1} .

distCoeffs

Input vector of distortion coefficients (k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]]) of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.

R

Rectification transformation in the object space (3x3 matrix). R1 or R2 computed by #stereoRectify can be passed here. If the matrix is empty, the identity transformation is used.

P

New camera matrix (3x3) or new projection matrix (3x4) \begin{bmatrix} {f'}_x & 0 & {c'}_x & t_x \\ 0 & {f'}_y & {c'}_y & t_y \\ 0 & 0 & 1 & t_z \end{bmatrix}. P1 or P2 computed by #stereoRectify can be passed here. If the matrix is empty, the identity new camera matrix is used and output will be in normalized coordinates.

criteria

termination criteria for the iterative point undistortion algorithm

Upstream declaration ↗

These signatures describe this package. Upstream documentation can mention optional backends that are absent from this build. Check runtime compatibility before choosing a backend or file format.