cameraParameters

Object for storing camera parameters

Description

The cameraParameters object stores the intrinsic, extrinsic, and lens distortion parameters of a camera.

Creation

You can create a cameraParameters object using the cameraParameters function described here. You can also create a cameraParameters object by using the estimateCameraParameters with an M-by-2-by-numImages array of input image points. M is the number of keypoint coordinates in each pattern.

Syntax

cameraParams = cameraParameters

cameraParams = cameraParameters(Name,Value)

cameraParams = cameraParameters(paramStruct)

Description

cameraParams = cameraParameters creates a cameraParameters object that contains the intrinsic, extrinsic, and lens distortion parameters of a camera.

example

cameraParams = cameraParameters(Name,Value) sets properties of the cameraParameters object by using one or more Name,Value pair arguments. Unspecified properties use default values.

cameraParams = cameraParameters(paramStruct) creates an identical cameraParameters object from an existing cameraParameters object with parameters stored in paramStruct.

Input Arguments

expand all

`paramStruct` — Camera parameters
struct

Stereo parameters, specified as a stereo parameters struct. To get a paramStruct from an existing cameraParameters object, use the toStruct function.

Properties

expand all

Intrinsic Camera Parameters:

`IntrinsicMatrix` — Projection matrix
3-by-3 identity matrix

Projection matrix, specified as a 3-by-3 identity matrix. The object uses the following format for the matrix format:

$[\begin{matrix} f_{x} & 0 & 0 \\ s & f_{y} & 0 \\ c_{x} & c_{y} & 1 \end{matrix}]$

The coordinates [c_x c_y] represent the optical center (the principal point), in pixels. When the x and y axis are exactly perpendicular, the skew parameter, s, equals 0.

f_x = F*s_x

f_y = F*s_y

F, is the focal length in world units, typically expressed in millimeters.

[s_x, s_y] are the number of pixels per world unit in the x and y direction respectively.

fx and fy are expressed in pixels.

`Intrinsics` — Camera intrinsics object
`cameraIntrinsics` object

This property is read-only.

Camera intrinsics object, stated as a cameraIntrinsics object. The object contains information about camera intrinsic calibration parameters, including lens distortion.

Dependency

You must provide an image size (using the ImageSize property) for the Intrinsics property to be non-empty. The intrinsics for the camera parameters depends on the image size.

`ImageSize` — Image size
two-elment vector

Image size, specified as a two-element vector [mrows,ncols].

Camera Lens Distortion:

`RadialDistortion` — Radial distortion coefficients
`[0 0 0]` (default) | 2-element vector | 3-element vector

Radial distortion coefficients, specified as either a two- or three-element vector. When you specify a two-element vector, the object sets the third element to 0. Radial distortion occurs when light rays bend more near the edges of a lens than they do at its optical center. The smaller the lens, the greater the distortion. The camera parameters object calculates the radial distorted location of a point. You can denote the distorted points as (x_distorted, y_distorted), as follows:

x_distorted = x(1 + k₁*r² + k₂*r⁴ + k₃*r⁶)

y_distorted= y(1 + k₁*r² + k₂*r⁴ + k₃*r⁶)

x, y = undistorted pixel locations

k₁, k₂, and k₃ = radial distortion coefficients of the lens

r² = x² + y²

Typically, two coefficients are sufficient. For severe distortion, you can include k₃. The undistorted pixel locations appear in normalized image coordinates, with the origin at the optical center. The coordinates are expressed in world units.

`TangentialDistortion` — Tangential distortion coefficients
`[0 0]'` (default) | 2-element vector

Tangential distortion coefficients, specified as a two-element vector. Tangential distortion occurs when the lens and the image plane are not parallel. The camera parameters object calculates the tangential distorted location of a point. You can denote the distorted points as (x_distorted, y_distorted). The undistorted pixel locations appear in normalized image coordinates, with the origin at the optical center. The coordinates are expressed in world units.

Tangential distortion occurs when the lens and the image plane are not parallel. The tangential distortion coefficients model this type of distortion.

The distorted points are denoted as (x_distorted, y_distorted):

x_distorted = x + [2 * p₁ * x * y + p₂ * (r² + 2 * x²)]

y_distorted = y + [p₁ * (r² + 2 *y²) + 2 * p₂ * x * y]

x, y — Undistorted pixel locations. x and y are in normalized image coordinates. Normalized image coordinates are calculated from pixel coordinates by translating to the optical center and dividing by the focal length in pixels. Thus, x and y are dimensionless.
p₁ and p₂ — Tangential distortion coefficients of the lens.
r²: x² + y²

