pydistort.undistort_points#

pydistort.undistort_points(image_points: ndarray, K: ndarray | None, distortion: Distortion | None, R: ndarray | None = None, P: ndarray | None = None, transpose: bool = False, **kwargs) → ndarray[source]#

Undistort 2D image points using the camera intrinsic and distortion coefficients.

The process to undistort a 2D-image point is as follows:

  1. The image_points (\(x_I\)) are normalized by multiplying by the inverse of the intrinsic matrix K to obtain the distorted_points (\(x_D\)).

  2. The distorted_points (\(x_D\)) are undistorted by the distortion model using the coefficients \(\{\lambda_1, \lambda_2, \lambda_3, \ldots\}\) to obtain the normalized_points (\(x_N\)).

  3. A rectification matrix R and a new projection matrix P can be applied to the normalized_points to return the undistorted_points in the space required by the user.

Warning

Iterative non-linear optimization is used to find the undistorted points.

The given points image_points are assumed to be in the image coordinate system and expressed in 2D coordinates with shape (…, 2). If the user gives an identity matrix K, it equivalent to give directly the normalized points.

This method not compute the jacobians of the undistortion process, but it can be done by using the dx and dp flags in the intrinsic and distortion models.

Parameters:

  • image_points (numpy.ndarray) – The 2D image points in the camera coordinate system. Shape (…, 2)

  • K (Optional[numpy.ndarray]) – The intrinsic camera matrix (or vector). Shape (3, 3) or (4,). If None, the identity intrinsic matrix is used.

  • distortion (Optional[Distortion]) – The distortion model to be applied to the image points. If None, a zero distortion is applied.

  • R (Optional[numpy.ndarray], optional) – The rotation matrix (or vector) of the camera. Shape (3,) or (3, 3). If None, the identity rotation is used. Default is None.

  • P (Optional[numpy.ndarray], optional) – The new projection matrix (or vector). Shape (3, 3) or (4,). If None, the identity projection matrix is used. Default is None.

  • transpose (bool, optional) – If True, the input points are assumed to be in the shape (2, …) instead of (…, 2). Default is False. The output points will be in the same shape as the input points.

  • kwargs (optional) – Additional arguments to be passed to the distortion model “undistort” method. This is useful for some distortion models that require additional parameters.

Returns:

The undistorted 2D image points in the camera coordinate system. Shape (…, 2). If no P is given, the normalized_points are returned instead of the undistorted_points.

Return type:

numpy.ndarray

Example

The following example shows how to undistort 2D image points using the intrinsic camera matrix and a distortion model.

import numpy
from pydistort import undistort_points, Cv2Distortion
from py3dframe import Frame

# Define the 2D image points in the camera coordinate system
image_points = numpy.array([[320.0, 240.0],
                            [420.0, 440.0],
                            [520.0, 540.0],
                            [620.0, 640.0],
                            [720.0, 740.0]]) # shape (5, 2)

# Define the intrinsic camera matrix
K = numpy.array([[1000.0, 0.0, 320.0],
                [0.0, 1000.0, 240.0],
                [0.0, 0.0, 1.0]])

# Define the distortion model (optional)
distortion = Cv2Distortion([0.1, 0.2, 0.3, 0.4, 0.5])

# Undistort the 2D image points
normalized_points = undistort_points(image_points, K=K, distortion=distortion)

To return the undistorted points in the image coordinate system, you can provide a projection matrix P equal to the intrinsic matrix K:

undistorted_points = undistort_points(image_points, K=K, distortion=distortion, P=K)
On this page

This Page