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 的差异。

教程

• 3Blue1Brown 关于四元数的视频

• 在线四元数可视化

• 使用 3D 变换

• 第三人称射击（TPS）演示

• 高级四元数可视化

属性

构造函数

方法

运算符

常量

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

单位四元数，代表无旋转。这与 Basis.IDENTITY 具有相同的旋转。

如果一个 Vector3 被该四元数旋转（乘以），则它不会改变。

属性说明

float w = 1.0 🔗

四元数的 W 分量。这是“实数”的部分。

注意：四元数分量通常不应被直接操作。

float x = 0.0 🔗

四元数的 X 分量。这是沿“虚数” i 轴的值。

注意：四元数分量通常不应被直接操作。

float y = 0.0 🔗

四元数的 Y 分量。这是沿“虚数” j 轴的值。

注意：四元数分量通常不应被直接操作。

float z = 0.0 🔗

四元数的 Z 分量。这是沿“虚数” k 轴的值。

注意：四元数分量通常不应被直接操作。

构造函数说明

Quaternion Quaternion() 🔗

构造一个与 IDENTITY 相同的 Quaternion。

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

float get_angle() const 🔗

返回该四元数表示的旋转角度。

注意：该四元数必须被归一化。

Vector3 get_axis() const 🔗

返回该四元数表示的旋转的旋转轴。

Vector3 get_euler(order: int = 2) const 🔗

返回该四元数的旋转作为欧拉角弧度角的 Vector3。

每个连续旋转的顺序可以使用 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。

bool is_finite() const 🔗

如果该四元数是有限的，则返回 true，判断方法是在每个分量上调用 @GlobalScope.is_finite。

bool is_normalized() const 🔗

如果该四元数已被归一化，则返回 true。另见 normalized。

float length() const 🔗

返回该四元数的长度，也被称为幅度。

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 相同。这个操作得到的是代表相同旋转的四元数。