Extrinsic Camera Parameters:

`RotationMatrices` — 3-D rotation matrix
3-by-3-by-P matrix (read-only)

3-D rotation matrix, specified as a 3-by-3-by-P, with P number of pattern images. Each 3-by-3 matrix represents the same 3-D rotation as the corresponding vector.

The following equation provides the transformation that relates a world coordinate in the checkerboard frame [X Y Z] and the corresponding image point [x y]:

$s [\begin{matrix} x & y & 1 \end{matrix}] = [\begin{matrix} X & Y & Z & 1 \end{matrix}] [\begin{matrix} R \\ t \end{matrix}] K$

R is the 3-D rotation matrix.

t is the translation vector.

K is the IntrinsicMatrix.

s is a scalar.

This equation does not take distortion into consideration. The undistortImage function removes distortion.

`RotationVectors` — 3-D rotation vectors
`[]` (default) | P-by-3 matrix (read-only)

3-D rotation vectors, specified as a P-by-3 matrix containing P rotation vectors. Each vector describes the 3-D rotation of the camera image plane relative to the corresponding calibration pattern. The vector specifies the 3-D axis about which the camera is rotated, where the magnitude is the rotation angle in radians. The RotationMatrices property provides the corresponding 3-D rotation matrices.

`TranslationVectors` — Camera translations
P-by-3 matrix | `[]`

Camera translations, specified as an P-by-3 matrix. This matrix contains translation vectors for P images. The vectors contain the calibration pattern that estimates the calibration parameters. Each row of the matrix contains a vector that describes the translation of the camera relative to the corresponding pattern, expressed in world units.

The following equation provides the transformation that relates a world coordinate in the checkerboard frame [X Y Z] and the corresponding image point [x y]:

$s [\begin{matrix} x & y & 1 \end{matrix}] = [\begin{matrix} X & Y & Z & 1 \end{matrix}] [\begin{matrix} R \\ t \end{matrix}] K$

R is the 3-D rotation matrix.

t is the translation vector.

K is the IntrinsicMatrix.

s is a scalar.

This equation does not take distortion into consideration. The undistortImage function removes distortion.

To ensure that the number of rotation vectors equals the number of translation vectors, set the RotationVectors and TranslationVectors properties in the constructor. Setting only one property but not the other results in an error.

Estimated Camera Parameter Accuracy:

`MeanReprojectionError` — Average Euclidean distance
numeric value (read-only)

Average Euclidean distance between reprojected and detected points, specified as a numeric value in pixels.

`ReprojectionErrors` — Estimated camera parameters accuracy
M-by-2-by-P array

Estimated camera parameters accuracy, specified as an M-by-2-by-P array of [x y] coordinates. The [x y] coordinates represent the translation in x and y between the reprojected pattern key points and the detected pattern key points. The values of this property represent the accuracy of the estimated camera parameters. P is the number of pattern images that estimates camera parameters. M is the number of keypoints in each image.

`ReprojectedPoints` — World points reprojected onto calibration images
M-by-2-by-P array

World points reprojected onto calibration images, specified as an M-by-2-by-P array of [x y] coordinates. P is the number of pattern images and M is the number of keypoints in each image.

Settings for Camera Parameter Estimation:

`NumPatterns` — Number of calibrated patterns
integer

Number of calibration patterns that estimates camera extrinsics, specified as an integer. The number of calibration patterns equals the number of translation and rotation vectors.

`WorldPoints` — World coordinates
M-by-2 array | `[]`

World coordinates of key points on calibration pattern, specified as an M-by-2 array. M represents the number of key points in the pattern.

`WorldUnits` — World points units
`'mm'` (default) | character vector | string scalar

World points units, specified as a character vector or string scalar. The value describes the units of measure.

`EstimateSkew` — Estimate skew flag
`false` (default) | logical scalar

Estimate skew flag, specified as a logical scalar. When you set the logical to true, the object estimates the image axes skew. When you set the logical to false, the image axes are exactly perpendicular.

`NumRadialDistortionCoefficients` — Number of radial distortion coefficients
`2` (default) | `3`

Number of radial distortion coefficients, specified as the number '2' or '3'.

`EstimateTangentialDistortion` — Estimate tangential distortion flag
`false` (default) | logical scalar

Estimate tangential distortion flag, specified as the logical scalar true or false. When you set the logical to true, the object estimates the tangential distortion. When you set the logical to false, the tangential distortion is negligible.

Examples

collapse all

Remove Distortion from an Image Using the Camera Parameters Object

Open Live Script

