Table of Contents

Class Transform3D

A 3×4 matrix representing a 3D transformation.

Transform3D

Remarks

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 3D asset direction conventions tutorial.

See Also

Math documentation index
Matrices and transforms
Using 3D transforms
Matrix Transform Demo
3D Platformer Demo
2.5D Game Demo

Constructors

Transform3D

Constructs a Transform3D identical to IDENTITY.

Note: In C#, this constructs a Transform3D with its origin and the components of its basis set to ZERO.

Transform3D Transform3D

Transform3D(Transform3D)

Constructs a Transform3D as a copy of the given Transform3D.

Transform3D Transform3D(Transform3D from)

Parameters

from Transform3D

Transform3D(Basis, Vector3)

Constructs a Transform3D from a Basis and Vector3.

Transform3D Transform3D(Basis basis, Vector3 origin)

Parameters

basis Basis
origin Vector3

Transform3D(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(Projection from)

Parameters

from Projection

Transform3D(Vector3, Vector3, Vector3, Vector3)

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

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

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

Parameters

x_axis Vector3
y_axis Vector3
z_axis Vector3
origin Vector3

Fields

IDENTITY

The identity Transform3D. This is a transform with no translation, no rotation, and a scale of ONE. Its basis is equal to IDENTITY. This also means that:

  • Its x points right (RIGHT);

  • Its y points up (UP);

  • Its z points back (BACK).

var transform = Transform3D.IDENTITY
var basis = transform.basis
print("| X | Y | Z | Origin")
print("| %.f | %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x, transform.origin.x])
print("| %.f | %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y, transform.origin.y])
print("| %.f | %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z, transform.origin.z])
# Prints:
# | X | Y | Z | Origin
# | 1 | 0 | 0 | 0
# | 0 | 1 | 0 | 0
# | 0 | 0 | 1 | 0

If a Vector3, an AABB, a Plane, a PackedVector3Array, or another Transform3D is transformed (multiplied) by this constant, no transformation occurs.

Note: In GDScript, this constant is equivalent to creating a Transform3D without any arguments. It can be used to make your code clearer, and for consistency with C#.

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

FLIP_X

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

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

FLIP_Y

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

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

FLIP_Z

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

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

Properties

basis

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

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

Property Value

Basis

origin

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

var origin : Vector3 = Vector3(0, 0, 0)

Property Value

Vector3

Methods

affine_inverse

Qualifiers: 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 inverse.

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

Transform3D affine_inverse

interpolate_with(Transform3D, float)

Qualifiers: 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 interpolate_with(Transform3D xform, float weight)

Parameters

xform Transform3D
weight float

inverse

Qualifiers: const

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

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

Transform3D inverse

is_equal_approx(Transform3D)

Qualifiers: const

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

bool is_equal_approx(Transform3D xform)

Parameters

xform Transform3D

is_finite

Qualifiers: const

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

bool is_finite

looking_at(Vector3, Vector3, bool)

Qualifiers: 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 looking_at(Vector3 target, Vector3 up, bool use_model_front)

Parameters

target Vector3
up Vector3
use_model_front bool

orthonormalized

Qualifiers: 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.0), which also means it can only represent a rotation. See also orthonormalized.

Transform3D orthonormalized

rotated(Vector3, float)

Qualifiers: 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 (see normalized). If angle is positive, the basis is rotated counter-clockwise around the axis.

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(Vector3 axis, float angle)

Parameters

axis Vector3
angle float

rotated_local(Vector3, float)

Qualifiers: 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 in the transform's local coordinate system. For example, to rotate around the local X-axis, use RIGHT.

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 rotated_local(Vector3 axis, float angle)

Parameters

axis Vector3
angle float

scaled(Vector3)

Qualifiers: 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(Vector3 scale)

Parameters

scale Vector3

scaled_local(Vector3)

Qualifiers: 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 scaled_local(Vector3 scale)

Parameters

scale Vector3

translated(Vector3)

Qualifiers: 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(Vector3 offset)

Parameters

offset Vector3

translated_local(Vector3)

Qualifiers: 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.

Transform3D translated_local(Vector3 offset)

Parameters

offset Vector3

Operators

!= (Transform3D)

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

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

bool != (Transform3D right)

Parameters

right Transform3D

* (AABB)

Transforms (multiplies) the AABB by this transformation matrix.

AABB * (AABB right)

Parameters

right AABB

* (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.

PackedVector3Array * (PackedVector3Array right)

Parameters

right PackedVector3Array

* (Plane)

Transforms (multiplies) the Plane by this transformation matrix.

Plane * (Plane right)

Parameters

right Plane

* (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:

  • For translation, see Transform3D.translated or Transform3D.translated_local.

  • For rotation, see Transform3D.rotated or Transform3D.rotated_local.

  • For scale, see Transform3D.scaled or Transform3D.scaled_local.

Transform3D * (Transform3D right)

Parameters

right Transform3D

* (Vector3)

Transforms (multiplies) the Vector3 by this transformation matrix.

Vector3 * (Vector3 right)

Parameters

right Vector3

* (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 * (float right)

Parameters

right float

* (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 * (int right)

Parameters

right int

/ (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 / (float right)

Parameters

right float

/ (int)

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

Transform3D / (int right)

Parameters

right int

== (Transform3D)

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

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

bool == (Transform3D right)

Parameters

right Transform3D