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.

Checking the stable version of the documentation...

Basis

Матриця 3×3 для представлення тривимірного обертання та масштабу.

Опис

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

Note: In a boolean context, a basis will evaluate to false if it's equal to IDENTITY. Otherwise, a basis will always evaluate to true.

Примітка

Існують значні відмінності при використанні цього API із С#. Більше інформації: ref:doc_c_sharp_differences.

Посібники

Властивості

Vector3	x	`Vector3(1, 0, 0)`
Vector3	y	`Vector3(0, 1, 0)`
Vector3	z	`Vector3(0, 0, 1)`

Конструктори

Basis	Basis()
Basis	Basis(from: Basis)
Basis	Basis(axis: Vector3, angle: float)
Basis	Basis(from: Quaternion)
Basis	Basis(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3)

Методи

float	determinant() const
Basis	from_euler(euler: Vector3, order: int = 2) static
Basis	from_scale(scale: Vector3) static
Vector3	get_euler(order: int = 2) const
Quaternion	get_rotation_quaternion() const
Vector3	get_scale() const
Basis	inverse() const
bool	is_conformal() const
bool	is_equal_approx(b: Basis) const
bool	is_finite() const
bool	is_orthonormal() const
Basis	looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) static
Basis	orthonormalized() const
Basis	rotated(axis: Vector3, angle: float) const
Basis	scaled(scale: Vector3) const
Basis	scaled_local(scale: Vector3) const
Basis	slerp(to: Basis, weight: float) const
float	tdotx(with: Vector3) const
float	tdoty(with: Vector3) const
float	tdotz(with: Vector3) const
Basis	transposed() const

Оператори

bool	operator !=(right: Basis)
Basis	operator *(right: Basis)
Vector3	operator *(right: Vector3)
Basis	operator *(right: float)
Basis	operator *(right: int)
Basis	operator /(right: float)
Basis	operator /(right: int)
bool	operator ==(right: Basis)
Vector3	operator [](index: int)

Константи

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

Ідентичність Основа. Це ортонормований базис без обертання, без зсуву та масштабом Vector3.ONE. Це також означає, що:

x вказує праворуч (Vector3.RIGHT);
y вказує вгору (Vector3.UP);
z вказує назад (Vector3.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])
# Відбитки:
# | X | Y | Z
# | 1 | 0 | 0
# | 0 | 1 | 0
# | 0 | 0 | 1

Якщо Vector3 або інший Basis трансформується (помножується) на цю константу, перетворення не відбувається.

Примітка: у GDScript ця константа еквівалентна створенню основи конструктора без будь-яких аргументів. Його можна використовувати, щоб зробити ваш код зрозумілішим і узгоджено з C#.

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

Коли будь-який базис множиться на FLIP_X, він заперечує всі компоненти осі x (стовпець X).

Коли FLIP_X помножити на будь-яку основу, вона заперечує компонент Vector3.x усіх осей (рядок X).

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

Коли будь-який базис множиться на FLIP_Y, він заперечує всі компоненти осі y (стовпець Y).

Коли FLIP_Y помножити на будь-яку основу, вона заперечує компонент Vector3.y усіх осей (рядка Y).

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

Коли будь-який базис множиться на FLIP_Z, він заперечує всі компоненти осі z (стовпець Z).

Коли FLIP_Z помножити на будь-яку основу, вона заперечує компонент Vector3.z усіх осей (рядок Z).

Описи властивостей

Vector3 x = Vector3(1, 0, 0) 🔗

Вісь X основи та стовпець 0 матриці.

На основі тотожності цей вектор вказує праворуч (Vector3.RIGHT).

Vector3 y = Vector3(0, 1, 0) 🔗

Вісь Y основи та стовпець 1 матриці.

На основі тотожності цей вектор вказує вгору (Vector3.UP).

Vector3 z = Vector3(0, 0, 1) 🔗

Вісь Z основи та стовпець 2 матриці.

На основі тотожності цей вектор вказує назад (Vector3.BACK).

Описи конструкторів

Basis Basis() 🔗

Створює Basis, ідентичний IDENTITY.

Примітка: у C# це створює Basis з усіма його компонентами, встановленими на Vector3.ZERO.

Basis Basis(from: Basis)

