pycvcam.undistort_image#

undistort_image(src, intrinsic, distortion, interpolation='linear', intrinsic_kwargs=None, inverse_intrinsic_kwargs=None, distortion_kwargs=None)[source]#

Undistort an image using the camera intrinsic and distortion coefficients.

This method use the same architecture as the cv2.undistort function from OpenCV, but it is implemented in a more flexible way to allow the use of different distortion models.

The process to undistort an image is as follows:

  1. The output pixels are converted to a normalized coordinate system using the inverse intrinsic transformation.

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

  3. The distorted points are projected back to the input image coordinate system using the same intrinsic transformation.

  4. The undistorted image is obtained by mapping the pixels from the original image to the undistorted 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.

Fill Values for the output image are set to 0.0.

The mapping is performed using using OpenCV’s cv2.remap function (or scipy.interpolate), which requires the source image and the mapping of pixel coordinates.

Different interpolation methods can be used, such as “linear”, “nearest”, etc. The default is “linear”. The table below shows the available interpolation methods:

Interpolation

Description

“linear”

Linear interpolation (default). Use cv2.INTER_LINEAR.

“nearest”

Nearest neighbor interpolation. Use cv2.INTER_NEAREST.

“cubic”

Bicubic interpolation. Use cv2.INTER_CUBIC.

“area”

Resampling using pixel area relation. Use cv2.INTER_AREA.

“lanczos4”

Lanczos interpolation over 8x8 pixel neighborhood. Use cv2.INTER_LANCZOS4.

“spline3”

Spline interpolation. Use scipy.interpolate.RectBivariateSpline for kx=ky=3

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.

Warning

  • For scipy, output values are not positive integer values (even if the input image is integer).

Parameters:

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

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

  • distortion (Optional[Distortion]) – The distortion model to be applied. If None, no distortion is applied.

  • interpolation (str, optional) – The interpolation method to be used for remapping the pixels. Default is “linear”.

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

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

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

Returns:

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

Return type:

numpy.ndarray

See also

pycvcam.distort_image

Similar function to distort an image using the camera intrinsic and distortion coefficients.

Example

import numpy
from pycvcam import undistort_image, Cv2Distortion, Cv2Intrinsic

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

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

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

This Page