transformPointsForward

Apply forward geometric transformation

Syntax

[x,y] = transformPointsForward(tform,u,v)

[x,y,z] = transformPointsForward(tform,u,v,w)

X = transformPointsForward(tform,U)

Description

[x,y] = transformPointsForward(tform,u,v) applies the forward transformation of 2-D geometric transformation tform to the points specified by coordinates u and v.

[x,y,z] = transformPointsForward(tform,u,v,w) applies the forward transformation of 3-D geometric transformation tform to the points specified by coordinates u, v, and w.

X = transformPointsForward(tform,U) applies the forward transformation of tform to the input coordinate matrix U and returns the coordinate matrix X. transformPointsForward maps the kth point U(k,:) to the point X(k,:).

Examples

Apply Forward Transformation of 2-D Geometric Transformation

Define a 3-by-3 geometric transformation matrix. This example specifies a matrix for an affine transformation consisting of vertical shear and horizontal stretch.

A = [1.5 0 0; 0.8 1 0; 0 0 1];

Create an affinetform2d object from the transformation matrix.

tform = affinetform2d(A);

Apply the forward geometric transformation to an input point.

u = 5;
v = 10;
[x,y] = transformPointsForward(tform,u,v)

x = 
7.5000

y = 
14

Transform Coordinate Arrays Using Custom 2-D Transformation

Specify the x- and y-coordinates vectors of five points to transform.

x = [10 11 15 2 2];
y = [15 32 34 7 10];

Define the inverse and forward mapping functions. Both functions accept and return points in packed (x,y) format.

inversefn = @(c) [c(:,1).^2,sqrt(c(:,2))];
forwardfn = @(c) [sqrt(c(:,1)),c(:,2).^2];

Create a 2-D geometric transform object, tform, that stores the inverse mapping function and the optional forward mapping function.

tform = geometricTransform2d(inversefn,forwardfn)

tform = 
  geometricTransform2d with properties:

        InverseFcn: @(c)[c(:,1).^2,sqrt(c(:,2))]
        ForwardFcn: @(c)[sqrt(c(:,1)),c(:,2).^2]
    Dimensionality: 2

Apply the inverse geometric transform to the input points.

[u,v] = transformPointsInverse(tform,x,y)

u = 1×5

   100   121   225     4     4

v = 1×5

    3.8730    5.6569    5.8310    2.6458    3.1623

Apply the forward geometric transform to the transformed points u and v.

[x,y] = transformPointsForward(tform,u,v)

x = 1×5

    10    11    15     2     2

y = 1×5

   15.0000   32.0000   34.0000    7.0000   10.0000

Apply Forward Transformation of 3-D Geometric Transformation

Define a rigid geometric transformation consisting only of translation.

t = [10 20.5 15];
tform = transltform3d(t);

Apply the forward geometric transformation to an input point.

u = 1;
v = 1;
w = 1.01;
[x,y,z] = transformPointsForward(tform,u,v,w)

x = 
11

y = 
21.5000

z = 
16.0100

Transform Coordinate Arrays Using Custom 3-D Transformation

Specify the x-, y- and the z-coordinate vectors of five points to transform.

x = [3 5 7 9 11];
y = [2 4 6 8 10];
z = [5 9 13 17 21];

Define the inverse and forward mapping functions that accept and return points in packed (x,y,z) format.

inverseFcn = @(c)[c(:,1).^2,c(:,2).^2,c(:,3).^2];
forwardFcn = @(c)[sqrt(c(:,1)),sqrt(c(:,2)),sqrt(c(:,3))];

Create a 3-D geometric transformation object, tform, that stores these inverse and forward mapping functions.

tform = geometricTransform3d(inverseFcn,forwardFcn)

tform = 
  geometricTransform3d with properties:

        InverseFcn: @(c)[c(:,1).^2,c(:,2).^2,c(:,3).^2]
        ForwardFcn: @(c)[sqrt(c(:,1)),sqrt(c(:,2)),sqrt(c(:,3))]
    Dimensionality: 3

Apply the inverse transformation of this 3-D geometric transformation to the input points.

[u,v,w] = transformPointsInverse(tform,x,y,z)

u = 1×5

     9    25    49    81   121

v = 1×5

     4    16    36    64   100

