pycvcam.undistort_points#

undistort_points(image_points, intrinsic, distortion, R=None, P=None, *, transpose=False, inverse_intrinsic_kwargs=None, inverse_distortion_kwargs=None, R_kwargs=None, P_kwargs=None)[source]#

Undistort 2D image_points using the camera intrinsic, distortion transformations to obtain the normalized_points in the normalized coordinate system or undistorted_points if R or P are provided.

As a reminder,

\[\begin{split}\vec{x}_d = \text{Intrinsic}^{-1}(\vec{x}_i) \\ \vec{x}_n = \text{Distortion}^{-1}(\vec{x}_d)\end{split}\]

Then optionally,

\[\vec{x}_u = P(R(\vec{x}_n)))\]

Where:

  • \(\vec{x}_i\) are the 2D image_points in the image coordinate system \((\vec{e}_x, \vec{e}_y)\).

  • \(\vec{x}_d\) are the 2D distorted_points in the normalized coordinate system \((\vec{I}, \vec{J})\).

  • \(\vec{x}_n\) are the 2D normalized_points in the normalized coordinate system \((\vec{I}, \vec{J})\).

  • \(\vec{x}_u\) are the 2D undistorted_points in the space required by the user.

Note

The behavior of the function can be adapted to the user’s needs by providing the appropriate transformations.

  • Use intrinsic = None to give directly the distorted points in the normalized coordinate system.

  • Use P = intrinsic to return the undistorted points in the image coordinate system.

  • Use intrinsic = None and P = None if the distortion model is defined in the image coordinate system.

Warning

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

The given points image_points are assumed to be in the sensor coordinate system and expressed in 2D coordinates with shape (…, 2).

Note

The expected image_points can be extracted from the pixel_points by swapping the axes.

Parameters:

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

  • intrinsic (Optional[Intrinsic]) – The intrinsic transformation to be applied to the image points. If None, a no intrinsic transformation is applied (i.e., identity transformation).

  • distortion (Optional[Distortion]) – The distortion model to be applied to the normalized points. If None, a no distortion transformation is applied (i.e., identity transformation).

  • R (Optional[Extrinsic], optional) – The rectification extrinsic transformation (rotation and translation) to be applied to the normalized points. If None, a no extrinsic transformation is applied (i.e., identity transformation). Default is None.

  • P (Optional[Intrinsic], optional) – The projection intrinsic transformation to be applied to the normalized points. If None, a no intrinsic transformation is applied (i.e., identity transformation). This is useful to return the undistorted points in the image coordinate system.

  • 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.

  • inverse_intrinsic_kwargs (Optional[Dict], optional) – Additional keyword arguments to be passed to the intrinsic inverse transformation (intrinsic._inverse_transform). Default is None.

  • inverse_distortion_kwargs (Optional[Dict], optional) – Additional keyword arguments to be passed to the distortion inverse transformation (distortion._inverse_transform). Default is None.

  • R_kwargs (Optional[Dict], optional) – Additional keyword arguments to be passed to the rectification extrinsic transformation (R._transform). Default is None.

  • P_kwargs (Optional[Dict], optional) – Additional keyword arguments to be passed to the projection intrinsic transformation (P._transform). Default is None.

Returns:

The 2D normalized points in the normalized coordinate system with shape (…, 2) or the 2D undistorted points in the user coordinate system if P or R are given.

Return type:

numpy.ndarray

See also

pycvcam.distort_points

Similar to this function but applies the transformations in the opposite direction to distort the points instead of undistorting them.

pycvcam.undistort_image

Undistort an image using the camera intrinsic and distortion transformations.

pycvcam.project_points

Project 3D points to 2D image points using the camera intrinsic, distortion, and extrinsic transformations.

Example

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

import numpy
from pycvcam import undistort_points, Cv2Distortion, Cv2Intrinsic

# 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]])

# Create the intrinsic object
intrinsic = Cv2Intrinsic.from_matrix(K)

# 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,
    intrinsic=intrinsic,
    distortion=distortion
)

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

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

This Page