imageToWorldPlaneMapping

R2026b

Compute displacement field to map image plane with reference plane in world coordinate system

Since R2026b

collapse all in page

    Syntax

    D = imageToWorldPlaneMapping(intrinsics,tform)
    D = imageToWorldPlaneMapping(intrinsics,tform,Name=Value)
    [D,Rout] = imageToWorldPlaneMapping(___)

    Description

    D = imageToWorldPlaneMapping(intrinsics,tform) computes a displacement field, D, that maps image pixels onto the Z=0 world plane using the camera intrinsic parameters intrinsics and extrinsic rigid transform tform. The displacement field accounts for both the lens distortion and perspective distortion caused by the camera pose. The function determines the world bounds and pixel resolution automatically from the camera geometry.

    D = imageToWorldPlaneMapping(intrinsics,tform,Name=Value) specifies options to control the output spatial referencing or pixel resolution of the displacement field by using name-value arguments.

    example

    [D,Rout] = imageToWorldPlaneMapping(___) also returns Rout, a spatial referencing object that maps pixel locations in the output space to world coordinates on the Z=0 plane.

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

    Use the imageToWorldPlaneMapping function to compute the displacement field and spatial referencing object for the camera. The displacement field represents the difference the between distorted pixel coordinates in the input image and the intrinsic grid positions in the output space.

    [D,Rout] = imageToWorldPlaneMapping(camIntrinsics,camExtrinsics);

    Use the precomputed displacement field to rectify an image using the imwarp function. 

    rectifiedImage = imwarp(imOrig,D);
imageshow(rectifiedImage,Transformation=Rout)

    Input Arguments

    collapse all

    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.

    Data Types: cameraIntrinsics | cameraIntrinsicsKB

    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. The Z=0 world plane must be at least partially visible from the camera for the mapping to succeed.

    Name-Value Arguments

    collapse all

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: imageToWorldPlaneMapping(intrinsics,tform,PixelExtentInWorld=0.1) specifies to use a metric pixel resolution of 0.1 mm.

    Metric pixel resolution, specified as a positive numeric scalar. The value defines the number of world units per pixel in the rectified output image. The units match the calibration units used by the estimateCameraParameters function. For example, if the calibration pattern square size is in millimeters, then PixelExtentInWorld is in millimeters per pixel.

    If you specify this value as "auto", the function estimates the resolution from the camera intrinsic parameters and extrinsic pose. Set this value smaller than the size of objects you want to measure. Decrease this value to preserve detail in the image you want to measure at the cost of larger output images.

    You cannot specify the OutputView and PixelExtentInWorld arguments simultaneously.

    Spatial referencing information, specified as an imref2d object.

    If you specify this value as "auto", the function automatically computes world bounds and resolution of the rectified image from the camera intrinsic parameters and extrinsic pose. When you specify this value as an imref2d object, the function uses the provided spatial referencing to define the output image bounds and resolution. Use this argument to focus on a specific region of interest or to ensure consistent output dimensions across multiple images.

    You cannot specify the OutputView and PixelExtentInWorld arguments simultaneously.

    Output Arguments

    collapse all

    Displacement field for image-to-world plane mapping, returned as an M-by-N-by-2 numeric array. D(:,:,1) contains the x-displacement and D(:,:,2) contains the y-displacement for each output grid point. The displacements represent the difference between distorted pixel coordinates in the input image and the intrinsic grid positions in the output space.

    Use D with the imwarp function to resample an image onto the world plane. Because the displacement field depends on only the camera parameters and not the image content, you can precompute D once and reuse it for all images from the same camera setup.

    Output spatial referencing, returned as an imref2d object. Rout maps pixel indices in the displacement field to world coordinates on the Z=0 plane, enabling direct metric measurement from images resampled using D.

    Tips

    • Use imageToWorldPlaneMapping for production vision systems that process many images from the same fixed camera. Precompute the displacement field once during setup, then apply it to each image using imwarp. This is significantly faster than using the imageToWorldPlane function on every frame.

    • If the camera moves or is repositioned, you must recompute the displacement field with the new extrinsic parameters. If the camera has preset positions, save a separate displacement field for each position.

    • For one-off or exploratory rectification where performance is not critical, use imageToWorldPlane instead.

    Extended Capabilities

    expand all

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

    Version History

    Introduced in R2026b

    See Also

    | | | | | | | |