imtransform

Apply 2-D spatial transformation to image

imtransform is not recommended. Use imwarp instead.

Syntax

B = imtransform(A,tform)
B = imtransform(A,tform,interp)
B = imtransform(___,Name,Value)
[B,xdata,ydata] = imtransform(___)

Description

example

B = imtransform(A,tform) transforms image A according to the 2-D spatial transformation defined by tform, and returns the transformed image, B.

If A is a color image, then imtransform applies the same 2-D transformation to each color channel. Likewise, if A is a volume or image sequence with three or more dimensions, then imtransform applies the same 2-D transformation to all 2-D planes along the higher dimensions. For arbitrary-dimensional array transformations, use tformarray.

B = imtransform(A,tform,interp) specifies the form of interpolation to use.

B = imtransform(___,Name,Value) uses name-value pairs to control various aspects of the spatial transformation.

example

[B,xdata,ydata] = imtransform(___) also returns the extent of the output image B in the output X-Y space. By default, imtransform calculates xdata and ydata automatically so that B contains the entire transformed image A. However, you can override this automatic calculation by specifying values for the XData and YData name-value pair input arguments.

Examples

Simple Transformation

Apply a horizontal shear to a grayscale image.

I = imread('cameraman.tif');
tform = maketform('affine',[1 0 0; .5 1 0; 0 0 1]);
J = imtransform(I,tform);
imshow(J)

Projective Transformation

Map a square to a quadrilateral with a projective transformation. Set up an input coordinate system so that the input image fills the unit square with vertices (0 0), (1 0), (1 1), (0 1).

I = imread('cameraman.tif');
udata = [0 1];  vdata = [0 1];

Transform to a quadrilateral with vertices (-4 2), (-8 3), (-3 -5), (6 3).

tform = maketform('projective',[ 0 0;  1  0;  1  1; 0 1],...
                               [-4 2; -8 -3; -3 -5; 6 3]);

Fill with gray and use bicubic interpolation. Make the output size the same as the input size.

[B,xdata,ydata] = imtransform(I,tform,'bicubic', ...
                              'udata',udata,...
                              'vdata',vdata,...
                              'size',size(I),...
                              'fill',128);
subplot(1,2,1); imshow(I,'XData',udata,'YData',vdata)
subplot(1,2,2); imshow(B,'XData',xdata,'YData',ydata)

Image Registration

Read an aerial photo into the MATLAB® workspace and view it.

unregistered = imread('westconcordaerial.png');
figure
imshow(unregistered)

Read an orthophoto into the MATLAB workspace and view it.

figure
imshow('westconcordorthophoto.png')

Load control points that were previously picked.

load westconcordpoints

Create a transformation structure for a projective transformation using the points.

t_concord = cp2tform(movingPoints,fixedPoints,'projective');

Get the width and height of the orthophoto, perform the transformation, and view the result.

info = imfinfo('westconcordorthophoto.png');

registered = imtransform(unregistered,t_concord,...
    'XData',[1 info.Width],'YData',[1 info.Height]);
figure
imshow(registered)

Input Arguments

collapse all

Image to be transformed, specified as a numeric or logical array of any dimension.

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

Transformation structure, specified as a struct, such as returned by maketform or cp2tform. The first dimension of the transformation is the horizontal or x-coordinate, and the second dimension is the vertical or y-coordinate. This convention is the reverse of the array subscripting convention in MATLAB.

Interpolation method, specified as one of these values.

Interpolation MethodDescription
'bilinear'Linear interpolation
'nearest'Nearest-neighbor interpolation—the output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered.
'bicubic'Cubic interpolation
resampler structureresampler structure returned by makeresampler. This option allows more control over how imtransform performs resampling.

Data Types: char

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: B = imtransform(A,T,'FillValues',128)

Spatial extent of input image A in the U-V input space, specified as 2-element numeric vectors. The values of UData and VData represent coordinates in the world coordinate system. The two elements of UData give the u-coordinates (horizontal) of the first and last columns of A, respectively. The two elements of VData give the v-coordinates (vertical) of the first and last rows of A.

By default, the spatial extent of A in the U-V space is the same as the image extent in intrinsic coordinates. In other words, the default value of UData is [1 size(A,2)] and the default value of VData is [1 size(A,1)].

Spatial extent of transformed image B in the X-Y input space, specified as 2-element numeric vectors. The values of XData and YData represent coordinates in the world coordinate system. The two elements of XData give the x-coordinates (horizontal) of the first and last columns of B, respectively. The two elements of YData give the y-coordinates (vertical) of the first and last rows of B.

If you do not specify XData and YData, then imtransform estimates values that contain the entire transformed output image. To determine these values, imtransform uses the findbounds function.

