Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Transform3D

A 3×4 matrix representing a 3D transformation.

Description

A 3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of a basis (first 3 columns) and a Vector3 for the origin (last column).

For more information, read the “Matrices and transforms” documentation article.

Tutorials

• Math documentation index

• Matrices and transforms

• Using 3D transforms

• Matrix Transform Demo

• 3D Platformer Demo

• 2.5D Demo

Properties

Constructors

Methods

Operators

Constants

IDENTITY = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)

Transform3D with no translation, rotation or scaling applied. When applied to other data structures, IDENTITY performs no transformation.

FLIP_X = Transform3D(-1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)

Transform3D with mirroring applied perpendicular to the YZ plane.

FLIP_Y = Transform3D(1, 0, 0, 0, -1, 0, 0, 0, 1, 0, 0, 0)

Transform3D with mirroring applied perpendicular to the XZ plane.

FLIP_Z = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 0)

Transform3D with mirroring applied perpendicular to the XY plane.

Property Descriptions

Basis basis = Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)

The basis is a matrix containing 3 Vector3 as its columns: X axis, Y axis, and Z axis. These vectors can be interpreted as the basis vectors of local coordinate system traveling with the object.

Vector3 origin = Vector3(0, 0, 0)

The translation offset of the transform (column 3, the fourth column). Equivalent to array index 3.

Constructor Descriptions

Transform3D Transform3D ( )

Constructs a default-initialized Transform3D set to IDENTITY.

Transform3D Transform3D ( Transform3D from )

Constructs a Transform3D as a copy of the given Transform3D.

Transform3D Transform3D ( Basis basis, Vector3 origin )

Constructs a Transform3D from a Basis and Vector3.

Transform3D Transform3D ( Projection from )

Constructs a Transform3D from a Projection by trimming the last row of the projection matrix (from.x.w, from.y.w, from.z.w, and from.w.w are not copied over).

Transform3D Transform3D ( Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin )

Constructs a Transform3D from four Vector3 values (matrix columns). Each axis corresponds to local basis vectors (some of which may be scaled).

Method Descriptions

Transform3D affine_inverse ( ) const

Returns the inverse of the transform, under the assumption that the transformation is composed of rotation, scaling and translation.

Transform3D interpolate_with ( Transform3D xform, float weight ) const

Returns a transform interpolated between this transform and another by a given weight (on the range of 0.0 to 1.0).

Transform3D inverse ( ) const

Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use affine_inverse for transforms with scaling).

bool is_equal_approx ( Transform3D xform ) const

Returns true if this transform and xform are approximately equal, by calling is_equal_approx on each component.

bool is_finite ( ) const

Returns true if this transform is finite, by calling @GlobalScope.is_finite on each component.

Transform3D looking_at ( Vector3 target, Vector3 up=Vector3(0, 1, 0), bool use_model_front=false ) const

Returns a copy of the transform rotated such that the forward axis (-Z) points towards the target position.

The up axis (+Y) points as close to the up vector as possible while staying perpendicular to the forward axis. The resulting transform is orthonormalized. The existing rotation, scale, and skew information from the original transform is discarded. The target and up vectors cannot be zero, cannot be parallel to each other, and are defined in global/parent space.

If use_model_front is true, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the target position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right).

Transform3D orthonormalized ( ) const

Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors (scale of 1 or -1).

Transform3D rotated ( Vector3 axis, float angle ) const

Returns a copy of the transform rotated around the given axis by the given angle (in radians).

The axis must be a normalized vector.

This method is an optimized version of multiplying the given transform X with a corresponding rotation transform R from the left, i.e., R * X.

This can be seen as transforming with respect to the global/parent frame.

Transform3D rotated_local ( Vector3 axis, float angle ) const

Returns a copy of the transform rotated around the given axis by the given angle (in radians).

The axis must be a normalized vector.

This method is an optimized version of multiplying the given transform X with a corresponding rotation transform R from the right, i.e., X * R.

This can be seen as transforming with respect to the local frame.

Transform3D scaled ( Vector3 scale ) const

Returns a copy of the transform scaled by the given scale factor.

This method is an optimized version of multiplying the given transform X with a corresponding scaling transform S from the left, i.e., S * X.

This can be seen as transforming with respect to the global/parent frame.

Transform3D scaled_local ( Vector3 scale ) const

Returns a copy of the transform scaled by the given scale factor.

This method is an optimized version of multiplying the given transform X with a corresponding scaling transform S from the right, i.e., X * S.

This can be seen as transforming with respect to the local frame.

Transform3D translated ( Vector3 offset ) const

Returns a copy of the transform translated by the given offset.

This method is an optimized version of multiplying the given transform X with a corresponding translation transform T from the left, i.e., T * X.

This can be seen as transforming with respect to the global/parent frame.

Transform3D translated_local ( Vector3 offset ) const

Returns a copy of the transform translated by the given offset.

This method is an optimized version of multiplying the given transform X with a corresponding translation transform T from the right, i.e., X * T.

This can be seen as transforming with respect to the local frame.

Operator Descriptions

bool operator != ( Transform3D right )

Returns true if the transforms are not equal.

Note: Due to floating-point precision errors, consider using is_equal_approx instead, which is more reliable.

AABB operator * ( AABB right )

Transforms (multiplies) the AABB by the given Transform3D matrix.

PackedVector3Array operator * ( PackedVector3Array right )

Transforms (multiplies) each element of the Vector3 array by the given Transform3D matrix.

Plane operator * ( Plane right )

Transforms (multiplies) the Plane by the given Transform3D transformation matrix.

Transform3D operator * ( Transform3D right )

Composes these two transformation matrices by multiplying them together. This has the effect of transforming the second transform (the child) by the first transform (the parent).

Vector3 operator * ( Vector3 right )

Transforms (multiplies) the Vector3 by the given Transform3D matrix.

Transform3D operator * ( float right )

This operator multiplies all components of the Transform3D, including the origin vector, which scales it uniformly.

Transform3D operator * ( int right )

This operator multiplies all components of the Transform3D, including the origin vector, which scales it uniformly.

bool operator == ( Transform3D right )

Returns true if the transforms are exactly equal.

Note: Due to floating-point precision errors, consider using is_equal_approx instead, which is more reliable.