tformfwd

Apply forward N-D spatial transformation

The tformfwd function is not recommended for 2-D and 3-D geometric transformations. Use the transformPointsForward function instead. For more information, see Version History.

Syntax

[X1,X2,...,X_ndims_out] = tformfwd(T,U1,U2,...,U_ndims_in)

X = tformfwd(T,U)

[X1,X2,...,X_ndims_out] = tformfwd(T,U)

X = tformfwd(T,U1,U2,...,U_ndims_in)

Description

[X1,X2,...,X_ndims_out] = tformfwd(T,U1,U2,...,U_ndims_in) applies the ndims_in-to-ndims_out spatial transformation defined in T to the coordinate arrays U1,U2,...,U_ndims_in. The transformation maps the point [U1(k) U2(k) ...U_ndims_in(k)] to the point [X1(k) X2(k) ... X_ndims_out(k)].

The number of input coordinate arrays, ndims_in, must equal T.ndims_in. The number of output coordinate arrays, ndims_out, must equal T.ndims_out. The arrays U1,U2,...,U_ndims_in can have any dimensionality, but must be the same size. The output arrays X1,X2,...,X_ndims_out must be this size also.

X = tformfwd(T,U) applies the spatial transformation defined in T to coordinate array U.

• When U is a 2-D matrix with dimensions m-by-ndims_in, X is a 2-D matrix with dimensions m-by-ndims_out. tformfwd applies the ndims_in-to-ndims_out transformation to each row of U. tformfwd maps the point U(k, : ) to the point X(k, : ).

• When U is an (N+1)-dimensional array, tformfwd maps the point U(k₁, k₂, … ,k_N, : ) to the point X(k₁, k₂, … ,k_N, : ).

  size(U,N+1) must equal ndims_in. X is an (N+1)-dimensional array, with size(X,I) equal to size(U,I) for I = 1, … ,N, and size(X,N+1) equal to ndims_out.

The syntax X = tformfwd(U,T) is an older form of this syntax that remains supported for backward compatibility.

[X1,X2,...,X_ndims_out] = tformfwd(T,U) maps one (N+1)-dimensional array to ndims_out equally sized N-dimensional arrays.

X = tformfwd(T,U1,U2,...,U_ndims_in) maps ndims_in N-dimensional arrays to one (N+1)-dimensional array.

Examples

Create Affine Transformation and Validate It with Forward Mapping

Create an affine transformation that maps the triangle with vertices (0,0), (6,3), (-2,5) to the triangle with vertices (-1,-1), (0,-10), (4,4).

u = [ 0   6  -2]';
v = [ 0   3   5]';
x = [-1   0   4]';
y = [-1 -10   4]';
tform = maketform('affine',[u v],[x y]);

Validate the mapping by applying tformfwd. The results should equal x and y.

[xm,ym] = tformfwd(tform,u,v)

xm = 3×1

    -1
     0
     4

ym = 3×1

    -1
   -10
     4

Input Arguments

T — Spatial transformation

TFORM structure

Spatial transformation, specified as a TFORM structure. Create T using the maketform function.

Data Types: struct

U — Input coordinate points

numeric array

Input coordinate points, specified as a numeric array. The size and dimensionality of U can have additional limitations depending on the syntax used.

Data Types: double

U1,U2,...,U_ndims_in — Input coordinate points

multiple numeric arrays

Input coordinate points, specified as multiple numeric arrays. The size and dimensionality of U1,U2,...,U_ndims_in can have additional limitations depending on the syntax used.

Data Types: double

Output Arguments

X — Coordinate array of output points

numeric array

Coordinate array of output points, returned as a numeric array. The size and dimensionality of X can have additional limitations depending on the syntax used.

X1,X2,...,X_ndims_out — Coordinates of output points

multiple numeric arrays

Coordinates of output points, returned as multiple numeric arrays. The size and dimensionality of X1,X2,...,X_ndims_out can have additional limitations depending on the syntax used.

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

tformfwd now supports thread-based environments.

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

The tformfwd function is not recommended for 2-D and 3-D geometric transformations. Instead, create a 2-D or 3-D geometric transformation object, then use the transformPointsForward function. For more information about geometric transformation objects, see 2-D and 3-D Geometric Transformation Process Overview.

This table shows a syntax of tformfwd with the recommended replacement code.

Discouraged Usage	Recommended Replacement
Apply a forward 2-D affine transformation defined in TFORM struct T to coordinate arrays U and V, mapping the point [U(k) V(k)] to the point [X(k) Y(k)]. [X,Y] = tformfwd(T,U,V);	Apply a forward 2-D affine transformation using the affinetform2d object T and the transformPointsForward function. [X,Y] = transformPointsForward(T,U,V);