undistortFisheyeImage

Correct fisheye image for lens distortion

Syntax

J = undistortFisheyeImage(I,intrinsics)

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

[___] = undistortFisheyeImage(___,interp)

[___] = undistortFisheyeImage(___,Name=Value)

Description

J = undistortFisheyeImage(I,intrinsics) removes lens distortion for image I and returns the result as image J.

[J,camIntrinsics] = undistortFisheyeImage(I,intrinsics) also returns a cameraIntrinsics object, which corresponds to a virtual pinhole camera.

[___] = undistortFisheyeImage(___,interp) specifies the interpolation method, interp, using the preceding syntaxes.

[___] = undistortFisheyeImage(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, "ScaleFactor"=2 increases the zoom in the camera view by a factor of 2.

Examples

Correct Fisheye Image for Lens Distortion

Remove lens distortion from a fisheye image by detecting a checkboard calibration pattern and calibrating the camera. Then, display the results.

Gather a set of checkerboard calibration images.

images = imageDatastore('calibrationImages');

Detect the calibration pattern from the images. The 'PartialDetections' Name-Value argument is set to true by default allowing detection of partial checkerboards.

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

Generate world coordinates for the corners of the checkerboard squares.

squareSize = 20; % millimeters
worldPoints = patternWorldPoints('checkerboard',boardSize,squareSize);

Estimate the fisheye camera calibration parameters based on the image and world points. Use the first image to get the image size.

I = readimage(images,10); 
imageSize = [size(I,1) size(I,2)];
params = estimateFisheyeParameters(imagePoints,worldPoints,imageSize);

Remove lens distortion from the first image I and display the results.

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

J2 = undistortFisheyeImage(I,params.Intrinsics,'OutputView','same', 'ScaleFactor', 0.2);
figure
imshow(J2)
title('Output View with low Scale Factor')

Input Arguments

I — Input image

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

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

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

intrinsics — Fisheye intrinsic camera parameters

fisheyeIntrinsics object

Fisheye intrinsic camera parameters, specified as a fisheyeIntrinsics object.

interp — Interpolation method

'bilinear' (default) | 'nearest' | 'cubic'

Interpolation method to use on the input image, specified as 'bilinear', '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: "ScaleFactor"=2 increases the zoom in the camera view by a factor of 2

OutputView — Size of the output image

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

Size of the output image, specified as either "same", "full", or "valid".

The "full" output image size is not suitable for fisheye images created with wide-angle lenses, including catadioptic lenses, which generate spherical images.

ScaleFactor — Scale factor for focal length

1 (default) | scalar | [sx sy] vector

Scale factor for the focal length of a virtual camera perspective, in pixels, specified as a scalar or an [sx sy] vector. Specify a vector to scale the x and y axes individually. Increase the scale to zoom in the perspective of the camera view.

FillValues — Output pixel fill values

0 (default) | scalar | 3-element vector

Output pixel fill values, specified as the comma-separated pair consisting of 'FillValues' and scalar or 3-element vector. 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, FillValues must be a scalar. When you use a truecolor image, FillValues can be a scalar or a 3-element vector of RGB values.

Output Arguments

J — Undistorted image

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

Undistorted image, returned as an M-by-N-by-3 truecolor or M-by-N 2-D grayscale image.

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

camIntrinsics — Undistorted intrinsics of virtual camera

cameraIntrinsics object

Undistorted intrinsics of a virtual camera, returned as a cameraIntrinsics object. The camIntrinsics object represents a virtual pinhole camera. You can use this object with the pinhole model calibration workflow functions. These intrinsics are for a camera that has a perspective that produces the undistorted image.

Tips

• The Computer Vision Toolbox™ calibration algorithm uses the fisheye camera model proposed by Scaramuzza [1].

References

[1] Scaramuzza, D., A. Martinelli, and R. Siegwart. "A Toolbox for Easy Calibrating Omnidirectional Cameras." Proceedings to IEEE International Conference on Intelligent Robots and Systems, (IROS). Beijing, China, October 7–15, 2006.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2017b

R2024a: Generate C/C++ code using MATLAB Coder

undistortFisheyeImage now supports the generation of C/C++ code (requires MATLAB^® Coder™).