Quaternion
代表 3D 旋转的单位四元数。
描述
Quaternion 即四元数，是一种内置的 Variant 类型，这种 4D 数据结构使用哈密顿四元数来代表旋转。Basis 类型能够同时存储旋转和缩放，而四元数只能存储旋转。
Quaternion 由 4 个浮点分量组成：w、x、y、z。这些分量在内存中非常紧凑，因此部分运算更加高效、造成的浮点数误差也更低。get_angle()、get_axis()、slerp() 等方法与 Basis 中的版本相比也更快。
四元数的入门知识请观看 3Blue1Brown 的这个视频。四元数背后的数学原理并不需要理解，因为 Godot 提供了一些辅助方法能够帮你处理相关的情况。其中包含 slerp()、spherical_cubic_interpolate() 以及 * 运算符。
注意：用于旋转前，必须将四元数归一化（见 normalized()）。
注意：与 Vector2 和 Vector3 类似，四元数的分量默认使用的是 32 位精度，而 float 则是 64 位。如果需要双精度，请使用 precision=double 选项编译引擎。
备注
通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。
教程
属性
|
||
|
||
|
||
|
构造函数
Quaternion(from: Quaternion) |
|
Quaternion(arc_from: Vector3, arc_to: Vector3) |
|
Quaternion(axis: Vector3, angle: float) |
|
Quaternion(from: Basis) |
|
Quaternion(x: float, y: float, z: float, w: float) |
方法
angle_to(to: Quaternion) const |
|
dot(with: Quaternion) const |
|
exp() const |
|
from_euler(euler: Vector3) static |
|
get_angle() const |
|
get_axis() const |
|
inverse() const |
|
is_equal_approx(to: Quaternion) const |
|
is_finite() const |
|
is_normalized() const |
|
length() const |
|
length_squared() const |
|
log() const |
|
normalized() const |
|
slerp(to: Quaternion, weight: float) const |
|
slerpni(to: Quaternion, weight: float) const |
|
spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const |
|
spherical_cubic_interpolate_in_time(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const |
运算符
operator !=(right: Quaternion) |
|
operator *(right: Quaternion) |
|
operator *(right: Vector3) |
|
operator *(right: float) |
|
operator *(right: int) |
|
operator +(right: Quaternion) |
|
operator -(right: Quaternion) |
|
operator /(right: float) |
|
operator /(right: int) |
|
operator ==(right: Quaternion) |
|
operator [](index: int) |
|
常量
IDENTITY = Quaternion(0, 0, 0, 1) 🔗
单位四元数，代表无旋转。这与 Basis.IDENTITY 具有相同的旋转。
如果一个 Vector3 被该四元数旋转（乘以），则它不会改变。
注意：在 GDScript 中，该常量等价于不带任何参数创建 Quaternion。可以用来让代码更加清晰，并且与 C# 保持一致。
属性说明
四元数的 W 分量。这是“实数”的部分。
注意：四元数分量通常不应被直接操作。
四元数的 X 分量。这是沿“虚数” i 轴的值。
注意：四元数分量通常不应被直接操作。
四元数的 Y 分量。这是沿“虚数” j 轴的值。
注意：四元数分量通常不应被直接操作。
四元数的 Z 分量。这是沿“虚数” k 轴的值。
注意：四元数分量通常不应被直接操作。
构造函数说明
Quaternion Quaternion() 🔗
构造与 IDENTITY 相同的 Quaternion。
注意：在 C# 中构造的 Quaternion 的所有分量都为 0.0。
Quaternion Quaternion(from: Quaternion)
构造给定 Quaternion 的副本。
Quaternion Quaternion(arc_from: Vector3, arc_to: Vector3)
构造一个表示 arc_from 和 arc_to 之间最短弧的 Quaternion。这些可以想象为与球体表面相交的两个点，球面半径为 1.0。
Quaternion Quaternion(axis: Vector3, angle: float)
构造一个 Quaternion，表示围绕 axis 旋转给定的 angle 弧度。该轴必须是一个归一化向量。
Quaternion Quaternion(from: Basis)
根据给定的旋转 Basis 构造一个 Quaternion。
该构造函数比 Basis.get_rotation_quaternion() 更快，但给定的基必须是正交归一化的（请参阅 Basis.orthonormalized()）。否则，构造函数将失败并返回 IDENTITY。
Quaternion Quaternion(x: float, y: float, z: float, w: float)
构造一个由给定值定义的 Quaternion。
注意：只有归一化的四元数才表示旋转；如果这些值没有归一化，则新的 Quaternion 将不是有效的旋转。
方法说明
float angle_to(to: Quaternion) const 🔗
返回这个四元数与 to 之间的角度。这是从一个旋转到另一个旋转所需的角度大小。
注意：该方法的浮点数误差异常地高，因此 is_zero_approx 等方法的结果不可靠。
float dot(with: Quaternion) const 🔗
返回该四元数与 with 的点积。
等价于 (quat.x * with.x) + (quat.y * with.y) + (quat.z * with.z) + (quat.w * with.w)。
Quaternion exp() const 🔗
返回该四元数的指数。该结果的旋转轴是该四元数的归一化旋转轴，该结果的角度是该四元数的向量部分的长度。
Quaternion from_euler(euler: Vector3) static 🔗
从给定的 欧拉角的 Vector3 弧度角构造一个新的 Quaternion。该方法始终使用 YXZ 约定（@GlobalScope.EULER_ORDER_YXZ）。
返回该四元数表示的旋转角度。
注意：该四元数必须被归一化。
返回该四元数表示的旋转的旋转轴。
Vector3 get_euler(order: int = 2) const 🔗
每个连续旋转的顺序可以使用 order 更改（请参阅 EulerOrder 常量）。默认情况下，使用 YXZ 约定（@GlobalScope.EULER_ORDER_YXZ）：首先计算 Z（翻滚），然后计算 X（俯仰），最后计算 Y（偏航）。当使用相反的方法 from_euler() 时，该顺序相反。
Quaternion inverse() const 🔗
返回该四元数的逆版本，反转除 w 之外的每个分量的符号。
bool is_equal_approx(to: Quaternion) const 🔗
如果该四元数和 to 近似相等，则返回 true，判断方法是通过对每个分量调用 @GlobalScope.is_equal_approx()。
如果该四元数是有限的，则返回 true，判断方法是在每个分量上调用 @GlobalScope.is_finite()。
如果该四元数已被归一化，则返回 true。另见 normalized()。
返回该四元数的长度，也被称为幅度。
float length_squared() const 🔗
返回该四元数的长度的平方。
注意：该方法比 length() 更快，因此如果你只需要比较四元数的长度，则优先使用它。
Quaternion log() const 🔗
返回该四元数的对数。将该四元数的旋转轴乘以它的旋转角度，并将结果存储在返回的四元数的向量部分（x、y 和 z）中。返回的四元数的实数部分（w）始终为 0.0。
Quaternion normalized() const 🔗
返回该四元数的副本，已归一化，因此其长度为 1.0。另见 is_normalized()。
Quaternion slerp(to: Quaternion, weight: float) const 🔗
使用 to 四元数，在给定 weight 下执行球面线性插值并返回结果。该四元数和 to 都必须已归一化。
Quaternion slerpni(to: Quaternion, weight: float) const 🔗
在给定 weight 的情况下，使用 to 四元数执行球面线性插值并返回结果。与 slerp() 不同，该方法不检查旋转路径是否小于 90 度。该四元数和 to 都必须是归一化的。
Quaternion spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const 🔗
在四元数 pre_a、这个向量、b 以及 post_b 之间按照给定的 weight 进行球面三次插值。
Quaternion spherical_cubic_interpolate_in_time(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const 🔗
在四元数 pre_a、该向量、b 和 post_b 之间，按给定量 weight 执行三次球面插值。
它可以根据时间值执行比 spherical_cubic_interpolate() 更平滑的插值。
运算符说明
bool operator !=(right: Quaternion) 🔗
如果两个四元数的分量不完全相等，则返回 true。
注意：由于浮点精度误差，请考虑改用 is_equal_approx()，这样更可靠。
Quaternion operator *(right: Quaternion) 🔗
组合（相乘）两个四元数。这会由该四元数（父项）旋转 right 四元数（子项）。
Vector3 operator *(right: Vector3) 🔗
由该四元数旋转（乘以） right 向量，返回一个 Vector3。
Quaternion operator *(right: float) 🔗
将该 Quaternion 的每个分量乘以右侧的 float 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator *(right: int) 🔗
将该 Quaternion 的每个分量乘以右侧 int 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator +(right: Quaternion) 🔗
将左侧 Quaternion 的每个分量添加到右侧 Quaternion。
该操作本身没有意义，但可以用作更大表达式的一部分，例如用于近似两个相邻旋转之间的中间旋转。
Quaternion operator -(right: Quaternion) 🔗
将左侧 Quaternion 的每个分量减去右侧 Quaternion。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator /(right: float) 🔗
将该 Quaternion 的每个分量除以右侧 float 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator /(right: int) 🔗
将该 Quaternion 的每个分量除以右侧的 int 值。
该操作本身没有意义，但可以用作更大表达式的一部分。
bool operator ==(right: Quaternion) 🔗
如果两个四元数的分量完全相等，则返回 true。
注意：由于浮点精度误差，请考虑改用 is_equal_approx()，这样更可靠。
float operator [](index: int) 🔗
通过索引访问该四元数的每个分量。
索引 0 与 x 相同，索引 1 与 y 相同，索引 2 与 z 相同，索引 3 与 w 相同。
Quaternion operator unary+() 🔗
返回与 + 不存在时相同的值。单目 + 没有作用，但有时可以使你的代码更具可读性。
Quaternion operator unary-() 🔗
返回该 Quaternion 的负值。这与将所有分量乘以 -1 相同。这个操作得到的是代表相同旋转的四元数。