stereoParameters

Object for storing stereo camera system parameters

Description

The stereoParameters object stores the intrinsic and extrinsic parameters of two cameras and their geometric relationship.

Creation

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

Syntax

stereoParams = stereoParameters(cameraParameters1,cameraParameters2,poseCamera2)

stereoParams = stereoParameters(paramStruct)

Description

stereoParams = stereoParameters(cameraParameters1,cameraParameters2,poseCamera2) returns a stereo camera system parameters object using the camera parameters from two cameras and the pose of camera 2. cameraParameters1 and cameraParameters2 are cameraParameters or cameraIntrinsics objects that contain the intrinsics of camera 1 and camera 2, respectively. The three input arguments set the CameraParameters1, CameraParameters2, and PoseCamera2 properties, respectively.

example

stereoParams = stereoParameters(paramStruct) creates an identical stereoParameters object from an existing stereoParameters object with parameters stored in paramStruct.

Input Arguments

expand all

`paramStruct` — Stereo parameters
struct

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

Properties

expand all

Intrinsic and extrinsic parameters of the two cameras

`CameraParameters1` — Parameters of camera 1
`cameraParameters` object

Parameters of camera 1, specified as a cameraParameters object. The object contains the intrinsic, extrinsic, and lens distortion parameters of a camera.

`CameraParameters2` — Parameters of camera 2
`cameraParameters` object

Parameters of camera 2, specified as a cameraParameters object. The object contains the intrinsic, extrinsic, and lens distortion parameters of a camera.

Geometric relationship between the two cameras

`PoseCamera2` — Relative pose of second camera
`rigidtform3d` object

Relative pose of the second camera, specified as a rigidtform3d object. The R and the Translation properties of the object represent the relative rotation and translation between camera 1 and camera 2, respectively. They convert camera 2 coordinates back to camera 1 coordinates using:

orientation1 = orientation2 * R
location1 = orientation2 * Translation + location2

orientation1 and location1 represent the absolute pose of camera 1, and orientation2 and location2 represent the absolute pose of camera 2.

Camera 2 displayed in camera 1 coordinate system, with the axis origin at the optical center of camera 1.

You cannot set the value of PoseCamera2 after you create the stereoParameters object.

`FundamentalMatrix` — Fundamental matrix
3-by-3 matrix

Fundamental matrix, stored as a 3-by-3 matrix. The fundamental matrix relates the two stereo cameras, such that the following equation must be true:

$[\begin{matrix} P_{1} & 1 \end{matrix}] * F u n d a m e n t a l M a t r i x * [\begin{matrix} P_{2} \\ 1 \end{matrix}] = 0$

P₁, the point in image 1, corresponds to the point, P₂, in image 2. Both points are expressed in pixel coordinates.

`EssentialMatrix` — Essential matrix
3-by-3 matrix

Essential matrix, stored as a 3-by-3 matrix. The essential matrix relates the two stereo cameras, such that the following equation must be true:

$[\begin{matrix} P_{1} & 1 \end{matrix}] * E s s e n t i a l M a t r i x * [\begin{matrix} P_{2} \\ 1 \end{matrix}] = 0$

P₁, the point in image 1, corresponds to P₂, the point in image 2. Both points are expressed in normalized image coordinates, where the origin is at the camera’s optical center. The x and y pixel coordinates are normalized by the focal length f_x and f_y.

Accuracy of estimated parameters

`MeanReprojectionError` — Average Euclidean distance
number of pixels

Average Euclidean distance between reprojected points and detected points over all image pairs, specified in pixels.

Settings for camera parameter estimation

`NumPatterns` — Number of calibrated patterns
integer

Number of calibration patterns that estimate the extrinsics of the two cameras, stored as an integer.

`WorldPoints` — World coordinates
M-by-2 array

World coordinates of key points in the 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

World points units, specified as a character vector. The character vector describes the units of measure.

Object Functions

toStruct Convert a stereo parameters object into a struct

Examples

collapse all

Perform Stereo Camera Calibration

Open Live Script

Specify calibration images.

leftImages = imageDatastore(fullfile(toolboxdir("vision"),"visiondata", ...
    "calibration","stereo","left"));
rightImages = imageDatastore(fullfile(toolboxdir("vision"),"visiondata", ...
    "calibration","stereo","right"));

Detect the checkerboards.

[imagePoints,boardSize] = ...
  detectCheckerboardPoints(leftImages.Files,rightImages.Files);

Specify the world coordinates of the checkerboard keypoints. Square size is in millimeters.

squareSize = 108;
worldPoints = patternWorldPoints("checkerboard",boardSize,squareSize);

Calibrate the stereo camera system. Both cameras have the same resolution.

I = readimage(leftImages,1); 
imageSize = [size(I,1) size(I,2)];
params = estimateCameraParameters(imagePoints,worldPoints, ...
    "ImageSize",imageSize);

