pycvcam.distort_points#

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

Distort 2D image_points using the camera intrinsic, distortion transformations to obtain the distorted_points in the normalized coordinate system or transformed_points if R or P are provided.

As a reminder,

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

Then optionally,

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

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 transformed_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 normalized points in the normalized coordinate system.

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

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

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 distorted 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 distorted points. If None, a no intrinsic transformation is applied (i.e., identity transformation). This is useful to return the distorted 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.

  • distortion_kwargs (Optional[Dict], optional) – Additional keyword arguments to be passed to the distortion transformation (distortion._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 distorted points in the normalized coordinate system with shape (…, 2) or the 2D transformed points in the user coordinate system if P or R are given.

Return type:

numpy.ndarray

See also

pycvcam.undistort_points

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

pycvcam.distort_image

Distort 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 distort 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