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...
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 选项编译引擎。
Note
通过 C# 使用该 API 时会有显著不同，详见 C# API differences to 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 相同。这个操作得到的是代表相同旋转的四元数。