tformarray (Image Processing Toolbox User's Guide)

Image Processing Toolbox User's Guide

Spatial transformation of a multidimensional array

Syntax

B = tformarray(A,T,R,TDIMS_A,TDIMS_B,TSIZE_B,TMAP_B,F)

Description

B = tformarray(A,T,R,TDIMS_A,TDIMS_B,TSIZE_B,TMAP_B,F) applies a spatial transformation to array A to produce array B. The tformarray function is like imtransform, but is intended for problems involving higher-dimensioned arrays or mixed input/output dimensionality, or requiring greater user control or customization. (Anything that can be accomplished with imtransform can be accomplished with a combination of maketform, makeresampler, findbounds, and tformarray; but for many tasks involving 2-D images, imtransform is simpler.)

This table provides a brief description of all the input arguments. See the following section for more detail about each argument. (Click an argument in the table to move to the appropriate section.)

Argument
Description

A
Input array or image

T
Spatial transformation structure, called a TFORM, typically created with maketform

R
Resampler structure, typically created with makeresampler

TDIMS_A
Row vector listing the input transform dimensions

TDIMS_B
Row vector listing the output transform dimensions

TSIZE_B
Output array size in the transform dimensions

TMAP_B
Array of point locations in output space; can be used as an alternative way to specify a spatial transformation

F
Array of fill values

Argument	Description
A	Input array or image
T	Spatial transformation structure, called a `TFORM`, typically created with `maketform`
R	Resampler structure, typically created with `makeresampler`
TDIMS_A	Row vector listing the input transform dimensions
TDIMS_B	Row vector listing the output transform dimensions
TSIZE_B	Output array size in the transform dimensions
TMAP_B	Array of point locations in output space; can be used as an alternative way to specify a spatial transformation
F	Array of fill values

A can be any nonsparse numeric array, and can be real or complex.

T is a TFORM structure that defines a particular spatial transformation. For each location in the output transform subscript space (as defined by TDIMS_B and TSIZE_B), tformarray uses T and the function tforminv to compute the corresponding location in the input transform subscript space (as defined by TDIMS_A and size(A)).

If T is empty, tformarray operates as a direct resampling function, applying the resampler defined in R to compute values at each transform space location defined in TMAP_B (if TMAP_B is nonempty), or at each location in the output transform subscript grid.

R is a structure that defines how to interpolate values of the input array at specified locations. R is usually created with makeresampler, which allows fine control over how to interpolate along each dimension, as well as what input array values to use when interpolating close to the edge of the array.

TDIMS_A and TDIMS_B indicate which dimensions of the input and output arrays are involved in the spatial transformation. Each element must be unique, and must be a positive integer. The entries need not be listed in increasing order, but the order matters. It specifies the precise correspondence between dimensions of arrays A and B and the input and output spaces of the transformer T. length(TDIMS_A) must equal T.ndims_in, and length(TDIMS_B) must equal T.ndims_out.

For example, if T is a 2-D transformation, TDIMS_A = [2 1], and TDIMS_B = [1 2], then the column dimension and row dimension of A correspond to the first and second transformation input-space dimensions, respectively. The row and column dimensions of B correspond to the first and second output-space dimensions, respectively.

TSIZE_B specifies the size of the array B along the output-space transform dimensions. Note that the size of B along nontransform dimensions is taken directly from the size of A along those dimensions. If, for example, T is a 2-D transformation, size(A) = [480 640 3 10], TDIMS_B is [2 1], and TSIZE_B is [300 200], then size(B) is [200 300 3].

TMAP_B is an optional array that provides an alternative way of specifying the correspondence between the position of elements of B and the location in output transform space. TMAP_B can be used, for example, to compute the result of an image warp at a set of arbitrary locations in output space. If TMAP_B is not empty, then the size of TMAP_B takes the form

```
 [D1 D2 D3 ... DN L]
```

where N equals length(TDIMS_B). The vector [D1 D2 ... DN] is used in place of TSIZE_B. If TMAP_B is not empty, then TSIZE_B should be [].

The value of L depends on whether or not T is empty. If T is not empty, then L is T.ndims_out, and each L-dimension point in TMAP_B is transformed to an input-space location using T. If T is empty, then L is length(TDIMS_A), and each L-dimensional point in TMAP_B is used directly as a location in input space.

F is a double-precision array containing fill values. The fill values in F can be used in three situations:

When a separable resampler is created with makeresampler and its padmethod is set to either 'fill' or 'bound'.
When a custom resampler is used that supports the 'fill' or 'bound' pad methods (with behavior that is specific to the customization).
When the map from the transform dimensions of B to the transform dimensions of A is deliberately undefined for some points. Such points are encoded in the input transform space by NaNs in either TMAP_B or in the output of TFORMINV.

In the first two cases, fill values are used to compute values for output locations that map outside or near the edges of the input array. Fill values are copied into B when output locations map well outside the input array. See makeresampler for more information about 'fill' and 'bound'.

F can be a scalar (including NaN), in which case its value is replicated across all the nontransform dimensions. F can also be a nonscalar, whose size depends on size(A) in the nontransform dimensions. Specifically, if K is the Jth nontransform dimension of A, then size(F,J) must be either size(A,K) or 1. As a convenience to the user, tformarray replicates F across any dimensions with unit size such that after the replication size(F,J) equals size(A,K).

For example, suppose A represents 10 RGB images and has size 200-by-200-by-3-by-10, T is a 2-D transformation, and TDIMS_A and TDIMS_B are both [1 2]. In other words, tformarray will apply the same 2-D transform to each color plane of each of the 10 RGB images. In this situation you have several options for F:

F can be a scalar, in which case the same fill value is used for each color plane of all 10 images.
F can be a 3-by-1 vector, [R G B]'. Then R, G, and B are used as the fill values for the corresponding color planes of each of the 10 images. This can be interpreted as specifying an RGB fill color, with the same color used for all 10 images.
F can be a 1-by-10 vector. This can be interpreted as specifying a different fill value for each of 10 images, with that fill value being used for all three color planes.
F can be a 3-by-10 matrix, which can be interpreted as supplying a different RGB fill color for each of the 10 images.

Class Support

A can be any nonsparse numeric array, and can be real or complex. It can also be of class logical.

Example

Create a 2-by-2 checkerboard image where each square is 20 pixels wide, then transform it with a projective transformation. Use a pad method of 'circular' when creating a resampler, so that the output appears to be a perspective view of an infinite checkerboard. Swap the output dimensions. Specify a 100-by-100 output image. Leave TMAP_B empty, since TSIZE_B is specified. Leave the fill value empty, since it won't be needed.

I = checkerboard(20,1,1);
figure; imshow(I)
T = maketform('projective',[1 1; 41 1; 41 41;   1 41],...
                           [5 5; 40 5; 35 30; -10 30]);
R = makeresampler('cubic','circular');
J = tformarray(I,T,R,[1 2],[2 1],[100 100],[],[]);
figure; imshow(J)

subimage tformfwd