imtransform - Apply 2-D spatial transformation to image

Syntax

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

Description

B = imtransform(A,tform) transforms the image A according to the 2-D spatial transformation defined by tform. If ndims(A) > 2, such as for an RGB image, then imtransform applies the same 2-D transformation to all 2-D planes along the higher dimensions.

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

[B,xdata,ydata] = imtransform(...) returns the location 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' arguments.

[B,xdata,ydata] = imtransform(...,Name,Value) transforms the image with additional options for controlling various aspects of the spatial transformation specified by one or more Name,Value pair arguments.

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 Example: Performing a Translation in the User's Guide, especially the section Understanding the Coordinates of the Transformed Image.

• Transformation Speed. When you do not specify the output-space location for B using 'XData' and 'YData', 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 the polynomial ones computed by cp2tform, findbounds can take much longer. If you can specify 'XData' and 'YData' directly for such transformations, 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.

Input Arguments

A	An image of any nonsparse numeric class (real or complex) or of class logical.
tform	A spatial transformation structure returned by maketform or cp2tform. imtransform assumes spatial-coordinate conventions for the transformation tform. Specifically, 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.
interp	A string that specifies the form of interpolation to use. interp can be one of the following strings: 'bicubic', 'bilinear', or 'nearest' (nearest-neighbor). Alternatively, interp can be a resampler structure returned by makeresampler. This option allows more control over how imtransform performs resampling. Default: 'bilinear'

Name-Value Pair Arguments

Optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear within single quotes (' ') and is not case sensitive. You can specify several name and value pair arguments in any order as Name1, Value1, ..., NameN, ValueN.

'UData'	A two-element, real vector that, when combined with 'VData', specifies the spatial location of image A in the 2-D input space U-V. The two elements of 'UData' give the u-coordinates (horizontal) of the first and last columns of A, respectively. Default: [1 size(A,2)]
'VData'	A two-element, real vector that, when combined with 'UData', specifies the spatial location of image A in the 2-D input space U-V. The two elements of 'VData' give the v-coordinates (vertical) of the first and last rows of A, respectively. Default: [1 size(A,1)]
'XData'	A two-element, real vector that, when combined with 'YData', specifies the spatial location of the output image B in the 2-D output space X-Y. The two elements of 'XData' give the x-coordinates (horizontal) of the first and last columns of B, respectively. Default: If you do not specify 'XData' and 'YData', imtransform estimates values that contain the entire transformed output image. To determine these values, imtransform uses the findbounds function.
'YData'	A two-element real vector that, when combined with 'XData', specifies the spatial location of the output image B in the 2-D output space X-Y. The two elements of 'YData' give the y-coordinates (vertical) of the first and last rows of B, respectively. Default: If you do not specify 'XData' and 'YData', imtransform estimates values that contain the entire transformed output image. To determine these values, imtransform uses the findbounds function.
'XYScale'	A one- or two-element real vector. The first element of 'XYScale' specifies the width of each output pixel in X-Y space. The second element (if present) specifies the height of each output pixel. If 'XYScale' has only one element, then the same value specifies both width and height. Default: If you do not specify 'XYScale' but you do specify 'Size', then imtransform calculates 'XYScale' from 'Size', 'XData', and 'YData'. If you do not provide 'XYScale' or '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 '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'	A two-element vector of nonnegative integers that specifies the number of rows and columns of the output image B. For higher dimensions, imtransform takes the size of B directly from the size of A. Thus, size(B,k) equals size(A,k) for k > 2. Default: If you do not specify 'Size', imtransform derives this value from 'XData', 'YData', and 'XYScale'.
'FillValues'	An array containing one or several fill values. The imtransform function uses fill values for output pixels when the corresponding transformed location in the input image is completely outside the input image boundaries. If A is 2-D, 'FillValues' requires a scalar. However, if A's dimension is greater than two, then you can specify 'FillValues' as an array whose size satisfies the following constraint: size(fill_values,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. Value Fill 0 Fill with black [0;0;0] Fill with black 255 Fill with white [255;255;255] Fill with white [0;0;255] Fill with blue [255;255;0] Fill with yellow 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, 3-by-1, or 3-by-10.

Output Arguments

B	Output image of any nonsparse numeric class (real or complex) or of class logical.
xdata	Two-element vector that specifies the x-coordinates of the first and last columns of B. Note   Sometimes the output values xdata and ydata do not exactly equal the input 'XData' and 'YData' arguments. The values differ either because of the need for an integer number of rows and columns, or because you specify values for 'XData', 'YData', 'XYScale', and 'Size' that are not entirely consistent. In either case, the first element of xdata and ydata always equals the first element of 'XData' and 'YData', respectively. Only the second elements of xdata and ydata can be different.
ydata	Two-element vector that specifies the y-coordinates of the first and last rows of B.

Examples

Simple Transformation. Apply a horizontal shear to an intensity image:

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

Horizontal Shear

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), ...
   axis on 
subplot(1,2,2), imshow(B,'XData',xdata,'YData',ydata), ...
   axis on 

Projective Transformation

Image Registration. Register an aerial photo to an orthophoto:

% Read in the aerial photo.
unregistered = imread('westconcordaerial.png');
figure, imshow(unregistered)

Aerial Photo

% Read in the orthophoto.
figure, imshow('westconcordorthophoto.png')

Orthophoto

% Load control points that were previously picked.
load westconcordpoints

% Create a transformation structure for a projective 
% transformation.
t_concord = cp2tform(input_points,base_points,'projective');

% Get the width and height of the orthophoto and perform 
% the transformation.
info = imfinfo('westconcordorthophoto.png');

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

Transformed Image

See Also

checkerboard | cp2tform | imresize | imrotate | makeresampler | maketform | tformarray

Tutorials

• Example: Performing a Translation
• Exploring Slices from a 3-Dimensional MRI Data Set
• Padding and Shearing an Image Simultaneously

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS