tforminv

Apply inverse N-D spatial transformation

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

Syntax

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

U = tforminv(T,X)

[U1,U2,...,U_ndims_in] = tforminv(T,X)

U = tforminv(T,X1,X2,...,X_ndims_out)

Description

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

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

U = tforminv(T,X) applies the ndims_out-to-ndims_in inverse transformation defined in T to array X.

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

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

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

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

[U1,U2,...,U_ndims_in] = tforminv(T,X) maps one (N+1)-dimensional array to ndims_in equally sized N-dimensional arrays.

U = tforminv(T,X1,X2,...,X_ndims_out) maps ndims_out N-dimensional arrays to one (N+1)-dimensional array.

Examples

Create Affine Transformation and Validate It with Inverse 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 tforminv. The results should equal u and v.

[um, vm] = tforminv(tform, x, y)

um = 3×1

         0
    6.0000
   -2.0000

vm = 3×1

         0
    3.0000
    5.0000

Input Arguments

T — Spatial transformation

TFORM spatial transformation structure

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

Data Types: struct

X — Input coordinate points

numeric array

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

Data Types: double

X1,X2,...,X_ndims_out — Input coordinate points

multiple numeric arrays

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

Data Types: double

Output Arguments

U — Coordinate array of output points

numeric array

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

U1,U2,...,U_ndims_in — Coordinates of output points

multiple numeric arrays

Coordinates of output points, returned as multiple arrays. The size and dimensionality of U1,U2,...,U_ndims_in 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

tforminv now supports thread-based environments.

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

The tforminv 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 transformPointsInverse function. For more information about geometric transformation objects, see 2-D and 3-D Geometric Transformation Process Overview.

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

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