rigidtform3d

3-D rigid geometric transformation

Since R2022b. Recommended over rigid3d.

Description

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

Creation

You can create a rigidtform3d object in these ways:

imregtform — Estimates a geometric transformation that maps a moving image to a fixed image using similarity optimization.
Functions in other toolboxes that return geometric transformations, including but not limited to:
- fitgeotform3d (Medical Imaging Toolbox)
The rigidtform3d function described here.

Syntax

tform = rigidtform3d

tform = rigidtform3d(rotMat,t)

tform = rigidtform3d(eulerAngles,t)

tform = rigidtform3d(rigidMat)

tform = rigidtform3d(tformIn)

Description

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

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

tform = rigidtform3d(eulerAngles,t) creates a rigidtform3d object that performs a rigid transformation based on the specified Euler angles and amount of translation in each dimension, t.

example

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

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

Input Arguments

expand all

`rotMat` — Rotation matrix
3-by-3 identity matrix (default) | 3-by-3 numeric matrix

Rotation matrix, specified as a 3-by-3 numeric matrix. The rotation matrix has the effect of rotating about the z-axis first, then the y-axis, and then the x-axis.

This argument sets the R property.

`t` — Amount of translation
`[0 0 0]` (default) | 3-element numeric vector

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

This argument sets the Translation property.

Data Types: double | single

`eulerAngles` — Euler angles
`[0 0 0]` (default) | 3-element numeric vector

Euler angles in x,y,z-order in degrees, specified as a 3-element numeric vector of the form [rx ry rz]. The Euler angles set the R property as a product of three rotation matrices according to:

 Rx = [1 0 0; 0 cosd(rx) -sind(rx); 0 sind(rx) cosd(rx)];
 Ry = [cosd(ry) 0 sind(ry); 0 1 0; -sind(ry) 0 cosd(ry)];
 Rz = [cosd(rz) -sind(rz) 0; sind(rz) cosd(rz) 0; 0 0 1];
  R = Rz*Ry*Rx;

Data Types: double | single

`rigidMat` — Forward 3-D rigid transformation
4-by-4 identity matrix (default) | 4-by-4 numeric matrix | 3-by-4 numeric matrix

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

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

$Α = [\begin{matrix} R (1, 1) & R (1, 2) & R (1, 3) & t_{x} \\ R (2, 1) & R (2, 2) & R (2, 3) & t_{y} \\ R (3, 1) & R (3, 2) & R (3, 3) & t_{z} \\ 0 & 0 & 0 & 1 \end{matrix}]$

R(i,j) are the elements of the rotation matrix and set the R property. t_x, t_y, and t_z are the amount of translation in the x-, y-, and z-directions, respectively, and set the Translation property.

This argument sets the A property.

Data Types: double | single

`tformIn` — Rigid 3-D geometric transformation
`affinetform3d` object | `rigidtform3d` object | `simtform3d` object | `transltform3d` object

Rigid 3-D geometric transformation, specified as an affinetform3d object, rigidtform3d object, simtform3d object, or transltform3d object.

Output Arguments

expand all

`tform` — Rigid 3-D geometric transformation
`rigidtform3d` object

Rigid 3-D geometric transformation, returned as an rigidtform3d object.

Properties

expand all

`A` — Forward 3-D rigid transformation
4-by-4 identity matrix (default) | 4-by-4 numeric matrix

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

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

$[\begin{matrix} x \\ y \\ z \\ 1 \end{matrix}] = Α \times [\begin{matrix} u \\ v \\ w \\ 1 \end{matrix}]$

For a rigid transformation, A has the form:

$Α = [\begin{matrix} R (1, 1) & R (1, 2) & R (1, 3) & t_{x} \\ R (2, 1) & R (2, 2) & R (2, 3) & t_{y} \\ R (3, 1) & R (3, 2) & R (3, 3) & t_{z} \\ 0 & 0 & 0 & 1 \end{matrix}]$

where each element R(i,j) is element (i, j) of the rotation matrix specified by the R property. t_x, t_y, and t_z are the amount of translation in the x-, y-, and z-directions, respectively, and correspond to the Translation property.

Data Types: double | single

`R` — Rotation matrix
3-by-3 identity matrix (default) | 3-by-3 numeric matrix

Rotation matrix, specified as a 3-by-3 numeric matrix. The rotation matrix has the effect of rotating about the z-axis first, then the y-axis, and then the x-axis.

`Translation` — Amount of translation
`[0 0 0]` (default) | 3-element numeric vector

Amount of translation, specified as a 3-element numeric vector of the form [t_x t_y t_z].

Data Types: double | single

