imtransform (Image Processing Toolbox)

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(...,PARAM1,VAL1,PARAM2,VAL2,...)

Description

B = imtransform(A,TFORM) transforms the image A according to the 2-D spatial transformation defined by TFORM, which is a spatial transformation structure (TFORM) as returned by maketform or cp2tform. If ndims(A) > 2, such as for an RGB image, then the same 2-D transformation is automatically applied to all 2-D planes along the higher dimensions.

When you use this syntax, imtransform automatically shifts the origin of your output image to make as much of the transformed image visible as possible. If you are using imtransform to do image registration, this syntax is not likely to give you the results you expect; you may want to set 'XData' and 'YData' explicitly. For more information, see Parameters, as well as Example 3.

B = imtransform(A,TFORM,INTERP) specifies the form of interpolation to use. INTERP can be one of the strings 'nearest', 'bilinear', or 'bicubic'. Alternatively, INTERP can be a RESAMPLER structure as returned by makeresampler. This option allows more control over how resampling is performed. The default value for INTERP is 'bilinear'.

[B,XDATA,YDATA] = imtransform(...) returns the location of the output image B in the output X-Y space. XDATA and YDATA are two-element vectors. The elements of XDATA specify the x-coordinates of the first and last columns of B. The elements of YDATA specify the y-coordinates of the first and last rows of B. Normally, imtransform computes XDATA and YDATA automatically so that B contains the entire transformed image A. However, you can override this automatic computation; see below.

[B,XDATA,YDATA] = imtransform(...,PARAM1,VAL1,PARAM2,VAL2,...) specifies parameters that control various aspects of the spatial transformation. Parameter names can be abbreviated, and case does not matter.

Parameters

This table lists all the parameters you can specify. Note that parameter names can be abbreviated and are not case-sensitive.

Parameter
Description

'UData'
'VData'
Both of these parameters are two-element real vectors. 'UData' and 'VData' specify the spatial location of the 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. The two elements of 'VData' give the v-coordinates (vertical) of the first and last rows of A, respectively.
The default values for 'UData' and 'VData' are [1 size(A,2)] and [1 size(A,1)], respectively.

'XData'
'YData'
Both of these parameters are two-element real vectors. 'XData' and 'YData' specify 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. The two elements of 'YData' give the y-coordinates (vertical) of the first and last rows of B, respectively.

If 'XData' and 'YData' are not specified, imtransform estimates values for them that will completely contain the entire transformed output image.

'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 is used for both width and height.
If 'XYScale' is not specified but 'Size' is, then 'XYScale' is computed from 'Size', 'XData', and 'YData'. If neither 'XYScale' nor 'Size' is provided, then the scale of the input pixels is used for 'XYScale'.

'Size'
A two-element vector of nonnegative integers. 'Size' specifies the number of rows and columns of the output image B. For higher dimensions, the size of B is taken directly from the size of A. In other words, size(B,k) equals size(A,k) for k > 2. If 'Size' is not specified, then it is computed from 'XData', 'YData', and 'XYScale'.

'FillValues'
An array containing one or several fill values.
Fill values are used 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' must be a scalar. However, if A's dimension is greater than two, then 'FillValues' can be an array whose size satisfies the following constraint: size(fill_values,k) must either equal 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:
0 - fill with black
[0;0;0]- also fill with black
255 - fill with white
[255;255;255]- also 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 'FillValues' can be a scalar, 1-by-10, 3-by-1, or 3-by-10.

Parameter	Description
`'UData'` `'VData'`	Both of these parameters are two-element real vectors. `'UData'` and `'VData'` specify the spatial location of the 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. The two elements of `'VData'` give the v-coordinates (vertical) of the first and last rows of `A`, respectively. The default values for `'UData'` and `'VData'` are `[1 size(A,2)]` and `[1 size(A,1)]`, respectively.
`'XData'` `'YData'`	Both of these parameters are two-element real vectors. `'XData'` and `'YData'` specify 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. The two elements of `'YData'` give the y-coordinates (vertical) of the first and last rows of `B`, respectively.
	If `'XData'` and `'YData'` are not specified, `imtransform` estimates values for them that will completely contain the entire transformed output image.
