imagePointsToWorldPlane

R2026b

Project image points onto reference plane in world coordinate system

Since R2026b

collapse all in page

    Syntax

    worldPoints = imagePointsToWorldPlane(imgPoints,intrinsics,tform)

    Description

    worldPoints = imagePointsToWorldPlane(imgPoints,intrinsics,tform) projects the image points imgPoints onto the Z=0 world plane using the camera intrinsic parameters intrinsics and extrinsic rigid transform tform. The function removes lens distortion from the image points, then maps them to world coordinates using a projective transformation derived from the camera pose. The output coordinates are in the same units used during camera calibration.

    example

    Examples

    collapse all

    Open Live Script

    Create a set of calibration images. These images contain a checkerboard pattern captured from different camera views by an SLR camera. 

    images = imageDatastore(fullfile(toolboxdir("vision"),"visiondata","calibration","slr"));

    Detect the checkerboard corners in all calibration images and estimate the camera intrinsic parameters. The checkerboard squares are 29 mm per side, so all world measurements are in millimeters.

    [imagePoints,patternDims] = detectCheckerboardPoints(images.Files);
squareSize = 29;
worldPoints = patternWorldPoints("checkerboard",patternDims,squareSize);
I = readimage(images,1);
imageSize = [size(I,1) size(I,2)];
cameraParams = estimateCameraParameters(imagePoints,worldPoints,ImageSize=imageSize);
intrinsics = cameraParams.Intrinsics;

    Load an image you want to rectify, and display it. 

    imOrig = readimage(images,9);
imshow(imOrig)

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

    Detect the checkerboard in the image, and estimate the camera extrinsic pose relative to the checkerboard plane.

    [imagePoints,patternDims] = detectCheckerboardPoints(imOrig);
camIntrinsics = cameraParams.Intrinsics;
camExtrinsics = estimateExtrinsics(imagePoints,worldPoints,camIntrinsics);

    Specify the pixel coordinates of points on the opposite edges of objects visible in the image. These coordinates correspond to the edges of the bottom coin on the right side of the image. Use imagePointsToWorldPlane to transform the pixel coordinates into world coordinates on the Z=0 measurement plane. The function first undistorts the points to remove lens distortion, then applies the projective mapping derived from the camera pose. 

    objectEdgePoints = [2505 1068; 2396 1054];
worldCoords = imagePointsToWorldPlane(objectEdgePoints,camIntrinsics,camExtrinsics);
disp(worldCoords)
       39.6356  196.2585
   43.4462  179.8766

    Calculate the Euclidean distance between the projected world points to obtain the diameter of the coin, in millimeters.

    d = worldCoords(2,:) - worldCoords(1,:);
distanceMM = hypot(d(1),d(2));
disp("Measured distance: " + num2str(distanceMM,'%.2f') + " mm")
    Measured distance: 16.82 mm

    Overlay the measurement points and connecting line on the original image to confirm the measurement locations.

    imshow(imOrig,InitialMagnification=25)
hold on
plot(objectEdgePoints(:,1),objectEdgePoints(:,2),"r-o",LineWidth=2,MarkerSize=8)
hold off
title("Measurement Points Overlaid on Image")

    Figure contains an axes object. The hidden axes object with title Measurement Points Overlaid on Image contains 2 objects of type image, line.

    Input Arguments

    collapse all

    Image point coordinates, specified as an M-by-2 numeric matrix. Each row represents the [x y] pixel coordinates of a point in the image. The coordinate system uses standard image coordinates, where (1, 1) is the upper-left corner, xincreases rightward, and y increases downward.

    Data Types: double | single | uint8 | uint16 | uint32 | int8 | int16 | int32

    Camera intrinsic parameters, specified as a cameraIntrinsics or cameraIntrinsicsKB object. The intrinsic parameters include focal length, principal point, image size, and distortion coefficients, defining the mapping between 3-D camera coordinates and 2-D image coordinates. Use estimateCameraParameters to obtain camera intrinsics parameters for the standard lens model, or use estimateFisheyeParameters to obtain camera intrinsic parameters for the Kannala-Brandt fisheye model.

    Camera extrinsic pose, specified as a rigidtform3d object. The transform defines the rotation and translation between the world coordinate system and the camera coordinate system. Use the estimateExtrinsics function to obtain the camera extrinsic pose from an image of a calibration pattern placed on the measurement reference plane.

    Output Arguments

    collapse all

    World plane coordinates, returned as an M-by-2 numeric matrix. Each row contains the [x y] world coordinates of a point on the Z=0 world plane, in the same units as the calibration pattern used during camera calibration. For example, if the calibration pattern square size is in millimeters, the output is in millimeters. The number of rows matches the number of input image points, with worldPoints(i,:) corresponding to imgPoints(i,:).

    Points that map behind the camera might have unreliable coordinates. For critical applications, verify point visibility using camera geometry.

    Data Types: double

    Tips

    • Use imagePointsToWorldPlane when you need world coordinates for a small number of specific points, such as feature locations or centroids. This is more efficient than rectifying the entire image with the imageToWorldPlane function.

    • For dense measurements, or when you intend to use visual measurement tools such as caliper or regionprops, use imageToWorldPlane to rectify the full image instead.

    Extended Capabilities

    expand all

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

    Version History

    Introduced in R2026b

    See Also

    | | | | | | | |