affinetform3d

3-D affine geometric transformation

Since R2022b. Recommended over affine3d.

Description

An affinetform3d object stores information about a 3-D affine geometric transformation and enables forward and inverse transformations.

Creation

You can create an affinetform3d object in these ways:

• imregtform — Estimates a geometric transformation that maps a moving image to a fixed image using similarity optimization.

• randomAffine3d — Creates a randomized 3-D affine transformation.

• Functions in other toolboxes that return geometric transformations, including but not limited to:

  • fitgeotform3d (Medical Imaging Toolbox)

• The affinetform3d function described here.

Syntax

tform = affinetform3d

tform = affinetform3d(affineMat)

tform = affinetform3d(tformIn)

Description

tform = affinetform3d creates an affinetform3d object that performs an identity transformation.

tform = affinetform3d(affineMat) creates an affinetform3d object from a valid 3-D affine transformation matrix, affineMat.

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

Input Arguments

affineMat — Forward 3-D affine transformation

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

Forward 3-D affine transformation, specified as a 4-by-4 numeric matrix. When you create the object, you can also specify affineMat 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 affine transformation A has the form:

$${\rm A}=\left[\begin{array}{cccc}a& b& c& d\\ e& f& g& h\\ i& j& k& l\\ 0& 0& 0& 1\end{array}\right]$$

This argument sets the A property.

Data Types: double | single

tformIn — Affine 3-D geometric transformation

affinetform3d object | rigidtform3d object | simtform3d object | transltform3d object

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

Output Arguments

tform — Affine 3-D geometric transformation

affinetform3d object

Affine 3-D geometric transformation, returned as an affinetform3d object.

Properties

A — Forward 3-D affine transformation

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

Forward 3-D affine transformation, specified as a 4-by-4 numeric matrix. The default value 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 an affine transformation, A has the form:

$${\rm A}=\left[\begin{array}{cccc}a& b& c& d\\ e& f& g& h\\ i& j& k& l\\ 0& 0& 0& 1\end{array}\right]$$

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 Affine Transformation

Define a 4-by-4 geometric transformation matrix. This matrix specifies an affine transformation consisting of translation and anisotropic scaling.

[sx,sy,sz] = deal(2,2,2.5);
[tx,ty,tz] = deal(10,20.5,15);
A = [sx 0 0 tx; 0 sy 0 ty; 0 0 sz tz; 0 0 0 1];

Create an affinetform3d object that performs the scaling and translation.

tform = affinetform3d(A)

tform = 
  affinetform3d with properties:

    Dimensionality: 3

                 A: [2.0000         0         0   10.0000
                          0    2.0000         0   20.5000
                          0         0    2.5000   15.0000
                          0         0         0    1.0000]

Examine the value of the A property.

tform.A

ans = 4×4

    2.0000         0         0   10.0000
         0    2.0000         0   20.5000
         0         0    2.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:

• affinetform3d 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 an affinetform3d 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

R2022b: Recommended over affine3d

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. The affinetform3d object stores information about 3-D affine geometric transformations in a format consistent with the premultiply convention.

The affine3d object is not recommended because it uses the postmultiply convention. Although there are no plans to remove the affine3d object at this time, you can streamline your geometric transformation workflows by switching to the affinetform3d object. For more information, see Migrate Geometric Transformations to Premultiply Convention.