Створює Basis як копію даного Basis.

Basis Basis(axis: Vector3, angle: float)

Будує Basis, який представляє лише обертання, обертаючись навколо осі axis на заданий angle, у радіанах. Вісь має бути нормалізованим вектором.

Примітка: це те саме, що використовувати rotated() на основі IDENTITY. З більш ніж одним кутом краще використовувати from_euler().

Basis Basis(from: Quaternion)

Будує Basis, який представляє лише обертання від даного Quaternion.

Примітка: ** Кватерніони *лише* зберігають обертання, а не масштаб. Через це перетворення з **Basis на Quaternion не завжди можна скасувати.

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

Будує Basis із 3-х осьових векторів. Це стовпці базисної матриці.

Описи методів

float determinant() const 🔗

Повертає визначник матриці цієї бази. Для просунутої математики це число може бути використане для визначення декількох атрибутів:

Якщо визначник дорівнює точно 0.0, база не є оберненою (див. inverse()).
Якщо визначник є від'ємним числом, основа представляє від'ємну шкалу.

Примітка: Якщо шкала основи однакова для кожної осі, її визначник завжди дорівнює цій шкалі, піднесеної до степеня 3.

Basis from_euler(euler: Vector3, order: int = 2) static 🔗

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

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

# 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). In Godot, Euler angles always use intrinsic order. By default, the intrinsic YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): the basis rotates first around the local Y axis (yaw), then local X (pitch), and lastly local Z (roll). When using the opposite method get_euler() to decompose a rotation, this order is reversed.

Basis from_scale(scale: Vector3) static 🔗

Створює новий Basis, який представляє лише масштаб, без обертання чи зсуву, із заданого вектора scale.

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

print(my_basis.x) # Виводить (2, 0, 0).
print(my_basis.y) # Виводить (0, 4, 0).
print(my_basis.z) # Виводить (0, 0, 8).

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

GD.Print(myBasis.X); // Виводить (2, 0, 0).
GD.Print(myBasis.Y); // Виводить (0, 4, 0).
GD.Print(myBasis.Z); // Виводить (0, 0, 8).

Примітка. У лінійній алгебрі матриця цього базису також відома як діагональна матриця.

Vector3 get_euler(order: int = 2) const 🔗

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

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

The order of each consecutive rotation can be changed with order (see EulerOrder constants). In Godot, Euler angles always use intrinsic order. By default, the intrinsic YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): since we are decomposing, local Z (roll) is calculated first, then local X (pitch), and lastly local Y (yaw). When using the opposite method from_euler() to compose a rotation, 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 Node3D.rotation property.

Quaternion get_rotation_quaternion() const 🔗

Повертає обертання бази як Quaternion.

Примітка: Кватеніони набагато більше підходять для 3D-математики, але менш інтуїтивно зрозумілі. Для інтерфейсів користувача розгляньте можливість використання методу get_euler(), який повертає кути Ейлера.

Vector3 get_scale() const 🔗

Повертає довжину кожної осі базису як Vector3. Якщо основа не зрізана, це коефіцієнт масштабування. На нього не впливає обертання.

var my_basis = Basis(
     Vector3(2, 0, 0),
     Vector3(0, 4, 0),
     Vector3(0, 0, 8)
 )
 # Обертання основи будь-яким способом зберігає її масштаб.
my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)

print(my_basis.get_scale()) # Друк (2, 4, 8).

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)
 );
 // Обертання основи будь-яким способом зберігає її масштаб.
myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f);
myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f);

GD.Print(myBasis.Scale); // Виводить (2, 4, 8).

Примітка. Якщо значення, яке повертає determinant(), є негативним, шкала також є негативною.

Basis inverse() const 🔗

Повертає обернену до базисної матриці.

bool is_conformal() const 🔗

Повертає true, якщо цей базис конформний. Конформна основа є як ортогональною (осі перпендикулярні одна до одної), так і однорідною (осі мають однакову довжину). Цей метод може бути особливо корисним під час фізичних розрахунків.

bool is_equal_approx(b: Basis) const 🔗

Повертає true, якщо ця основа та b приблизно рівні, шляхом виклику @GlobalScope.is_equal_approx() для всіх компонентів вектора.

bool is_finite() const 🔗

