imref2d

Reference 2-D image to world coordinates

Description

An imref2d object stores the relationship between the intrinsic coordinates anchored to the rows and columns of a 2-D image and the spatial location of the same row and column locations in a world coordinate system.

The image is sampled regularly in the planar world-x and world-y coordinate system such that intrinsic-x values align with world-x values, and intrinsic-y values align with world-y values. The resolution in each dimension can be different.

Creation

You can create an imref2d object in these ways.

• affineOutputView — Store the spatial extent of an image that is warped by a 2-D affine geometric transformation.

• The imref2d function described here.

Syntax

R = imref2d

R = imref2d(imageSize)

R = imref2d(imageSize,pixExtentWorldX,pixExtentWorldY)

R = imref2d(imageSize,xWorldLim,yWorldLim)

Description

R = imref2d creates an imref2d object with default property settings.

R = imref2d(imageSize) specifies the image size in each spatial dimension.

R = imref2d(imageSize,pixExtentWorldX,pixExtentWorldY) also specifies the spatial extent of a single pixel in the x- and y-dimensions in the world coordinate system.

R = imref2d(imageSize,xWorldLim,yWorldLim) also specifies the limits of the image in the x- and y-dimensions in the world coordinate system.

Input Arguments

imageSize — Number of elements in each spatial dimension

2-element positive row vector

Number of elements in each spatial dimension, specified as a 2-element positive row vector. imageSize is the same form as that returned by the size function.

This argument sets the ImageSize property.

Data Types: double

pixExtentWorldX — Size of single pixel in x-dimension

positive number

Size of a single pixel in the x-dimension measured in the world coordinate system, specified as a positive number.

This argument sets the PixelExtentInWorldX property.

Data Types: double

pixExtentWorldY — Size of single pixel in y-dimension

positive number

Size of a single pixel in the y-dimension measured in the world coordinate system, specified as a positive number.

This argument sets the PixelExtentInWorldY property.

Data Types: double

xWorldLim — Limits of image in world x-dimension

2-element numeric row vector

Limits of image in world x-dimension, specified as a 2-element row numeric vector [xMin xMax].

This argument sets the XWorldLimits property.

Data Types: double

yWorldLim — Limits of image in world y-dimension

2-element numeric row vector

Limits of image in world y-dimension, specified as a 2-element numeric row vector [yMin yMax].

This argument sets the YWorldLimits property.

Data Types: double

Output Arguments

R — 2-D spatial referencing

imref2d object

2-D spatial referencing, returned as an imref2d object.

Properties

ImageExtentInWorldX — Span of image in the x-dimension in the world coordinate system

numeric scalar

Span of image in the x-dimension in the world coordinate system, specified as a numeric scalar. The imref2d object sets this value as PixelExtentInX * ImageSize(2).

Data Types: double

ImageExtentInWorldY — Span of image in the y-dimension in the world coordinate system

numeric scalar

Span of image in the y-dimension in the world coordinate system, specified as a numeric scalar. The imref2d object sets this value as PixelExtentInY * ImageSize(1).

Data Types: double

ImageSize — Number of elements in each spatial dimension

2-element positive row vector

Number of elements in each spatial dimension, specified as a 2-element positive row vector. ImageSize is the same form as that returned by the size function.

Data Types: double

PixelExtentInWorldX — Size of a single pixel in the x-dimension measured in the world coordinate system

positive number

Size of a single pixel in the x-dimension measured in the world coordinate system, specified as a positive number.

Data Types: double

PixelExtentInWorldY — Size of a single pixel in the y-dimension measured in the world coordinate system

positive number

Size of a single pixel in the y-dimension measured in the world coordinate system, specified as a positive number.

Data Types: double

XWorldLimits — Limits of image in world x-dimension

2-element numeric row vector

Limits of image in world x-dimension, specified as a 2-element row numeric vector [xMin xMax].

Data Types: double

YWorldLimits — Limits of image in world y-dimension

2-element numeric row vector

Limits of image in world y-dimension, specified as a 2-element numeric row vector [yMin yMax].

Data Types: double

XIntrinsicLimits — Limits of image in intrinsic units in the x-dimension

