Main Content

world2img

Project world points into image

Since R2022b

collapse all in page

    Syntax

    imagePoints = world2img(worldPoints,tform,intrinsics)
    imagePoints = world2img(worldPoints,tform,intrinsics,ApplyDistortion=distort)
    [imagePoints,validIndex] = world2img(___)

    Description

    imagePoints = world2img(worldPoints,tform,intrinsics) projects 3-D world points worldPoints into points on an image, imagePoints, according to a rigid geometric transformation, tform. intrinsics can be a cameraIntrinsics, cameraIntrinsicsKB, or a fisheyeIntrinsics object.

    example

    imagePoints = world2img(worldPoints,tform,intrinsics,ApplyDistortion=distort) returns the projection with distortion applied. Use this syntax only with cameraIntrinsics and cameraIntrinsicsKB objects.

    [imagePoints,validIndex] = world2img(___) also returns the indices of valid image points that are within the boundary of the image.

    Examples

    collapse all

    Open Live Script

    Create a set of calibration images.

    dataDir = fullfile(toolboxdir("vision"),"visiondata", ...
      "calibration","slr");
images = imageDatastore(dataDir);
imageSize = size(readimage(images,1));

    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 = patternWorldPoints("checkerboard",boardSize,squareSize);

    Calibrate the camera.

    cameraParams = estimateCameraParameters(imagePoints,worldPoints, ...
    ImageSize=imageSize(1:2));
intrinsics = cameraParams.Intrinsics;

    Load the image at a new location.

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

    Undistort the image.

    imUndistorted = undistortImage(imOrig,intrinsics);

    Find a reference object in the new image.

    [imagePoints,boardSize] = detectCheckerboardPoints(imUndistorted);

    Calculate new extrinsics.

    camExtrinsics = estimateExtrinsics(imagePoints,worldPoints,intrinsics);

    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 = world2img(worldPoints,camExtrinsics,intrinsics);
hold on
plot(projectedPoints(:,1),projectedPoints(:,2),"g*-");
legend("Projected Points");
hold off

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

    Input Arguments

    collapse all

    3-D world points, specified as an M-by-3 matrix containing M [x,y,z] coordinates of 3-D world points. The worldPoints coordinates must be in the same units as the Translation property of the tform object.

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

    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 the intrinsics argument is a cameraIntrinsics or cameraIntrinsicsKB object.

    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 vector 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

    Version History

    Introduced in R2022b

    expand all

    See Also

    Apps

    Functions

    Objects