Visualize the calibration accuracy.

showReprojectionErrors(params)

Figure contains an axes object. The axes object with title Mean Reprojection Error per Image, xlabel Image Pairs, ylabel Mean Error in Pixels contains 5 objects of type bar, line. These objects represent Camera 1, Camera 2, Overall Mean Error: 0.06 pixels.

Visualize camera extrinsics.

figure
showExtrinsics(params)

Figure contains an axes object. The axes object with title Extrinsic Parameters Visualization, xlabel X (mm), ylabel Z (mm) contains 28 objects of type patch, text, line.

Convert to structure.

paramsStruct = toStruct(params)

paramsStruct = struct with fields:
       CameraParameters1: [1x1 struct]
       CameraParameters2: [1x1 struct]
       RotationOfCamera2: [3x3 double]
    TranslationOfCamera2: [-119.8720 -0.4005 -0.0258]
                 Version: [1x1 struct]
     RectificationParams: [1x1 struct]

References

[1] Zhang, Z. "A Flexible New Technique for Camera Calibration." IEEE Transactions on Pattern Analysis and Machine Intelligence 22, no. 11 (November 2000): 1330–34. https://doi.org/10.1109/34.888718..

[2] Heikkila, J., and O. Silven. “A Four-Step Camera Calibration Procedure with Implicit Image Correction.” In Proceedings of IEEE Computer Society Conference on Computer Vision and Pattern Recognition, 1106–12. San Juan, Puerto Rico: IEEE Comput. Soc, 1997. https://doi.org/10.1109/CVPR.1997.609468.

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 stereoParameters object into generated code. See the Code Generation for Depth Estimation from Stereo Video example.

Version History

Introduced in R2014a

expand all

R2022b: Supports premultiply matrix convention

Starting in R2022b, many Computer Vision Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, some input arguments and properties of stereoParameters object have changed to support the premultiply convention.

You can now specify the tformOfCamera2 argument as a rigidtform3d object, which uses the premultiply convention. Although you can still specify tformOfCamera2 as a rigid3d object, this object uses the postmultiply convention and is not recommended.
The new PoseCamera2 property replaces the old RotationOfCamera2 and TranslationOfCamera2 properties. You can access the rotation matrix and translation vector by querying the R and Translation properties of the rigidtform3d object stored in the PoseCamera2 property. The value of the R property is the transpose of RotationOfCamera2.

For more information, see Migrate Geometric Transformations to Premultiply Convention.

stereoParameters

Description

Creation

Syntax

Description

Input Arguments

`paramStruct` — Stereo parameters
struct

Properties

Intrinsic and extrinsic parameters of the two cameras

`CameraParameters1` — Parameters of camera 1
`cameraParameters` object

`CameraParameters2` — Parameters of camera 2
`cameraParameters` object

Geometric relationship between the two cameras

`PoseCamera2` — Relative pose of second camera
`rigidtform3d` object

`FundamentalMatrix` — Fundamental matrix
3-by-3 matrix

`EssentialMatrix` — Essential matrix
3-by-3 matrix

Accuracy of estimated parameters

`MeanReprojectionError` — Average Euclidean distance
number of pixels

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

Object Functions

Examples

Perform Stereo Camera Calibration

References

Extended Capabilities

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

Version History

R2022b: Supports premultiply matrix convention

See Also

Apps

Objects

Functions

Topics

stereoParameters

Description

Creation

Syntax

Description

Input Arguments

paramStruct — Stereo parameters struct

Properties

Intrinsic and extrinsic parameters of the two cameras

CameraParameters1 — Parameters of camera 1 cameraParameters object

CameraParameters2 — Parameters of camera 2 cameraParameters object

Geometric relationship between the two cameras

PoseCamera2 — Relative pose of second camera rigidtform3d object

FundamentalMatrix — Fundamental matrix 3-by-3 matrix

EssentialMatrix — Essential matrix 3-by-3 matrix

Accuracy of estimated parameters

MeanReprojectionError — Average Euclidean distance number of pixels

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

Object Functions

Examples

Perform Stereo Camera Calibration

References

Extended Capabilities

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

Version History

R2022b: Supports premultiply matrix convention

See Also

Apps

Objects

Functions

Topics

`paramStruct` — Stereo parameters
struct

`CameraParameters1` — Parameters of camera 1
`cameraParameters` object

`CameraParameters2` — Parameters of camera 2
`cameraParameters` object

`PoseCamera2` — Relative pose of second camera
`rigidtform3d` object

`FundamentalMatrix` — Fundamental matrix
3-by-3 matrix

`EssentialMatrix` — Essential matrix
3-by-3 matrix

`MeanReprojectionError` — Average Euclidean distance
number of pixels

`NumPatterns` — Number of calibrated patterns
integer

`WorldPoints` — World coordinates
M-by-2 array

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

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