`Dimensionality` — Dimensionality of geometric transformation
Read-only: `3` (default)

This property is read-only.

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

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

collapse all

Create 3-D Rigid Transformation

Open Live Script

Specify Euler angles and amounts of translation.

angles = [30 0 90];
translation = [10 20.5 15];

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

tform = rigidtform3d(angles,translation)

tform = 
  rigidtform3d with properties:

    Dimensionality: 3
       Translation: [10 20.5000 15]
                 R: [3×3 double]

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

Examine the value of the A property.

tform.A

ans = 4×4

         0   -0.8660    0.5000   10.0000
    1.0000         0         0   20.5000
         0    0.5000    0.8660   15.0000
         0         0         0    1.0000

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

rigidtform3d 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.
Generated code cannot return a rigidtform3d object. Instead, you can return a numeric array, such as the value of the A property.

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 in R2022b

expand all

R2022b: Recommended over `rigid3d`

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

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

rigidtform3d

Description

Creation

Syntax

Description

Input Arguments

`rotMat` — Rotation matrix
3-by-3 identity matrix (default) | 3-by-3 numeric matrix

`t` — Amount of translation
`[0 0 0]` (default) | 3-element numeric vector

`eulerAngles` — Euler angles
`[0 0 0]` (default) | 3-element numeric vector

`rigidMat` — Forward 3-D rigid transformation
4-by-4 identity matrix (default) | 4-by-4 numeric matrix | 3-by-4 numeric matrix

`tformIn` — Rigid 3-D geometric transformation
`affinetform3d` object | `rigidtform3d` object | `simtform3d` object | `transltform3d` object

Output Arguments

`tform` — Rigid 3-D geometric transformation
`rigidtform3d` object

Properties

`A` — Forward 3-D rigid transformation
4-by-4 identity matrix (default) | 4-by-4 numeric matrix

`R` — Rotation matrix
3-by-3 identity matrix (default) | 3-by-3 numeric matrix

`Translation` — Amount of translation
`[0 0 0]` (default) | 3-element numeric vector

`Dimensionality` — Dimensionality of geometric transformation
Read-only: `3` (default)

Object Functions

Examples

Create 3-D Rigid Transformation

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

Version History

R2022b: Recommended over `rigid3d`

See Also

Topics

rigidtform3d

Description

Creation

Syntax

Description

Input Arguments

rotMat — Rotation matrix 3-by-3 identity matrix (default) | 3-by-3 numeric matrix

t — Amount of translation [0 0 0] (default) | 3-element numeric vector

eulerAngles — Euler angles [0 0 0] (default) | 3-element numeric vector

rigidMat — Forward 3-D rigid transformation 4-by-4 identity matrix (default) | 4-by-4 numeric matrix | 3-by-4 numeric matrix

tformIn — Rigid 3-D geometric transformation affinetform3d object | rigidtform3d object | simtform3d object | transltform3d object

Output Arguments

tform — Rigid 3-D geometric transformation rigidtform3d object

Properties

A — Forward 3-D rigid transformation 4-by-4 identity matrix (default) | 4-by-4 numeric matrix

R — Rotation matrix 3-by-3 identity matrix (default) | 3-by-3 numeric matrix

Translation — Amount of translation [0 0 0] (default) | 3-element numeric vector

Dimensionality — Dimensionality of geometric transformation Read-only: 3 (default)

Object Functions

Examples

Create 3-D Rigid Transformation

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

Version History

R2022b: Recommended over rigid3d

See Also

Topics

`rotMat` — Rotation matrix
3-by-3 identity matrix (default) | 3-by-3 numeric matrix

`t` — Amount of translation
`[0 0 0]` (default) | 3-element numeric vector

`eulerAngles` — Euler angles
`[0 0 0]` (default) | 3-element numeric vector

`rigidMat` — Forward 3-D rigid transformation
4-by-4 identity matrix (default) | 4-by-4 numeric matrix | 3-by-4 numeric matrix

`tformIn` — Rigid 3-D geometric transformation
`affinetform3d` object | `rigidtform3d` object | `simtform3d` object | `transltform3d` object

`tform` — Rigid 3-D geometric transformation
`rigidtform3d` object

`A` — Forward 3-D rigid transformation
4-by-4 identity matrix (default) | 4-by-4 numeric matrix

`R` — Rotation matrix
3-by-3 identity matrix (default) | 3-by-3 numeric matrix

`Translation` — Amount of translation
`[0 0 0]` (default) | 3-element numeric vector

`Dimensionality` — Dimensionality of geometric transformation
Read-only: `3` (default)

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

R2022b: Recommended over `rigid3d`