Class Basis

A 3×3 matrix for representing 3D rotation and scale.

Basis

Remarks

The Basis built-in Variant type is a 3×3 matrix used to represent 3D rotation, scale, and shear. It is frequently used within a Transform3D.

A Basis is composed by 3 axis vectors, each representing a column of the matrix: x, y, and z. The length of each axis (length) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted.

A Basis is:

Orthogonal if its axes are perpendicular to each other.
Normalized if the length of every axis is 1.0.
Uniform if all axes share the same length (see get_scale).
Orthonormal if it is both orthogonal and normalized, which allows it to only represent rotations (see orthonormalized).
Conformal if it is both orthogonal and uniform, which ensures it is not distorted.

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.

Note: The basis matrices are exposed as column-major order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX.

Constructors

Basis

Constructs a Basis identical to IDENTITY.

Note: In C#, this constructs a Basis with all of its components set to ZERO.

Basis Basis

Basis(Basis)

Constructs a Basis as a copy of the given Basis.

Basis Basis(Basis from)

Parameters

from Basis

Basis(Vector3, float)

Constructs a Basis that only represents rotation, rotated around the axis by the given angle, in radians. The axis must be a normalized vector.

Note: This is the same as using Basis.rotated on the IDENTITY basis. With more than one angle consider using Basis.from_euler, instead.

Basis Basis(Vector3 axis, float angle)

Parameters

axis Vector3
angle float

Basis(Quaternion)

Constructs a Basis that only represents rotation from the given Quaternion.

Note: Quaternions only store rotation, not scale. Because of this, conversions from Basis to Quaternion cannot always be reversed.

Basis Basis(Quaternion from)

Parameters

from Quaternion

Basis(Vector3, Vector3, Vector3)

Constructs a Basis from 3 axis vectors. These are the columns of the basis matrix.

Basis Basis(Vector3 x_axis, Vector3 y_axis, Vector3 z_axis)

Parameters

x_axis Vector3
y_axis Vector3
z_axis Vector3

Fields

IDENTITY

The identity Basis. This is an orthonormal basis with no rotation, no shear, and a scale of ONE. This also means that:

The x points right (RIGHT);
The y points up (UP);
The z points back (BACK).

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

If a Vector3 or another Basis is transformed (multiplied) by this constant, no transformation occurs.

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

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

FLIP_X

When any basis is multiplied by FLIP_X, it negates all components of the x axis (the X column).

When FLIP_X is multiplied by any basis, it negates the x component of all axes (the X row).

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

FLIP_Y

When any basis is multiplied by FLIP_Y, it negates all components of the y axis (the Y column).

When FLIP_Y is multiplied by any basis, it negates the y component of all axes (the Y row).

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

FLIP_Z

When any basis is multiplied by FLIP_Z, it negates all components of the z axis (the Z column).

When FLIP_Z is multiplied by any basis, it negates the z component of all axes (the Z row).

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

Properties

x

The basis's X axis, and the column 0 of the matrix.

On the identity basis, this vector points right (RIGHT).

var x : Vector3 = Vector3(1, 0, 0)

Property Value

Vector3

y

The basis's Y axis, and the column 1 of the matrix.

On the identity basis, this vector points up (UP).

var y : Vector3 = Vector3(0, 1, 0)

Property Value

Vector3

z

The basis's Z axis, and the column 2 of the matrix.

On the identity basis, this vector points back (BACK).

var z : Vector3 = Vector3(0, 0, 1)

Property Value

Vector3

Methods

determinant

Qualifiers: const

Returns the determinant of this basis's matrix. For advanced math, this number can be used to determine a few attributes:

If the determinant is exactly 0.0, the basis is not invertible (see inverse).
If the determinant is a negative number, the basis represents a negative scale.

Note: If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2.

float determinant

from_euler(Vector3, int)

Qualifiers: static

Constructs a new Basis that only represents rotation from the given Vector3 of Euler angles, in radians.

The x should contain the angle around the x axis (pitch);
The y should contain the angle around the y axis (yaw);
The z should contain the angle around the z axis (roll).

gdscript
C#

# Creates a Basis whose z axis points down.
var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))

print(my_basis.z) # Prints (0.0, -1.0, 0.0)

