pydistort.distort_image#

pydistort.distort_image(src: ndarray, K: ndarray | None, distortion: Distortion | None, method: str = 'undistort', **kwargs) → ndarray[source]#

Distort an image using the camera intrinsic and distortion coefficients.

The process to undistort an image is as follows:

  1. The output pixels are converted to a normalized coordinate system using the intrinsic matrix K.

  2. The normalized points are undistorted by the distortion model using the coefficients \(\{\lambda_1, \lambda_2, \lambda_3, \ldots\}\).

  3. The undistorted points are projected back to the input image coordinate system using the intrinsic matrix K.

  4. The distorted image is obtained by mapping the pixels from the original image to the distorted points.

The given image src is assumed to be in the image coordinate system and expressed in 2D coordinates with shape (H, W, [C], [D]). If the user gives an identity matrix K, it is equivalent to giving directly the normalized points.

Note

  • For an image the X dimension corresponds to the width and the Y dimension corresponds to the height.

  • Pixel [0, 1] is at XY = [1, 0] in the image coordinate system.

Linear interpolation is used for each method to compute the pixel values in the distorted image.

Fill Values for the output image are set to 0.0.

METHOD 1 : Undistort#

The mapping is performed using OpenCV’s cv2.remap function, which requires the source image and the mapping of pixel coordinates. The mapping of pixel coordinates is performed using the undistort method of the distortion model, which applies the inverse distortion to the normalized points.

In this case, the output pixels (distorted_image) are projected back to the input image coordinate system using the intrinsic matrix K. Then an interpolation is performed in the input image where the known points are a perfect regular grid of pixels !

Warning

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

METHOD 2 : Distort#

The mapping is performed using scipy scipy.interpolate.LinearNDInterpolator function, which requires the source image and the mapping of pixel coordinates. The mapping of pixel coordinates is performed using the distort method of the distortion model, which applies the distortion to the normalized points.

In this case, the input pixels (src) are projected to the output image coordinate system using the intrinsic matrix K. Then an interpolation is performed in the output image for all the output pixels where the known points are a irregular cloud of points.

Warning

  • Time computation is higher than the first method.

  • Output values are not integer values (even if the input image is integer), so the user must apply (numpy.round) to the output image to get integer values.

param src:

The input image to be undistorted. Shape (H, W, …) where H is the height, W is the width.

type src:

numpy.ndarray

param K:

The intrinsic camera matrix (or vector). Shape (3, 3) or (4,). If None, the identity intrinsic matrix is used.

type K:

Optional[numpy.ndarray]

param distortion:

The distortion model to be applied. If None, no distortion is applied.

type distortion:

Optional[Distortion]

param method:

The method to use for undistortion. The value can be “undistort” or “distort”.

  • “undistort”: Uses OpenCV’s cv2.remap and the undistort method of the distortion model.

  • “distort”: Uses scipy.interpolate.LinearNDInterpolator and the distort method of the distortion model.

type method:

str

param kwargs:

Additional arguments to be passed to the distortion model “undistort” method.

type kwargs:

dict

returns:

The undistorted image. Shape (H, W, …) where H is the height.

rtype:

numpy.ndarray

Example

import numpy
from pydistort import undistort_points, Cv2Distortion

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

# Load the image to be undistorted
src = cv2.imread('image.jpg')

# Undistort the image
undistorted_image = undistort_image(src, K, distortion)
On this page

This Page