render: add glTF/GLB animation export (#90)

Adds exportGLTF() (and buildAnimatedRig()) to posecode-render: bakes a
movement into a glTF/GLB asset — the procedural mannequin rig plus one
AnimationClip driving joint rotations and root travel/turn — via Three.js
GLTFExporter.

- Samples the authored timeline at a configurable fps; joint nodes are named
  by Posecode bone id, the animated root group is 'posecode_root'.
- Full looped runtime baked as keyframes so duration/loop count survive.
- Returns a GLB ArrayBuffer by default, or a glTF JSON object (binary:false).
- Playground gains a 'Download glTF' button; render chunk stays lazy-loaded.
- Documented limitations: procedural rig (no retargeting onto external/humanoid
  skeletons yet) and authored motion (not the contact/IK-solved motion).

Tested headlessly: track construction, and a GLB round-trip through
GLTFLoader that rebinds the clip to an AnimationMixer and advances it.

Signed-off-by: Claude <noreply@anthropic.com>

Author: claude

README.md

@@ -551,6 +551,36 @@ calibrated rig.
   (e.g. `reach: hand_left floor`) export the authored pose rather than the
   solved one. See [issue #63](https://github.com/posecode-dev/posecode/issues/63).
 
+### Exporting motion (glTF / GLB)
+
+For web animation pipelines, `posecode-render` can export the rig **and** a
+baked animation clip as a glTF/GLB asset. In the playground, use **Download
+glTF**; programmatically:
+
+```ts
+import { parse } from "posecode-parser";
+import { exportGLTF } from "posecode-render";
+
+const { ir } = parse(source);
+const glb = await exportGLTF(ir!);            // GLB ArrayBuffer (default)
+const gltf = await exportGLTF(ir!, { binary: false }); // glTF JSON object
+```
+
+The result loads with Three.js [`GLTFLoader`](https://threejs.org/docs/#GLTFLoader.load),
+and the clip plays on the included rig:
+
+```ts
+const gltf = await new GLTFLoader().loadAsync(url);
+const mixer = new THREE.AnimationMixer(gltf.scene);
+mixer.clipAction(gltf.animations[0]).play();
+```
+
+- Joint nodes are named by Posecode bone id; the animated root is `posecode_root`.
+- **Limitations:** exports the procedural mannequin rig, not a humanoid/Mixamo
+  skeleton, so there is **no retargeting** onto external rigs yet, and (as with
+  BVH) it bakes the authored motion, not the contact/IK-solved motion. See
+  [issue #90](https://github.com/posecode-dev/posecode/issues/90).
+
 ---
 
 ## How Posecode Stays Honest

ROADMAP.md

@@ -122,10 +122,11 @@ Each prop is a small scene object + an anchor type; movements then reference it
 - Self-collision is a bounded corrective pass over selected body pairs, not a
   comprehensive physics system. It exposes residuals for those sampled pairs,
   but does not detect every possible body-body collision.
-- BVH motion export bakes the **authored** joint motion and root choreography
-  (travel/turn); it does not yet re-run the renderer's contact/IK solve, so
-  IK-dependent movements export their authored pose rather than the solved one.
-  There is no glTF/GLB export yet.
+- BVH and glTF/GLB motion export bake the **authored** joint motion and root
+  choreography (travel/turn); they do not yet re-run the renderer's contact/IK
+  solve, so IK-dependent movements export their authored pose rather than the
+  solved one. glTF export uses the procedural mannequin rig with no retargeting
+  onto external/humanoid skeletons yet.
 - A **starter** prop set (chair / wall / bar / box / dip bars): no bench,
   rings, bands, or loaded implements yet, and props sit at fixed default
   placements.

packages/posecode-render/src/gltf.ts

@@ -0,0 +1,150 @@
+/**
+ * glTF / GLB animation export.
+ *
+ * Bakes a Posecode movement into a standard glTF asset — the rig plus a baked
+ * animation clip — so it can drop into an existing web animation pipeline and
+ * load with Three.js' `GLTFLoader`.
+ *
+ * ## What is exported
+ *
+ * The procedural mannequin rig (bone hierarchy with limb meshes parented to
+ * each joint) and one `AnimationClip` that drives the joint rotations and the
+ * root travel/turn. Like the BVH path, this bakes the **authored** joint motion
+ * plus root choreography; it does not re-run the renderer's contact/IK solve,
+ * so IK-dependent movements export their authored pose. Exporting the fully
+ * solved motion, and retargeting onto external/humanoid skeletons, are
+ * documented future work (see issue #90).
+ *
+ * ## Conventions
+ *
+ * - Right-handed, **Y-up**, figure faces **+Z** at rest (Three.js default).
+ * - Units are metres.
+ * - Joint nodes are named by their Posecode bone id (`elbow_left`, `hip_right`,
+ *   …); the animated root group is `posecode_root`.
+ * - The full looped runtime (cycle incl. loop-reset wrap × repeats) is baked as
+ *   keyframes, so duration and loop count survive without a runtime loop flag.
+ */
+
+import * as THREE from "three";
+import { GLTFExporter } from "three/examples/jsm/exporters/GLTFExporter.js";
+import type { PosecodeIR } from "posecode-parser";
+import { buildMannequin, type Proportions } from "./mannequin.js";
+import { buildTimeline } from "./timeline.js";
+
+const DEFAULT_FPS = 30;
+const ROOT_NODE_NAME = "posecode_root";
+
+export interface GltfExportOptions {
+  /** Keyframe sample rate. Defaults to 30 fps. */
+  fps?: number;
+  /** true → GLB binary ArrayBuffer (default); false → glTF JSON object. */
+  binary?: boolean;
+  /** Rig proportions, if exporting for a calibrated character. */
+  proportions?: Proportions;
+}
+
+const _up = new THREE.Vector3(0, 1, 0);
+const _yaw = new THREE.Quaternion();
+
+/**
+ * Build the mannequin rig and a baked `AnimationClip` for a movement, without
+ * touching the DOM. Exposed for tests and advanced callers; most consumers want
+ * {@link exportGLTF}.
+ */
+export function buildAnimatedRig(
+  ir: PosecodeIR,
+  options: GltfExportOptions = {},
+): { root: THREE.Group; clip: THREE.AnimationClip } {
+  const fps = options.fps && options.fps > 0 ? options.fps : DEFAULT_FPS;
+  const mannequin = buildMannequin(undefined, options.proportions);
+  const timeline = buildTimeline(ir);
+
+  // Name every joint node by its bone id so animation tracks bind by name and
+  // the exported glTF uses a stable, documented joint-naming convention.
+  mannequin.root.name = ROOT_NODE_NAME;
+  const animatedBones: string[] = [];
+  for (const [id, node] of mannequin.bones) {
+    node.name = id;
+    animatedBones.push(id);
+  }
+
+  const cycle = Math.max(timeline.duration, 1e-6);
+  const total = cycle * Math.max(1, timeline.repeat);
+  const dt = 1 / fps;
+  const frameCount = Math.max(1, Math.round(total * fps)) + 1;
+
+  const times = new Float32Array(frameCount);
+  const rootPos = new Float32Array(frameCount * 3);
+  const rootQuat = new Float32Array(frameCount * 4);
+  const boneQuat = new Map<string, Float32Array>();
+  for (const id of animatedBones) boneQuat.set(id, new Float32Array(frameCount * 4));
+
+  for (let f = 0; f < frameCount; f++) {
+    const t = Math.min(f * dt, total);
+    times[f] = t;
+    const info = timeline.sample(t, mannequin.bones);
+
+    // Root group carries the world travel (x,z) and the body yaw.
+    rootPos[f * 3] = info.rootOffset.x;
+    rootPos[f * 3 + 1] = 0;
+    rootPos[f * 3 + 2] = info.rootOffset.z;
+    _yaw.setFromAxisAngle(_up, info.rootYaw);
+    rootQuat[f * 4] = _yaw.x;
+    rootQuat[f * 4 + 1] = _yaw.y;
+    rootQuat[f * 4 + 2] = _yaw.z;
+    rootQuat[f * 4 + 3] = _yaw.w;
+
+    for (const id of animatedBones) {
+      const q = mannequin.bones.get(id)!.quaternion;
+      const buf = boneQuat.get(id)!;
+      buf[f * 4] = q.x;
+      buf[f * 4 + 1] = q.y;
+      buf[f * 4 + 2] = q.z;
+      buf[f * 4 + 3] = q.w;
+    }
+  }
+
+  const tracks: THREE.KeyframeTrack[] = [
+    new THREE.VectorKeyframeTrack(`${ROOT_NODE_NAME}.position`, Array.from(times), Array.from(rootPos)),
+    new THREE.QuaternionKeyframeTrack(`${ROOT_NODE_NAME}.quaternion`, Array.from(times), Array.from(rootQuat)),
+  ];
+  for (const id of animatedBones) {
+    tracks.push(
+      new THREE.QuaternionKeyframeTrack(
+        `${id}.quaternion`,
+        Array.from(times),
+        Array.from(boneQuat.get(id)!),
+      ),
+    );
+  }
+
+  const clip = new THREE.AnimationClip(ir.name || "posecode", total, tracks);
+  // Reset the rig to its rest pose so the exported node transforms are neutral;
+  // the clip supplies all motion.
+  timeline.sample(0, mannequin.bones);
+  return { root: mannequin.root, clip };
+}
+
+/**
+ * Export a parsed Posecode movement as a glTF/GLB asset.
+ *
+ * Returns a GLB `ArrayBuffer` (default) or a glTF JSON object when
+ * `binary: false`. The result loads with Three.js `GLTFLoader`, and the baked
+ * clip plays on the included rig.
+ */
+export async function exportGLTF(
+  ir: PosecodeIR,
+  options: GltfExportOptions = {},
+): Promise<ArrayBuffer | Record<string, unknown>> {
+  const { root, clip } = buildAnimatedRig(ir, options);
+  const exporter = new GLTFExporter();
+  const binary = options.binary ?? true;
+  return await new Promise((resolve, reject) => {
+    exporter.parse(
+      root,
+      (result) => resolve(result as ArrayBuffer | Record<string, unknown>),
+      (error) => reject(error),
+      { binary, animations: [clip] },
+    );
+  });
+}

packages/posecode-render/src/index.ts

@@ -1547,3 +1547,4 @@ export {
 } from "./contacts.js";
 export type { PhaseSegment } from "./timeline.js";
 export { exportBVH, type BvhExportOptions } from "./bvh.js";
+export { exportGLTF, buildAnimatedRig, type GltfExportOptions } from "./gltf.js";

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

@@ -0,0 +1,113 @@
+import { describe, expect, it, beforeAll } from "vitest";
+import * as THREE from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { parse } from "posecode-parser";
+import { exportGLTF, buildAnimatedRig } from "../src/gltf.js";
+
+// GLTFExporter serializes buffers via FileReader, which browsers provide but
+// Node does not. Polyfill it faithfully over Node's global Blob so the headless
+// round-trip mirrors the browser export the playground actually runs.
+beforeAll(() => {
+  if (typeof (globalThis as { FileReader?: unknown }).FileReader !== "undefined") return;
+  class NodeFileReader {
+    result: ArrayBuffer | string | null = null;
+    onloadend: (() => void) | null = null;
+    onerror: ((err: unknown) => void) | null = null;
+    readAsArrayBuffer(blob: Blob): void {
+      blob.arrayBuffer().then(
+        (buf) => {
+          this.result = buf;
+          this.onloadend?.();
+        },
+        (err) => this.onerror?.(err),
+      );
+    }
+    readAsDataURL(blob: Blob): void {
+      blob.arrayBuffer().then(
+        (buf) => {
+          const b64 = Buffer.from(buf).toString("base64");
+          this.result = `data:${blob.type || "application/octet-stream"};base64,${b64}`;
+          this.onloadend?.();
+        },
+        (err) => this.onerror?.(err),
+      );
+    }
+  }
+  (globalThis as { FileReader?: unknown }).FileReader = NodeFileReader;
+});
+
+const BICEPS = `posecode exercise "Biceps curl"
+  rig humanoid
+  pose start = standing
+
+  step "Curl" 1.1s settle:
+    elbows: flex 135
+  step "Lower" 1.4s settle:
+    elbows: flex 15
+  repeat 2
+`;
+
+function loadGlb(buffer: ArrayBuffer): Promise<THREE.Object3D & { animations: THREE.AnimationClip[] }> {
+  return new Promise((resolve, reject) => {
+    new GLTFLoader().parse(
+      buffer,
+      "",
+      (gltf) => resolve(Object.assign(gltf.scene, { animations: gltf.animations })),
+      reject,
+    );
+  });
+}
+
+describe("exportGLTF", () => {
+  it("builds a rig plus a baked clip with the expected tracks", () => {
+    const { ir } = parse(BICEPS);
+    expect(ir).toBeTruthy();
+    const { root, clip } = buildAnimatedRig(ir!, { fps: 30 });
+
+    expect(root.name).toBe("posecode_root");
+    // Root gets a position + quaternion track; each joint gets a quaternion track.
+    expect(clip.tracks.some((t) => t.name === "posecode_root.position")).toBe(true);
+    expect(clip.tracks.some((t) => t.name === "elbow_left.quaternion")).toBe(true);
+    expect(clip.duration).toBeGreaterThan(0);
+    // The elbow actually moves: some frame differs from the first keyframe.
+    const elbow = clip.tracks.find((t) => t.name === "elbow_left.quaternion")!;
+    const vals = elbow.values;
+    const frames = vals.length / 4;
+    let moved = false;
+    for (let i = 1; i < frames && !moved; i++) {
+      for (let k = 0; k < 4; k++) {
+        if (Math.abs(vals[i * 4 + k]! - vals[k]!) > 1e-3) moved = true;
+      }
+    }
+    expect(moved).toBe(true);
+  });
+
+  it("exports a GLB that reloads through GLTFLoader with its animation", async () => {
+    const { ir } = parse(BICEPS);
+    const glb = await exportGLTF(ir!, { fps: 24, binary: true });
+    expect(glb).toBeInstanceOf(ArrayBuffer);
+
+    const scene = await loadGlb(glb as ArrayBuffer);
+    // The rig survived the round-trip.
+    expect(scene.getObjectByName("elbow_left")).toBeTruthy();
+    // Exactly one baked animation clip, and it drives the elbow joint.
+    expect(scene.animations).toHaveLength(1);
+    const clip = scene.animations[0]!;
+    expect(clip.duration).toBeGreaterThan(0);
+    expect(clip.tracks.some((t) => /elbow_left\.quaternion$/.test(t.name))).toBe(true);
+
+    // The clip can be bound to a mixer and advanced without error (plays).
+    const mixer = new THREE.AnimationMixer(scene);
+    const action = mixer.clipAction(clip);
+    action.play();
+    expect(() => mixer.update(0.5)).not.toThrow();
+  });
+
+  it("can emit a glTF JSON object instead of GLB", async () => {
+    const { ir } = parse(BICEPS);
+    const gltf = (await exportGLTF(ir!, { binary: false })) as Record<string, unknown>;
+    expect(gltf).toMatchObject({ asset: expect.anything() });
+    expect(Array.isArray(gltf.animations)).toBe(true);
+    expect((gltf.animations as unknown[]).length).toBe(1);
+  });
+});

playground/play.html

@@ -127,6 +127,14 @@
         >
           <span class="lbl" aria-live="polite">Download BVH</span>
         </button>
+        <button
+          id="download-gltf"
+          class="btn ghost"
+          aria-label="Download glTF"
+          title="Download the movement as a .glb glTF asset (rig + animation) for Three.js and web pipelines"
+        >
+          <span class="lbl" aria-live="polite">Download glTF</span>
+        </button>
         <button
           id="copy-prompt"
           class="btn primary"

playground/src/main.ts

@@ -54,6 +54,7 @@ const floorGuideReset = $<HTMLSpanElement>("floor-guide-reset");
 const copyBtn = $<HTMLButtonElement>("copy-prompt");
 const shareBtn = $<HTMLButtonElement>("share");
 const downloadBvhBtn = $<HTMLButtonElement>("download-bvh");
+const downloadGltfBtn = $<HTMLButtonElement>("download-gltf");
 const tabEditor = $<HTMLButtonElement>("tab-editor");
 const tabViewer = $<HTMLButtonElement>("tab-viewer");
 
@@ -685,6 +686,36 @@ async function downloadBvh(): Promise<void> {
 }
 downloadBvhBtn.addEventListener("click", downloadBvh);
 
+// --- glTF / GLB export ---
+// Bake the current movement into a GLB (rig + animation clip) and download it.
+async function downloadGltf(): Promise<void> {
+  if (!editorApi) return;
+  const source = editorApi.getValue();
+  const { ir, errors } = parse(source);
+  if (!ir || errors.length > 0) {
+    flash(downloadGltfBtn, "Fix errors first", "error");
+    return;
+  }
+  flash(downloadGltfBtn, "Exporting…", "pending", 0);
+  try {
+    const { exportGLTF } = await import("posecode-render");
+    const glb = (await exportGLTF(ir, { binary: true })) as ArrayBuffer;
+    const blob = new Blob([glb], { type: "model/gltf-binary" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${slugifyName(ir.name)}.glb`;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    URL.revokeObjectURL(url);
+    flash(downloadGltfBtn, "Downloaded ✓", "success");
+  } catch {
+    flash(downloadGltfBtn, "Export failed", "error");
+  }
+}
+downloadGltfBtn.addEventListener("click", downloadGltf);
+
 // --- Slide-over panels (how-to, movement library) sharing one scrim ---
 const howto = $<HTMLElement>("howto");
 const scrim = $<HTMLDivElement>("scrim");