Повертає true, якщо ця основа скінченна, за викликом @GlobalScope.is_finite() на всіх векторних компонентах.

bool is_orthonormal() const 🔗

Returns true if this basis is orthonormal. An orthonormal basis is both orthogonal (the axes are perpendicular to each other) and normalized (the length of every axis is 1.0). This method can be especially useful during physics calculations.

Basis looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) static 🔗

Створює нову основу з обертанням таким чином, що передня вісь (-Z) вказує на позицію target.

За замовчуванням вісь -Z (передня камера) розглядається як передня (вказує на те, що +X правильна). Якщо use_model_front має значення true, вісь +Z (фронт активу) розглядається як передня (означає, що +X ліворуч) і вказує на позицію target.

Вісь вгору (+Y) спрямована якомога ближче до вектора up, залишаючись перпендикулярною до передньої осі. Повернений базис є ортонормованим (див. orthonormalized()).

target і up не можуть бути Vector3.ZERO і не повинні бути колінеарними, щоб уникнути ненавмисного обертання навколо локальної осі Z.

Basis orthonormalized() const 🔗

Повертає ортонормовану версію цього базису. Ортонормований базис є як ортогональним (осі перпендикулярні одна до одної), так і нормованим (осі мають довжину 1), що також означає, що він може представляти лише обертання.

Часто корисно викликати цей метод, щоб уникнути помилок округлення на ротаційній основі:

# Обертайте цей Node3D кожен кадр.
func _process(delta):
    base = basis.rotated(Vector3.UP, TAU * delta)
    base = basis.rotated(Vector3.RIGHT, TAU * delta)
    base = basis.orthonormalized()

// Обертати цей Node3D кожен кадр.
public override void _Process(double delta)
{
    Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta)
            .Rotated(Vector3.Right, Mathf.Tau * (float)delta)
            .Orthonormalized();
}

Basis rotated(axis: Vector3, angle: float) const 🔗

Повертає цей базис, повернутий навколо заданої axis на angle (у радіанах). axis має бути нормалізованим вектором (див. Vector3.normalized()).

Додатні значення повертають цей базис за годинниковою стрілкою навколо осі, а від’ємні значення обертають його проти годинникової стрілки.

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

my_basis = my_basis.rotated(Vector3.UP, angle) # Обертання навколо осі вгору (yaw).
my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Обертання навколо правої осі (крок).
my_basis = my_basis.rotated(Vector3.BACK, angle) # Обертання навколо задньої осі (перекочування).

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

myBasis = myBasis.Rotated(Vector3.Up, кут); // Обертання навколо осі вгору (рискання).
myBasis = myBasis.Rotated(Vector3.Right, angle); // Поворот навколо правої осі (тангаж).
myBasis = myBasis.Rotated(Vector3.Back, angle); // Поворот навколо задньої осі (перекат).

Basis scaled(scale: Vector3) const 🔗

Повертає цю базу з компонентами кожної осі, масштабованими за заданими компонентами scale.

Рядки базової матриці множаться на компоненти scale. Ця операція має глобальний масштаб (щодо батьківської).

var my_basis = Основа(
     Vector3(1, 1, 1),Basis
     Vector3(2, 2, 2),
     Vector3(3, 3, 3)
 )
my_basis = my_basis.scaled(Vector3(0, 2, -2))

print(my_basis.x) # Виводить (0, 2, -2).
print(my_basis.y) # Виводить (0, 4, -4).
print(my_basis.z) # Виводить (0, 6, -6).

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); // Виводить (0, 2, -2).
GD.Print(myBasis.Y); // Виводить (0, 4, -4).
GD.Print(myBasis.Z); // Виводить (0, 6, -6).

Basis scaled_local(scale: Vector3) const 🔗

Повертає цей basis, при цьому кожна вісь масштабується на відповідний компонент у заданому scale.

Стовпці базисної матриці множаться на компоненти scale. Ця операція є локальним масштабуванням (відносно себе).

[gdscript]
var my_basis = Basis(
Vector3(1, 1, 1),
Vector3(2, 2, 2),
Vector3(3, 3, 3)
)
my_basis = my_basis.scaled_local(Vector3(0, 2, -2))

