maketform

Create N-D spatial transformation structure (TFORM)

The maketform function is not recommended for 2-D and 3-D geometric transformations. For more information, see Version History.

Syntax

T = maketform("affine",A)

T = maketform("projective",P)

T = maketform("custom",ndims_in,ndims_out,forward_fcn,inverse_fcn,tdata)

T = maketform("box",tsize,outCornerStart,outCornerEnd)

T = maketform("box",inCorners,outCorners)

T = maketform("composite",T1,T2,...,TL)

T = maketform("composite",[T1,T2,...,TL])

Description

Create N-D Affine and Projective Transformations from Matrices

T = maketform("affine",A) creates a spatial transformation structure T for an N-dimensional affine transformation specified as matrix A. The transformation structure T has both forward and inverse transformations.

A spatial transformation structure (called a TFORM structure) can be used with the tformarray, tformfwd, and tforminv functions.

T = maketform("projective",P) creates a TFORM structure for an N-dimensional projective transformation specified as matrix P. T has both forward and inverse transformations.

Create Transformation from Forward or Inverse Functions

T = maketform("custom",ndims_in,ndims_out,forward_fcn,inverse_fcn,tdata) creates a custom TFORM structure T based on user-provided function handles and parameters. ndims_in and ndims_out are the numbers of input and output dimensions. forward_fcn and inverse_fcn are function handles to forward and inverse functions. The tdata argument can be any MATLAB^® array and is typically used to store parameters of the custom transformation. It is accessible to forward_fcn and inverse_fcn via the tdata field of T.

Create Transformation for Spatial Referencing

T = maketform("box",tsize,outCornerStart,outCornerEnd) creates an N-dimensional affine TFORM structure T that maps an input box defined by the coordinates of a corner, ones(1,N), and size tsize, to an output box defined by the opposite corners outCornerStart and outCornerEnd. The "box" TFORM structure is typically used to register the row and column subscripts of an image or array to some world coordinate system.

T = maketform("box",inCorners,outCorners) creates an N-dimensional affine TFORM structure T. The transformation maps an input box defined by the opposite corners inCorners(1,:) and inCorners(2,:) to an output box defined by the opposite corners outCorners(1,:) and outCorners(2,:).

Create Composite Transformation

T = maketform("composite",T1,T2,...,TL) creates a TFORM structure T that is a composite of transformations T1, T2, ..., TL specified as comma-separated TFORM structures. The forward and inverse functions of T are the functional compositions of the forward and inverse functions of the component transformations T1, T2, ..., TL.

T = maketform("composite",[T1,T2,...,TL]) builds a TFORM structure T that is a composite of transformations T1, T2, ..., TL specified in a vector. The forward and inverse functions of T are the functional compositions of the forward and inverse functions of the component transformations T1, T2, ..., TL.

Examples

Calculate Boundaries of Transformed Output Image

Read an image into the workspace, and display the image.

I = imread('cameraman.tif');
figure
imshow(I)

Create a spatial transformation structure that stretches an image.

T = maketform('affine',[.5 0 0; .5 2 0; 0 0 1]);

Calculate the boundaries of the output image, given the size of the input image and the spatial transformation. The dimensions of the input image are 256-by-256. The boundaries of the output image reflect the transformation: 256-by-512.

outb = findbounds(T,[0 0;256 256])

outb = 2×2

     0     0
   256   512

Apply the transformation, and display the image.

transformedI = imtransform(I,T);
figure
imshow(transformedI)

Input Arguments

A — Affine transformation

(N+1)-by-(N+1) matrix | (N+1)-by-N matrix

Affine transformation, specified as an (N+1)-by-(N+1) matrix or an (N+1)-by-N matrix, where N is the dimensionality of the affine transformation. The matrix must be nonsingular and real.

If A is (N+1)-by-(N+1), the last column of A must be [zeros(N,1);1]. Otherwise, A is augmented automatically, such that its last column is [zeros(N,1);1]. The matrix A defines a forward transformation such that tformfwd(U,T), where U is a 1-by-N vector, returns a 1-by-N vector X, such that X = U * A(1:N,1:N) + A(N+1,1:N).

Data Types: double

P — Projective transformation

(N+1)-by-(N+1) matrix

Projective transformation, specified as an (N+1)-by-(N+1) matrix, where N is the dimensionality of the projective transformation. The matrix must be nonsingular and real. P(N+1,N+1) cannot be 0.

The matrix P defines a forward transformation such that tformfwd(U,T), where U is a 1-by-N vector, returns a 1-by-N vector X, such that X = W(1:N)/W(N+1), where W = [U 1] * P.

Data Types: double

ndims_in — Number of input dimensions

positive integer

Number of input dimensions, specified as a positive integer.

Data Types: double

ndims_out — Number of output dimensions

positive integer

Number of output dimensions, specified as a positive integer.

Data Types: double

forward_fcn — Forward function

function handle | []

Forward function, specified as a function handle that supports the syntax X = forward_fcn(U,T). U is a numpts-by-ndims_in matrix whose rows are points in the transformation input space and X is a numpts-by-ndims_out matrix whose rows are points in the transformation output space.

forward_fcn can be empty.

Data Types: function_handle

inverse_fcn — Inverse function

function handle