// Creates a Basis whose z axis points down.
var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f));

GD.Print(myBasis.Z); // Prints (0, -1, 0)

The order of each consecutive rotation can be changed with order (see EulerOrder constants). By default, the YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): the basis rotates first around the Y axis (yaw), then X (pitch), and lastly Z (roll). When using the opposite method Basis.get_euler, this order is reversed.

Basis from_euler(Vector3 euler, int order)

Parameters

euler Vector3
order int

from_scale(Vector3)

Qualifiers: static

Constructs a new Basis that only represents scale, with no rotation or shear, from the given scale vector.

gdscript
C#

var my_basis = Basis.from_scale(Vector3(2, 4, 8))

print(my_basis.x) # Prints (2.0, 0.0, 0.0)
print(my_basis.y) # Prints (0.0, 4.0, 0.0)
print(my_basis.z) # Prints (0.0, 0.0, 8.0)

var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f));

GD.Print(myBasis.X); // Prints (2, 0, 0)
GD.Print(myBasis.Y); // Prints (0, 4, 0)
GD.Print(myBasis.Z); // Prints (0, 0, 8)

Note: In linear algebra, the matrix of this basis is also known as a diagonal matrix.

Basis from_scale(Vector3 scale)

Parameters

scale Vector3

get_euler(int)

Qualifiers: const

Returns this basis's rotation as a Vector3 of Euler angles, in radians. For the returned value:

The x contains the angle around the x axis (pitch);
The y contains the angle around the y axis (yaw);
The z contains the angle around the z axis (roll).

The order of each consecutive rotation can be changed with order (see EulerOrder constants). By default, the YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method Basis.from_euler, this order is reversed.

Note: For this method to return correctly, the basis needs to be orthonormal (see orthonormalized).

Note: Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the get_rotation_quaternion method instead, which returns a Quaternion.

Note: In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the rotation property.

Vector3 get_euler(int order)

Parameters

order int

get_rotation_quaternion

Qualifiers: const

Returns this basis's rotation as a Quaternion.

Note: Quaternions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the Basis.get_euler method, which returns Euler angles.

Quaternion get_rotation_quaternion

get_scale

Qualifiers: const

Returns the length of each axis of this basis, as a Vector3. If the basis is not sheared, this value is the scaling factor. It is not affected by rotation.

gdscript
C#

var my_basis = Basis(
    Vector3(2, 0, 0),
    Vector3(0, 4, 0),
    Vector3(0, 0, 8)
)
# Rotating the Basis in any way preserves its scale.
my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)

print(my_basis.get_scale()) # Prints (2.0, 4.0, 8.0)

var myBasis = new Basis(
    Vector3(2.0f, 0.0f, 0.0f),
    Vector3(0.0f, 4.0f, 0.0f),
    Vector3(0.0f, 0.0f, 8.0f)
);
// Rotating the Basis in any way preserves its scale.
myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f);
myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f);

GD.Print(myBasis.Scale); // Prints (2, 4, 8)

Note: If the value returned by determinant is negative, the scale is also negative.

Vector3 get_scale

inverse

Qualifiers: const

Returns the inverse of this basis's matrix.

Basis inverse

is_conformal

Qualifiers: const

Returns true if this basis is conformal. A conformal basis is both orthogonal (the axes are perpendicular to each other) and uniform (the axes share the same length). This method can be especially useful during physics calculations.

bool is_conformal

is_equal_approx(Basis)

Qualifiers: const

Returns true if this basis and b are approximately equal, by calling @GlobalScope.is_equal_approx on all vector components.

bool is_equal_approx(Basis b)

Parameters

b Basis

is_finite

Qualifiers: const

Returns true if this basis is finite, by calling @GlobalScope.is_finite on all vector components.

bool is_finite

looking_at(Vector3, Vector3, bool)

Qualifiers: static

Creates a new Basis with a rotation such that the forward axis (-Z) points towards the target position.

By default, the -Z axis (camera forward) is treated as forward (implies +X is right). 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.

The up axis (+Y) points as close to the up vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see orthonormalized).

The target and the up cannot be ZERO, and shouldn't be colinear to avoid unintended rotation around local Z axis.

Basis looking_at(Vector3 target, Vector3 up, bool use_model_front)

Parameters

target Vector3
up Vector3
use_model_front bool

orthonormalized

Qualifiers: const

Returns the orthonormalized version of this basis. 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.

It is often useful to call this method to avoid rounding errors on a rotating basis:

gdscript
C#

# Rotate this Node3D every frame.
func _process(delta):
    basis = basis.rotated(Vector3.UP, TAU * delta)
    basis = basis.rotated(Vector3.RIGHT, TAU * delta)

    basis = basis.orthonormalized()

// Rotate this Node3D every frame.
public override void _Process(double delta)
{
    Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta)
                 .Rotated(Vector3.Right, Mathf.Tau * (float)delta)
                 .Orthonormalized();

}

Basis orthonormalized

rotated(Vector3, float)

Qualifiers: const

Returns a copy of this basis 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.

gdscript
C#

var my_basis = Basis.IDENTITY
var angle = TAU / 2

my_basis = my_basis.rotated(Vector3.UP, angle)    # Rotate around the up axis (yaw).
my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch).
my_basis = my_basis.rotated(Vector3.BACK, angle)  # Rotate around the back axis (roll).

var myBasis = Basis.Identity;
var angle = Mathf.Tau / 2.0f;

myBasis = myBasis.Rotated(Vector3.Up, angle);    // Rotate around the up axis (yaw).
myBasis = myBasis.Rotated(Vector3.Right, angle); // Rotate around the right axis (pitch).
myBasis = myBasis.Rotated(Vector3.Back, angle);  // Rotate around the back axis (roll).

Basis rotated(Vector3 axis, float angle)

Parameters

axis Vector3
angle float

scaled(Vector3)

Qualifiers: const

Returns this basis with each axis's components scaled by the given scale's components.

The basis matrix's rows are multiplied by scale's components. This operation is a global scale (relative to the parent).

gdscript
C#

var my_basis = Basis(
    Vector3(1, 1, 1),
    Vector3(2, 2, 2),
    Vector3(3, 3, 3)
)
my_basis = my_basis.scaled(Vector3(0, 2, -2))

print(my_basis.x) # Prints (0.0, 2.0, -2.0)
print(my_basis.y) # Prints (0.0, 4.0, -4.0)
print(my_basis.z) # Prints (0.0, 6.0, -6.0)

var myBasis = new Basis(
    new Vector3(1.0f, 1.0f, 1.0f),
    new Vector3(2.0f, 2.0f, 2.0f),
    new Vector3(3.0f, 3.0f, 3.0f)
);
myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f));

GD.Print(myBasis.X); // Prints (0, 2, -2)
GD.Print(myBasis.Y); // Prints (0, 4, -4)
GD.Print(myBasis.Z); // Prints (0, 6, -6)

Basis scaled(Vector3 scale)

Parameters

scale Vector3

slerp(Basis, float)

Qualifiers: const

Performs a spherical-linear interpolation with the to basis, given a weight. Both this basis and to should represent a rotation.

Example: Smoothly rotate a Node3D to the target basis over time, with a Tween:

var start_basis = Basis.IDENTITY
var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2)

func _ready():
    create_tween().tween_method(interpolate, 0.0, 1.0, 5.0).set_trans(Tween.TRANS_EXPO)

func interpolate(weight):
    basis = start_basis.slerp(target_basis, weight)

Basis slerp(Basis to, float weight)

Parameters

to Basis
weight float

tdotx(Vector3)

Qualifiers: const

Returns the transposed dot product between with and the x axis (see transposed).

This is equivalent to basis.x.dot(vector).

float tdotx(Vector3 with)

Parameters

with Vector3

tdoty(Vector3)

Qualifiers: const

Returns the transposed dot product between with and the y axis (see transposed).

This is equivalent to basis.y.dot(vector).

float tdoty(Vector3 with)

Parameters

with Vector3

tdotz(Vector3)

Qualifiers: const

Returns the transposed dot product between with and the z axis (see transposed).

This is equivalent to basis.z.dot(vector).

float tdotz(Vector3 with)

Parameters

with Vector3

transposed

Qualifiers: const

Returns the transposed version of this basis. This turns the basis matrix's columns into rows, and its rows into columns.

gdscript
C#

var my_basis = Basis(
    Vector3(1, 2, 3),
    Vector3(4, 5, 6),
    Vector3(7, 8, 9)
)
my_basis = my_basis.transposed()

print(my_basis.x) # Prints (1.0, 4.0, 7.0)
print(my_basis.y) # Prints (2.0, 5.0, 8.0)
print(my_basis.z) # Prints (3.0, 6.0, 9.0)

var myBasis = new Basis(
    new Vector3(1.0f, 2.0f, 3.0f),
    new Vector3(4.0f, 5.0f, 6.0f),
    new Vector3(7.0f, 8.0f, 9.0f)
);
myBasis = myBasis.Transposed();

GD.Print(myBasis.X); // Prints (1, 4, 7)
GD.Print(myBasis.Y); // Prints (2, 5, 8)
GD.Print(myBasis.Z); // Prints (3, 6, 9)

Basis transposed

Operators

!= (Basis)

Returns true if the components of both Basis matrices are not equal.

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

bool != (Basis right)

Parameters

right Basis

* (Basis)

Transforms (multiplies) the right basis by this basis.

This is the operation performed between parent and child Node3Ds.

Basis * (Basis right)

Parameters

right Basis

* (Vector3)

Transforms (multiplies) the right vector by this basis, returning a Vector3.

gdscript
C#

# Basis that swaps the X/Z axes and doubles the scale.
var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2))
print(my_basis * Vector3(1, 2, 3)) # Prints (4.0, 2.0, 6.0)

// Basis that swaps the X/Z axes and doubles the scale.
var myBasis = new Basis(new Vector3(0, 2, 0), new Vector3(2, 0, 0), new Vector3(0, 0, 2));
GD.Print(myBasis * new Vector3(1, 2, 3)); // Prints (4, 2, 6)

Vector3 * (Vector3 right)

Parameters

right Vector3

* (float)

Multiplies all components of the Basis by the given float. This affects the basis's scale uniformly, resizing all 3 axes by the right value.

Basis * (float right)

Parameters

right float

* (int)

Multiplies all components of the Basis by the given int. This affects the basis's scale uniformly, resizing all 3 axes by the right value.

Basis * (int right)

Parameters

right int

/ (float)

Divides all components of the Basis by the given float. This affects the basis's scale uniformly, resizing all 3 axes by the right value.

Basis / (float right)

Parameters

right float

/ (int)

Divides all components of the Basis by the given int. This affects the basis's scale uniformly, resizing all 3 axes by the right value.

Basis / (int right)

Parameters

right int

== (Basis)

Returns true if the components of both Basis matrices are exactly equal.

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

bool == (Basis right)

Parameters

right Basis

[] (int)

Accesses each axis (column) of this basis by their index. Index 0 is the same as x, index 1 is the same as y, and index 2 is the same as z.

Note: In C++, this operator accesses the rows of the basis matrix, not the columns. For the same behavior as scripting languages, use the set_column and get_column methods.

Vector3 [] (int index)

Parameters

index int

Table of Contents

Class Basis

Remarks

See Also

Constructors

Basis

Basis(Basis)

Parameters

Basis(Vector3, float)

Parameters

Basis(Quaternion)

Parameters

Basis(Vector3, Vector3, Vector3)

Parameters

Fields

IDENTITY

FLIP_X

FLIP_Y

FLIP_Z

Properties

x

Property Value

y

Property Value

z

Property Value

Methods

determinant

from_euler(Vector3, int)

Parameters

from_scale(Vector3)

Parameters

get_euler(int)

Parameters

get_rotation_quaternion

get_scale

inverse

is_conformal

is_equal_approx(Basis)

Parameters

is_finite

looking_at(Vector3, Vector3, bool)

Parameters

orthonormalized

rotated(Vector3, float)

Parameters

scaled(Vector3)

Parameters

slerp(Basis, float)

Parameters

tdotx(Vector3)

Parameters

tdoty(Vector3)

Parameters

tdotz(Vector3)

Parameters

transposed

Operators

!= (Basis)

Parameters

* (Basis)

Parameters

* (Vector3)

Parameters

* (float)

Parameters

* (int)

Parameters

/ (float)

Parameters

/ (int)

Parameters

== (Basis)

Parameters

[] (int)

Parameters