Basis

Una matrice 3×3 per rappresentare la rotazione e la scala 3D.

Descrizione

Il tipo di Variant integrato Basis è una matrice 3×3 utilizzata per rappresentare rotazione, scala e deformazione. Viene spesso utilizzato all'interno di un Transform3D.

Una base è composta da 3 vettori di assi, ciascuno dei quali rappresenta una colonna della matrice: x, y e z. La lunghezza di ciascun asse (Vector3.length()) influenza la scala della base, mentre la direzione di tutti gli assi influenza la rotazione. Di solito questi assi sono perpendicolari tra loro. Tuttavia, quando si ruota un asse individualmente, la base diventa inclinata. L'applicazione di una base inclinata a un modello 3D farà apparire il modello distorto.

Una base è:

Ortogonale se i suoi assi sono perpendicolari tra loro.
Normalizzata se la lunghezza di ogni asse è 1.0.
Uniforme se tutti gli assi condividono la stessa lunghezza (vedi get_scale()).
Ortonormale se è sia ortogonale che normalizzata, il che le consente di rappresentare solo rotazioni. (vedi orthonormalized()).
Conforme se è sia ortogonale che uniforme, il che garantisce che non sia distorta.

Per un'introduzione generale, consulta il tutorial Matrici e trasformazioni.

Nota: Godot utilizza un sistema di coordinate destrorso, che è uno standard comune. Per le direzioni, la convenzione per i tipi integrati come Camera3D prevede che -Z punti in avanti (+X è destra, +Y è su e +Z è indietro). Altri oggetti possono utilizzare convenzioni di direzione diverse. Per ulteriori informazioni, consulta il tutorial Convenzioni sulla direzione delle risorse 3D.

Nota: Le matrici di base sono esposte come ordine di colonna prima, che è lo stesso di OpenGL. Tuttavia, sono memorizzati internamente in ordine di riga prima, che è lo stesso di DirectX.

Nota

Ci sono differenze sostanziali quando si usa questa API con C#. Vedi Differenze dell'API C# rispetto a GDScript per maggiori informazioni.

Tutorial

Proprietà

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

Costruttori

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)

Metodi

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
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

Operatori

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)

Costanti

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

La Basis di identità. Questa è una base senza rotazione, senza inclinazione e con una scala pari a Vector3.ONE. Ciò significa anche che:

La x punta a destra (Vector3.RIGHT);
La y punta in alto (Vector3.UP);
La z punta indietro (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])
# Stampa:
# | X | Y | Z
# | 1 | 0 | 0
# | 0 | 1 | 0
# | 0 | 0 | 1

Se un Vector3 o un altra Basis viene trasformata (moltiplicata) per questa costante, non si verifica alcuna trasformazione.

Nota: In GDScript, questa costante è identica alla creazione di una Basis senza parametri. Questa costante può essere usata per rendere il codice più chiaro e per coerenza con C#.

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

Quando qualsiasi base è moltiplicata per FLIP_X, nega tutti i componenti dell'asse x (la colonna X).

Quando FLIP_X è moltiplicata per qualsiasi base, nega il componente Vector3.x di tutti gli assi (la riga X).

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

Quando qualsiasi base è moltiplicata per FLIP_Y, nega tutti i componenti dell'asse y (la colonna Y).

Quando FLIP_Y è moltiplicata per qualsiasi base, nega il componente Vector3.y di tutti gli assi (la riga Y).

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

Quando qualsiasi base è moltiplicata per FLIP_Z, nega tutti i componenti dell'asse z (la colonna Z).

Quando FLIP_Z è moltiplicata per qualsiasi base, nega il componente Vector3.z di tutti gli assi (la riga Z).

Descrizioni delle proprietà

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

L'asse X della base e la colonna 0 della matrice.

Sulla base di identità, questo vettore punta a destra (Vector3.RIGHT).

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

L'asse Y della base e la colonna 1 della matrice.

Sulla base di identità, questo vettore punta in alto (Vector3.UP).

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

L'asse Z della base e la colonna 2 della matrice.

