undistortImage

Correct image for lens distortion

Syntax

[J,newOrigin] = undistortImage(I,cameraParams)

[J,newOrigin] = undistortImage(I,cameraParams,interp)

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

Description

[J,newOrigin] = undistortImage(I,cameraParams) returns an image, J, containing the input image, I, with lens distortion removed. The function also returns the [x,y] location of the output image origin. The location is set in terms of the input intrinsic coordinates specified in cameraParams.

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

[J,newOrigin] = undistortImage(___,Name,Value) specifies one or more Name,Value pair arguments, using any of the preceding syntaxes. Unspecified properties have their default values.

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 = generateCheckerboardPoints(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

cameraParams — Object for storing camera parameters

cameraParameters object | cameraIntrinsics object

Camera parameters, specified as a cameraParameters or cameraIntrinsics object. You can return the cameraParameters object using the estimateCameraParameters function. The cameraParameters object contains the intrinsic, extrinsic, and lens distortion parameters of a camera.

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 sets the sets the output pixel fill values to 0.

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

newOrigin — Output image origin

2-element vector

Output image origin, returned as a 2-element [x,y] vector. The function sets the output origin location in terms of the input intrinsic coordinates. When you set OutputView to 'same', which means the output image is the same size as the input image, the function sets the newOrigin to [0,0].

The newOrigin output represents the translation from the intrinsic coordinates of the output image J into the intrinsic coordinates of the input image I.

Let PI represent a point in the intrinsic coordinates of input image I.

Let PJ represent the same point in the intrinsic coordinates of the output image J.

P_I = P_J + newOrigin

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.

Version History

Introduced in R2014a