`'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 is used for both width and height. If `'XYScale'` is not specified but `'Size'` is, then `'XYScale'` is computed from `'Size'`, `'XData'`, and `'YData'`. If neither `'XYScale'` nor `'Size'` is provided, then the scale of the input pixels is used for `'XYScale'`.
`'Size'`	A two-element vector of nonnegative integers. `'Size'` specifies the number of rows and columns of the output image `B`. For higher dimensions, the size of `B` is taken directly from the size of `A`. In other words, `size(B,k)` equals `size(A,k)` for `k > 2`. If `'Size'` is not specified, then it is computed from `'XData'`, `'YData'`, and `'XYScale'`.
`'FillValues'`	An array containing one or several fill values. Fill values are used 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'` must be a scalar. However, if `A`'s dimension is greater than two, then `'FillValues'` can be an array whose size satisfies the following constraint: `size(fill_values,k)` must either equal `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: `0` - fill with black `[0;0;0]`- also fill with black `255` - fill with white `[255;255;255]`- also 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 `'FillValues'` can be a scalar, 1-by-10, 3-by-1, or 3-by-10.

Notes

When you do not specify the output-space location for B using 'XData' and 'YData', imtransform estimates them automatically using the function findbounds. For some commonly-used transformations, such as affine or projective, for which a forward-mapping is easily computable, findbounds is fast. For transformations that do not have a forward mapping, such as the polynomial ones computed by cp2tform, findbounds can take significantly longer. If you can specify 'XData' and 'YData' directly for such transformations, imtransform may run noticeably faster.
The automatic estimate of 'XData' and 'YData' using findbounds is not guaranteed in all cases to completely contain all the pixels of the transformed input image.
The output values XDATA and YDATA may not exactly equal the input 'XData' and 'YData' parameters. This can happen either because of the need for an integer number or rows and columns, or if 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 might be different.
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. Note that this is the reverse of the array subscripting convention in MATLAB.
TFORM must be a 2-D transformation to be used with imtransform. For arbitrary-dimensional array transformations, see tformarray.

Class Support

The input image, A, can be of any nonsparse numeric class, real or complex, or it can be of class logical. The class of B is the same as the class of A.

Example

Example 1

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)

Example 2

A projective transformation can map a square to a quadrilateral. In this example, set up an input coordinate system so that the input image fills the unit square and then transform the image into the quadrilateral with vertices (0 0), (1 0), (1 1), (0 1) to the quadrilateral with vertices (-4 2), (-8 3), (-3 -5), and (6 3). Fill with gray and use bicubic interpolation. Make the output size the same as the input size.

I = imread('cameraman.tif');
udata = [0 1];  vdata = [0 1];  % input coordinate system
tform = maketform('projective',[ 0 0;  1  0;  1  1; 0 1],...
                               [-4 2; -8 -3; -3 -5; 6 3]);
[B,xdata,ydata] = 
imtransform(I,tform,'bicubic','udata',udata,...
                              'vdata',vdata,...
                              'size',size(I),...
                              'fill',128);
subplot(1,2,1), imshow(udata,vdata,I), axis on
subplot(1,2,2), imshow(xdata,ydata,B), axis on

Example 3

unregistered = imread('westconcordaerial.png');
figure, imshow(unregistered)
figure, imshow('westconcordorthophoto.png')
load westconcordpoints % load some points that were already picked     
t_concord = cp2tform(input_points,base_points,'projective');
info = imfinfo('westconcordorthophoto.png');
registered = imtransform(unregistered,t_concord,...
    'XData',[1 info.Width], 'YData',[1 info.Height]);
figure, imshow(registered)

imtophat imwrite