Sulla base di identità, questo vettore punta indietro (Vector3.BACK).

Descrizioni dei costruttori

Basis Basis() 🔗

Costruisce una Basis identica a IDENTITY.

Nota: In C#, costruisce una Basis con tutti i suoi componenti impostati su Vector3.ZERO.

Basis Basis(from: Basis)

Costruisce un Basis come copia del Basis specificato.

Basis Basis(axis: Vector3, angle: float)

Costruisce un Basis che rappresenta solo la rotazione, ruotato intorno all'asse axis per l'angolo angle, in radianti. L'asse deve essere un vettore normalizzato.

Nota: Questo è lo stesso di usare rotated() sulla base IDENTITY. Con più di un angolo considera usare from_euler(), invece.

Basis Basis(from: Quaternion)

Costruisce un Basis che rappresenta solo la rotazione dal Quaternion specificato.

Nota: I quaternioni memorizzano solo la rotazione, non la scala. Per questo motivo, le conversioni da Basis a Quaternion non possono essere sempre invertite.

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

Costruisce un Basis da 3 vettori assi. Queste sono le colonne della matrice base.

Descrizioni dei metodi

float determinant() 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 3.

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

Costruisce una nuova Basis che rappresenta solo la rotazione dal Vector3 fornito di angoli di Eulero, in radianti.

Il Vector3.x dovrebbe contenere l'angolo attorno all'asse x (beccheggio).
Il Vector3.y dovrebbe contenere l'angolo attorno all'asse y (imbardata).
Il Vector3.z dovrebbe contenere l'angolo attorno all'asse z (rollio).

# Crea una base il cui asse z punta verso il basso.
var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))

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

// Crea una base il cui asse z punta verso il basso.
var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f));

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

L'ordine di ogni rotazione consecutiva si essere cambiare con order (vedi le costanti di EulerOrder). Come predefinito, è usata la convenzione YXZ (@GlobalScope.EULER_ORDER_YXZ): la base ruota prima attorno all'asse Y (imbardata), poi X (beccheggio) e infine Z (rollio). Quando si utilizza il metodo opposto get_euler(), questo ordine è invertito.

Basis from_scale(scale: Vector3) static 🔗

Costruisce una nuova Basis che rappresenta solo la scala, senza rotazione o inclinazione, dal vettore scale specificato.

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

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

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

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

Nota: Nell'algebra lineare, la matrice di questa base è anche conosciuta come matrice diagonale.

Vector3 get_euler(order: int = 2) const 🔗

Restituisce la rotazione di questa base come un Vector3 di angoli di Eulero, in radianti. Per il valore restituito:

Vector3.x contiene l'angolo attorno all'asse x (beccheggio);
Vector3.y contiene l'angolo attorno all'asse y (imbardata);
Vector3.z contiene l'angolo attorno all'asse z (rollio).

L'ordine di ogni rotazione consecutiva può essere modificato con order (vedi le costanti di EulerOrder). Come predefinito, è usata la convenzione YXZ (@GlobalScope.EULER_ORDER_YXZ): viene calcolato prima Z (rollio), poi X (beccheggio) e infine Y (imbardata). Quando si utilizza il metodo opposto from_euler(), questo ordine viene invertito.

Nota: Affinché questo metodo restituisca correttamente, la base deve essere ortonormale (vedi orthonormalized()).

Nota: Gli angoli di Eulero sono molto più intuitivi ma non sono adatti per la matematica 3D. Per questo motivo, considera invece usare il metodo get_rotation_quaternion(), che restituisce un Quaternion.

Nota: Nel pannello dell'Ispettore, la rotazione di una base è spesso visualizzata in angoli di Eulero (in gradi), come nel caso della proprietà Node3D.rotation.

Quaternion get_rotation_quaternion() const 🔗

Restituisce la rotazione di questa base come Quaternion.

Nota: I quaternioni sono molto più adatti alla matematica 3D ma sono meno intuitivi. Per le interfacce utente, considera l'utilizzo del metodo get_euler(), che restituisce angoli di Eulero.

Vector3 get_scale() const 🔗

