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¶

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.

## 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 ( Basis basis, Vector3 origin ) Transform3D Transform3D ( Projection from ) Transform3D Transform3D ( Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin )

## Methods¶

 Transform3D affine_inverse ( ) const Transform3D interpolate_with ( Transform3D xform, float weight ) const Transform3D inverse ( ) const bool is_equal_approx ( Transform3D xform ) const bool is_finite ( ) const Transform3D looking_at ( Vector3 target, Vector3 up=Vector3(0, 1, 0), bool use_model_front=false ) const Transform3D orthonormalized ( ) const Transform3D rotated ( Vector3 axis, float angle ) const Transform3D rotated_local ( Vector3 axis, float angle ) const Transform3D scaled ( Vector3 scale ) const Transform3D scaled_local ( Vector3 scale ) const Transform3D translated ( Vector3 offset ) const Transform3D translated_local ( Vector3 offset ) const

## Operators¶

 bool operator != ( Transform3D right ) AABB operator * ( AABB right ) PackedVector3Array operator * ( PackedVector3Array right ) Plane operator * ( Plane right ) Transform3D operator * ( Transform3D right ) Vector3 operator * ( Vector3 right ) Transform3D operator * ( float right ) Transform3D operator * ( int right ) bool operator == ( Transform3D right )

## 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 ( 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. 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 ( Vector3 x_axis, Vector3 y_axis, Vector3 z_axis, Vector3 origin )

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

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 ( 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 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 ( Vector3 axis, float angle ) 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 ( Vector3 axis, float angle ) 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 ( Vector3 scale ) 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 ( Vector3 scale ) 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 ( Vector3 offset ) 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 ( Vector3 offset ) 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 != ( Transform3D right )

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

Transforms (multiplies) the AABB by this transformation matrix.

PackedVector3Array operator * ( PackedVector3Array right )

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

Transforms (multiplies) the Plane by this transformation matrix.

Transform3D operator * ( Transform3D right )

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

Transforms (multiplies) the Vector3 by this transformation matrix.

Transform3D operator * ( float right )

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

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

bool operator == ( Transform3D right )

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.