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(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

You can the apply the rigid transformation saved in the simtform3d object to an image by using the imwarp function. To fine-tune the simtform3d object by visually examining the output of the imwarp function, tune the scale, rotation, and translation components of the transformation matrix. You can directly tune the scale factor and translation coordinates by examining the visual output. However, if you create the simtform3d object using a rotation matrix, you may need to estimate the Euler angles to tune the rotation component by examining the visual output. To tune the rotation matrix based on visual output, estimate the Euler angles from the rotation matrix and tune the Euler angles.

R = tform.R;
x = atan2(R(3,2),R(3,3));
y = asin(-R(3,1));
z = atan2(R(2,1),R(1,1));
x = rad2deg(x);
y = rad2deg(y);
z = rad2deg(z);

This method provides a starting point to start tuning the rotation matrix. This method only estimates the Euler angles. To accurately calculate the Euler angles, including edge cases, use the rotm2eul (Robotics System Toolbox) 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.