Restituisce la lunghezza di ogni asse di questa base, come Vector3. Se la base non è inclinata, questo è il fattore di scala. Non è influenzato dalla rotazione.

var my_basis = Basis(
    Vector3(2, 0, 0),
    Vector3(0, 4, 0),
    Vector3(0, 0, 8)
)
# Ruotando la base in qualsiasi modo conserva la sua scala.
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)
);
// Ruotando la base in qualsiasi modo conserva la sua scala.
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)

Nota: Se il valore restituito da determinant() è negativo, anche la scala è negativa.

Basis inverse() const 🔗

Restituisce l'inverso della matrice di questa base.

bool is_conformal() const 🔗

Restituisce true se questa base è conforme. Una base conforme è sia ortogonale (gli assi sono perpendicolari tra loro) sia uniforme (gli assi condividono la stessa lunghezza). Questo metodo può essere particolarmente utile durante i calcoli di fisica.

bool is_equal_approx(b: Basis) const 🔗

Restituisce true se questa base e b sono approssimativamente eguali, chiamando @GlobalScope.is_equal_approx() su tutti i componenti vettoriali.

bool is_finite() const 🔗

Restituisce true se i valori di questa base sono finiti, chiamando Vector2.is_finite() su tutti i componenti vettoriali.

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

Crea una nuova Basis con una rotazione tale che l'asse in avanti (-Z) punti verso la posizione target.

Come predefinito, l'asse -Z (avanti per la telecamera) viene trattato come "in avanti" (implica che +X sia a destra). Se use_model_front è true, l'asse +Z (avanti per gli asset) viene trattato come "in avanti" (implica che +X sia a sinistra) e punta verso la posizione target.

L'asse in alto (+Y) punta il più vicino possibile al vettore up pur rimanendo perpendicolare all'asse in avanti. La base restituita è ortonormalizzata (vedi orthonormalized()).

I vettori target e up non possono essere Vector3.ZERO e non dovrebbero essere collineari per evitare una rotazione involontaria attorno all'asse Z locale.

Basis orthonormalized() const 🔗

Restituisce la versione ortonormalizzata di questa base. Una base ortonormale è sia ortogonale (gli assi sono perpendicolari tra loro) sia normalizzata (gli assi hanno una lunghezza di 1.0), il che significa inoltre che può rappresentare solo la rotazione.

Spesso è utile chiamare questo metodo per evitare errori di arrotondamento su una base in rotazione:

# Ruota questo Node3D ogni frame.
func _process(delta):
    basis = basis.rotated(Vector3.UP, TAU * delta)
    basis = basis.rotated(Vector3.RIGHT, TAU * delta)
    basis = basis.orthonormalized()

// Ruota questo Node3D ogni 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 rotated(axis: Vector3, angle: float) const 🔗

Restituisce questa base ruotata attorno all'asse axis di angle (in radianti).

axis deve essere un vettore normalizzato (vedi Vector3.normalized()). Se angle è positivo, la base viene ruotata in senso antiorario attorno all'asse.

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

my_basis = my_basis.rotated(Vector3.UP, angle)    # Ruota intorno all'asse superiore (imbardata).
my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Ruota intorno all'asse destro (beccheggio).
my_basis = my_basis.rotated(Vector3.BACK, angle)  # Ruota intorno all'asse posteriore (rollio).

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

myBasis = myBasis.Rotated(Vector3.Up, angle);    // Ruota intorno all'asse superiore (imbardata).
myBasis = myBasis.Rotated(Vector3.Right, angle); // Ruota intorno all'asse destro (beccheggio).
myBasis = myBasis.Rotated(Vector3.Back, angle);  // Ruota intorno all'asse posteriore (rollio).

Basis scaled(scale: Vector3) const 🔗

Restituisce questa base con i componenti di ciascun asse ridimensionati in base ai componenti di scale.

Le righe della matrice base sono moltiplicate per i componenti di scale. Questa operazione è una scala globale (relativa al genitore).

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) # Stampa (0.0, 2.0, -2.0)
print(my_basis.y) # Stampa (0.0, 4.0, -4.0)
print(my_basis.z) # Stampa (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); // Stampa (0, 2, -2)
GD.Print(myBasis.Y); // Stampa (0, 4, -4)
GD.Print(myBasis.Z); // Stampa (0, 6, -6)

