Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/quaternion-algebra

quaternion-algebra

Verified

Abstract math for quaternion algebra (hypercomplex numbers ℍ). USE FOR: implementing quaternion multiplication (Hamilton product, non-commutative); conjugate, norm, and inverse; unit quaternions on S³ as double cover of SO(3); rotating 3D vectors with quaternions; understanding why q and −q represent the same rotation; normalizing after operations; constructing rotation quaternions from axis-angle. DO NOT USE FOR: converting between rotation representations (use 3d-rotation-theory); slerp/lerp interpolation (use interpolation-on-manifolds); basic vector cross/dot products (use vector-algebra).

FileKindSize
SKILL.mdskill md2.4 KB
references/formulas.mdmarkdown2.6 KB
references/numerical-stability.mdmarkdown2.0 KB

references/formulas.md

View on GitHub
# Quaternion Algebra — Formulas

## Hamilton Product — Compact Vector Form

Given **q₁** = (**v₁**, w₁) and **q₂** = (**v₂**, w₂):

```
q₁q₂ = (w₁v₂ + w₂v₁ + v₁×v₂,  w₁w₂ − v₁·v₂)
```

The cross product term `v₁×v₂` is what makes multiplication non-commutative.

## Algebraic Properties

```
q₁(q₂q₃) = (q₁q₂)q₃            (associative)
q₁q₂ ≠ q₂q₁                    (NOT commutative in general)
(q₁q₂)* = q₂* q₁*               (conjugate reverses order)
‖q₁q₂‖ = ‖q₁‖ · ‖q₂‖            (norm is multiplicative)
```

## Norm Preservation of Product

Because `‖q₁q₂‖ = ‖q₁‖·‖q₂‖`, the product of two unit quaternions is a unit quaternion.
This means unit quaternions are **closed** under multiplication — the set of rotations is a group.

## Inverse Formula

```
q⁻¹ = q* / ‖q‖²
```

Derivation: `q · q* = ‖q‖²` (scalar), so `q · (q*/‖q‖²) = 1`.

For unit q: `‖q‖ = 1`, so `q⁻¹ = q* = (−x, −y, −z, w)`.

## Double-Cover of SO(3)

The map `φ: S³ → SO(3)` defined by `φ(q)(p) = qpq*` is:
- **Surjective**: every rotation is represented
- **2-to-1**: `φ(q) = φ(−q)` — negating all four components gives the same rotation

Consequence: when interpolating or composing rotations, choose the hemisphere consistently (dot product check).

## Rotation Construction from Axis-Angle

Given unit axis **n** = (nₓ, nᵧ, n_z) and angle θ:

```
q = (sin(θ/2) · nₓ,  sin(θ/2) · nᵧ,  sin(θ/2) · n_z,  cos(θ/2))
```

Derivation: from the exponential map `exp(θ/2 · n̂)` in the Lie algebra of quaternions.

Note: **n** must be a unit vector before applying this formula.

## Rotation from Yaw-Pitch-Roll (Euler Angles)

Yaw (ψ around Z), Pitch (φ around Y), Roll (ρ around X), intrinsic ZYX order:

```
qψ = (0, 0, sin(ψ/2), cos(ψ/2))
qφ = (0, sin(φ/2), 0, cos(φ/2))
qρ = (sin(ρ/2), 0, 0, cos(ρ/2))

q = qψ · qφ · qρ         (apply roll first, then pitch, then yaw)
```

## Dot Product of Quaternions

```
q₁ · q₂ = x₁x₂ + y₁y₂ + z₁z₂ + w₁w₂
```

For unit quaternions: `q₁·q₂ = cos(Ω/2)` where Ω is the angle between the two rotations.

If `q₁·q₂ < 0`, then **−q₂** represents the same rotation but with a shorter interpolation arc.

## Rotating a Vector — Sandwich Product

```
p_rotated = q · (0, pₓ, pᵧ, p_z) · q*
```

Result is a pure quaternion (w = 0); extract (x, y, z) as the rotated vector.

This requires two quaternion multiplications. Converting to a rotation matrix is faster
if the same rotation is applied to many vectors.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall