Object for storing camera parameters

`cameraParams = cameraParameters`

cameraParams = cameraParameters(Name,Value)

cameraParams = cameraParameters(paramStruct)

returns
an object that contains the intrinsic, extrinsic, and lens distortion
parameters of a camera.`cameraParams`

= cameraParameters

configures
the camera parameters object properties, specified as one or more `cameraParams`

= cameraParameters(`Name,Value`

)`Name,Value`

pair
arguments. Unspecified properties use default values.

returns
a `cameraParams`

= cameraParameters(`paramStruct`

)`cameraParameters`

object
containing the parameters specified by `paramStruct`

input. `paramStruct`

is
returned by the `toStruct`

method.

The object contains intrinsic, extrinsic, lens distortion, and estimation properties.

Specify optional comma-separated pairs of `Name,Value`

arguments.
`Name`

is the argument
name and `Value`

is the corresponding
value. `Name`

must appear
inside single quotes (`' '`

).
You can specify several name and value pair
arguments in any order as `Name1,Value1,...,NameN,ValueN`

.

`'RadialDistortion'`

,```
[0 0
0]
```

sets the `'RadialDistortion'`

to ```
[0
0 0]
```

.`'IntrinsicMatrix'`

— Projection matrix3-by-3 identity matrixProjection matrix, specified as the comma-separated pair consisting
of '`IntrinsicMatrix`

' and a 3-by-3 identity matrix.
For the matrix format, the object uses the following 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}*

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

f and _{x}f are
expressed in pixels._{y} |

`'RadialDistortion'`

— Radial distortion coefficients`[0 0 0] `

(default) | 2-element vector | 3-element vectorRadial distortion coefficients, specified as the comma-separated
pair consisting of '`RadialDistortion`

' and either
a 2- or 3-element vector. If you specify a 2-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} |

Typically, two coefficients are sufficient. For severe
distortion, you can include *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 vectorTangential distortion coefficients, specified as the comma-separated
pair consisting of '`TangentialDistortion`

' and
a 2-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}),
as follows:

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

p_{1} and p_{2} =
tangential distortion coefficients of the lens |

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

The undistorted pixel locations appear in normalized image coordinates, with the origin at the optical center. The coordinates are expressed in world units.

`'RotationVectors'`

— Camera rotations`[]`

Camera rotations, specified as the comma-separated pair consisting
of '`RotationVectors`

' and an *M*-by-3
matrix. The matrix contains rotation vectors for *M* images,
which contain the calibration pattern that estimates the calibration
parameters. Each row of the matrix contains a vector that describes
the 3-D rotation of the camera relative to the corresponding pattern.

Each vector specifies the 3-D axis about which the camera is rotated. The magnitude of the vector represents the angle of rotation in medians. You can convert any rotation vector to a 3-by-3 rotation matrix using the Rodrigues formula.

You must set the `RotationVectors`

and `TranslationVectors`

properties
together in the constructor to ensure that the number of rotation
vectors equals the number of translation vectors. Setting only one
property but not the other results in an error.

`'TranslationVectors'`

— Camera translations`[]`

Camera translations, specified as the comma-separated pair consisting
of '`RotationVectors`

' and an *M*-by-3
matrix. This matrix contains translation vectors for *M* 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 [*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. |

This equation does not take distortion into consideration.
Distortion is removed by the `undistortImage`

function.

You must set the `RotationVectors`

and `TranslationVectors`

properties
together in the constructor to ensure that the number of rotation
vectors equals the number of translation vectors. Setting only one
property results in an error.

`'WorldPoints'`

— World coordinates`[]`

World coordinates of key points on calibration pattern, specified
as the comma-separated pair consisting of '`WorldPoints`

'
and an *M*-by-2 array. *M* represents
the number of key points in the pattern.

`'WorldUnits'`

— World points units`'mm'`

(default) | stringWorld points units, specified as the comma-separated pair consisting
of '`WorldUnits`

' and a string. The string describes
the units of measure.

`'EstimateSkew'`

— Estimate skew flag`false`

(default) | logical scalarEstimate skew flag, specified as the comma-separated pair consisting
of '`EstimateSkew`

' and 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 comma-separated
pair consisting of '`NumRadialDistortionCoefficients`

'
and the number '`2`

' or '`3`

'.

`'NumRadialDistortionCoefficients'`

— Number of radial distortion coefficients`2`

(default) | `3`

`NumRadialDistortionCoefficients`

'
and the number '`2`

' or '`3`

'.

`'EstimateTangentialDistortion'`

— Estimate tangential distortion flag`false`

(default) | logical scalarEstimate tangential distortion flag, specified as the comma-separated
pair of consisting of '`EstimateTangentialDistortion`

'
and 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.

**Intrinsic camera parameters:**

`IntrinsicMatrix`

— Projection matrix3-by-3 identity matrixProjection 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}*

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

**Camera lens distortion:**

`RadialDistortion`

— Radial distortion coefficients`[0 0 0] `

(default) | 2-element vector | 3-element vectorRadial distortion coefficients, specified as either a 2- or
3-element vector. When you specify a 2-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} |

Typically, two coefficients are sufficient. For severe
distortion, you can include *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 vectorTangential distortion coefficients, specified as a 2-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}),
as follows:

*x*_{distorted} = *x* +
[2 * *p*_{1} * *y* + *p*_{2} *
(*r*^{2} + 2 * *x*^{2})]

*y*_{distorted} = *y* +
[*p*_{1} * (*r*^{2} +
2**y*^{2}) + 2 * *p*_{2} * *x*]

x, y = undistorted pixel
locations |

p_{1} and p_{2} =
tangential distortion coefficients of the lens |

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

The undistorted pixel locations appear in normalized image coordinates, with the origin at the optical center. The coordinates are expressed in world units.

**Extrinsic camera parameters:**

`RotationMatrices`

— 3-D rotation matrix3-by-3-by-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 [*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. |

This equation does not take distortion into consideration.
Distortion is removed by the `undistortImage`

function.

`TranslationVectors`

— Camera translations`[]`

Camera translations, specified as an *M*-by-3
matrix. This matrix contains translation vectors for *M* 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 [*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. |

This equation does not take distortion into consideration.
Distortion is removed by the `undistortImage`

function.

You must set the `RotationVectors`

and `TranslationVectors`

properties
in the constructor to ensure that the number of rotation vectors equals
the number of translation vectors. Setting only one property but not
the other results in an error.

**Estimated camera parameter
accuracy:**

`MeanReprojectionError`

— Average Euclidean distancenumeric value (read-only)Average Euclidean distance between reprojected and detected points, specified as a numeric value in pixels.

`ReprojectionErrors`

— Estimated camera parameters accuracyEstimated 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 imagesWorld 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.

**Estimate camera parameters
settings:**

`NumPatterns`

— Number of calibrated patternsintegerNumber 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`[]`

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) | stringWorld points units, specified as a string. The string describes the units of measure.

`EstimateSkew`

— Estimate skew flag`false`

(default) | logical scalarEstimate 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 scalarEstimate 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.

pointsToWorld | Determine world coordinates of image points |

toStruct | Convert a camera parameters object into a struct |

`cameraParams`

— Camera parameters`cameraParameters`

objectCamera parameters, returned as a `cameraParameters`

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

**Code Generation Support:**

Supports
Code Generation: Yes

Supports MATLAB Function block:
No

Code Generation Support, Usage Notes, and Limitations

This example shows you how to use the cameraParameters object in a workflow to remove distortion from an image. The example creates a cameraParameters object manually. In practice, use the estimateCameraParameters or the cameraCalibrator app to derive the object.

Create a 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 image.

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

Display the original and undistorted images.

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

[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.

Camera Calibrator | `detectCheckerboardPoints`

| `estimateCameraParameters`

| `generateCheckerboardPoints`

| `showExtrinsics`

| `showReprojectionErrors`

| `stereoParameters`

| `undistortImage`

Was this topic helpful?