Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Transform3D

A 3×4 matrix representing a 3D transformation.

Description

The Transform3D built-in Variant type is a 3×4 matrix representing a transformation in 3D space. It contains a Basis, which on its own can represent rotation, scale, and shear. Additionally, combined with its own origin, the transform can also represent a translation.

For a general introduction, see the Matrices and transforms tutorial.

Note: Godot uses a right-handed coordinate system, which is a common standard. For directions, the convention for built-in types like Camera3D is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the Importing 3D Scenes tutorial.

Note

There are notable differences when using this API with C#. See C# API differences to GDScript for more information.

Tutorials

Properties

Basis

basis

Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)

Vector3

origin

Vector3(0, 0, 0)

Constructors

Transform3D

Transform3D()

Transform3D

Transform3D(from: Transform3D)

Transform3D

Transform3D(basis: Basis, origin: Vector3)

Transform3D

Transform3D(from: Projection)

Transform3D

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

Methods

Transform3D

affine_inverse() const

Transform3D

interpolate_with(xform: Transform3D, weight: float) const

Transform3D

inverse() const

bool

is_equal_approx(xform: Transform3D) const

bool

is_finite() const

Transform3D

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

Transform3D

orthonormalized() const

Transform3D

rotated(axis: Vector3, angle: float) const

Transform3D

rotated_local(axis: Vector3, angle: float) const

Transform3D

scaled(scale: Vector3) const

Transform3D

scaled_local(scale: Vector3) const

Transform3D

translated(offset: Vector3) const

Transform3D

translated_local(offset: Vector3) const

Operators

bool

operator !=(right: Transform3D)

AABB

operator *(right: AABB)

PackedVector3Array

operator *(right: PackedVector3Array)

Plane

operator *(right: Plane)

Transform3D

operator *(right: Transform3D)

Vector3

operator *(right: Vector3)

Transform3D

operator *(right: float)

Transform3D

operator *(right: int)

Transform3D

operator /(right: float)

Transform3D

operator /(right: int)

bool

operator ==(right: Transform3D)


Constants

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

A transform with no translation, no rotation, and its scale being 1. Its basis is equal to Basis.IDENTITY.

When multiplied by another Variant such as AABB or another Transform3D, no transformation occurs.

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

Transform3D with mirroring applied perpendicular to the YZ plane. Its basis is equal to Basis.FLIP_X.

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

Transform3D with mirroring applied perpendicular to the XZ plane. Its basis is equal to Basis.FLIP_Y.

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

Transform3D with mirroring applied perpendicular to the XY plane. Its basis is equal to Basis.FLIP_Z.


Property Descriptions

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

The Basis of this transform. It is composed by 3 axes (Basis.x, Basis.y, and Basis.z). Together, these represent the transform's rotation, scale, and shear.


Vector3 origin = Vector3(0, 0, 0)

The translation offset of this transform. In 3D space, this can be seen as the position.


Constructor Descriptions

Transform3D Transform3D()

Constructs a Transform3D identical to the IDENTITY.


Transform3D Transform3D(from: Transform3D)

Constructs a Transform3D as a copy of the given Transform3D.


Transform3D Transform3D(basis: Basis, origin: Vector3)

Constructs a Transform3D from a Basis and Vector3.


Transform3D Transform3D(from: Projection)

Constructs a Transform3D from a Projection. Because Transform3D is a 3×4 matrix and Projection is a 4×4 matrix, this operation trims the last row of the projection matrix (from.x.w, from.y.w, from.z.w, and from.w.w are not included in the new transform).


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

Constructs a Transform3D from four Vector3 values (also called matrix columns).

The first three arguments are the basis's axes (Basis.x, Basis.y, and Basis.z).


Method Descriptions

Transform3D affine_inverse() const

Returns the inverted version of this transform. Unlike inverse, this method works with almost any basis, including non-uniform ones, but is slower. See also Basis.inverse.

Note: For this method to return correctly, the transform's basis needs to have a determinant that is not exactly 0 (see Basis.determinant).


Transform3D interpolate_with(xform: Transform3D, weight: float) const

Returns the result of the linear interpolation between this transform and xform by the given weight.

The weight should be between 0.0 and 1.0 (inclusive). Values outside this range are allowed and can be used to perform extrapolation instead.


Transform3D inverse() const

Returns the inverted version of this transform. See also Basis.inverse.

Note: For this method to return correctly, the transform's basis needs to be orthonormal (see Basis.orthonormalized). That means, the basis should only represent a rotation. If it does not, use affine_inverse instead.


bool is_equal_approx(xform: Transform3D) const

Returns true if this transform and xform are approximately equal, by running @GlobalScope.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(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) const

Returns a copy of this transform rotated so 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 a copy of this transform with its basis orthonormalized. An orthonormal basis is both orthogonal (the axes are perpendicular to each other) and normalized (the axes have a length of 1), which also means it can only represent rotation. See also Basis.orthonormalized.


Transform3D rotated(axis: Vector3, angle: float) const

Returns a copy of this 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(axis: Vector3, angle: float) const

Returns a copy of this 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(scale: Vector3) const

Returns a copy of this 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(scale: Vector3) const

Returns a copy of this 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(offset: Vector3) const

Returns a copy of this 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(offset: Vector3) const

Returns a copy of this 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 !=(right: Transform3D)

Returns true if the components of both transforms are not equal.

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


AABB operator *(right: AABB)

Transforms (multiplies) the AABB by this transformation matrix.


PackedVector3Array operator *(right: PackedVector3Array)

Transforms (multiplies) every Vector3 element of the given PackedVector3Array by this transformation matrix.

On larger arrays, this operation is much faster than transforming each Vector3 individually.


Plane operator *(right: Plane)

Transforms (multiplies) the Plane by this transformation matrix.


Transform3D operator *(right: Transform3D)

Transforms (multiplies) this transform by the right transform.

This is the operation performed between parent and child Node3Ds.

Note: If you need to only modify one attribute of this transform, consider using one of the following methods, instead:


Vector3 operator *(right: Vector3)

Transforms (multiplies) the Vector3 by this transformation matrix.


Transform3D operator *(right: float)

Multiplies all components of the Transform3D by the given float, including the origin. This affects the transform's scale uniformly, scaling the basis.


Transform3D operator *(right: int)

Multiplies all components of the Transform3D by the given int, including the origin. This affects the transform's scale uniformly, scaling the basis.


Transform3D operator /(right: float)

Divides all components of the Transform3D by the given float, including the origin. This affects the transform's scale uniformly, scaling the basis.


Transform3D operator /(right: int)

Divides all components of the Transform3D by the given int, including the origin. This affects the transform's scale uniformly, scaling the basis.


bool operator ==(right: Transform3D)

Returns true if the components of both transforms are exactly equal.

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


User-contributed notes

Please read the User-contributed notes policy before submitting a comment.