affine3d

(Not recommended) 3-D affine geometric transformation using postmultiply convention

affine3d is not recommended. Use the affinetform3d object instead. For more information, see Compatibility Considerations.

Description

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

Creation

Syntax

tform = affine3d

tform = affine3d(t)

Description

tform = affine3d creates an affine3d object with default property settings that correspond to the identity transformation.

tform = affine3d(t) sets the property T as the specified 3-D affine transformation matrix t.

Properties

T — Forward 3-D affine transformation

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

Forward 3-D affine transformation, specified as a nonsingular 4-by-4 numeric matrix.

The matrix T uses the convention:

[x y z 1] = [u v w 1] * T

where T has the form:

 [a b c 0;
  d e f 0;
  g h i 0;
  j k l 1];

The default of T is the identity transformation.

Data Types: double | single

Dimensionality — Dimensionality of geometric transformation

3 (default)

Describes the dimensionality of the geometric transformation for both input and output points, specified as the value 3.

Object Functions

invert	Invert geometric transformation
isRigid	Determine if geometric transformation is rigid transformation
isSimilarity	Determine if geometric transformation is similarity transformation
isTranslation	Determine if geometric transformation is pure translation
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 Object for Anisotropic Scaling

Create an affine3d object that scales a 3-D image by a different factor in each dimension.

Sx = 1.2;
Sy = 1.6;
Sz = 2.4;
T = [Sx 0 0 0; 0 Sy 0 0; 0 0 Sz 0; 0 0 0 1];
tform = affine3d(T)

tform = 
  affine3d with properties:

                 T: [4x4 double]
    Dimensionality: 3

Examine the value of the T property.

tform.T

ans = 4×4

    1.2000         0         0         0
         0    1.6000         0         0
         0         0    2.4000         0
         0         0         0    1.0000

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• affine3d 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 an affine3d object. Instead, you can return a numeric array, such as the value of the T 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 R2013a

R2022b: Not recommended

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, 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, which supports the premultiply convention. For more information, see Migrate Geometric Transformations to Premultiply Convention.

To update your code:

• Change instances of the function name affine3d to affinetform3d.

• Specify the transformation matrix as the transpose of the matrix T, where T is either the value of the T property of the affine3d object or the transformation matrix used to create the affine3d object.

Discouraged Usage	Recommended Replacement
This example creates an affine3d object from transformation matrix T in the postmultiply convention. T = [2 0 0 0; 0 2 0 0; 0 0 4 0; 5 10 -5 1]; tformPost = affine3d(T);	This example creates an affinetform3d object from the transpose of the transformation matrix T. T = [2 0 0 0; 0 2 0 0; 0 0 4 0; 5 10 -5 1]; A = T'; tform = affinetform3d(A); This example starts with an affine3d object called tformPost and creates an affinetform3d object from the transpose of the T property of tformPost. T = tformPost.T; tform = affinetform3d(T');

R2022b: Fewer functions create affine3d objects

You can no longer create an affine3d object using the imregtform or randomAffine3d functions. These functions return 3-D affine transformations as an affinetform3d, rigidtform3d, simtform3d, or transltform3d object.

R2021b: Support for thread-based environments

affine3d now supports thread-based environments.