pointsToWorld

(Not recommended) Determine world coordinates of image points

pointsToWorld is not recommended. Use the img2world2d function instead. For more information, see Version History.

Syntax

worldPoints = pointsToWorld(intrinsics,tform,imagePoints)

worldPoints = pointsToWorld(intrinsics,rotationMatrix,translationVector,imagePoints)

Description

worldPoints = pointsToWorld(intrinsics,tform,imagePoints) maps undistorted image points imagePoints, onto points on the X-Y plane in world coordinates, worldPoints using the rigid3d transformation tform.

worldPoints = pointsToWorld(intrinsics,rotationMatrix,translationVector,imagePoints) returns world points on the X-Y plane, which correspond to the input image points. Points are converted using the input rotation matrix, translation vector, and camera intrinsics.

Examples

Map Image Points of Fisheye Image to World Coordinates

Map the points of a fisheye image to world coordinates and compare these points to the ground truth points. A series of checkerboard pattern images are used to estimate the fisheye parameters and calibrate the camera.

Create a set of checkerboard calibration images.

images = imageDatastore(fullfile(toolboxdir('vision'),'visiondata' ,...
      'calibration','gopro'));

Detect the checkerboard corners in the images. Leave the last image for testing.

[imagePoints,boardSize] = detectCheckerboardPoints(images.Files(1:end-1));

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

squareSize = 29; % millimeters
worldPoints = patternWorldPoints('checkerboard',boardSize,squareSize);

Estimate the fisheye camera parameters from the image and world points. Use the first image to get image size.

I = imread(images.Files{end}); 
imageSize = [size(I,1) size(I,2)];
fisheyeParams = estimateFisheyeParameters(imagePoints,worldPoints,imageSize);
intrinsics = fisheyeParams.Intrinsics;

Find the reference object in the new image.

imagePoints = detectCheckerboardPoints(I, 'PartialDetections', false);

Compute new extrinsics.

[R,t] = extrinsics(imagePoints,worldPoints,intrinsics);

Map image points to world coordinates in the X-Y plane.

newWorldPoints = pointsToWorld(intrinsics,R,t,imagePoints);

Compare estimated world points to the ground truth points.

plot(worldPoints(:,1),worldPoints(:,2),'gx');
hold on
plot(newWorldPoints(:,1),newWorldPoints(:,2),'ro');
legend('Ground Truth','Estimates');
hold off

Input Arguments

intrinsics — Camera intrinsics

cameraIntrinsics object | fisheyeIntrinsics object

Camera parameters, specified as a cameraIntrinsics or a fisheyeIntrinsics object. The objects store information about a camera’s intrinsic calibration parameters, including the lens distortion parameters.

tform — Transformation

rigid3d object

Transformation of the camera in world coordinates, specified as a rigid3d object.

rotationMatrix — 3-D rotation

3-by-3 matrix

3-D rotation of the world coordinates relative to the image coordinates, specified as a 3-by-3 matrix. The rotation matrix, together with the translation vector, enable you to transform points from the world coordinate system to the camera coordinate system. The rotationMatrix and translationVector inputs must be the same data type.

Data Types: double | single

translationVector — 3-D translation

1-by-3 vector

3-D translation of the world coordinates relative to the image coordinates, specified as a 1-by-3 vector. The translation vector, together with the rotation matrix, enable you to transform points from the world coordinate system to the camera coordinate system. The rotationMatrix and translationVector inputs must be the same data type.

Data Types: double | single

imagePoints — Image points

M-by-2 matrix

Image points, specified as an M-by-2 matrix containing M [x, y] coordinates of image points.

When using the cameraParameters object as the cameraParams input, pointsToWorld does not account for lens distortion. Therefore, the imagePoints input must contain image points detected in the undistorted image, or they must be undistorted using the undistortPoints function. For a fisheyeIntrinsics object, the image points are distorted.

Output Arguments

worldPoints — World coordinates

M-by-2 matrix

World coordinates, returned as an M-by-2 matrix. M represents the number of undistorted points in [x, y] world coordinates.

Extended Capabilities

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

Version History

Introduced in R2016a

R2022b: Not recommended

Starting in R2022b, most Computer Vision Toolbox™ functions create and perform geometric transformations using the premultiply convention. However, the pointsToWorld function uses the postmultiply convention. Although there are no plans to remove pointsToWorld at this time, you can streamline your geometric transformation workflows by switching to the img2world2d 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 pointsToWorld to img2world2d.

• Switch the order of the intrinsics and the imagePoints arguments.

• Specify the transformation as a rigidtform3d object using the tform argument. img2world2d does not support the rotationMatrix and translationVector input arguments. Note that you create the rigidtform3d object using the transpose of rotationMatrix or the transpose of the transformation matrix in the T property of tform.

Discouraged Usage	Recommended Replacement
This example specifies the transformation as a rotation matrix and a translation vector, then determines the world coordinates of image points using the pointsToWorld function. worldPoints = pointsToWorld(intrinsics, ... rotationMatrix,translationVector,imagePoints)	This example specifies the transformation as a rigidtform3d object, then determines the world coordinates of image points using the img2world2d function. Note that you create the rigidtform3d object using the transpose of the rotation matrix, rotationMatrix. tform = rigidtform3d(rotationMatrix',translationVector); worldPoints = img2world2d(imagePoints,tform,intrinsics);
This example specifies the transformation as a rigid3d object using the transpose of the geometric transformation matrix A in the premultiply convention, then determines the world coordinates of image points using the pointsToWorld function. A = [1 0 0 0; 0 1 0 0; 0 0 1 -10; 0 0 0 1]; tformOld = rigid3d(A'); worldPoints = pointsToWorld(intrinsics,tformOld,imagePoints);	This example specifies the transformation as a rigidtform3d object using the geometric transformation matrix A, then determines the world coordinates of image points using the img2world2d function A = [1 0 0 0; 0 1 0 0; 0 0 1 -10; 0 0 0 1]; tform = rigidtform3d(A); worldPoints = img2world2d(imagePoints,tform,intrinsics); If instead you start with an existing rigid3d object tformOld, then you can get the geometric transformation matrix in the postmultiply convention by querying the property T of tformOld. T = tformOld.T; tform = rigidtform3d(T'); worldPoints = img2world2d(imagePoints,tform,intrinsics);