rigidtform2d

R2026b

2-D rigid geometric transformation

Since R2022b. Recommended over rigid2d.

Description

A rigidtform2d object stores information about a 2-D rigid geometric transformation and enables forward and inverse transformations.

Creation

Syntax

tform = rigidtform2d

tform = rigidtform2d(t)

tform = rigidtform2d(rotAngle,t)

tform = rigidtform2d(rotMat,t)

tform = rigidtform2d(rigidMat)

tform = rigidtform2d(tformIn)

Description

tform = rigidtform2d creates a rigidtform2d object that performs an identity transformation.

tform = rigidtform2d(t) creates a rigidtform2d object that performs a rigid transformation consisting only of translation by the specified amount t.

If you want a transformation that performs only 2-D translation, consider using the transltform2d object.

tform = rigidtform2d(rotAngle,t) creates a rigidtform2d object that performs a rigid transformation based on the specified angle of rotation about the origin rotAngle, and amount of translation t.

tform = rigidtform2d(rotMat,t) creates a rigidtform2d object that performs a rigid transformation based on the specified rotation matrix rotMat, and amount of translation t.

tform = rigidtform2d(rigidMat) creates a rigidtform2d object from a specified 2-D rigid transformation matrix, rigidMat.

tform = rigidtform2d(tformIn) creates a rigidtform2d object from another geometric transformation object, tformIn, that represents a valid 2-D rigid geometric transformation.

Input Arguments

t — Amount of translation

[0 0] (default) | 2-element numeric vector

Amount of translation, specified as a 2-element numeric vector of the form [t_x t_y]. These amounts of translation correspond to the values t_x and t_y in the rigid transformation matrix defined by A.

This argument sets the Translation property.

Data Types: double | single

rotAngle — Rotation angle about origin

0 (default) | numeric scalar

Rotation angle about the origin, in degrees, specified as a numeric scalar. The rotation angle corresponds to the value r in the transformation matrix defined by the property A, and in the rotation matrix defined by the property R.

This argument sets the RotationAngle property.

Data Types: double | single

rotMat — Rotation matrix

2-by-2 identity matrix (default) | 2-by-2 numeric matrix

Rotation matrix, specified as a 2-by-2 numeric matrix. The matrix must have the form

 rotMat = [cosd(r) -sind(r); sind(r)  cosd(r)]

where r is the value of the rotation angle about the origin.

This argument sets the R property.

rigidMat — Forward 2-D rigid transformation

3-by-3 identity matrix (default) | 3-by-3 numeric matrix | 2-by-3 numeric matrix

Forward 2-D rigid transformation, specified as a 3-by-3 numeric matrix. You can also specify rigidMat as a 2-by-3 numeric matrix. In this case, the object concatenates the row vector [0 0 1] to the end of the matrix, forming a 3-by-3 matrix.

A valid 2-D rigid transformation A has the form:

$${\rm A}=\left[\begin{array}{ccc}cosd(r)& -\mathrm{sind}(r)& t_x\\ \mathrm{sind}(r)& cosd(r)& t_y\\ 0& 0& 1\end{array}\right]$$

r is the rotation angle and sets the RotationAngle property. t_x and t_y are the amount of translation in the x- and y- directions, respectively, and set the Translation property.

This argument sets the A property.

Data Types: double | single

tformIn — Rigid 2-D geometric transformation

affinetform2d object | rigidtform2d object | simtform2d object | transltform2d object | projtform2d object

Rigid 2-D geometric transformation, specified as an affinetform2d object, rigidtform2d object, simtform2d object, transltform2d object, or projtform2d object.

Output Arguments

tform — Rigid 2-D geometric transformation

rigidtform2d object

Rigid 2-D geometric transformation, returned as a rigidtform2d object.

Properties

A — Forward 2-D rigid transformation

3-by-3 identity matrix (default) | 3-by-3 numeric matrix

