Module metrics 

Locomotion clip metrics: loop-seam ratio, gait phase, root-motion speed. Ported from a production game pipeline’s reference implementation (verified there against Blender pose-matrix FK to <0.01×) — the algorithms are kept semantically identical so the numbers reproduce.

Structs

FootCycleMetrics

Foot-cycle metrics for one sampled clip.

MetricGrids

Lazily sampled metric pose grids for one document.

Constants

MIN_STRIDE_STEP_M

Below this per-frame foot move (metres), a clip has no real stride (idle / block / stationary action) and the seam ratio would be a divide-by-noise, so no ratio is reported.

Functions

circular_phase_spread

Maximum circular distance (in cycle fraction, [0, 0.5]) of a set of normalized phases from their circular mean. Phases live on a ring, so a naive max−min would over-report a cluster straddling the 0/1 wrap.

foot_cycle_metrics

Measure the foot cycle of a clip from its pose grid. Requires the Hips role and at least one foot role; returns None otherwise (the caller decides whether that’s a skip-note or nothing).

fundamental_trough_phase

Normalized cycle position [0,1) of the minimum of the signal’s first Fourier harmonic. Robust to plateaus and per-frame noise: the minimum of A·cos(2π·t/N − φ) sits at t/N = (φ/2π + 0.5) mod 1.

metric_frame_count

The metric sampling grid for a clip: uniform, resolution = max key count (mirroring how the runtime loops a clip over [0, duration], wrapping duration→0 at render times unaligned with authored keys). None for clips too short to carry a cycle (< 3 keys), matching the reference implementation.

root_motion_speed_mps

Horizontal (XZ-plane) root displacement over the clip, divided by duration. Uses the Root role, falling back to Hips (clips without a dedicated root bone carry travel on the hips).

rotation_range_deg

Maximum angular deviation (degrees) of a rotation track from its first keyed rotation.