feat(render): look-at head tracking toward active contacts (L4.3)

Author: a-baran-orhan

packages/posecode-render/src/contacts.ts

@@ -211,3 +211,33 @@ export function swingArms(
   }
   if (changed) m.root.updateMatrixWorld(true);
 }
+
+/** Max head turn toward a look target (radians) so the neck never over-rotates. */
+export const MAX_LOOK = 55 * (Math.PI / 180);
+const LOOK_FWD = new THREE.Vector3(0, 0, 1);
+
+/**
+ * Turn the head toward a world focus point (look-at): aims the face (+Z) at the
+ * target, clamped to MAX_LOOK so the head tracks the action (up at the bar in a
+ * pull-up, down at the hands in a floor fold) without spinning unnaturally.
+ */
+export function aimHead(m: Mannequin, focus: THREE.Vector3): void {
+  const head = m.bones.get("head");
+  if (!head?.parent) return;
+  const headPos = head.getWorldPosition(new THREE.Vector3());
+  const desired = focus.clone().sub(headPos);
+  if (desired.lengthSq() < 1e-6) return;
+  desired.normalize();
+  const world = head.getWorldQuaternion(new THREE.Quaternion());
+  const currentZ = LOOK_FWD.clone().applyQuaternion(world).normalize();
+  const full = new THREE.Quaternion().setFromUnitVectors(currentZ, desired);
+  const angle = 2 * Math.acos(THREE.MathUtils.clamp(Math.abs(full.w), -1, 1));
+  const correction =
+    angle > MAX_LOOK
+      ? new THREE.Quaternion().slerpQuaternions(new THREE.Quaternion(), full, MAX_LOOK / angle)
+      : full;
+  const desiredWorld = correction.multiply(world);
+  const parentWorld = head.parent.getWorldQuaternion(new THREE.Quaternion());
+  head.quaternion.copy(parentWorld.invert().multiply(desiredWorld));
+  m.root.updateMatrixWorld(true);
+}

packages/posecode-render/src/index.ts

@@ -27,7 +27,7 @@ import {
   type ClipSource,
 } from "./clips.js";
 import { depenetrate } from "./depenetrate.js";
-import { alignFloorPalms, levelPlantedFeet, wrapGrip, relaxHands, swingArms } from "./contacts.js";
+import { alignFloorPalms, levelPlantedFeet, wrapGrip, relaxHands, swingArms, aimHead } from "./contacts.js";
 
 const DEG = Math.PI / 180;
 
@@ -279,6 +279,8 @@ export function createViewer(
   let authoredFingers = new Set<string>();
   // Shoulders the document poses: L4.2 arm-swing leaves these to the author.
   let authoredShoulders = new Set<string>();
+  // True when the document poses the head/neck: L4.3 look-at then stays off.
+  let authoredHead = false;
   // The last loaded document, kept so the viewer can re-solve base pose and
   // ground anchors when the character (with its own proportions) arrives.
   let lastIR: PosecodeIR | null = null;
@@ -538,6 +540,31 @@ export function createViewer(
     wrapGrip(mannequin, grips);
   }
 
+  /**
+   * L4.3 look-at: turn the head toward the action. Collects the world points of
+   * this phase's active grips/reaches (up at the bar, down at a floor reach) and
+   * aims the head at their average. Skipped when the document poses the head/neck.
+   */
+  function applyLookAt(info: { grips: GripTarget[]; reaches: ReachTarget[] }): void {
+    if (authoredHead) return;
+    const pts: THREE.Vector3[] = [];
+    const collect = (effectorName: string, anchorName: string): void => {
+      const bone = EFFECTOR_BONE[effectorName] ?? effectorName;
+      const eff = mannequin.bones.get(bone);
+      if (!eff) return;
+      const t =
+        resolveReachTarget(anchorName, eff) ??
+        resolveReachTarget(anchorName.replace(/_(left|right)$/, ""), eff);
+      if (t) pts.push(t);
+    };
+    for (const g of info.grips) collect(g.effector, g.anchor);
+    for (const r of info.reaches) collect(r.effector, r.target);
+    if (pts.length === 0) return;
+    const focus = new THREE.Vector3();
+    for (const p of pts) focus.add(p);
+    aimHead(mannequin, focus.multiplyScalar(1 / pts.length));
+  }
+
   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
@@ -609,6 +636,8 @@ export function createViewer(
       swingArms(mannequin, authoredShoulders, gripSidesOf(info.grips));
       // L4.1 aliveness: relax idle hands into a natural curl (grips still wrap).
       relaxHands(mannequin, gripSidesOf(info.grips), authoredFingers);
+      // L4.3 aliveness: turn the head toward the active contact (bar / floor reach).
+      applyLookAt(info);
       // Safety net: nothing above ever intentionally pushes part of the body
       // below the floor, so clamp the root up whenever the lowest point dips
       // below y=0, a no-op whenever the pose is legitimately grounded or
@@ -709,8 +738,10 @@ export function createViewer(
       levelPlantedFeet(mannequin, ir.phases[0]?.groundLock ?? []);
       authoredFingers = new Set(timeline.bonesUsed.filter(isFingerId));
       authoredShoulders = new Set(timeline.bonesUsed.filter((id) => id.startsWith("shoulder_")));
+      authoredHead = timeline.bonesUsed.some((id) => id === "head" || id === "neck");
       swingArms(mannequin, authoredShoulders, gripSidesOf(ir.phases[0]?.grips ?? []));
       relaxHands(mannequin, gripSidesOf(ir.phases[0]?.grips ?? []), authoredFingers);
+      applyLookAt({ grips: ir.phases[0]?.grips ?? [], reaches: ir.phases[0]?.reaches ?? [] });
       captureGroundTargets();
       baseRootPos.copy(mannequin.root.position);
       baseRootQuat.copy(mannequin.root.quaternion);

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

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import * as THREE from "three";
 import { buildMannequin } from "../src/mannequin.js";
-import { levelPlantedFeet, relaxHands, swingArms } from "../src/contacts.js";
+import { levelPlantedFeet, relaxHands, swingArms, aimHead } from "../src/contacts.js";
 import { groundFigure } from "../src/groundlock.js";
 
 const DEG = Math.PI / 180;
@@ -105,3 +105,33 @@ describe("swingArms (L4.2)", () => {
     expect(m.bones.get("shoulder_left")!.rotation.x).toBeCloseTo(before, 5);
   });
 });
+
+describe("aimHead (L4.3 look-at)", () => {
+  it("turns the head toward a focus point (face +Z tracks the target)", () => {
+    const m = buildMannequin();
+    m.root.updateMatrixWorld(true);
+    const head = m.bones.get("head")!;
+    const headPos = head.getWorldPosition(new THREE.Vector3());
+    const focus = headPos.clone().add(new THREE.Vector3(0, 1.2, 0.6));
+    const faceDir = () =>
+      new THREE.Vector3(0, 0, 1)
+        .applyQuaternion(head.getWorldQuaternion(new THREE.Quaternion()))
+        .normalize();
+    const want = focus.clone().sub(headPos).normalize();
+    const before = faceDir().dot(want);
+    aimHead(m, focus);
+    m.root.updateMatrixWorld(true);
+    expect(faceDir().dot(want)).toBeGreaterThan(before);
+  });
+
+  it("clamps the look so the head never spins past its range", () => {
+    const m = buildMannequin();
+    m.root.updateMatrixWorld(true);
+    const head = m.bones.get("head")!;
+    const headPos = head.getWorldPosition(new THREE.Vector3());
+    const behind = headPos.clone().add(new THREE.Vector3(0, 0, -2));
+    aimHead(m, behind);
+    const e = new THREE.Euler().setFromQuaternion(m.bones.get("head")!.quaternion, "XYZ");
+    expect(Math.hypot(e.x, e.y, e.z)).toBeLessThan(1.2);
+  });
+});