Inverse function, specified as a function handle that supports the syntax U = inverse_fcn(X,T). U is a numpts-by-ndims_in matrix whose rows are points in the transformation input space and X is a numpts-by-ndims_out matrix whose rows are points in the transformation output space.

inverse_fcn can be empty. However, to use the TFORM struct T with the tformarray function, you must define inverse_fcn.

Data Types: function_handle

tdata — Parameters of custom transformation

array

Parameters of custom transformation, specified as an array.

Data Types: double

tsize — Size of input box

N-element vector of positive integers

Size of input box, specified as an N-element vector of positive integers.

Data Types: double

outCornerStart — Starting corner coordinates in output space

N-element vector

Starting corner coordinates in the output space, specified as an N-element vector. outCornerStart(k) and outCornerEnd(k) must be different unless tsize(k) is 1, in which case the affine scale factor along the k-th dimension is assumed to be 1.0.

Data Types: double

outCornerEnd — Opposite corner coordinates in output space

N-element vector

Opposite corner coordinates in the output space, specified as an N-element vector. outCornerStart(k) and outCornerEnd(k) must be different unless tsize(k) is 1, in which case the affine scale factor along the k-th dimension is assumed to be 1.0.

Data Types: double

inCorners — Corner coordinates in input space

N-by-2 numeric matrix

Corner coordinates in the input space, specified as an N-by-2 numeric matrix. The first column represents the coordinates of one corner and the second column represents the coordinates of the opposite corner. inCorners(1,k) and inCorners(2,k) must be different unless outCorners(1,k) and outCorners(2,k) are the same.

Data Types: double

outCorners — Corner coordinates in output space

N-by-2 numeric matrix

Corner coordinates in the output space, specified as an N-by-2 numeric matrix. The first column represents the coordinates of one corner and the second column represents the coordinates of the opposite corner. outCorners(1,k) and outCorners(2,k) must be different unless inCorners(1,k) and inCorners(2,k) are the same.

Data Types: double

T1,T2,...,TL — Component transformations

TFORM structures

Component transformations, specified as TFORM structures.

The inputs T1, T2, ..., TL are ordered just as they would be when using the standard notation for function composition: T = T1 ⚬ T2 ⚬ ... ⚬ TL. Composition is associative, but not commutative. This means that to apply T to the input U, you must apply TL first and T1 last. Thus if L = 3, for example, then tformfwd(U,T) is the same as tformfwd(tformfwd(tformfwd(U,T3),T2),T1). The components T1 through TL must be compatible in terms of the numbers of input and output dimensions.

T has a defined forward transformation function only if all the component transformations have defined forward transform functions. T has a defined inverse transformation function only if all the component transformations have defined inverse transform functions.

Data Types: function_handle

Output Arguments

T — Multidimensional spatial transformation

TFORM structure

Multidimensional spatial transformation, returned as a TFORM structure.

Extended Capabilities

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 before R2006a

R2021b: Support for thread-based environments

maketform now supports thread-based environments.

R2018b: maketform is not recommended for 2-D and 3-D geometric transformations

The maketform function is not recommended for 2-D and 3-D geometric transformations. Instead, create a 2-D or 3-D geometric transformation in these ways:

• Define a 2-D affine or projective transformation from a 3-by-3 matrix using the affinetform2d, rigidtform2d, simtform2d, transltform2d, or projtform2d object.

• Define a 3-D affine transformation from a 4-by-4 matrix using the affinetform3d, rigidtform3d, simtform3d, or transltform3d object.

• Define a 2-D affine, projective, polynomial, or other nonlinear transformation from pairs of control points using the fitgeotform2d function.

• Define a 2-D or 3-D geometric transformation from point-wise mapping functions using the geometricTransform2d or geometricTransform3d object.

For more information about 2-D and 3-D geometric transformation objects, see 2-D and 3-D Geometric Transformation Process Overview.

This table shows a few syntaxes of maketform with the recommended replacement code.

Discouraged Usage	Recommended Replacement
Create a 2-D affine transformation from a 3-by-3 matrix A. A = [0.5 0 0; 0.5 2 0; 0 0 1]; T = maketform("affine",A);	Create an affinetform2d object. A = [0.5 0 0; 0.5 2 0; 0 0 1]; T = affinetform2d(A);
Create a 2-D affine transformation that maps each row of U to the corresponding row of X. The U and X arguments define the corners of triangles as a 3-by-2 matrix. U = [21.6 64.2; 71.1 70.3; 28.7 48.3]; X = [10.7 30.6; 40.5 50.6; 20.6 10.7]; T = maketform("affine",U,X);	Create an affinetform2d object using the fitgeotform2d function. U = [21.6 64.2; 71.1 70.3; 28.7 48.3]; X = [10.7 30.6; 40.5 50.6; 20.6 10.7]; T = fitgeotform2d(U,X,"affine");
Create a 2-D projective transformation that maps each row of U to the corresponding row of X. The U and X arguments define the corners of quadrangles as a 4-by-2 matrix. U = [121 94; 319 79; 128 292; 352 281]; X = [165 113; 354 130; 143 285; 354 312]; T = maketform("projective",U,X);	Create a projtform2d object using the fitgeotform2d function. U = [121 94; 319 79; 128 292; 352 281]; X = [165 113; 354 130; 143 285; 354 312]; T = fitgeotform2d(U,X,"projective");