feat(render): bar grip solve — two-point anchors, arm IK, finger wrap

Author: a-baran-orhan

packages/posecode-eval/src/probe.ts

@@ -176,7 +176,7 @@ export function probeMovement(source: string): ProbeResult {
       reaches: [...info.reaches],
       rootOffset: [info.rootOffset.x, 0, info.rootOffset.z],
       rootYaw: info.rootYaw,
-      usesSceneIk: info.pins.length > 0 || info.reaches.length > 0,
+      usesSceneIk: info.pins.length > 0 || info.reaches.length > 0 || info.grips.length > 0,
       bones: snapshotBones(m.bones),
       boneQuaternions: snapshotBoneQuaternions(m.bones),
     };

packages/posecode-render/src/contacts.ts

@@ -1,6 +1,6 @@
 /** Semantic contact-orientation helpers shared by viewer and eval. */
 import * as THREE from "three";
-import { eulerRomFor, type PinTarget, type ReachTarget } from "posecode-parser";
+import { eulerRomFor, type PinTarget, type ReachTarget, type GripTarget } from "posecode-parser";
 import type { Mannequin } from "./mannequin.js";
 
 const DOWN = new THREE.Vector3(0, -1, 0);
@@ -103,3 +103,37 @@ export function levelPlantedFeet(m: Mannequin, activeGroundLock: readonly string
   }
   if (changed) m.root.updateMatrixWorld(true);
 }
+
+/** Finger curl (radians about the knuckle X axis) that wraps a gripping hand. */
+export const FINGER_CURL = 1.35;
+/** Thumb opposition curl (radians) toward the fingers. */
+export const THUMB_CURL = 0.9;
+const FINGERS = ["index", "middle", "ring", "pinky"] as const;
+
+/**
+ * Curl the fingers of each gripping hand around the bar. Grips are per-side
+ * after resolution (`hand_left` / `hand_right`), so the side comes straight off
+ * the effector. The four fingers flex at the knuckle and the thumb opposes,
+ * turning the open reach pose into a closed grip on the bar.
+ */
+export function wrapGrip(m: Mannequin, grips: readonly GripTarget[]): void {
+  let changed = false;
+  for (const g of grips) {
+    const side = /_(left|right)$/.exec(g.effector)?.[1];
+    if (!side) continue;
+    for (const f of FINGERS) {
+      const bone = m.bones.get(`${f}_${side}`);
+      if (bone) {
+        bone.rotation.set(FINGER_CURL, 0, 0);
+        changed = true;
+      }
+    }
+    const thumb = m.bones.get(`thumb_${side}`);
+    if (thumb) {
+      // Thumb wraps from the opposite side: curl plus a sideways opposition.
+      thumb.rotation.set(THUMB_CURL, 0, side === "left" ? -THUMB_CURL : THUMB_CURL);
+      changed = true;
+    }
+  }
+  if (changed) m.root.updateMatrixWorld(true);
+}

packages/posecode-render/src/index.ts

@@ -12,7 +12,7 @@ import * as THREE from "three";
 import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
 import { eulerRomFor } from "posecode-parser";
-import type { PosecodeIR, ReachTarget, PinTarget } from "posecode-parser";
+import type { PosecodeIR, ReachTarget, PinTarget, GripTarget } from "posecode-parser";
 import { buildMannequin, type Mannequin } from "./mannequin.js";
 import { applyGroundLock as applyGroundLockTo, groundFigure as groundFigureOf } from "./groundlock.js";
 import { buildTimeline, type BuiltTimeline, type PhaseSegment } from "./timeline.js";
@@ -27,7 +27,7 @@ import {
   type ClipSource,
 } from "./clips.js";
 import { depenetrate } from "./depenetrate.js";
-import { alignFloorPalms, levelPlantedFeet } from "./contacts.js";
+import { alignFloorPalms, levelPlantedFeet, wrapGrip } from "./contacts.js";
 
 const DEG = Math.PI / 180;
 
@@ -482,6 +482,50 @@ export function createViewer(
     }
   }
 
+  /**
+   * Bar grips: unlike a pin (body translate only), a grip makes each hand hold
+   * the bar. (1) Translate the body by the average wrist→anchor delta — the
+   * authored elbow flex raises the wrists, so the body rises: the pull-up. (2)
+   * Per-hand arm IK drives each wrist exactly onto its own two-point anchor
+   * (`bar_left`/`bar_right`), so the hands grip shoulder-width and the arms angle
+   * naturally instead of pointing straight up. (3) Wrap the fingers round the bar.
+   */
+  function applyGrips(grips: GripTarget[]): void {
+    if (grips.length === 0) return;
+    const resolveGrip = (anchor: string, effector: THREE.Object3D): THREE.Vector3 | null =>
+      resolveReachTarget(anchor, effector) ??
+      resolveReachTarget(anchor.replace(/_(left|right)$/, ""), effector);
+    // 1. Body translate (the vertical pull).
+    const delta = new THREE.Vector3();
+    let n = 0;
+    for (const g of grips) {
+      const effectorBone = EFFECTOR_BONE[g.effector] ?? g.effector;
+      const effector = mannequin.bones.get(effectorBone);
+      if (!effector) continue;
+      const target = resolveGrip(g.anchor, effector);
+      if (!target) continue;
+      delta.add(target.clone().sub(effector.getWorldPosition(new THREE.Vector3())));
+      n++;
+    }
+    if (n > 0) {
+      mannequin.root.position.add(delta.multiplyScalar(1 / n));
+      mannequin.root.updateMatrixWorld(true);
+    }
+    // 2. Per-hand arm IK onto each grip point (ROM-clamped via reachChain).
+    for (const g of grips) {
+      const effectorBone = EFFECTOR_BONE[g.effector] ?? g.effector;
+      const effector = mannequin.bones.get(effectorBone);
+      if (!effector) continue;
+      const target = resolveGrip(g.anchor, effector);
+      if (!target) continue;
+      const { joints, limits } = reachChain(effectorBone);
+      if (joints.length === 0) continue;
+      solveCCD({ joints, limits, effector, target }, 12);
+    }
+    // 3. Finger wrap.
+    wrapGrip(mannequin, grips);
+  }
+
   function frameCamera(): void {
     // Auto-frame the figure: fit its bounding box, keep a pleasant angle.
     // Include any scene prop too: a pull-up bar sits well above the figure's
@@ -535,6 +579,7 @@ export function createViewer(
       depenetrate(mannequin);
       applyGroundLockTo(mannequin, info.groundLock, frameAnchors(info.rootYaw, info.rootOffset));
       applyPins(info.pins);
+      applyGrips(info.grips);
       // Reach-IK BEFORE the floor safety clamp. When authored FK pushes a
       // reaching limb through the floor (cobra: prone + shoulders flex 50),
       // the limb must bend to meet the floor. Running reaches after the clamp

packages/posecode-render/src/props.ts

@@ -54,7 +54,13 @@ export function buildProps(types: string[], material?: THREE.Material): PropScen
         post.position.set(x, barH / 2, 0);
         group.add(post);
       }
+      // Centre anchor (back-compat) plus two shoulder-width grip points so a
+      // `grip: hands bar` lands each hand on its own spot instead of both at
+      // centre. GRIP_HALF ≈ half a shoulder width.
+      const GRIP_HALF = 0.18;
       anchors.set("bar", new THREE.Vector3(0, barH, 0));
+      anchors.set("bar_left", new THREE.Vector3(GRIP_HALF, barH, 0));
+      anchors.set("bar_right", new THREE.Vector3(-GRIP_HALF, barH, 0));
     } else if (type === "wall") {
       const wall = box(2.2, 2.6, 0.1, mat);
       wall.position.set(0, 1.3, -0.34);

packages/posecode-render/src/timeline.ts

@@ -8,7 +8,7 @@
  */
 
 import * as THREE from "three";
-import type { PosecodeIR, ReachTarget, PinTarget, TimingMode } from "posecode-parser";
+import type { PosecodeIR, ReachTarget, PinTarget, GripTarget, TimingMode } from "posecode-parser";
 import { poseFor, type PoseSpec } from "./poses.js";
 import { squad, squadControl } from "./squad.js";
 
@@ -25,6 +25,7 @@ interface Keyframe {
   groundLock: string[];
   reaches: ReachTarget[];
   pins: PinTarget[];
+  grips: GripTarget[];
   /** Root facing (yaw about world Y, radians) at this keyframe. */
   yaw: number;
   /** Root ground offset (world X/Z metres) from the load spot at this keyframe. */
@@ -56,6 +57,7 @@ export interface BuiltTimeline {
     groundLock: string[];
     reaches: ReachTarget[];
     pins: PinTarget[];
+    grips: GripTarget[];
     /** Interpolated root facing (yaw about world Y, radians). */
     rootYaw: number;
     /** Interpolated root ground offset (world X/Z metres) from the load spot. */
@@ -117,6 +119,7 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
     groundLock: [],
     reaches: [],
     pins: [],
+    grips: [],
     yaw: 0,
     pos: { x: 0, z: 0 },
   });
@@ -139,6 +142,7 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
       groundLock: phase.groundLock,
       reaches: phase.reaches,
       pins: phase.pins,
+      grips: phase.grips,
       yaw: currYaw * DEG,
       pos: { ...currPos },
     });