Forward 2-D rigid transformation, specified as a 3-by-3 numeric matrix. The default value of A is the identity matrix.

The matrix A transforms the point (u, v) in the input coordinate space to the point (x, y) in the output coordinate space using the convention:

$$\left[\begin{array}{c}x\\ y\\ 1\end{array}\right]={\rm A}\times \left[\begin{array}{c}u\\ v\\ 1\end{array}\right]$$

For a rigid transformation, A has the form:

$${\rm A}=\left[\begin{array}{ccc}cosd(r)& -\mathrm{sind}(r)& t_x\\ \mathrm{sind}(r)& cosd(r)& t_y\\ 0& 0& 1\end{array}\right]$$

where r is the rotation angle and corresponds to the property RotationAngle. t_x and t_y are the amount of translation in the x- and y- directions, respectively, and correspond to the property Translation.

Data Types: double | single

R — Rotation matrix

2-by-2 identity matrix (default) | 2-by-2 numeric matrix

Rotation matrix, specified as a 2-by-2 numeric matrix. The matrix must have the form

 R = [cosd(r) -sind(r); sind(r)  cosd(r)]

where r is the value of the RotationAngle property.

RotationAngle — Rotation angle about origin

0 (default) | numeric scalar

Rotation angle about the origin, in degrees, specified as a numeric scalar. The rotation angle corresponds to the value r in the transformation matrix defined by A, and in the rotation matrix defined by R.

Data Types: double | single

Translation — Amount of translation

[0 0] (default) | 2-element numeric vector

Amount of translation, specified as a 2-element numeric vector of the form [t_x t_y]. These amounts of translation correspond to the values t_x and t_y in the rigid transformation matrix defined by A.

Data Types: double | single

Dimensionality — Dimensionality of geometric transformation

Read-only: 2 (default)

This property is read-only.

Dimensionality of the geometric transformation for both input and output points, returned as the value 2.

Data Types: double

Object Functions

invert	Invert geometric transformation
outputLimits	Find output spatial limits given input spatial limits
transformPointsForward	Apply forward geometric transformation
transformPointsInverse	Apply inverse geometric transformation

Examples

Create 2-D Rigid Transformation

Specify a rotation angle and an amount of translation.

theta = 30;
translation = [10 20.5];

Create a rigidtform2d object that performs the specified rotation and translation.

tform = rigidtform2d(theta,translation)

tform = 
  rigidtform2d with properties:

    Dimensionality: 2
     RotationAngle: 30
       Translation: [10 20.5000]
                 R: [2×2 double]

                 A: [0.8660   -0.5000   10.0000
                     0.5000    0.8660   20.5000
                          0         0    1.0000]

Examine the value of the A property.

tform.A

ans = 3×3

    0.8660   -0.5000   10.0000
    0.5000    0.8660   20.5000
         0         0    1.0000

Tips

• The rigidtform2d object does not support reflection. To create a geometric transformation that includes reflection, use an affinetform2d object instead. To check for reflection, calculate the determinant of the rotation matrix rotMat or the upper‑left 2-by-2 submatrix of the rigid transformation matrix, rigidMat. A negative determinant indicates that the transformation includes a reflection.

• You can the apply the rigid transformation saved in the rigidtform2d object to an image by using the imwarp function.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• rigidtform2d supports the generation of C and C++ code (requires MATLAB^® Coder™). For more information, see Code Generation for Image Processing.

• When generating code, you can only specify singular objects. Arrays of objects are not supported.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The rigidtform2d function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2022b

R2022b: Recommended over rigid2d

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. The rigidtform2d object stores information about 2-D rigid geometric transformations in a format consistent with the premultiply convention.

The rigid2d object is not recommended because it uses the postmultiply convention. Although there are no plans to remove the rigid2d object at this time, you can streamline your geometric transformation workflows by switching to the rigidtform2d object. For more information, see Migrate Geometric Transformations to Premultiply Convention.