2-element row vector

Limits of image in intrinsic units in the x-dimension, specified as a 2-element row vector [xMin xMax]. For an m-by-n image (or an m-by-n-by-p image), XIntrinsicLimits equals [0.5, n+0.5].

Data Types: double

YIntrinsicLimits — Limits of image in intrinsic units in the y-dimension

2-element row vector

Limits of image in intrinsic units in the y-dimension, specified as a 2-element row vector [yMin yMax]. For an m-by-n image (or an m-by-n-by-p image), YIntrinsicLimits equals [0.5, m+0.5].

Data Types: double

Object Functions

contains	Determine if image contains points in world coordinate system
intrinsicToWorld	Convert from intrinsic to world coordinates
sizesMatch	Determine if object and image are size-compatible
worldToIntrinsic	Convert from world to intrinsic coordinates
worldToSubscript	Convert world coordinates to row and column subscripts

Examples

Create 2-D Spatial Referencing Object Knowing Image Size and World Limits

Read a 2-D grayscale image into the workspace.

A = imread('pout.tif');

Create an imref2d object, specifying the size and world limits of the image associated with the object.

xWorldLimits = [2 5];
yWorldLimits = [3 6];
RA = imref2d(size(A),xWorldLimits,yWorldLimits)

RA = 
  imref2d with properties:

           XWorldLimits: [2 5]
           YWorldLimits: [3 6]
              ImageSize: [291 240]
    PixelExtentInWorldX: 0.0125
    PixelExtentInWorldY: 0.0103
    ImageExtentInWorldX: 3
    ImageExtentInWorldY: 3
       XIntrinsicLimits: [0.5000 240.5000]
       YIntrinsicLimits: [0.5000 291.5000]

Display the image, specifying the spatial referencing object. The axes coordinates reflect the world coordinates.

figure
imshow(A,RA);

Create 2-D Spatial Referencing Object Knowing Image Size and Resolution

Read a 2-D grayscale image into the workspace.

m = dicominfo('knee1.dcm');
A = dicomread(m);

Create an imref2d object, specifying the size and the resolution of the pixels. The DICOM file contains a metadata field PixelSpacing that specifies the image resolution in each dimension in millimeters per pixel.

RA = imref2d(size(A),m.PixelSpacing(2),m.PixelSpacing(1))

RA = 
  imref2d with properties:

           XWorldLimits: [0.1562 160.1562]
           YWorldLimits: [0.1562 160.1562]
              ImageSize: [512 512]
    PixelExtentInWorldX: 0.3125
    PixelExtentInWorldY: 0.3125
    ImageExtentInWorldX: 160
    ImageExtentInWorldY: 160
       XIntrinsicLimits: [0.5000 512.5000]
       YIntrinsicLimits: [0.5000 512.5000]

Display the image, specifying the spatial referencing object. The axes coordinates reflect the world coordinates.

figure
imshow(A,RA,'DisplayRange',[0 512])

Compare the width of the image in world coordinates and intrinsic coordinates. This image width in intrinsic coordinates, with units of pixels, is:

RA.ImageSize(1)

ans = 
512

The image width in world coordinates, with units of millimeters, is:

RA.ImageExtentInWorldX

ans = 
160

More About

Intrinsic Coordinate System

The intrinsic coordinate values (x,y) of the center point of any pixel are identical to the values of the column and row subscripts for that pixel. For example, the center point of the pixel in row 5, column 3 has intrinsic coordinates x = 3.0, y = 5.0.

The order of coordinate specification (3.0,5.0) is reversed in intrinsic coordinates relative to pixel subscripts (5,3). Intrinsic coordinates are defined on a continuous plane, while the subscript locations are discrete locations with integer values.

Tips

• You can create an imref2d object for an RGB image. If you create the object specifying the ImageSize property as a three-element vector (such as that returned by the size function), only the first two elements are used to set ImageSize.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• imref2d supports the generation of C and C++ code (requires MATLAB^® Coder™). For more information, see Code Generation for Image Processing.

• When generating code, you can only specify singular objects—arrays of objects are not supported.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2013a