Luna Flow
日本語

quaternion

quaternion は Hamilton の四元数 H\mathbb H のための Luna-Flow ライブラリです。四元数は i2=j2=k2=ijk=−1i^2 = j^2 = k^2 = ijk = -1 を満たす w+xi+yj+zkw + xi + yj + zk の形の 4 次元の数の体系です。単位四元数はオイラー角の特異点なしに 3 次元回転を表し、合成・逆・補間を安価に行えます。本ライブラリはジェネリック型 Quaternion[T] を 1 つ提供し、環演算、右除算と左除算、ノルム、ベクトルの回転、球面補間、オイラー角変換を備えています。

パッケージ

モジュール Luna-Flow/quaternion には、ソースルート src に 1 つのパッケージだけがあり、ドキュメントでは core と呼びます。

パッケージインポートパス内容ページ
coreLuna-Flow/quaternionQuaternion[T]、その算術と回転の関数、DoubleConvert traitAPI · チュートリアル · 設計

ソースは 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−1q\,r^{-1}、q.left_div(r) は左除算 r−1qr^{-1} q です。0.2.0 より前、/ は r−1qr^{-1} q を計算していました。
  • この型は luna-generic の Zero、One、AddMonoid、MulMonoid、Semiring、Ring、Inverse、Conjugate を実装します。乗法が可換でないため、Field は実装しません。
  • 回転：from_axis_angle、from_euler、Quaternion::rotate、slerp、Quaternion::to_euler とその 8 つの順序固定版。

どこから読むか

  • 四元数が初めての方： チュートリアルをクイックスタートから「2 つの回転を比較する」まで読んでください。ベクトルと角度以上の数学は必要ありません。
  • ライブラリを使う方： 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 の変更を意味します。