@@ -160,6 +164,7 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
     groundLock: [],
     reaches: [],
     pins: [],
+    grips: [],
     yaw: wrapYaw,
     pos: { x: 0, z: 0 },
   });
@@ -244,6 +249,7 @@ export function buildTimeline(ir: PosecodeIR): BuiltTimeline {
         groundLock: b.groundLock,
         reaches: b.reaches,
         pins: b.pins,
+        grips: b.grips,
         rootYaw,
         rootOffset,
       };

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

@@ -6,7 +6,7 @@ import { solveCCD } from "../src/ik.js";
 import { poseFor } from "../src/poses.js";
 import { buildProps } from "../src/props.js";
 import { applyGroundLock, groundFigure } from "../src/groundlock.js";
-import { levelPlantedFeet } from "../src/contacts.js";
+import { levelPlantedFeet, wrapGrip } from "../src/contacts.js";
 import { parse, eulerRomFor } from "posecode-parser";
 
 const DEG = Math.PI / 180;
@@ -787,3 +787,29 @@ describe("foot-flat correction (L3.1)", () => {
     expect(soleDot()).toBeGreaterThan(0.9);
   });
 });
+
+describe("bar grip (L3.2)", () => {
+  it("exposes two-point bar grip anchors shoulder-width apart", () => {
+    const { anchors } = buildProps(["bar"]);
+    const l = anchors.get("bar_left");
+    const r = anchors.get("bar_right");
+    expect(l).toBeDefined();
+    expect(r).toBeDefined();
+    expect(l!.x).toBeGreaterThan(0); // left hand grips the +X side
+    expect(r!.x).toBeLessThan(0);
+    expect(Math.abs(l!.x - r!.x)).toBeCloseTo(0.36, 2);
+    expect(l!.y).toBeCloseTo(r!.y, 5); // same bar height
+  });
+
+  it("wraps the fingers of a gripping hand into a curl", () => {
+    const m = buildMannequin();
+    const restIndex = m.bones.get("index_left")!.rotation.x;
+    const restThumb = m.bones.get("thumb_left")!.rotation.x;
+    wrapGrip(m, [{ effector: "hand_left", anchor: "bar_left" }]);
+    expect(m.bones.get("index_left")!.rotation.x).toBeGreaterThan(restIndex + 0.5);
+    expect(m.bones.get("middle_left")!.rotation.x).toBeGreaterThan(0.5);
+    expect(m.bones.get("thumb_left")!.rotation.x).toBeGreaterThan(restThumb + 0.3);
+    // the un-gripped right hand is untouched
+    expect(m.bones.get("index_right")!.rotation.x).toBeCloseTo(0, 5);
+  });
+});