worldToImage

Project world points into image

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.