rigid3d

(Not recommended) 3-D rigid geometric transformation using postmultiply convention

Since R2020a

rigid3d is not recommended. Use the rigidtform3d object instead. For more information, see Compatibility Considerations.

Description

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

Creation

Syntax

tform = rigid3d

tform = rigid3d(t)

tform = rigid3d(rot,trans)

Description

tform = rigid3d creates a default rigid3d object that corresponds to an identity transformation.

tform = rigid3d(t) sets the T property as the specified 3-D rigid transformation matrix t.

tform = rigid3d(rot,trans) sets the Rotation and Translation properties as the specified rotation matrix rot and translation vector trans, respectively.

Properties

T — Forward rigid transformation

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

Forward rigid transformation, specified as a 4-by-4 numeric matrix. This matrix must be a homogeneous transformation matrix that satisfies the postmultiply convention given by:

$$\left[\begin{array}{cccc}x& y& z& 1\end{array}\right]=\left[\begin{array}{cccc}u& v& w& 1\end{array}\right]*T$$

T has the form

$$\begin{array}{ccccc}[r_{11}& r_{12}& r_{13}& 0;& \mathrm{...}\\ r_{21}& r_{22}& r_{23}& 0;& \mathrm{...}\\ r_{31}& r_{32}& r_{33}& 0;& \mathrm{...}\\ t_x& t_y& t_z& 1];& \end{array}$$

Data Types: single | double

Rotation — Rotation component of transformation

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

Rotation component of the transformation, specified as a 3-by-3 numeric matrix. This rotation matrix satisfies the postmultiply convention given by:

$$\left[\begin{array}{ccc}x& y& z\end{array}\right]=\left[\begin{array}{ccc}u& v& w\end{array}\right]*R$$

Data Types: single | double

Translation — Translation component of transformation

[0 0 0] (default) | 3-element numeric row vector

Translation component of the transformation, specified as a 3-element numeric row vector. This translation vector satisfies the convention given by

$$\left[\begin{array}{ccc}x& y& z\end{array}\right]=\left[\begin{array}{ccc}u& v& w\end{array}\right]+t$$

Data Types: single | double

Dimensionality — Dimensionality of geometric transformation

3 (default)

This property is read-only.

Dimensionality of the geometric transformation, specified as the value 3.

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 Rigid 3-D Object with Defined Translation and Rotation

Specify an angle of rotation in degrees and create a 3-by-3 rotation matrix.

theta = 30;
rot = [ cosd(theta) sind(theta) 0; ...
       -sind(theta) cosd(theta) 0; ...
       0 0 1];

Specify the amount of horizontal, vertical, and depthwise translation, respectively.

trans = [2 3 4];

Create a rigid3d object that performs the rotation and translation.

tform = rigid3d(rot,trans)

tform = 
  rigid3d with properties:

       Rotation: [3x3 double]
    Translation: [2 3 4]

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• rigid3d supports the generation of 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 rigid3d object. Instead, you can return a numeric array, such as the value of the T 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 R2020a

R2022b: Not recommended

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, 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, which supports the premultiply convention. For more information, see Migrate Geometric Transformations to Premultiply Convention.

To update your code:

• Change instances of the function name rigid3d to rigidtform3d.

• Specify the transformation matrix as the transpose of T or the rotation matrix as the transpose of Rotation. T is either the value of the T property of the rigid3d object or the transformation matrix used to create the rigid3d object. Rotation is either the value of the Rotation property of the rigid3d object or the rotation matrix used to create the rigid3d object.

Discouraged Usage	Recommended Replacement
This example creates a rigid3d object from transformation matrix T in the postmultiply convention. T = [1 0 0 0; 0 1 0 0; 0 0 1 0; 5 10 -5 1]; tformPost = rigid3d(T);	This example creates a rigidtform3d object from the transpose of matrix T. T = [1 0 0 0; 0 1 0 0; 0 0 1 0; 5 10 -5 1]; tform = rigidtform3d(T'); This example starts with a rigid3d object called tformPost and creates a rigidtform3d object from the transpose of the T property of tformPost. T = tformPost.T; tform = rigidtform2d(T');
This example creates a rigid3d object from a rotation matrix rot in the postmultiply convention and a translation trans. theta = 30; rot = [ cosd(theta) sind(theta) 0; ... -sind(theta) cosd(theta) 0; ... 0 0 1]; trans = [5 10 -5]; tformPost = rigid3d(rot,trans);	This example creates a rigidtform3d object from the transpose of the rotation matrix rot and a translation trans. theta = 30; rot = [ cosd(theta) sind(theta) 0; ... -sind(theta) cosd(theta) 0; ... 0 0 1]; trans = [5 10 -5]; tform = rigidtform3d(rot',trans);