# 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

example

````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.```
````stereoParams = stereoParameters(paramStruct)` creates an identical `stereoParameters` object from an existing `stereoParameters` object with parameters stored in `paramStruct`.```

### Input Arguments

expand all

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

expand all

## Intrinsic and extrinsic parameters of the two cameras

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

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

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.

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

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}_{1}& 1\end{array}\right]*FundamentalMatrix*\left[\begin{array}{c}{P}_{2}\\ 1\end{array}\right]=0$`

P1, the point in image 1, corresponds to the point, P2, in image 2. Both points are expressed in pixel coordinates.

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}_{1}& 1\end{array}\right]*EssentialMatrix*\left[\begin{array}{c}{P}_{2}\\ 1\end{array}\right]=0$`

P1, the point in image 1, corresponds to P2, 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 fx and fy.

## Accuracy of estimated parameters

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

## Settings for camera parameter estimation

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

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.

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

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

## Version History

Introduced in R2014a

expand all