quaternion

quaternion 是 Luna-Flow 的 Hamilton 四元数 $\mathbb H$ 库：四元数是形如 $w + xi + yj + zk$、满足 $i^2 = j^2 = k^2 = ijk = -1$ 的四维数系。单位四元数描述三维旋转，没有欧拉角的奇异性，并且复合、求逆与插值的代价都很低。本库提供一个泛型类型 Quaternion[T]，支持环运算、右除与左除、范数、向量旋转、球面插值以及欧拉角转换。

包

模块 Luna-Flow/quaternion 只有一个位于源码根目录 src 的包，文档中称为 core：

包	导入路径	内容	页面
core	Luna-Flow/quaternion	Quaternion[T]、其算术与旋转函数、DoubleConvert trait	API · 教程 · 设计

源码为 src/quaternion.mbt（类型及全部运算）、src/double_conv.mbt（DoubleConvert）与 src/extends.mbt（哪些 trait 方法可以作为方法调用）。生成的接口文件 src/pkg.generated.mbti 列出了所有公开签名。

概览

• Quaternion[T] 对其分量类型是泛型的。环运算可在 Int 等精确类型上进行；需要平方根或三角函数的函数经由 DoubleConvert 在 Double 中计算，该 trait 为 Int 与 Double 实现。
• +、-、一元 - 与 *（Hamilton 积）是常规运算。* 不可交换。
• q / r 是右除 $q\,r^{-1}$；q.left_div(r) 是左除 $r^{-1} q$。0.2.0 之前，/ 计算的是 $r^{-1} q$。
• 该类型实现了 luna-generic 的 Zero、One、AddMonoid、MulMonoid、Semiring、Ring、Inverse 与 Conjugate。由于乘法不可交换，它不实现 Field。
• 旋转：from_axis_angle、from_euler、Quaternion::rotate、slerp、Quaternion::to_euler 及其八个固定顺序的变体。

从哪里开始

• 初识四元数： 从快速入门读到“比较两个旋转”为止的教程。除了向量与角度，不需要其他数学知识。
• 使用本库： API 参考列出了每个函数的精确签名、约定、边界情况与已知问题。转换角度前请先查看其中的欧拉角约定。
• 贡献或审阅： 设计页面从 Hamilton 关系出发推导 Hamilton 积、旋转公式、除法、slerp 与欧拉角提取，解释每个设计决策，并列出实现目前与数学存在偏差之处。

安装与工具链

本库需要 moonc 0.10 或更高版本的 MoonBit，并依赖 Luna-Flow/luna-generic 0.3.3。用下面的命令把它加入模块：

moon add Luna-Flow/quaternion@0.2.0

然后在使用它的包的 moon.pkg 中导入 "Luna-Flow/quaternion"。代码与目标平台无关，并在 wasm、wasm-gc、js 与 native 后端上测试。

验证

在仓库根目录下：

moon check --target all
moon test --target all
moon info

moon info 会重新生成 src/pkg.generated.mbti；该文件的变化即公开 API 的变化。