# 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

### Description

`cameraParams = cameraParameters`

creates a
`cameraParameters`

object that contains the intrinsic,
extrinsic, and lens distortion parameters of a camera.

`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(`

creates an identical `paramStruct`

)`cameraParameters`

object from an existing
`cameraParameters`

object with parameters stored in
`paramStruct`

.

### Input Arguments

`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

## 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:

$$\left[\begin{array}{ccc}{f}_{x}& 0& 0\\ s& {f}_{y}& 0\\ {c}_{x}& {c}_{y}& 1\end{array}\right]$$

The coordinates
[*c _{x}*

*c*] represent the optical center (the principal point), in pixels. When the

_{y}*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*_{1}**r*^{2}
+
*k*_{2}**r*^{4}
+
*k*_{3}**r*^{6})

*y*_{distorted}=
*y*(1 +
*k*_{1}**r*^{2}
+
*k*_{2}**r*^{4}
+
*k*_{3}**r*^{6})

x, y = undistorted pixel
locations |

k_{1},
k_{2}, and
k_{3} = radial distortion
coefficients of the lens |

r^{2} =
x^{2} +
y^{2} |

*k*

_{3}. 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*_{1} * *x* * *y* + *p*_{2} *
(*r*^{2} + 2 * *x*^{2})]

*y*_{distorted} = *y* +
[*p*_{1} * (*r*^{2} +
2 **y*^{2}) + 2 * *p*_{2} * *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*_{1}and*p*_{2}— Tangential distortion coefficients of the lens.*r*^{2}=*x*^{2}+*y*^{2}

## 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\left[\begin{array}{ccc}x& y& 1\end{array}\right]=\left[\begin{array}{cccc}X& Y& Z& 1\end{array}\right]\left[\begin{array}{c}R\\ t\end{array}\right]K$$

R is the 3-D rotation matrix. |

t is the translation vector. |

K is the
`IntrinsicMatrix` . |

s is a scalar. |

`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

`[]`

(default) | *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\left[\begin{array}{ccc}x& y& 1\end{array}\right]=\left[\begin{array}{cccc}X& Y& Z& 1\end{array}\right]\left[\begin{array}{c}R\\ t\end{array}\right]K$$

R is the 3-D rotation matrix. |

t is the translation vector. |

K is the
`IntrinsicMatrix` . |

s is a scalar. |

`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

`[]`

(default) | *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. Missing points in the pattern's detected keypoints are denoted as
[`NaN,NaN`

].

`DetectedKeypoints`

— Detected keypoints in the calibration pattern

`[]`

(default) | *M*-by-*P* array

Detected keypoints in the calibration pattern, specified as a logical
*M*-by-*P* array. *M*
is the number of keypoints in the entire calibration pattern and
*P* specifies the number of calibration images.

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

### Remove Distortion from an Image Using the Camera Parameters Object

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 the

`toStruct`

method to pass a`cameraParameters`

object into generated code. See the Code Generation for Depth Estimation From Stereo Video example.

## See Also

### Apps

### Classes

`stereoParameters`

|`cameraCalibrationErrors`

|`intrinsicsEstimationErrors`

|`extrinsicsEstimationErrors`

|`cameraIntrinsics`

### Functions

**Introduced in R2014a**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)