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,tformOfCamera2)

stereoParams = stereoParameters(cameraParameters1,cameraParameters2,rotationOfCamera2,translationOfCamera2)

stereoParams = stereoParameters(paramStruct)

Description

stereoParams = stereoParameters(cameraParameters1,cameraParameters2,tformOfCamera2) returns a stereo camera system parameters object using the camera parameters from two cameras and a tformOfCamera2 object that specifies the transformation of camera 2 relative to camera 1. cameraParameters1 and cameraParameters2 are cameraParameters or cameraIntrinsics objects that contain the intrinsics of camera 1 and camera 2 respectively.

stereoParams = stereoParameters(cameraParameters1,cameraParameters2,rotationOfCamera2,translationOfCamera2) creates a stereoParameters object that contains the parameters of a stereo camera system, and sets the cameraParameters1, cameraParameters2, rotationOfCamera2, and translationOfCamera2 properties.

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

Input Arguments

tformOfCamera2 — Transformation of camera 2

rigid3d object

Transformation of camera 2 relative to camera 1, specified as a rigid3d.

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

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

rotationOfCamera2 — Rotation of camera 2

3-by-3 matrix

Rotation of camera 2 relative to camera 1, specified as a 3-by-3 matrix.

The rotationOfCamera2 and the translationOfCamera2 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 = rotationOfCamera2 * orientation2
location1 = translationOfCamera2 * orienation2 + location2

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

translationOfCamera2 — Translation of camera 2

3-element vector

Translation of camera 2 relative to camera 1, specified as a 3-element vector.

The rotationOfCamera2 and the translationOfCamera2 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 = rotationOfCamera2 * orientation2
location1 = translationOfCamera2 * orienation2 + location2

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

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:

$$\left[\begin{array}{cc}{P}_2& 1\end{array}\right]*FundamentalMatrix*{\left[\begin{array}{cc}{P}_1& 1\end{array}\right]}^{\text{'}}=0$$

P₁, the point in image 1 in pixels, corresponds to the point, P₂, in image 2.

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:

$$\left[\begin{array}{cc}{P}_2& 1\end{array}\right]*EssentialMatrix*{\left[\begin{array}{cc}{P}_1& 1\end{array}\right]}^{\text{'}}=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

Stereo Camera Calibration

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 = generateCheckerboardPoints(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);

Visualize camera extrinsics.

figure;
showExtrinsics(params);

References

[1] Zhang, Z. “A Flexible New Technique for Camera Calibration”. IEEE Transactions on Pattern Analysis and Machine Intelligence.Vol. 22, No. 11, 2000, pp. 1330–1334.

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

Version History

Introduced in R2014a