# Mission: 3D math intuition for sensor-driven skeletons

## Why

We build sensor pipelines that end in an animated virtual skeleton. When a pose comes out
twisted, mirrored, or drifting, the team currently debugs by permuting signs and multiply
orders until it looks right — which means wrong fixes survive and nobody can explain the
correct ones. We want the intuition to predict and diagnose these failures from the
conventions involved, instead of rediscovering them per bug.

## Success looks like

- Given a wrong-looking skeleton, anyone on the team names the failure class — reflection,
  wrong basis, wrong multiply order, or accumulating error — before touching code.
- We can state our pipeline's conventions explicitly (handedness, up axis, forward axis,
  units, quaternion component order) at every boundary it crosses, and cite the spec for each.
- Converting a pose between Unity and glTF/three.js is a rule we can derive, not a snippet we
  copy: positions and rotations both, in both directions.
- Sensor-to-segment calibration is understood as a fixed change of basis, not a magic offset.
- A new team member can work through the lessons in this repo unaided and reach the same place.

## Constraints

- **Two target conventions, both first-class:** Unity (left-handed, Y-up) and glTF/three.js
  (right-handed, Y-up). They agree on up and forward and differ in handedness, which is exactly
  the pair that generates our bugs.
- **Both sensor modalities:** IMU orientation streams and optical/vision joint positions,
  including where a fused pipeline joins them.
- **Mixed maths background.** All professional software developers. Calculus and linear algebra
  range from solid to rusty; trigonometry and geometry are rusty across the board. Lessons must
  not assume a specific course was taken and retained.
- **Offline, zero-install.** Lessons are self-contained HTML opened by double-clicking. No CDN,
  no build step, no network. They have to work on a plane and still work in two years.
- **Team artefact, not a personal notebook.** This repo is the shared onboarding path, so
  lessons must stand alone without the conversation that produced them.

## Out of scope

- Rendering, shading, and GPU work. We are chasing pose correctness, not pixels.
- Unreal and ROS/REP-103 conventions. Worth adding once the Unity ⇄ glTF pair is solid; adding
  four conventions at once would obscure the one distinction that matters most to us.
- Geometric algebra and rotors. Genuinely illuminating, and a detour until quaternions are
  comfortable.
- Deriving the sensor fusion filters themselves (Madgwick, Mahony, EKF). We need to reason about
  what their output means and where its reference frame comes from, not reimplement them.