w = 1×5

    25    81   169   289   441

Apply the forward geometric transform to the transformed points u, v, and w.

[x,y,z] = transformPointsForward(tform,u,v,w)

x = 1×5

     3     5     7     9    11

y = 1×5

     2     4     6     8    10

z = 1×5

     5     9    13    17    21

Input Arguments

tform — Geometric transformation

geometric transformation object

Geometric transformation, specified as a geometric transformation object listed in the table.

Geometric Transformation Object	Description
2-D Linear Geometric Transformations
transltform2d	Translation transformation
rigidtform2d	Rigid transformation: translation and rotation
simtform2d	Similarity transformation: translation, rotation, and isotropic scaling
affinetform2d	Affine transformation: translation, rotation, anisotropic scaling, reflection, and shearing
projtform2d	Projective transformation
3-D Linear Geometric Transformations
transltform3d	Translation transformation
rigidtform3d	Rigid transformation: translation and rotation
simtform3d	Similarity transformation: translation, rotation, and isotropic scaling
affinetform3d	Affine transformation: translation, rotation, anisotropic scaling, reflection, and shearing
Nonlinear Geometric Transformations
geometricTransform2d	Custom 2-D geometric transformation using point-wise mapping functions
geometricTransform3d	Custom 3-D geometric transformation using point-wise mapping functions

Note

You can also specify tform as an object of type rigid2d, rigid3d, affine2d, affine3d, or projective2d. However, these objects are not recommended. For more information, see Version History.

u — x-coordinates of points to be transformed

m-by-n or m-by-n-by-p numeric array

x-coordinates of points to be transformed, specified as an m-by-n or m-by-n-by-p numeric array. The number of dimensions of u matches the dimensionality of tform.

Data Types: single | double

v — y-coordinates of points to be transformed

m-by-n or m-by-n-by-p numeric array

y-coordinates of points to be transformed, specified as an m-by-n or m-by-n-by-p numeric array. The size of v must match the size of u.

Data Types: single | double

w — z-coordinates of points to be transformed

m-by-n-by-p numeric array

z-coordinates of points to be transformed, specified as an m-by-n-by-p numeric array. w is used only when tform is a 3-D geometric transformation. The size of w must match the size of u.

Data Types: single | double

U — Coordinates of points to be transformed

l-by-2 or l-by-3 numeric array

Coordinates of points to be transformed, specified as an l-by-2 or l-by-3 numeric array. The number of columns of U matches the dimensionality of tform.

The first column lists the x-coordinate of each point to transform, and the second column lists the y-coordinate. If tform represents a 3-D geometric transformation, U has size l-by-3 and the third column lists the z-coordinate of the points to transform.

Data Types: single | double

Output Arguments

x — x-coordinates of points after transformation

m-by-n or m-by-n-by-p numeric array

x-coordinates of points after transformation, returned as an m-by-n or m-by-n-by-p numeric array. The number of dimensions of x matches the dimensionality of tform.

Data Types: single | double

y — y-coordinates of points after transformation

m-by-n or m-by-n-by-p numeric array

y-coordinates of points after transformation, returned as an m-by-n or m-by-n-by-p numeric array. The size of y matches the size of x.

Data Types: single | double

z — z-coordinates of points after transformation

m-by-n-by-p numeric array

z-coordinates of points after transformation, returned as an m-by-n-by-p numeric array. The size of z matches the size of x.

Data Types: single | double

X — Coordinates of points after transformation

numeric array

Coordinates of points after transformation, returned as a numeric array. The size of X matches the size of U.

The first column lists the x-coordinate of each point after transformation, and the second column lists the y-coordinate. If tform represents a 3-D geometric transformation, the third column lists the z-coordinate of the points after transformation.

Data Types: single | double

Version History

Introduced in R2013a

R2022b: Supports new geometric transformation objects

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, you can now specify tform as a geometric transformation object that uses the premultiply convention, such as an affinetform2d object.

Before, for linear geometric transformations, you specified tform as a geometric transformation object that uses a postmultiply convention, such as an affine2d object. Although transformPointsForward still accepts objects that use the postmultiply convention, these objects are not recommended. For more information, see Migrate Geometric Transformations to Premultiply Convention.

There is no change to the support for nonlinear geometric transformations.