img2world2d

Determine world coordinates of image points

Since R2022b

Syntax

worldPoints = img2world2d(imagePoints,tform,intrinsics)

Description

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

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.

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

Calculate new extrinsics.

camExtrinsics = estimateExtrinsics(imagePoints,worldPoints,intrinsics);

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

newWorldPoints = img2world2d(imagePoints,camExtrinsics,intrinsics);

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

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 you specify the cameraParams argument as a cameraIntrinsics object, img2world2d 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.

tform — Transformation

rigidtform3d object

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

intrinsics — Camera intrinsics

cameraIntrinsics object | fisheyeIntrinsics object | cameraIntrinsicsKB object

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

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

Usage notes and limitations:

Code generation not supported for cameraIntrinsicsKB object input.

Version History

Introduced in R2022b

R2024a: Added support for the cameraIntrinsicsKB object

Support added for the cameraIntrinsicsKB object as the cameraParams input.

R2022b: Recommended over pointsToWorld

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.