Basis scaled_local(scale: Vector3) const 🔗

Restituisce questa base con i componenti di ciascun asse ridimensionati in base ai componenti di scale.

Le righe della matrice base sono moltiplicate per i componenti di scale. Questa operazione è una scala locale (relativa a se stesso).

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) # Stampa (0.0, 0.0, 0.0)
print(my_basis.y) # Stampa (4.0, 4.0, 4.0)
print(my_basis.z) # Stampa (-6.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); // Stampa (0, 0, 0)
GD.Print(myBasis.Y); // Stampa (4, 4, 4)
GD.Print(myBasis.Z); // Stampa (-6, -6, -6)

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

Esegue un'interpolazione sferico-lineare con la base to, dato un peso weight. Sia questa base che to dovrebbero rappresentare una rotazione.

Esempio: Ruota gradualmente un Node3D sulla base di destinazione nel corso del tempo, con un 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)

float tdotx(with: Vector3) const 🔗

Restituisce il prodotto scalare trasposto tra with e l'asse x (vedi transposed()).

Questo è equivalente a basis.x.dot(vector).

float tdoty(with: Vector3) const 🔗

Restituisce il prodotto scalare trasposto tra with e l'asse y (vedi transposed()).

Questo è equivalente a basis.y.dot(vector).

float tdotz(with: Vector3) const 🔗

Restituisce il prodotto scalare trasposto tra with e l'asse z (vedi transposed()).

Questo è equivalente a basis.z.dot(vector).

Basis transposed() const 🔗

Restituisce la versione trasposta di questa base. Ciò trasforma le colonne della matrice base in righe e le sue righe in colonne.

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) # Stampa (1.0, 4.0, 7.0).
print(my_basis.y) # Stampa (2.0, 5.0, 8.0).
print(my_basis.z) # Stampa (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); // Stampa (1, 4, 7).
GD.Print(myBasis.Y); // Stampa (2, 5, 8).
GD.Print(myBasis.Z); // Stampa (3, 6, 9).

Descrizioni degli operatori

bool operator !=(right: Basis) 🔗

Restituisce true se i componenti di entrambe le basi non sono eguali.

Note: A causa di errori di precisione per virgola mobile, considera invece utilizzare is_equal_approx(), che è più affidabile.

Basis operator *(right: Basis) 🔗

Trasforma (moltiplica) la base right per questa base.

Questa è l'operazione eseguita tra genitore e figlio Node3D.

Vector3 operator *(right: Vector3) 🔗

Trasforma (moltiplica) il vettore right per questa base, restituendo un Vector3.

# Base che scambia gli assi X/Z e raddoppia la scala.
var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2))
print(my_basis * Vector3(1, 2, 3)) # Stampa (4.0, 2.0, 6.0)

// Base che scambia gli assi X/Z e raddoppia la scala.
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)

Basis operator *(right: float) 🔗

Moltiplica tutti i componenti del Basis per il float indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

Basis operator *(right: int) 🔗

Moltiplica tutti i componenti del Basis per l'int indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

Basis operator /(right: float) 🔗

Divide tutti i componenti di Basis per il float indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

Basis operator /(right: int) 🔗

Divide tutti i componenti di Basis per il int indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

bool operator ==(right: Basis) 🔗

Restituisce true se i componenti di entrambe le basi sono esattamente eguali.

Note: A causa di errori di precisione per virgola mobile, considera invece utilizzare is_equal_approx(), che è più affidabile.

Vector3 operator [](index: int) 🔗

Accede a ciascun asse (colonna) di questa base tramite il relativo indice. L'indice 0 è uguale a x, l'indice 1 è uguale a y e l'indice 2 è uguale a z.

Nota: In C++, questo operatore accede alle righe della matrice base, non alle colonne. Per lo stesso comportamento dei linguaggi di scripting, utilizza i metodi set_column e get_column.