Use the camera calibration functions to remove distortion from an image. This example creates a vision.cameraParameters object manually, but in practice, you would use the estimateCameraParameters or the Camera Calibrator app to derive the object.

Create a vision.cameraParameters object manually.

IntrinsicMatrix = [715.2699 0 0; 0 711.5281 0; 565.6995 355.3466 1];
radialDistortion = [-0.3361 0.0921]; 
cameraParams = cameraParameters('IntrinsicMatrix',IntrinsicMatrix,'RadialDistortion',radialDistortion);

Remove distortion from the images.

I = imread(fullfile(matlabroot,'toolbox','vision','visiondata','calibration','mono','image01.jpg'));
J = undistortImage(I,cameraParams);

Display the original and the undistorted images.

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

References

[1] Zhang, Z. “A flexible new technique for camera calibration”. IEEE Transactions on Pattern Analysis and Machine Intelligence, Vol. 22, No. 11, pp. 1330–1334, 2000.

[2] Heikkila, J, and O. Silven. “A Four-step Camera Calibration Procedure with Implicit Image Correction”, IEEE International Conference on Computer Vision and Pattern Recognition, 1997.

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.
Use the toStruct method to pass a cameraParameters object into generated code. See the Code Generation for Depth Estimation From Stereo Video example.

Documentation

cameraParameters

Description

Creation

Syntax

Description

Input Arguments

paramStruct — Camera parameters struct

Properties

Intrinsic Camera Parameters:

IntrinsicMatrix — Projection matrix 3-by-3 identity matrix

Intrinsics — Camera intrinsics object cameraIntrinsics object

Dependency

ImageSize — Image size two-elment vector

Camera Lens Distortion:

RadialDistortion — Radial distortion coefficients [0 0 0] (default) | 2-element vector | 3-element vector

TangentialDistortion — Tangential distortion coefficients [0 0]' (default) | 2-element vector

Extrinsic Camera Parameters:

RotationMatrices — 3-D rotation matrix 3-by-3-by-P matrix (read-only)

RotationVectors — 3-D rotation vectors [] (default) | P-by-3 matrix (read-only)

TranslationVectors — Camera translations P-by-3 matrix | []

Estimated Camera Parameter Accuracy:

MeanReprojectionError — Average Euclidean distance numeric value (read-only)

ReprojectionErrors — Estimated camera parameters accuracy M-by-2-by-P array

ReprojectedPoints — World points reprojected onto calibration images M-by-2-by-P array

Settings for Camera Parameter Estimation:

NumPatterns — Number of calibrated patterns integer

WorldPoints — World coordinates M-by-2 array | []

WorldUnits — World points units 'mm' (default) | character vector | string scalar

EstimateSkew — Estimate skew flag false (default) | logical scalar

NumRadialDistortionCoefficients — Number of radial distortion coefficients 2 (default) | 3

EstimateTangentialDistortion — Estimate tangential distortion flag false (default) | logical scalar

Examples

Remove Distortion from an Image Using the Camera Parameters Object

References

Extended Capabilities

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

See Also

Apps

Classes

Functions

Topics

Computer Vision Toolbox Documentation

Support

`paramStruct` — Camera parameters
struct

`IntrinsicMatrix` — Projection matrix
3-by-3 identity matrix

`Intrinsics` — Camera intrinsics object
`cameraIntrinsics` object

`ImageSize` — Image size
two-elment vector

`RadialDistortion` — Radial distortion coefficients
`[0 0 0]` (default) | 2-element vector | 3-element vector

`TangentialDistortion` — Tangential distortion coefficients
`[0 0]'` (default) | 2-element vector

`RotationMatrices` — 3-D rotation matrix
3-by-3-by-P matrix (read-only)

`RotationVectors` — 3-D rotation vectors
`[]` (default) | P-by-3 matrix (read-only)

`TranslationVectors` — Camera translations
P-by-3 matrix | `[]`

`MeanReprojectionError` — Average Euclidean distance
numeric value (read-only)

`ReprojectionErrors` — Estimated camera parameters accuracy
M-by-2-by-P array

`ReprojectedPoints` — World points reprojected onto calibration images
M-by-2-by-P array

`NumPatterns` — Number of calibrated patterns
integer

`WorldPoints` — World coordinates
M-by-2 array | `[]`

`WorldUnits` — World points units
`'mm'` (default) | character vector | string scalar

`EstimateSkew` — Estimate skew flag
`false` (default) | logical scalar

`NumRadialDistortionCoefficients` — Number of radial distortion coefficients
`2` (default) | `3`

`EstimateTangentialDistortion` — Estimate tangential distortion flag
`false` (default) | logical scalar

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