extrinsics

(Not recommended) Compute location of calibrated camera

extrinsics is not recommended. Use the estimateExtrinsics function instead. For more information, see Version History.

Syntax

[rotationMatrix,translationVector] = extrinsics(imagePoints,worldPoints,cameraParams)

Description

[rotationMatrix,translationVector] = extrinsics(imagePoints,worldPoints,cameraParams) returns the 3-D rotation matrix and the 3-D translation vector to allow you to transform points from the world coordinate to the camera coordinate system.

Examples

Compute Camera Extrinsics

Create a set of calibration images.

  images = imageDatastore(fullfile(toolboxdir("vision"),"visiondata", ...
      "calibration", "slr"));

Detect the checkerboard corners in the images.

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

Generate the world coordinates of the checkerboard corners in the pattern-centric coordinate system, with the upper-left corner at (0,0). The square size is in millimeters.

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

Calibrate the camera.

I = readimage(images,1); 
imageSize = [size(I,1), size(I,2)];
cameraParams = estimateCameraParameters(imagePoints,worldPoints, ...
                                        ImageSize=imageSize);
intrinsics = cameraParams.Intrinsics;

Load image at new location.

imOrig = imread(fullfile(matlabroot,"toolbox","vision","visiondata", ...
    "calibration","slr","image9.jpg"));
figure 
imshow(imOrig);
title("Input Image");

Undistort image.

[im,newIntrinsics] = undistortImage(imOrig,intrinsics,OutputView="full");

Find reference object in new image.

[imagePoints,boardSize] = detectCheckerboardPoints(im);

Compensate for image coordinate system shift.

newOrigin = intrinsics.PrincipalPoint - newIntrinsics.PrincipalPoint;
imagePoints = [imagePoints(:,1) + newOrigin(1), ...
               imagePoints(:,2) + newOrigin(2)];

Compute new extrinsics.

[rotationMatrix, translationVector] = ...
    extrinsics(imagePoints,worldPoints,cameraParams);

Compute camera pose.

[orientation, location] = extrinsicsToCameraPose(rotationMatrix,translationVector);
figure
plotCamera(Location=location,Orientation=orientation,Size=20);
hold on
pcshow([worldPoints,zeros(size(worldPoints,1),1)], ...
  VerticalAxisDir="down",MarkerSize=40);

Input Arguments

imagePoints — Image coordinates of points

M-by-2 array

Image coordinates of points, specified as an M-by-2 array. The array contains M number of [x, y] coordinates. The imagePoints and worldPoints inputs must both be double or both be single.

Data Types: single | double

worldPoints — World coordinates corresponding to image coordinates

M-by-2 matrix

World coordinates corresponding to image coordinates, specified as an M-by-2 matrix. The imagePoints and worldPoints inputs must both be double or both be single. The function assumes that the points are coplanar with z= 0 and the number of points, M, must be at least 4.

Data Types: single | double

cameraParams — Camera parameters

cameraParameters object | cameraIntrinsics object | fisheyeIntrinsics object

Object for storing camera parameters, specified as a cameraParameters, cameraIntrinsics, or fisheyeIntrinsics object. These objects are returned by the estimateCameraParameters function, the estimateFisheyeParameters function, or the Camera Calibrator app. The object contains the intrinsic, extrinsic, and lens distortion parameters of a camera.

Output Arguments

rotationMatrix — 3-D rotation

3-by-3 matrix

3-D rotation, returned as a 3-by-3 matrix. The rotation matrix together with the translation vector allows you to transform points from the world coordinate to the camera coordinate system.

If you set the imagePoints and worldPoints inputs to class double, then the function returns the rotationMatrix and translationVector as double. Otherwise, they are single.

translationVector — 3-D translation

1-by-3 vector

3-D translation, returned as a 1-by-3 vector. The rotation matrix together with the translation vector allows you to transform points from the world coordinate to the camera coordinate system.

If you set the imagePoints and worldPoints inputs to class double, then the function returns the rotationMatrix and translationVector as double. Otherwise, they are single.

Algorithms

The extrinsics function uses two different algorithms to compute the extrinsics depending on whether worldPoints are specified as an M-by-2 matrix. Use an M-by-2 matrix for coplanar points where z= 0.

The extrinsics function computes the rotation matrix and translation vector for a single image in closed form. During calibration, the extrinsics are estimated numerically to minimize the reprojection errors for all calibration images. Therefore, using the extrinsics function on one of the calibration images returns rotation matrix and translation vector slightly different from the ones obtained during calibration.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Use in a MATLAB Function block is not supported.

• Use of a fisheyeIntrinsics object as the cameraParams input is not supported.

Version History

Introduced in R2014a

R2022b: Not recommended

Starting in R2022b, most Computer Vision Toolbox™ functions create and perform geometric transformations using the premultiply convention. However, the extrinsics function uses the postmultiply convention. Although there are no plans to remove extrinsics at this time, you can streamline your geometric transformation workflows by switching to the estimateExtrinsics function, which supports the premultiply convention. For more information, see Migrate Geometric Transformations to Premultiply Convention.

To update your code:

• Change instances of the function name extrinsics to estimateExtrinsics.

• Specify the cameraParams argument as a cameraIntrinsics or fisheyeIntrinsics object. If you have a cameraParameters object, then you can get a cameraIntrinsics object by querying the Intrinsics property. If the Intrinsics property is empty according to the isempty function, then set the ImageSize property of the cameraParameters object to an arbitrary vector before querying the Intrinsics property. For example:

  load worldToImageCorrespondences.mat
  if(isempty(cameraParams.Intrinsics))
      cameraParams.ImageSize = [128 128];
  end
  intrinsics = cameraParams.Intrinsics;

• Replace the two output arguments rotationMatrix and translationVector with a single output argument, camExtrinsics. The camExtrinsics argument returns a rigidtform3d object. If you need to obtain the orientation matrix and location vector, then you can query the R and Translation properties of the object. Note that the value of R is the transpose of rotationMatrix.

The table shows examples of how to update your code.

Discouraged Usage

Recommended Replacement

This example calculates the location of a calibrated camera using the exrinsics function with the cameraParams argument specified as a cameraParameters object. [rotMatrix,transVector] = extrinsics( ... imagePoints,worldPoints,cameraParams);

This example gets the camera intrinsics using the Intrinsics property of a cameraParameters object, then calculates the location of the calibrated camera using the estimateExtrinsics function. intrinsics = cameraParams.Intrinsics; camExtrinsics = estimateExtrinsics( ... imagePoints,worldPoints,intrinsics); If you need to obtain the camera orientation and location, then you can query properties of camExtrinsics. rotMatrix = camExtrinsics.R; transVector = camExtrinsics.Translation; If you want the orientation in the postmultiply convention, take the transpose of camExtrinsics.R. rotMatrix = camExtrinsics.R';