feat(render): squad spline sampling with per-phase timing modes

Author: a-baran-orhan

packages/posecode-render/src/timeline.ts

@@ -8,19 +8,19 @@
  */
 
 import * as THREE from "three";
-import type { PosecodeIR, ReachTarget, PinTarget } from "posecode-parser";
+import type { PosecodeIR, ReachTarget, PinTarget, TimingMode } from "posecode-parser";
 import { poseFor, type PoseSpec } from "./poses.js";
+import { squad, squadControl } from "./squad.js";
 
 const DEG = Math.PI / 180;
 
 type EulerDegTuple = [number, number, number];
-type Easing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
 
 interface Keyframe {
   time: number;
   name: string;
   cue?: string;
-  easing: Easing;
+  easing: TimingMode;
   quats: Map<string, THREE.Quaternion>;
   groundLock: string[];
   reaches: ReachTarget[];
@@ -71,11 +71,27 @@ function eulerToQuat([x, y, z]: EulerDegTuple): THREE.Quaternion {
   );
 }
 
-const EASE: Record<Easing, (t: number) => number> = {
+/**
+ * Per-mode remap of the normalized segment parameter (arrival shaping). `flow`
+ * and `linear` are even; `settle`/`snap` decelerate into rest; `drive`
+ * accelerates from rest. The spline (squad) carries velocity across keyframes;
+ * this only shapes the timing within a segment.
+ */
+const MODE_EASE: Record<TimingMode, (t: number) => number> = {
+  flow: (t) => t,
+  settle: (t) => 1 - (1 - t) * (1 - t),
+  drive: (t) => t * t,
+  snap: (t) => 1 - (1 - t) * (1 - t) * (1 - t),
   linear: (t) => t,
-  "ease-in": (t) => t * t,
-  "ease-out": (t) => 1 - (1 - t) * (1 - t),
-  "ease-in-out": (t) => t * t * (3 - 2 * t),
+};
+
+/** A keyframe is a rest-point (zero boundary velocity) for these modes. */
+const REST_MODE: Record<TimingMode, boolean> = {
+  flow: false,
+  settle: true,
+  drive: false,
+  snap: true,
+  linear: false,
 };
 
 export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
@@ -96,7 +112,7 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
   keyframes.push({
     time: 0,
     name: ir.startPose ?? "start",
-    easing: "linear",
+    easing: "flow",
     quats: snapshot(curr),
     groundLock: [],
     reaches: [],
@@ -139,7 +155,7 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
   keyframes.push({
     time: t,
     name: "reset",
-    easing: "ease-in-out",
+    easing: "flow",
     quats: snapshot(new Map(baseJoints)),
     groundLock: [],
     reaches: [],
@@ -179,23 +195,40 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
     travelExtent,
     sample(time, bones) {
       const tt = duration > 0 ? ((time % duration) + duration) % duration : 0;
+      let i = 0;
       let a = keyframes[0]!;
       let b = keyframes[keyframes.length - 1]!;
-      for (let i = 0; i < keyframes.length - 1; i++) {
-        if (tt >= keyframes[i]!.time && tt < keyframes[i + 1]!.time) {
-          a = keyframes[i]!;
-          b = keyframes[i + 1]!;
+      for (let k = 0; k < keyframes.length - 1; k++) {
+        if (tt >= keyframes[k]!.time && tt < keyframes[k + 1]!.time) {
+          i = k;
+          a = keyframes[k]!;
+          b = keyframes[k + 1]!;
           break;
         }
       }
       const span = Math.max(1e-6, b.time - a.time);
       const local = THREE.MathUtils.clamp((tt - a.time) / span, 0, 1);
-      const eased = EASE[b.easing](local);
+      const eased = MODE_EASE[b.easing](local);
 
+      // Neighbors for the squad control quaternions (clamp at the ends → the
+      // segment endpoint itself, giving a one-sided tangent).
+      const kPrev = keyframes[Math.max(0, i - 1)]!;
+      const kNext = keyframes[Math.min(keyframes.length - 1, i + 2)]!;
       for (const bone of bonesUsed) {
         const node = bones.get(bone);
         if (!node) continue;
-        node.quaternion.slerpQuaternions(a.quats.get(bone)!, b.quats.get(bone)!, eased);
+        const q0 = a.quats.get(bone)!;
+        const q1 = b.quats.get(bone)!;
+        // A rest-point keyframe uses its own value as the control (zero tangent
+        // → the spline comes to / leaves from rest there); otherwise the
+        // Shoemake control from the neighboring keyframe carries velocity.
+        const s0 = REST_MODE[a.easing]
+          ? q0.clone()
+          : squadControl(kPrev.quats.get(bone)!, q0, q1);
+        const s1 = REST_MODE[b.easing]
+          ? q1.clone()
+          : squadControl(q0, q1, kNext.quats.get(bone)!);
+        squad(q0, s0, s1, q1, eased, node.quaternion);
       }
       // Root facing/position: linear interpolation of the raw values so a large
       // turn (e.g. 360°) sweeps the whole way round rather than taking a short

packages/posecode-render/test/render.test.ts

@@ -703,3 +703,51 @@ describe("cobra", () => {
     expect(Math.abs(pelvisUp - pelvisFlat)).toBeLessThan(0.05);
   });
 });
+
+describe("spline interpolation (L2)", () => {
+  it("interpolates joints with continuous velocity through an interior keyframe", () => {
+    const src = [
+      'posecode exercise "flowy"',
+      "  rig humanoid",
+      '  step "A" 1s flow:',
+      "    shoulders: flex 40",
+      '  step "B" 1s flow:',
+      "    shoulders: flex 120",
+      '  step "C" 1s flow:',
+      "    shoulders: flex 40",
+    ].join("\n");
+    const { ir } = parse(src);
+    const tl = buildTimeline(ir!);
+    const m = buildMannequin();
+    const read = (t: number) => {
+      tl.sample(t, m.bones);
+      return m.bones.get("shoulder_left")!.quaternion.clone();
+    };
+    const eps = 1e-3;
+    const kf = 2; // end of "B" is an interior keyframe (t=2)
+    const vBefore = read(kf).angleTo(read(kf - eps)) / eps;
+    const vAfter = read(kf + eps).angleTo(read(kf)) / eps;
+    expect(Math.abs(vBefore - vAfter)).toBeLessThan(0.3); // flow carries velocity
+  });
+
+  it("settle brings a joint to rest at its keyframe", () => {
+    const src = [
+      'posecode exercise "rest"',
+      "  rig humanoid",
+      '  step "Down" 1s settle:',
+      "    knees: flex 90",
+      '  step "Up" 1s drive:',
+      "    knees: flex 0",
+    ].join("\n");
+    const { ir } = parse(src);
+    const tl = buildTimeline(ir!);
+    const m = buildMannequin();
+    const read = (t: number) => {
+      tl.sample(t, m.bones);
+      return m.bones.get("knee_left")!.quaternion.clone();
+    };
+    const eps = 1e-3;
+    const v = read(1).angleTo(read(1 - eps)) / eps; // velocity arriving at the settle kf
+    expect(v).toBeLessThan(0.2);
+  });
+});