NetFabric/NetFabric.Numerics / .agents/skills/3d-rotation-theory
3d-rotation-theory
VerifiedAbstract math for 3D rotation representations and conversions. USE FOR: understanding axis-angle representation; Euler angles (yaw/pitch/roll, convention choices); rotation matrices (SO(3)); quaternion-based rotation; converting between representations; identifying and avoiding gimbal lock; composing rotations; half-angle formula; right-hand rule. DO NOT USE FOR: quaternion arithmetic details (use quaternion-algebra); slerp/lerp interpolation (use interpolation-on-manifolds); coordinate system definitions (use coordinate-system-conversions).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
| references/formulas.md | markdown | 2.5 KB |
| references/numerical-stability.md | markdown | 2.1 KB |
references/numerical-stability.md
View on GitHub# 3D Rotation Theory — Numerical Stability
## Rotation Matrix Orthogonality Drift
After repeated floating-point matrix multiplications, R drifts away from SO(3):
- `RᵀR ≠ I` accumulates error
- `det(R) ≠ 1` can even become negative
**Fix**: periodically re-orthogonalize using Gram-Schmidt or SVD polar decomposition.
Quaternions are much cheaper to renormalize (4 values vs. 9).
## Gimbal Lock Detection
From the quaternion → Euler formula, the pitch singularity occurs when:
```
test = 2(wy − zx) ≈ ±1
```
When `|test| > 0.9999`, treat as gimbal-locked:
- Set roll = 0 (or preserve from context)
- Compute yaw = ±2 · atan2(x, w)
## Near-Zero Axis Extraction from Quaternion
When θ ≈ 0, `sin(θ/2) ≈ 0`, so dividing (x, y, z) by `sin(θ/2)` amplifies noise.
Guard:
```csharp
if (Math.Abs(1.0 - w) < ε)
return (Vector3.UnitZ, 0.0); // identity rotation; axis is arbitrary
```
## Matrix to Quaternion: Shepperd Branching
Naive `w = 0.5 · √(1 + trace)` becomes `√(near-zero)` when trace ≈ −1 (180° rotation).
Shepperd's method branches on the largest diagonal element to always use a well-conditioned square root.
## Pitch Clamp for arcsin
In quaternion → Euler: `φ = arcsin(2(wy − zx))`. Clamp the argument to [−1, 1]:
```csharp
double sinPitch = Math.Clamp(2.0 * (w*y - z*x), -1.0, 1.0);
```
Without clamping, rounding in unit quaternion multiplication can push the argument outside [−1, 1].
## Convention Ambiguity (Silent Correctness Bug)
Rotation representations have multiple incompatible conventions:
- Euler order: ZYX vs. XYZ vs. ZXZ — all are called "yaw/pitch/roll" in different fields
- Active vs. passive rotation
- Row-vector vs. column-vector matrix multiplication convention
Always document which convention is used; mixing conventions causes wrong-but-plausible results.
## Rotation Matrix Column/Row Major
`v' = R · v` (column vector) uses column-major matrix interpretation.
`v' = v · R` (row vector) uses row-major (transpose of above).
Most math literature uses column vectors; some graphics APIs use row vectors. This is a sign error.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |