worldToImage

(Not recommended) Project world points into image

worldToImage is not recommended. Use the world2img function instead. For more information, see Compatibility Considerations.

Syntax

imagePoints = worldToImage(intrinsics,tform,worldPoints)

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

[imagePoints,validIndex] = worldToImage(___)

[___] = worldToImage(___'ApplyDistortion',distort)

Description

imagePoints = worldToImage(intrinsics,tform,worldPoints) projects 3-D world points worldPoints into points on an image, imagePoints. intrinsics can be a cameraIntrinsics or a fisheyeIntrinsics object. tform is a rigid3d object.

imagePoints = worldToImage(intrinsics,rotationMatrix,translationVector,worldPoints) returns the projection of 3-D world points into an image given the camera intrinsics, the rotation matrix, and the translation vector.

[imagePoints,validIndex] = worldToImage(___) also returns the indices of valid image points that are within the boundary of the image using any of the previous syntax inputs.

[___] = worldToImage(___'ApplyDistortion',distort) returns the projection with the option of applying distortion. This syntax is supported for nonfisheye camera parameters.

Examples

Project World Points into Image

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

squareSize = 29; % in millimeters
worldPoints = generateCheckerboardPoints(boardSize,squareSize);

Calibrate the camera.

cameraParams = estimateCameraParameters(imagePoints,worldPoints);

Load the image at a new location.

imOrig = imread(fullfile(matlabroot,'toolbox','vision','visiondata', ...
        'calibration','slr','image9.jpg'));

imshow(imOrig,'InitialMagnification',30);

Undistort the image.

imUndistorted = undistortImage(imOrig,cameraParams);

Find a reference object in the new image.

[imagePoints,boardSize] = detectCheckerboardPoints(imUndistorted);

Compute new extrinsics.

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

Add a z-coordinate to the world points.

zCoord = zeros(size(worldPoints,1),1);
worldPoints = [worldPoints zCoord];

Project the world points back into the original image.

projectedPoints = worldToImage(cameraParams,R,t,worldPoints);
hold on
plot(projectedPoints(:,1),projectedPoints(:,2),'g*-');
legend('Projected points');
hold off

Input Arguments

tform — Transformation

rigid3d object

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

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.

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

worldPoints — 3-D world points

M-by-3 matrix

3-D world points, specified as an M-by-3 matrix containing M [x,y,z] coordinates of 3-D world points.

If you use the tform input argument then the worldPoints coordinates must be in the same units as the Translation property of the tform object.

distort — Apply lens distortion

false (default) | true

Option to apply lens distortion, specified as false or true. When you set this argument to true, the function applies lens distortion to the output imagePoints.

This argument is valid only when using a cameraParameters object as the cameraParams input.

Output Arguments

imagePoints — Image points

M-by-2 matrix

Image points, returned as an M-by-2 matrix of M [x,y] point coordinates.

validIndex — Valid index

M-by-1 logical array

Valid index returned as an M-by-1 logical array that specify the indices of valid image points in the imagePoints output that are within the boundary of the image. The world points that correspond to the indices are inside the field of view of the camera.

Extended Capabilities

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

Version History

Introduced in R2016b

R2022b: Not recommended

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

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

• Specify the transformation as a rigidtform3d object using the tform argument. world2img 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 projects 3-D world points into points on an image using the worldToImage function. imagePoints = worldToImage(intrinsics, ... rotationMatrix,translationVector,worldPoints);	This example specifies the transformation as a rigidtform3d object, then projects 3-D world points into points on an image using the world2img function. Note that you create the rigidtform3d object using the transpose of the rotation matrix, rotationMatrix. tform = rigidtform3d(rotationMatrix',translationVector); imagePoints = world2img(worldPoints,tform,intrinsics);
This example specifies the transformation rigid3d object using the transpose of the geometric transformation matrix A in the premultiply convention, then projects 3-D world points into points on an image using the worldToImage function. A = [1 0 0 0; 0 1 0 0; 0 0 1 -10; 0 0 0 1]; tformOld = rigid3d(A'); imagePoints = worldToImage(intrinsics,tformOld,worldPoints);	This example specifies the transformation as a rigidtform3d object using the geometric transformation matrix A, then projects 3-D world points into points on an image using the world2img function. A = [1 0 0 0; 0 1 0 0; 0 0 1 -10; 0 0 0 1]; tform = rigidtform3d(A); imagePoints = world2img(worldPoints,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'); imagePoints = world2img(worldPoints,tform,intrinsics);