print(my_basis.x) # Виводить (0.0, 0.0, 0.0)
print(my_basis.y) # Виводить (4.0, 4.0, 4.0)
print(my_basis.z) # Виводить (-6.0, -6.0, -6.0)
[/gdscript]
[csharp]
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.ScaledLocal(new Vector3(0.0f, 2.0f, -2.0f));

GD.Print(myBasis.X); // Виводить (0, 0, 0)
GD.Print(myBasis.Y); // Виводить (4, 4, 4)
GD.Print(myBasis.Z); // Виводить (-6, -6, -6)
[/csharp][/codeblocks]

Basis slerp(to: Basis, weight: float) const 🔗

Виконує сферично-лінійну інтерполяцію з основою to із заданою вагою weight. І цей базис, і to мають представляти обертання.

**Приклад: ** Плавно повертайте Node3D до цільової основи з часом за допомогою 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):

base = start_basis.slerp(target_basis, weight)

.. rst-class:: classref-item-separator

float tdotx(with: Vector3) const 🔗

Повертає транспонований скалярний добуток між with і віссю x (див. transponed()).

Це еквівалентно basis.x.dot(vector).

float tdoty(with: Vector3) const 🔗

Повертає транспонований скалярний добуток між with і віссю x (див. transponed()).

Це еквівалентно basis.x.dot(вектор).

float tdotz(with: Vector3) const 🔗

Повертає транспонований скалярний добуток між with і віссю z (див. transponed()).

Це еквівалентно basis.z.dot(vector).

Basis transposed() const 🔗

Повертає транспоновану версію цієї основи. Це перетворює стовпці базової матриці на рядки, а її рядки – на стовпці.

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) # Виводить (1, 4, 7).
print(my_basis.y) # Виводить (2, 5, 8).
print(my_basis.z) # Виводить (3, 6, 9).

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); // Виводить (1, 4, 7).
GD.Print(myBasis.Y); // Виводить (2, 5, 8).
GD.Print(myBasis.Z); // Виводить (3, 6, 9).

Описи операторів

bool operator !=(right: Basis) 🔗

Повертає true, якщо компоненти обох матриць Basis не рівні.

Примітка: Через помилки точності з плаваючою комою, краще використати is_equal_approx(), який є більш надійним.

Basis operator *(right: Basis) 🔗

Перетворює (множить) основу right на цю основу.

Це операція, яка виконується між батьківським і дочірнім Node3D.

Vector3 operator *(right: Vector3) 🔗

Перетворює (множить) вектор right на цю основу, повертаючи Vector3.

[gdscript]
 # Основа, яка змінює місцями осі X/Z і подвоює масштаб.
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, 2, 6)
[/gdscript]
[csharp]
 // Основа, яка змінює місцями осі X/Z і подвоює масштаб.
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)); // Друкує (4, 2, 6)
[/csharp][/codeblocks]

Basis operator *(right: float) 🔗

Множить усі компоненти Basis на заданий float. Це рівномірно впливає на масштаб основи, змінюючи розмір усіх 3 осей на значення right.

Basis operator *(right: int) 🔗

Множить усі компоненти Basis на заданий int. Це рівномірно впливає на масштаб основи, змінюючи розмір усіх 3 осей на значення right.

Basis operator /(right: float) 🔗

Розділяє всі компоненти Basis на заданий float. Це рівномірно впливає на масштаб основи, змінюючи розмір усіх 3 осей на значення right.

Basis operator /(right: int) 🔗

Розділяє всі компоненти Basis на заданий int. Це рівномірно впливає на масштаб основи, змінюючи розмір усіх 3 осей на значення right.

bool operator ==(right: Basis) 🔗

Повертає true, якщо компоненти обох матриць Basis абсолютно рівні.

Примітка: Через помилки точності з плаваючою комою, краще використати is_equal_approx(), який є більш надійним.

Vector3 operator [](index: int) 🔗

Звертається до кожної осі (стовпця) цього базису за їхнім індексом. Індекс 0 такий самий, як x, індекс 1 такий самий, як y, а індекс 2 такий самий, як z.

Примітка: у C++ цей оператор звертається до рядків базисної матриці, а не до стовпців. Для такої самої поведінки, як і мови сценаріїв, використовуйте методи set_column і get_column.