simtform3d

R2026b

3-D similarity geometric transformation

Since R2022b

Description

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

Creation

Syntax

tform = simtform3d

tform = simtform3d(s,rotMat,t)

tform = simtform3d(s,eulerAngles,t)

tform = simtform3d(simMat)

tform = simtform3d(tformIn)

Description

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

tform = simtform3d(s,rotMat,t) creates a simtform3d object that performs a similarity transformation based on the specified scale factor s, rotation matrix rotMat, and amount of translation t.

tform = simtform3d(s,eulerAngles,t) creates a simtform3d object that performs a similarity transformation based on the specified scale factor s, Euler angles, and amount of translation t.

tform = simtform3d(simMat) creates a simtform3d object from the specified 3-D similarity transformation matrix, simMat.

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

Input Arguments

s — 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.

This argument sets the Scale property.

Data Types: double | single

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 performs rotation about the x-axis first, then the y-axis, and then the z-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 similarity 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 (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

simMat — Forward 3-D similarity transformation

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

Forward 3-D similarity transformation, specified as a 4-by-4 numeric matrix. When you create the object, you can also specify simMat 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 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]$$

s is the scale factor and sets the Scale property. 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 — 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.

Output Arguments

tform — Similarity 3-D geometric transformation

simtform3d object

Similarity 3-D geometric transformation, returned as a simtform3d 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 x-axis first, then the y-axis, and then the z-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

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: [3×3 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

Tips

• The simtform3d object does not support reflection. To create a geometric transformation that includes reflection, use an affinetform3d object instead. To check for reflection, calculate the determinant of the rotation matrix rotMat or the upper‑left 3-by-3 submatrix of the similarity transformation matrix, simMat. A negative determinant indicates that the transformation includes a reflection.

• You can the apply the rigid transformation saved in the simtform3d 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:

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

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