simtform3d

3-D similarity geometric transformation

Since R2022b

Description

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

Creation

Syntax

tform = simtform3d

tform = simtform3d(Scale,R,Translation)

tform = simtform3d(Scale,eulerAngles,Translation)

tform = simtform3d(A)

tform = simtform3d(tformIn)

Description

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

tform = simtform3d(Scale,R,Translation) creates a simtform3d object that performs a similarity transformation based on the specified values of the Scale, R, and Translation properties. These properties specify the scale factor, rotation angle, and the amount of translation in the x-, y-, and z-directions, respectively.

tform = simtform3d(Scale,eulerAngles,Translation) creates a simtform3d object that performs a similarity transformation based on Euler angles and the specified value of the Scale and Translation properties.

tform = simtform3d(A) creates a simtform3d object and sets the property A to the specified 3-D similarity transformation matrix.

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

Input Arguments

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 (Rx, Ry, and Rz) 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

tformIn — Similarity 3-D geometric transformation

affinetform3d object | rigidtform3d object | simtform3d object | transltform3d object

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

Properties

A — Forward 3-D similarity transformation

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

Forward 3-D similarity 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:

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

For a similarity transformation, A has the form:

$${\rm A}=\left[\begin{array}{cccc}s\ast \text{R}(1,1)& s\ast \text{R}(1,2)& s\ast \text{R}(1,3)& t_x\\ s\ast \text{R}(2,1)& s\ast \text{R}(2,2)& s\ast \text{R}(2,3)& t_y\\ s\ast \text{R}(3,1)& s\ast \text{R}(3,2)& s\ast \text{R}(3,3)& t_z\\ 0& 0& 0& 1\end{array}\right]$$

where s is the scale factor and corresponds to the Scale property. R(i,j) are the elements of the rotation matrix specified by the corresponding (i,j) indices of 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 elements of the Translation property.

Data Types: double | single

Scale — Scale factor

1 (default) | positive number

Scale factor, specified as a positive number. The scale factor corresponds to the value s in the similarity transformation matrix defined by property A.

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 performs rotation 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

3 (default)

This property is read-only.

Dimensionality of the geometric transformation for both input and output points, specified as 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

Create 3-D Similarity Transformation

Specify the scale factor and the amount of translation. The transformation in this example does not perform rotation, so set the Euler angles to [0 0 0].

scaleFactor = 1.5;
eulerAngles = [0 0 0];
translation = [10 20.5 15];

Create a simtform3d object that performs the scaling and translation.

tform = simtform3d(scaleFactor,eulerAngles,translation)

tform = 
  simtform3d with properties:

    Dimensionality: 3
             Scale: 1.5000
       Translation: [10 20.5000 15]
                 R: [3x3 double]

                 A: [1.5000         0         0   10.0000
                          0    1.5000         0   20.5000
                          0         0    1.5000   15.0000
                          0         0         0    1.0000]

Examine the value of the A property.

tform.A

ans = 4×4

    1.5000         0         0   10.0000
         0    1.5000         0   20.5000
         0         0    1.5000   15.0000
         0         0         0    1.0000

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• simtform3d 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 simtform3d 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

R2024a: Scale must be positive

Starting in R2024a, you must specify the Scale property as a positive number. Negative scale factors are not supported because they cause an orientation-reversing reflection.

If you load a simtform3d object from a MAT file saved in a prior release, and the transformation has a negative scale factor, then the transformation loads as an affinetform3d object instead.