Size of pixels in X-Y output space, specified as a numeric scalar or 2-element numeric vector. If XYScale is a scalar, then output pixels are square and XYScale specifies the side length. Otherwise, the two elements of XYScale specify the width and height of each output pixel in X-Y space, respectively.

The default value of XYScale depends on whether you specify Size:

  • If you specify Size, then imtransform calculates XYScale from Size, XData, and YData.

  • If you do not specify Size, then imtransform uses the scale of the input pixels for XYScale, except in cases where an excessively large output image would result.

Note

In cases where preserving the scale of the input image would result in an excessively large output image, the imtransform function automatically increases the value of XYScale. To ensure that the output pixel scale matches the input pixel scale, specify the XYScale parameter. For example, call imtransform as shown in the following syntax:

B = imtransform(A,T,'XYScale',1)

Size of transformed image B, specified as a 2-element vector of positive integers. The two elements of Size specify the number of rows and columns of the output image B, respectively. For higher dimensions, imtransform takes the size of B directly from the size of input image A. Thus, size(B,k) equals size(A,k) for k > 2.

If you do not specify Size, then imtransform derives this value from XData, YData, and XYScale.

Fill value used for output pixels outside the input image boundaries, specified as the comma-separated pair consisting of 'FillValues' and a numeric scalar or numeric array. Fill values are used for output pixels when the corresponding inverse transformed location in the input image is completely outside the input image boundaries.

  • If the input image A is 2-D, then FillValues must be a scalar.

  • If A is 3-D or N-D, then FillValues can be an array whose size satisfies the following constraint: size(FillValues,k) must equal either size(A,k+2) or 1.

    For example, if A is a uint8 RGB image that is 200-by-200-by-3, then possibilities for 'FillValues' include the following values.

    ValueFill
    0Fill with black
    [0;0;0]Fill with black
    255Fill with white
    [255;255;255]Fill with white
    [0;0;255]Fill with blue
    [255;255;0]Fill with yellow

    For a second example, if A is 4-D with size 200-by-200-by-3-by-10, then you can specify 'FillValues' as a scalar, 1-by-10 vector, 3-by-1 vector, or 3-by-10 matrix.

Output Arguments

collapse all

Transformed image, returned as a numeric or logical array of the same dimensionality as the input image A.

Horizontal extent of the transformed image B in X-Y output space, returned as a 2-element numeric vector. The two elements of xdata give the x-coordinates (horizontal) of the first and last columns of B in the world coordinate system, respectively.

Note

The first element of xdata always equals the first element of the XData argument, if specified. However, sometimes the second element of xdata does not exactly equal the second element of XData. The values differ either because of the need for an integer number of rows and columns, or because you specified values for XData, YData, XYScale, and Size that are not entirely consistent.

Vertical extent of the transformed image B in X-Y output space, returned as a 2-element numeric vector. The two elements of ydata give the y-coordinates (vertical) of the first and last rows of B in the world coordinate system, respectively.

Note

The first element of ydata always equals the first element of the YData argument, if specified. However, sometimes the second element of ydata does not exactly equal the second element of YData. The values differ either because of the need for an integer number of rows and columns, or because you specified values for XData, YData, XYScale, and Size that are not entirely consistent.

Tips

  • Image Registration. The imtransform function automatically shifts the origin of your output image to make as much of the transformed image visible as possible. If you use imtransform to do image registration, the syntax B = imtransform(A,tform) can produce unexpected results. To control the spatial location of the output image, set XData and YData explicitly.

  • Pure Translation. Calling the imtransform function with a purely translational transformation results in an output image that is exactly like the input image unless you specify XData and YData values in your call to imtransform. For example, if you want the output to be the same size as the input revealing the translation relative to the input image, call imtransform as shown in the following syntax:

    B = imtransform(A,T,'XData',[1 size(A,2)],...
       'YData',[1 size(A,1)])

    For more information about this topic, see Perform Simple 2-D Translation Transformation.

  • Transformation Speed. If you do not specify the output-space location for B using XData and YData, then imtransform estimates the location automatically using the function findbounds. You can use findbounds as a quick forward-mapping option for some commonly used transformations, such as affine or projective. For transformations that do not have a forward mapping, such as polynomial transformations computed by fitgeotrans, findbounds can take much longer. If you can specify XData and YData directly for such transformations, then imtransform may run noticeably faster.

  • Clipping. The automatic estimate of XData and YData using findbounds sometimes clips the output image. To avoid clipping, set XData and YData directly.

  • Arbitrary Dimensional Transformations. Use a 2-D transformation for tform when using imtransform. For arbitrary-dimensional array transformations, see tformarray.

Introduced before R2006a