Body Mechanics — 3D Biomechanics Visualizer

Overview

An interactive, browser-native 3D biomechanics visualizer that animates a full human skeleton through procedural walking gait and breathing cycles. No plugins, no backend — runs as a static site.

Problem

Explaining joint compensation patterns to patients or students requires a live, controllable visual reference. Existing tools either require Unity installs or are locked behind expensive clinical software licenses. A web-based, zero-install solution makes biomechanics education accessible to any collaborator with a browser.

Approach

Procedural FK Animation

Walking and breathing animations are pure mathematical functions — input (t, params), output { jointId: [x, y, z] }. No pre-baked clips. Every gait preset is a different parameter set fed into the same FK pipeline.

• Walking: 10 configurable parameters (hip swing, knee flexion, ankle range, overpronation, pelvic sway, tibial rotation)
• Breathing: diaphragmatic vs. chest breathing, adjustable BPM (6–24), rib expansion vectors

Kinetic Chain Graph

The skeleton is modeled as an undirected adjacency graph. Clicking any joint triggers BFS traversal to highlight the upstream path to root and the downstream subtree — making kinetic chain relationships immediately visible.

// Joint graph — undirected adjacency list
{
  hip_l:  ['pelvis', 'knee_l'],
  knee_l: ['hip_l', 'ankle_l'],
  // ...
}

Physics Overlays

Toggle-able overlays driven by the animation data pipeline:

• COP Path: Centre of Pressure trail at floor level
• Force Vectors: Ground Reaction Force arrows from COP
• Rib Expansion: Directional arrows for breathing module
• Joint Axes: RGB axis triads at each joint

A/B Compare Mode

Split view renders two gait presets simultaneously (e.g. normal vs. overpronation), making compensation patterns immediately visible.

Stack

| Layer | Technology | |-------|------------| | Rendering | React 18 + react-three-fiber + Three.js | | 3D Helpers | @react-three/drei (OrbitControls, Text, Grid) | | State | Zustand | | Build | Vite | | Tests | Vitest (11 graph traversal unit tests) | | Deploy | Static site (no backend) |

Architecture

useStore (Zustand)
    │
    ├── time, module, presets, overlays
    ▼
animation/*.js  ──(pure functions)──▶  { jointId: [x,y,z] }
    ▼
Skeleton.jsx  ──  spheres + cylinders from positions
    ├── overlays/*.jsx  ──  COP, GRF, RibExpansion, JointAxes
    └── ui/*.jsx  ──  no Three.js imports, write to store

Key design choice: animation modules are pure functions with no framework imports — fully testable without a browser and swappable with real mocap data without changing the rendering layer.

Results

• Fully layered architecture: pure math → graph → renderer, each independently testable
• Pre-allocated THREE.js objects and material cache eliminate GC pressure in the render loop
• Zero install friction: npm install && npm run dev
• Designed so the rendering layer can swap to a real GLTF rig or Unity without touching the data or animation modules