simtform2d

R2026b

2-D similarity geometric transformation

Since R2022b

Description

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

Creation

You can create a simtform2d object in these ways:

• fitgeotform2d — Estimate a geometric transformation that maps pairs of control points between two images.

• The simtform2d function described here.

Syntax

tform = simtform2d

tform = simtform2d(s,rotAngle,t)

tform = simtform2d(s,rotMat,t)

tform = simtform2d(simMat)

tform = simtform2d(tformIn)

Description

tform = simtform2d creates a simtform2d object that performs the identity transformation.

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

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

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

tform = simtform2d(tformIn) creates a simtform2d object from another geometric transformation object, tformIn, that represents a valid 2-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

rotAngle — Rotation angle

0 (default) | numeric scalar

Rotation angle about the origin in degrees, specified as a numeric scalar in the range [-180, 180). If you specify a rotation angle outside of this range, then the simtform2d object automatically brings the value to the range [-180, 180) by adding positive or negative multiples of 360.

The rotation angle corresponds to the value r in the transformation matrix defined by property A and in the rotation matrix defined by property R.

This argument sets the RotationAngle property.

Data Types: double | single

rotMat — Rotation matrix

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

Rotation matrix, specified as a 2-by-2 numeric matrix. The matrix must have the form

 R = [cosd(r) -sind(r); sind(r)  cosd(r)]

where r is the value of the rotation angle about the origin.

This argument sets the R property.

t — Amount of translation

[0 0] (default) | 2-element numeric vector

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

This argument sets the Translation property.

Data Types: double | single

simMat — Forward 2-D similarity transformation

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

Forward 2-D similarity transformation, specified as a 3-by-3 numeric matrix. You can also specify simMat as a 2-by-3 numeric matrix. In this case, the object concatenates the row vector [0 0 1] to the end of the matrix, forming a 3-by-3 matrix.

A valid 2-D similarity transformation A has the form:

$${\rm A}=\left[\begin{array}{ccc}s\times \mathrm{cosd}(r)& -s\times \mathrm{sind}(r)& t_x\\ s\times \mathrm{sind}(r)& s\times \mathrm{cosd}(r)& t_y\\ 0& 0& 1\end{array}\right]$$

s is the scale factor and sets the Scale property. r is the rotation angle and sets the RotationAngle property. t_x and t_y are the amount of translation in the x- and y-directions, respectively, and set the Translation property.

This argument sets the A property.

Data Types: double | single

tformIn — Similarity 2-D geometric transformation

affinetform2d object | rigidtform2d object | simtform2d object | transltform2d object | projtform2d object

Similarity 2-D geometric transformation, specified as an affinetform2d object, rigidtform2d object, simtform2d object, transltform2d object, or projtform2d object.

Output Arguments

tform — Similarity 2-D geometric transformation

simtform2d object

Similarity 2-D geometric transformation, returned as a simtform2d object.

Properties

A — Forward 2-D similarity transformation

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

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

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

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

For a similarity transformation, A has the form:

$${\rm A}=\left[\begin{array}{ccc}s\times \mathrm{cosd}(r)& -s\times \mathrm{sind}(r)& t_x\\ s\times \mathrm{sind}(r)& s\times \mathrm{cosd}(r)& t_y\\ 0& 0& 1\end{array}\right]$$

where s is the scale factor and corresponds to the Scale property. r is the rotation angle and corresponds to the RotationAngle property. t_x and t_y are the amount of translation in the x- and y-directions, respectively, and correspond to 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

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

Rotation matrix, specified as a 2-by-2 numeric matrix. The matrix must have the form

 R = [cosd(r) -sind(r); sind(r)  cosd(r)]

where r is the value of the RotationAngle property.

RotationAngle — Rotation angle

0 (default) | numeric scalar

Rotation angle about the origin in degrees, specified as a numeric scalar in the range [-180, 180). If you specify a rotation angle outside of this range, then the simtform2d object automatically brings the value to the range [-180, 180) by adding positive or negative multiples of 360.

The rotation angle corresponds to the value r in the transformation matrix defined by A and in the rotation matrix defined by R.

Data Types: double | single

Translation — Amount of translation

[0 0] (default) | 2-element numeric vector

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

Data Types: double | single

Dimensionality — Dimensionality of geometric transformation

Read-only: 2 (default)

This property is read-only.

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

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 2-D Similarity Transformation

Specify the scale factor, rotation angle, and the amount of translation.

scaleFactor = 3;
theta = 30;
translation = [10 20.5];

Create a simtform2d object that performs the specified scaling, rotation, and translation.

tform = simtform2d(scaleFactor,theta,translation)

tform = 
  simtform2d with properties:

    Dimensionality: 2
             Scale: 3
     RotationAngle: 30
       Translation: [10 20.5000]
                 R: [2×2 double]

                 A: [2.5981   -1.5000   10.0000
                     1.5000    2.5981   20.5000
                          0         0    1.0000]

Examine the value of the A property.

tform.A

ans = 3×3

    2.5981   -1.5000   10.0000
    1.5000    2.5981   20.5000
         0         0    1.0000

Tips

• The simtform2d object does not support reflection. To create a geometric transformation that includes reflection, use an affinetform2d object instead. To check for reflection, calculate the determinant of the rotation matrix rotMat or the upper‑left 2-by-2 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 simtform2d 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:

• simtform2d 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.

• Only positive values of Scale are supported.

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 simtform2d 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, the simtform2d object stores the Scale property as a positive number. If you specify the scale factor as a negative number, then the simtform2d object converts the transformation to a mathematically equivalent similarity transformation. The equivalent similarity transformation uses a positive scale factor and adds (or subtracts) 180 degrees to the rotation angle.

Likewise, if you load a simtform2d object from a MAT file saved in a prior release, and the transformation has a negative scale factor, then the transformation loads as an equivalent similarity transformation.

You cannot specify the scale factor as a negative number when performing code generation.