undistortImage

Correct image for lens distortion

Syntax

[J,camIntrinsics] = undistortImage(I,intrinsics)

[J,camIntrinsics] = undistortImage(I,intrinsics,interp)

[J,camIntrinsics] = undistortImage(___,Name=Value)

Description

[J,camIntrinsics] = undistortImage(I,intrinsics) removes the lens distortion in the input image I using the camera parameters defined in intrinsics. The function returns the corrected image J.

[J,camIntrinsics] = undistortImage(I,intrinsics,interp) specifies the interpolation method for the function to use on the input image.

[J,camIntrinsics] = undistortImage(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, (FillValues=[0 0.4470 0.7410]) sets the output pixel values that are outside the input image boundaries to a blue color.

Examples

Correct Image for Lens Distortion

Create a set of calibration images.

images = imageDatastore(fullfile(toolboxdir('vision'),'visiondata', ...
    'calibration','mono'));

Detect calibration pattern.

[imagePoints,boardSize] = detectCheckerboardPoints(images.Files);

Generate world coordinates of the corners of the squares. The square size is in millimeters.

squareSize = 29;
worldPoints = patternWorldPoints('checkerboard',boardSize,squareSize);

Calibrate the camera.

I = readimage(images,1); 
imageSize = [size(I,1),size(I,2)];
cameraParams = estimateCameraParameters(imagePoints,worldPoints, ...
                                  'ImageSize',imageSize);

Remove lens distortion and display results.

I = images.readimage(1);
J1 = undistortImage(I,cameraParams);

figure; imshowpair(I,J1,'montage');
title('Original Image (left) vs. Corrected Image (right)');

J2 = undistortImage(I,cameraParams,'OutputView','full');
figure; 
imshow(J2);
title('Full Output View');

Input Arguments

I — Input image

M-by-N-by-3 truecolor image | M-by-N 2-D grayscale image

Input image, specified in either M-by-N-by-3 truecolor or M-by-N 2-D grayscale. The input image must be real and nonsparse.

Data Types: single | double | int16 | uint8 | uint16 | logical

intrinsics — Camera intrinsic parameters

cameraParameters object | cameraIntrinsics object | cameraIntrinsicsKB object

Camera intrinsic parameters, specified as a cameraParameters, cameraIntrinsics, cameraIntrinsicsKB object.

interp — Interpolation method

"linear" (default) | "nearest" | "cubic"

Interpolation method to use on the input image, specified as "linear", "nearest" , or "cubic".

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: (FillValues=[0 0.4470 0.7410]) sets the output pixel values that are outside the input image boundaries to a blue color.

FillValues — Output pixel fill values

0 (default) | scalar | 3-element vector

Output pixel fill values, specified as an array containing one or more fill values. When the corresponding inverse transformed location in the input image lies completely outside the input image boundaries, you use the fill values for output pixels. When you use a 2-D grayscale input image, you must set the FillValues to scalar. When you use a truecolor, FillValues can be a scalar or a 3-element vector of RGB values.

OutputView — Size of output image

"same" (default) | "full" | "valid"

Size of output image, specified as "same", "full", or "valid". When you set the property to "same", the function sets the output image to match the size of the input image. When you set the property to "full", the output includes all pixels from the input image. When you set the property to "valid", the function crops the output image to contain only valid pixels.

For the input image:

OutputView	Output Image
"same"	Match the size of the input image.
"full"	All pixels from the input image.
"valid"	Only valid pixels from the input image.

Output Arguments

J — Undistorted image

M-by-N-by-3 truecolor image | M-by-N 2-D grayscale image

Undistorted image, returned in either M-by-N-by-3 truecolor or M-by-N 2-D grayscale.

Data Types: single | double | int16 | uint8 | uint16 | logical

camIntrinsics — Camera intrinsic parameters

cameraIntrinsics object

Camera intrinsic parameters, returned as a cameraIntrinsics object which corresponds to a virtual perspective camera that produced the output image with lens distortion removed.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Use in a MATLAB Function block is not supported.

• 'interp' and 'OutputView' must be compile-time constants.

• Code generation not supported for cameraIntrinsicsKB object input.

Version History

Introduced in R2014a

R2024a: Returns camera intrinsic parameters object

This release replaces the second optional output argument. The function now returns a cameraIntrinsics object in the second argument. Prior to this release, the function returned a 2-element vector newOrigin. You can still calculate the new origin by subtracting the output intrinsics principal point from the intrinsics input principal point using this code:

newOrigin = intrinsics.PrincipalPoint - newIntrinsics.PrincipalPoint

R2024a: Added support for the cameraIntrinsicsKB object

Support added for the cameraIntrinsicsKB object as the intrinsics input.