Main Content

worldToImage

Project world points into image

collapse all in page

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.

example

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

collapse all

Open Live Script

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

Figure contains an axes object. The axes object contains an object of type image.

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

Figure contains an axes object. The axes object contains 2 objects of type image, line. This object represents Projected points.

Input Arguments

collapse all

Transformation of the camera in world coordinates, specified as a rigid3d 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.

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

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

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.

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

collapse all

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

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

See Also

Apps

Functions

Objects