@docyrus/animaguru 0.27.0 → 0.28.0

package/templates/video/src/kit/three-stage.ts

@@ -0,0 +1,262 @@
+import { Sprite, Texture } from "pixi.js";
+import * as THREE from "three";
+import { GLTFLoader, type GLTF } from "three/addons/loaders/GLTFLoader.js";
+import { HDRLoader } from "three/addons/loaders/HDRLoader.js";
+import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
+import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
+import { BokehPass } from "three/addons/postprocessing/BokehPass.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+import type { Pass } from "three/addons/postprocessing/Pass.js";
+import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+import { publicAsset } from "../assets";
+import { easeInOut } from "./motion";
+
+/*
+  3D shots for the film: three.js draws into its own canvas, which the film shows as one Pixi Sprite,
+  so 2D art can sit behind it (the canvas is transparent where nothing is drawn) and text, captions
+  and leader lines on top. Everything stays a function of film time: pose rigs with Rig.pose(), move
+  cameras with vecAt(), never use THREE.Clock, mixer.update(delta) or Math.random() in a frame, and draw
+  last, from the film.on() update registered after every 3D update. See the animaguru-3d-models skill.
+*/
+
+export { THREE };
+
+export type StageOptions = {
+  /** The design size the sprite covers, in film coordinates. */
+  width: number;
+  height: number;
+  /** Render scale: 1.5–2 renders larger and lets Pixi downsample it, on top of MSAA. */
+  supersample?: number;
+};
+
+/** `passes` (for example tilt-shift or colour grading ShaderPasses) run after depth of field and bloom, before tone mapping. */
+export type PostOptions = { bloom?: { strength: number; radius: number; threshold: number }; bokeh?: { focus: number; aperture: number; maxblur: number }; passes?: Pass[] };
+
+export class ThreeStage {
+  readonly renderer: THREE.WebGLRenderer;
+  readonly sprite: Sprite;
+  readonly width: number;
+  readonly height: number;
+  private readonly scale: number;
+  private readonly composers = new Map<THREE.Scene, EffectComposer>();
+  private readonly gltf = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
+
+  constructor({ width, height, supersample = 1.5 }: StageOptions) {
+    this.width = width;
+    this.height = height;
+    this.scale = supersample;
+    const canvas = document.createElement("canvas");
+    // preserveDrawingBuffer: Pixi reads the canvas after three.js has presented it.
+    this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true, preserveDrawingBuffer: true, powerPreference: "high-performance" });
+    this.renderer.setPixelRatio(supersample);
+    this.renderer.setSize(width, height, false);
+    this.renderer.setClearColor(0x000000, 0);
+    this.renderer.toneMapping = THREE.AgXToneMapping;
+    this.renderer.shadowMap.enabled = true;
+    this.renderer.shadowMap.type = THREE.PCFShadowMap;
+    this.sprite = new Sprite(Texture.from(canvas));
+    this.sprite.width = width;
+    this.sprite.height = height;
+  }
+
+  /** Loads a GLB from public/ (meshopt-compressed files too); its meshes cast and receive shadows. */
+  async load(path: string): Promise<GLTF> {
+    const gltf = await this.gltf.loadAsync(publicAsset(path));
+    gltf.scene.traverse((node) => { if ((node as THREE.Mesh).isMesh) { node.castShadow = true; node.receiveShadow = true; } });
+    return gltf;
+  }
+
+  /** An equirectangular .hdr from public/ as image-based lighting; `hdr` can also be a scene's background. */
+  async environment(path: string) {
+    const hdr = await new HDRLoader().loadAsync(publicAsset(path));
+    hdr.mapping = THREE.EquirectangularReflectionMapping;
+    const pmrem = new THREE.PMREMGenerator(this.renderer);
+    const env = pmrem.fromEquirectangular(hdr).texture;
+    pmrem.dispose();
+    return { hdr, env };
+  }
+
+  /** A soft studio environment generated in code, for image-based lighting without an HDR file. */
+  room(blur = 0.04) {
+    const pmrem = new THREE.PMREMGenerator(this.renderer);
+    const env = pmrem.fromScene(new RoomEnvironment(), blur).texture;
+    pmrem.dispose();
+    return env;
+  }
+
+  /** Post-processing for one scene: an MSAA target, optional depth of field and bloom, then tone mapping. Returns the depth-of-field pass, whose focus the film sets each frame. */
+  post(scene: THREE.Scene, camera: THREE.PerspectiveCamera, { bloom, bokeh, passes = [] }: PostOptions) {
+    const w = this.width * this.scale, h = this.height * this.scale;
+    const composer = new EffectComposer(this.renderer, new THREE.WebGLRenderTarget(w, h, { type: THREE.HalfFloatType, samples: 4 }));
+    composer.setPixelRatio(this.scale);
+    composer.setSize(this.width, this.height);
+    composer.addPass(new RenderPass(scene, camera));
+    const depth = bokeh ? new BokehPass(scene, camera, bokeh) : undefined;
+    if (depth) composer.addPass(depth);
+    if (bloom) composer.addPass(new UnrealBloomPass(new THREE.Vector2(w, h), bloom.strength, bloom.radius, bloom.threshold));
+    for (const pass of passes) composer.addPass(pass);
+    composer.addPass(new OutputPass());
+    this.composers.set(scene, composer);
+    return depth;
+  }
+
+  /** Compiles the scene's materials and draws it once, so the first exported frame never waits on shaders. Await it in build(). */
+  async warm(scene: THREE.Scene, camera: THREE.Camera) {
+    await this.renderer.compileAsync(scene, camera);
+    this.draw(scene, camera);
+  }
+
+  /** Draws the scene and hands the canvas to Pixi for this frame. */
+  draw(scene: THREE.Scene, camera: THREE.Camera) {
+    const composer = this.composers.get(scene);
+    if (composer) composer.render();
+    else this.renderer.render(scene, camera);
+    this.sprite.texture.source.update();
+  }
+
+  /** Film position of a world point, for 2D labels and leader lines that follow a 3D part. `behind` is true when the point is behind the camera. */
+  project(point: THREE.Vector3, camera: THREE.Camera) {
+    // three.js refreshes matrices while rendering, which happens after this; without this the label follows last frame's camera.
+    camera.updateMatrixWorld();
+    const v = point.clone().project(camera);
+    return { x: (v.x + 1) / 2 * this.width, y: (1 - v.y) / 2 * this.height, behind: v.z > 1 };
+  }
+
+  dispose() {
+    for (const composer of this.composers.values()) composer.dispose();
+    this.renderer.dispose();
+    this.sprite.destroy({ texture: true, textureSource: true });
+  }
+}
+
+/** Scales a model to `height` scene units (metres), stands it on y = 0 and centres it on the origin. Saved AnimaGuru models face +Z. */
+export function normalize<T extends THREE.Object3D>(object: T, height: number): T {
+  object.updateMatrixWorld(true);
+  const box = new THREE.Box3().setFromObject(object);
+  object.scale.multiplyScalar(height / box.getSize(new THREE.Vector3()).y);
+  object.updateMatrixWorld(true);
+  box.setFromObject(object);
+  const center = box.getCenter(new THREE.Vector3());
+  object.position.x -= center.x;
+  object.position.z -= center.z;
+  object.position.y -= box.min.y;
+  return object;
+}
+
+export type ClipLayer = { clip: string; time: number; weight?: number; loop?: boolean };
+
+/**
+  A rigged model's clips sampled at absolute times. pose() sets every clip's time and weight and applies
+  them with a zero-length update, so a frame depends only on its arguments, never on the frame before:
+  crossfade by easing two weights against film time.
+*/
+export class Rig {
+  readonly mixer: THREE.AnimationMixer;
+  private readonly actions = new Map<string, THREE.AnimationAction>();
+
+  constructor(root: THREE.Object3D, clips: THREE.AnimationClip[]) {
+    this.mixer = new THREE.AnimationMixer(root);
+    for (const clip of clips) {
+      const action = this.mixer.clipAction(clip);
+      action.play();
+      action.setEffectiveWeight(0);
+      this.actions.set(clip.name, action);
+    }
+  }
+
+  get clips() { return [...this.actions.keys()]; }
+  duration(clip: string) { return this.action(clip).getClip().duration; }
+
+  /** `loop: false` holds a clip's last pose after it ends. */
+  pose(layers: ClipLayer[]) {
+    for (const action of this.actions.values()) { action.enabled = true; action.paused = false; action.setEffectiveWeight(0); }
+    for (const layer of layers) {
+      const action = this.action(layer.clip);
+      const length = action.getClip().duration;
+      action.time = layer.loop === false ? Math.min(Math.max(layer.time, 0), length - 1e-4) : ((layer.time % length) + length) % length;
+      action.setEffectiveWeight(layer.weight ?? 1);
+    }
+    this.mixer.update(0);
+  }
+
+  private action(clip: string) {
+    const action = this.actions.get(clip);
+    if (!action) throw new Error(`No clip "${clip}"; the model has ${this.clips.join(", ")}`);
+    return action;
+  }
+}
+
+/**
+  Removes a clip's horizontal root motion (clips from motion capture or other rigs often travel forward) and
+  returns the speed it had in world units a second at the model's current scale, so the film moves the
+  character itself; it returns 0 for in-place clips such as Meshy's, whose speed strideSpeed() measures. Call it
+  after normalize() and before posing.
+*/
+export function inPlace(model: THREE.Object3D, clip: THREE.AnimationClip, bone = "Hips") {
+  const track = clip.tracks.find((item) => item.name === `${bone}.position`);
+  const node = model.getObjectByName(bone);
+  if (!track || !node?.parent) return 0;
+  model.updateMatrixWorld(true);
+  const parent = node.parent.matrixWorld, inverse = parent.clone().invert(), v = track.values, p = new THREE.Vector3();
+  const first = new THREE.Vector3(v[0], v[1], v[2]).applyMatrix4(parent);
+  const last = new THREE.Vector3(v[v.length - 3], v[v.length - 2], v[v.length - 1]).applyMatrix4(parent);
+  for (let i = 0; i < v.length; i += 3) {
+    p.set(v[i], v[i + 1], v[i + 2]).applyMatrix4(parent);
+    p.x = first.x;
+    p.z = first.z;
+    p.applyMatrix4(inverse);
+    v[i] = p.x; v[i + 1] = p.y; v[i + 2] = p.z;
+  }
+  return Math.hypot(last.x - first.x, last.z - first.z) / clip.duration;
+}
+
+/**
+ * Walking speed of an in-place walk cycle, in world units a second at the model's current scale. Meshy's clips
+ * have no root motion: while a foot is at its lowest it slides backwards at the speed the body must travel for it
+ * to stay planted. Call it after normalize(), with the model facing +Z and its holder not yet turned.
+ */
+export function strideSpeed(rig: Rig, model: THREE.Object3D, clip: string, feet = ["LeftToeBase", "RightToeBase"]) {
+  const bones = feet.map((name) => model.getObjectByName(name)).filter((bone): bone is THREE.Object3D => Boolean(bone));
+  if (!bones.length) return 0;
+  const length = rig.duration(clip), step = 1 / 120, p = new THREE.Vector3();
+  const tracks = bones.map(() => [] as { y: number; z: number }[]);
+  for (let t = 0; t <= length; t += step) {
+    rig.pose([{ clip, time: t }]);
+    model.updateMatrixWorld(true);
+    bones.forEach((bone, i) => { bone.getWorldPosition(p); tracks[i].push({ y: p.y, z: p.z }); });
+  }
+  const speeds: number[] = [];
+  for (const track of tracks) {
+    const low = Math.min(...track.map((sample) => sample.y));
+    for (let i = 1; i < track.length; i++) if (track[i].y < low + 0.012 && track[i - 1].y < low + 0.012) speeds.push((track[i - 1].z - track[i].z) / step);
+  }
+  speeds.sort((a, b) => a - b);
+  return speeds.length ? speeds[Math.floor(speeds.length / 2)] : 0;
+}
+
+/** Sets a named blend shape on every mesh that has it, for models that carry expressions or visemes. */
+export function setMorph(root: THREE.Object3D, name: string, weight: number) {
+  root.traverse((node) => {
+    const mesh = node as THREE.Mesh;
+    const index = mesh.morphTargetDictionary?.[name];
+    if (index !== undefined && mesh.morphTargetInfluences) mesh.morphTargetInfluences[index] = weight;
+  });
+}
+
+export type Key<T> = [time: number, value: T];
+
+/** Eased keyframes for a position or target: holds before the first key and after the last. */
+export function vecAt(t: number, keys: Key<[number, number, number]>[], out = new THREE.Vector3()) {
+  if (t <= keys[0][0]) return out.fromArray(keys[0][1]);
+  for (let i = 1; i < keys.length; i++) {
+    const [t1, b] = keys[i];
+    if (t <= t1) {
+      const [t0, a] = keys[i - 1];
+      const k = easeInOut((t - t0) / (t1 - t0));
+      return out.set(a[0] + (b[0] - a[0]) * k, a[1] + (b[1] - a[1]) * k, a[2] + (b[2] - a[2]) * k);
+    }
+  }
+  return out.fromArray(keys[keys.length - 1][1]);
+}

package/templates/video/src/resource-timeline.ts

@@ -9,6 +9,7 @@ const icons = {
   graphics: "m12 3 9 9-9 9-9-9Z", image: "M3 3h18v18H3zM3 17l6-6 4 4 3-3 5 5M15 7h.01",
   video: "M3 5h13v14H3zM16 9l5-3v12l-5-3", text: "M4 5h16M12 5v15M8 20h8",
   captions: "M3 5h18v14H3zM10 9H7v6h3m7-6h-3v6h3", audio: "M4 9v6m4-10v14m4-16v18m4-15v12m4-9v6",
+  model: "M12 3 3 7.5v9L12 21l9-4.5v-9ZM3 7.5 12 12l9-4.5M12 12v9",
 };
 
 /** A navigable resource view. It changes the playhead, never the film's clip timing. */

package/templates/video/src/studies/three/character-stage-3d.ts

@@ -0,0 +1,172 @@
+import { Container, FillGradient, Graphics } from "pixi.js";
+import { THREE, ThreeStage, clamp01, easeInOut, inOut, lerp, show, txt, win } from "../../kit";
+import type { ThreeStudy } from ".";
+
+/*
+  3D Character Stage study: a wooden artist's mannequin, built from primitives in a joint hierarchy and posed by
+  functions of t, walks across a painted 2D square, turns to the camera and waves, casting a real shadow onto
+  the painting. The 3D camera is matched to the painting: level, at its eye height, with the lens shifted so the
+  horizon sits where it is painted. A film replaces the mannequin with a generated, rigged character
+  (animaguru-3d-models) posed with Rig.pose(), and the drawn square with a painted backdrop.
+*/
+
+const W = 1920, H = 1080;
+/** The painted horizon and the matching camera: eye 1.0 m above the ground, 34° vertical field. */
+const HORIZON = 610, EYE = 1.0, FOV = 34;
+/** The walk crosses the square on this line and stops at its middle. */
+const FROM = new THREE.Vector3(-3.2, 0, -9.5), STOP = new THREE.Vector3(0.35, 0, -6.2);
+/** Two steps take CYCLE seconds; a 0.3 rad leg swing reaches ±0.27 m, so the body moves 2 × 0.54 m a cycle. */
+const CYCLE = 1.1, SWING = 0.3, SPEED = (4 * 0.9 * Math.sin(SWING)) / CYCLE;
+const ARRIVE = Math.min(4, FROM.distanceTo(STOP) / SPEED);
+
+/** The square, painted in flat strokes: sky, sun, roofs, the lit ground and the lines that recede to the horizon. */
+function paintSquare() {
+  const paint = new Container();
+  const sky = new FillGradient({ type: "linear", start: { x: 0, y: 0 }, end: { x: 0, y: 1 }, colorStops: [{ offset: 0, color: "#f2b563" }, { offset: 1, color: "#fde7b8" }] });
+  paint.addChild(new Graphics().rect(0, 0, W, HORIZON + 20).fill(sky));
+  for (const [r, a] of [[260, 0.16], [150, 0.28], [70, 0.9]] as const) paint.addChild(new Graphics().circle(760, HORIZON - 150, r).fill({ color: 0xfff3d1, alpha: a }));
+  paint.addChild(new Graphics().poly([0, HORIZON - 40, 380, HORIZON - 120, 760, HORIZON - 70, 1180, HORIZON - 150, 1600, HORIZON - 80, W, HORIZON - 110, W, HORIZON, 0, HORIZON]).fill({ color: 0xc98a5a, alpha: 0.55 }));
+  const houses = new Graphics();
+  const house = (x: number, w: number, h: number, wall: number, roof: number) => {
+    houses.rect(x, HORIZON - h, w, h).fill(wall);
+    houses.poly([x - 14, HORIZON - h, x + w / 2, HORIZON - h - w * 0.28, x + w + 14, HORIZON - h]).fill(roof);
+    for (let wx = x + 22; wx < x + w - 30; wx += 58) for (let wy = HORIZON - h + 34; wy < HORIZON - 60; wy += 78) houses.roundRect(wx, wy, 26, 40, 6).fill({ color: 0x5f7f8a, alpha: 0.8 });
+  };
+  house(-40, 300, 520, 0xe8b88a, 0xb5573c); house(250, 220, 360, 0xf1cf98, 0xa9573f); house(460, 180, 250, 0xe9c2a0, 0xb86a48);
+  house(1290, 200, 260, 0xefd0a6, 0xb0603f); house(1480, 230, 380, 0xe6b37f, 0xa8533a); house(1700, 260, 540, 0xf0c890, 0xb5573c);
+  paint.addChild(houses);
+  const ground = new FillGradient({ type: "linear", start: { x: 0, y: 0 }, end: { x: 0, y: 1 }, colorStops: [{ offset: 0, color: "#e8b27a" }, { offset: 1, color: "#c98656" }] });
+  paint.addChild(new Graphics().rect(0, HORIZON, W, H - HORIZON).fill(ground));
+  // Paving joints drawn toward the vanishing point: the 3D ground plane must agree with them.
+  const joints = new Graphics();
+  for (let i = -14; i <= 14; i++) joints.moveTo(W / 2 + i * 34, HORIZON).lineTo(W / 2 + i * 260, H);
+  for (let d = 1.5; d < 40; d *= 1.32) { const y = HORIZON + (H / 2 / Math.tan((FOV / 2) * Math.PI / 180)) * EYE / d; joints.moveTo(0, y).lineTo(W, y); }
+  joints.stroke({ color: 0xa8683f, alpha: 0.35, width: 2 });
+  paint.addChild(joints);
+  return paint;
+}
+
+type Limb = { top: THREE.Group; lower: THREE.Group; end: THREE.Group };
+
+/** A jointed wooden mannequin, 1.75 m tall, facing +Z like a generated model; each joint is a Group to rotate. */
+function mannequin() {
+  const wood = new THREE.MeshStandardMaterial({ color: 0xd7a066, roughness: 0.48 });
+  const knob = new THREE.MeshStandardMaterial({ color: 0xa8713f, roughness: 0.4 });
+  const piece = (length: number, radius: number, down = true) => {
+    const mesh = new THREE.Mesh(new THREE.CapsuleGeometry(radius, Math.max(0.01, length - 2 * radius), 6, 18), wood);
+    mesh.position.y = down ? -length / 2 : length / 2;
+    mesh.castShadow = true;
+    return mesh;
+  };
+  const ball = (radius: number) => { const mesh = new THREE.Mesh(new THREE.SphereGeometry(radius, 20, 14), knob); mesh.castShadow = true; return mesh; };
+  const joint = (parent: THREE.Object3D, x: number, y: number, z = 0) => { const group = new THREE.Group(); group.position.set(x, y, z); parent.add(group); return group; };
+  const root = new THREE.Group();
+  const hips = joint(root, 0, 0.95);
+  hips.add(new THREE.Mesh(new THREE.SphereGeometry(0.15, 22, 16).scale(1.2, 0.7, 0.85), wood));
+  const spine = joint(hips, 0, 0.05);
+  spine.add(piece(0.42, 0.13, false));
+  const chest = joint(spine, 0, 0.42);
+  chest.add(new THREE.Mesh(new THREE.SphereGeometry(0.17, 22, 16).scale(1.25, 0.8, 0.8), wood));
+  const neck = joint(chest, 0, 0.1);
+  neck.add(piece(0.1, 0.045, false));
+  const head = joint(neck, 0, 0.12);
+  head.add(new THREE.Mesh(new THREE.SphereGeometry(0.11, 24, 18).scale(0.88, 1.15, 0.95).translate(0, 0.1, 0.01), wood));
+  const limb = (parent: THREE.Object3D, x: number, y: number, upper: number, lower: number, radius: number, foot: boolean): Limb => {
+    const top = joint(parent, x, y);
+    top.add(ball(radius * 1.15), piece(upper, radius));
+    const knee = joint(top, 0, -upper);
+    knee.add(ball(radius * 0.95), piece(lower, radius * 0.85));
+    const end = joint(knee, 0, -lower);
+    end.add(foot ? Object.assign(new THREE.Mesh(new THREE.BoxGeometry(0.1, 0.06, 0.24).translate(0, -0.02, 0.06), wood), { castShadow: true }) : Object.assign(new THREE.Mesh(new THREE.SphereGeometry(0.05, 16, 12).scale(0.8, 1.4, 0.6).translate(0, -0.05, 0), wood), { castShadow: true }));
+    return { top, lower: knee, end };
+  };
+  const legs = [limb(hips, -0.1, -0.03, 0.44, 0.42, 0.06, true), limb(hips, 0.1, -0.03, 0.44, 0.42, 0.06, true)];
+  const arms = [limb(chest, -0.22, 0.02, 0.3, 0.27, 0.045, false), limb(chest, 0.22, 0.02, 0.3, 0.27, 0.045, false)];
+  root.traverse((node) => { if ((node as THREE.Mesh).isMesh) node.castShadow = true; });
+  return { root, hips, spine, head, legs, arms };
+}
+
+const study: ThreeStudy = async (root, lines) => {
+  const stage = new ThreeStage({ width: W, height: H, supersample: 1.5 });
+  stage.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  const scene = new THREE.Scene();
+  scene.environment = stage.room();
+  scene.environmentIntensity = 0.3;
+  const camera = new THREE.PerspectiveCamera(FOV, W / H, 0.1, 80);
+  camera.position.set(0, EYE, 0);
+  // Lens shift instead of tilt: verticals stay vertical, as in the painting, and the horizon lands on HORIZON.
+  camera.updateProjectionMatrix();
+  camera.projectionMatrix.elements[9] = -(1 - 2 * HORIZON / H);
+  camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
+
+  const figure = mannequin();
+  const holder = new THREE.Group();
+  holder.add(figure.root);
+  // The painted sun sits back left: the shadow falls right, toward the camera.
+  const sun = new THREE.DirectionalLight(0xffcf94, 2.8);
+  sun.position.set(STOP.x - 7, 5, STOP.z - 8);
+  sun.target.position.copy(STOP);
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(2048, 2048);
+  Object.assign(sun.shadow.camera, { left: -8, right: 8, top: 8, bottom: -8, near: 1, far: 30 });
+  sun.shadow.radius = 5;
+  sun.shadow.bias = -0.0005;
+  const ground = new THREE.Mesh(new THREE.PlaneGeometry(50, 50), new THREE.ShadowMaterial({ color: 0x4a2412, opacity: 0.55 }));
+  ground.rotation.x = -Math.PI / 2;
+  ground.receiveShadow = true;
+  scene.add(holder, sun, sun.target, ground, new THREE.HemisphereLight(0xffe0b0, 0xc98050, 1.6));
+
+  const caption = txt(lines[0], 46, { family: "heading", weight: "700", fill: 0xfff4e2, dropShadow: { color: 0x3a1a08, alpha: 0.6, blur: 8, distance: 2, angle: Math.PI / 2 } });
+  caption.anchor.set(0.5, 1);
+  caption.position.set(W / 2, H - 70);
+  const eyebrow = txt(lines[1], 30, { family: "mono", weight: "700", fill: 0x6b3a1c });
+  eyebrow.position.set(96, 84);
+  const beat = txt(lines[2], 30, { family: "heading", weight: "700", fill: 0x3b2414 });
+  const leader = new Graphics();
+  root.addChild(paintSquare(), stage.sprite, leader, beat, eyebrow, caption);
+  await stage.warm(scene, camera);
+
+  const direction = STOP.clone().sub(FROM).normalize();
+  const start = STOP.clone().addScaledVector(direction, -SPEED * ARRIVE);
+  const heading = Math.atan2(direction.x, direction.z);
+  const head = new THREE.Vector3();
+
+  return (t) => {
+    // Walk: legs and arms swing in opposition, knees bend in the swing, hips bob twice a cycle.
+    const phase = (t / CYCLE) * Math.PI * 2, walking = 1 - clamp01((t - ARRIVE + 0.2) / 0.4);
+    // Facing +Z, his right side is -X: arms[0] is the right arm, the one that waves.
+    const [left, right] = figure.legs, [armR, armL] = figure.arms;
+    for (const [leg, sign] of [[left, 1], [right, -1]] as const) {
+      const swing = Math.sin(phase) * sign;
+      leg.top.rotation.x = -SWING * swing * walking;
+      leg.lower.rotation.x = Math.max(0, Math.sin(phase * sign + 1.2)) * 0.7 * walking;
+      leg.end.rotation.x = -(leg.top.rotation.x + leg.lower.rotation.x) * 0.6;
+    }
+    figure.hips.position.y = 0.95 + Math.cos(phase * 2) * 0.02 * walking;
+    figure.spine.rotation.y = Math.sin(phase) * 0.08 * walking;
+    holder.position.lerpVectors(start, STOP, clamp01(t / ARRIVE));
+    // Turn to the camera, then wave: the right arm rises and the forearm rocks.
+    holder.rotation.y = lerp(heading, 0, easeInOut(win(t, ARRIVE - 0.1, 0.8)));
+    const wave = easeInOut(win(t, ARRIVE + 0.5, 0.5)) * (1 - easeInOut(win(t, 7.1, 0.6)));
+    armL.top.rotation.x = SWING * 1.1 * Math.sin(phase) * walking;
+    armL.top.rotation.z = 0.12;
+    armR.top.rotation.x = -SWING * 1.1 * Math.sin(phase) * walking;
+    armR.top.rotation.z = lerp(-0.12, -2.55, wave);
+    armR.lower.rotation.z = -lerp(0, 0.35 + 0.45 * Math.sin((t - ARRIVE) * Math.PI * 2 * 1.6), wave);
+    armL.lower.rotation.x = -0.25;
+    figure.head.rotation.z = Math.sin((t - ARRIVE) * 3) * 0.08 * wave;
+
+    // Text: the caption and eyebrow hold; the beat label follows his head through the shot.
+    show(caption, inOut(t, 0.4, 7.6));
+    show(eyebrow, inOut(t, 0.2, 7.6));
+    holder.updateMatrixWorld(true);
+    figure.head.getWorldPosition(head).y += 0.35;
+    const p = stage.project(head, camera), label = inOut(t, ARRIVE + 0.4, 7.6);
+    leader.clear().moveTo(p.x, p.y).lineTo(p.x + 70, p.y - 70).lineTo(p.x + 110, p.y - 70).stroke({ color: 0x3b2414, width: 3 }).circle(p.x, p.y, 6).fill(0x3b2414);
+    show(leader, label);
+    beat.position.set(p.x + 120, p.y - 90);
+    show(beat, label);
+    stage.draw(scene, camera);
+  };
+};
+export default study;

package/templates/video/src/studies/three/exploded-teardown-3d.ts

@@ -0,0 +1,214 @@
+import { FillGradient, Graphics, type Text } from "pixi.js";
+import { RoundedBoxGeometry } from "three/addons/geometries/RoundedBoxGeometry.js";
+import { THREE, ThreeStage, clamp01, easeInOut, lerp, rng, show, txt, win } from "../../kit";
+import type { ThreeStudy } from ".";
+
+/*
+  3D Exploded Teardown study: an invented handheld console modelled in code lies on a studio-grey set while the
+  camera orbits; its parts lift apart along the assembly axis in order, hold, and close again. Each part keeps a
+  numbered callout that follows it through the turn (the battery is named), drawn in Pixi over the three.js stage.
+  Parts, dimensions and the console are illustrative. Replace them with the product's own CAD (exported to GLB)
+  for a real product. Every value is a function of seconds.
+*/
+
+const W = 3.3, D = 1.62, R = 0.4;
+const INK = 0x1d2226, ACCENT = 0xe2552b;
+
+function rounded(width: number, height: number, radius: number, cx = 0, cy = 0, path = new THREE.Shape()) {
+  const x = cx - width / 2, y = cy - height / 2, r = Math.min(radius, width / 2, height / 2);
+  path.moveTo(x + r, y);
+  path.lineTo(x + width - r, y); path.quadraticCurveTo(x + width, y, x + width, y + r);
+  path.lineTo(x + width, y + height - r); path.quadraticCurveTo(x + width, y + height, x + width - r, y + height);
+  path.lineTo(x + r, y + height); path.quadraticCurveTo(x, y + height, x, y + height - r);
+  path.lineTo(x, y + r); path.quadraticCurveTo(x, y, x + r, y);
+  return path;
+}
+function circle(x: number, y: number, r: number) { const p = new THREE.Path(); p.absarc(x, y, r, 0, Math.PI * 2, true); return p; }
+function cross(cx: number, cy: number, arm: number, width: number) {
+  const s = new THREE.Shape(), w = width / 2;
+  ([[-w, arm], [w, arm], [w, w], [arm, w], [arm, -w], [w, -w], [w, -arm], [-w, -arm], [-w, -w], [-arm, -w], [-arm, w], [-w, w]] as const)
+    .forEach(([x, y], i) => (i ? s.lineTo(cx + x, cy + y) : s.moveTo(cx + x, cy + y)));
+  s.closePath();
+  return s;
+}
+/** A plan Shape (x right, y toward the back) extruded upward from y = 0 with softened edges. */
+function slab(shape: THREE.Shape, depth: number, bevel = 0.02) {
+  const geometry = new THREE.ExtrudeGeometry(shape, { depth: depth - bevel * 2, bevelEnabled: bevel > 0, bevelThickness: bevel, bevelSize: bevel, bevelSegments: 4, curveSegments: 24 });
+  geometry.rotateX(-Math.PI / 2);
+  geometry.translate(0, bevel, 0);
+  return geometry;
+}
+function mesh(geometry: THREE.BufferGeometry, material: THREE.Material, x = 0, y = 0, z = 0) {
+  const m = new THREE.Mesh(geometry, material);
+  m.position.set(x, y, z);
+  m.castShadow = m.receiveShadow = true;
+  return m;
+}
+/** Seeded board artwork, so every render draws the same traces. */
+function boardTexture() {
+  const canvas = document.createElement("canvas");
+  canvas.width = 1024; canvas.height = 512;
+  const g = canvas.getContext("2d")!, next = rng(81);
+  g.fillStyle = "#1b5a45"; g.fillRect(0, 0, 1024, 512);
+  g.lineCap = "round";
+  for (let i = 0; i < 90; i++) {
+    let x = next() * 1024, y = next() * 512;
+    g.strokeStyle = next() < 0.2 ? "rgba(214,176,92,.85)" : "rgba(64,140,104,.9)";
+    g.lineWidth = next() < 0.2 ? 4 : 2;
+    g.beginPath(); g.moveTo(x, y);
+    for (let s = 0; s < 3; s++) { const len = 30 + next() * 110, dir = Math.floor(next() * 8) * Math.PI / 4; x += Math.cos(dir) * len; y += Math.sin(dir) * len; g.lineTo(x, y); }
+    g.stroke();
+    g.fillStyle = "#d8b45e"; g.beginPath(); g.arc(x, y, 4, 0, Math.PI * 2); g.fill();
+  }
+  const map = new THREE.CanvasTexture(canvas);
+  map.colorSpace = THREE.SRGBColorSpace;
+  return map;
+}
+
+type Part = { group: THREE.Group; number: string; side: -1 | 1; lift: number; order: number; anchor: THREE.Vector3 };
+
+const study: ThreeStudy = async (root, lines) => {
+  const stage = new ThreeStage({ width: 1920, height: 1080 });
+  const scene = new THREE.Scene();
+  scene.environment = stage.room();
+  scene.environmentIntensity = 0.9;
+  const camera = new THREE.PerspectiveCamera(28, 1920 / 1080, 0.1, 80);
+
+  const pbr = (color: number, roughness: number, extra: THREE.MeshPhysicalMaterialParameters = {}) => new THREE.MeshPhysicalMaterial({ color, roughness, ...extra });
+  const shell = pbr(0xeae6df, 0.48, { clearcoat: 0.25, clearcoatRoughness: 0.5 });
+  const shellDark = pbr(0x5d6369, 0.5, { clearcoat: 0.2, clearcoatRoughness: 0.55 });
+  const chip = pbr(0x1b1d20, 0.42);
+  const metal = new THREE.MeshStandardMaterial({ color: 0xb9bec4, metalness: 1, roughness: 0.3 });
+
+  const parts: Part[] = [];
+  const part = (number: string, side: -1 | 1, lift: number, order: number, anchor: [number, number, number]) => {
+    const group = new THREE.Group();
+    parts.push({ group, number, side, lift, order, anchor: new THREE.Vector3(...anchor) });
+    return group;
+  };
+
+  const back = part("6", 1, -0.95, 0, [1.55, 0.24, 0.2]);
+  back.add(mesh(slab(rounded(W, D, R), 0.07, 0.03), shellDark));
+  const wall = rounded(W, D, R); wall.holes.push(rounded(W - 0.12, D - 0.12, R - 0.06));
+  back.add(mesh(slab(wall, 0.19, 0.012), shellDark, 0, 0.05));
+
+  const battery = part("5", 1, -0.42, 6, [0.62, 0.148, 0.26]);
+  battery.add(mesh(new RoundedBoxGeometry(1.5, 0.07, 0.8, 4, 0.03), new THREE.MeshStandardMaterial({ color: 0x3a63c9, metalness: 0.3, roughness: 0.45 }), 0, 0.11, 0.05));
+
+  const board = part("4", -1, 0.02, 5, [-1.3, 0.24, 0.48]);
+  board.add(mesh(new RoundedBoxGeometry(3.0, 0.035, 1.36, 2, 0.012), new THREE.MeshStandardMaterial({ map: boardTexture(), roughness: 0.55 }), 0, 0.22, 0));
+  for (const [x, z, size] of [[0.05, -0.08, 0.42], [0.5, -0.12, 0.26], [0.5, 0.28, 0.24], [-0.42, 0.3, 0.16]]) board.add(mesh(new RoundedBoxGeometry(size, 0.04, size, 2, 0.006), chip, x, 0.257, z));
+
+  const display = part("3", 1, 0.78, 4, [0.86, 0.336, 0.56]);
+  display.add(mesh(new RoundedBoxGeometry(1.86, 0.05, 1.28, 3, 0.02), metal, 0, 0.31, 0));
+  const panel = new THREE.Mesh(new THREE.PlaneGeometry(1.7, 1.12), new THREE.MeshStandardMaterial({ color: 0x000000, emissive: 0xe9805f, emissiveIntensity: 0.9, roughness: 0.25 }));
+  panel.rotation.x = -Math.PI / 2; panel.position.y = 0.337;
+  display.add(panel);
+
+  const keys = part("2", -1, 0.84, 3, [-1.5, 0.5, 0]);
+  keys.add(mesh(slab(cross(-1.25, 0, 0.27, 0.17), 0.12, 0.025), shellDark, 0, 0.38));
+  const cap = new THREE.LatheGeometry([[0, 0], [0.115, 0], [0.12, 0.05], [0.112, 0.085], [0.07, 0.1], [0, 0.103]].map(([x, y]) => new THREE.Vector2(x, y)), 40);
+  keys.add(mesh(cap, pbr(0xe2552b, 0.35, { clearcoat: 0.6 }), 1.38, 0.38, -0.08), mesh(cap, pbr(0x2f6f86, 0.35, { clearcoat: 0.6 }), 1.06, 0.38, 0.24));
+
+  const front = part("1", 1, 1.55, 2, [1.52, 0.44, 0.42]);
+  const face = rounded(W, D, R);
+  face.holes.push(rounded(1.86, 1.28, 0.08), cross(-1.25, 0, 0.3, 0.2), circle(1.38, 0.08, 0.13), circle(1.06, -0.24, 0.13));
+  front.add(mesh(slab(face, 0.08, 0.03), shell, 0, 0.36));
+  const lip = rounded(W, D, R); lip.holes.push(rounded(W - 0.12, D - 0.12, R - 0.06));
+  front.add(mesh(slab(lip, 0.09, 0.012), shell, 0, 0.27));
+
+  const product = new THREE.Group();
+  for (const p of parts) product.add(p.group);
+  scene.add(product);
+  const key = new THREE.DirectionalLight(0xfff4e8, 2.4);
+  key.position.set(-3.5, 7, 4);
+  key.castShadow = true;
+  key.shadow.mapSize.set(2048, 2048);
+  Object.assign(key.shadow.camera, { left: -4, right: 4, top: 4, bottom: -4, near: 1, far: 20 });
+  key.shadow.radius = 5;
+  key.shadow.normalBias = 0.02;
+  const ground = new THREE.Mesh(new THREE.PlaneGeometry(60, 60), new THREE.ShadowMaterial({ opacity: 0.18 }));
+  ground.rotation.x = -Math.PI / 2;
+  ground.position.y = -2;
+  ground.receiveShadow = true;
+  scene.add(key, new THREE.DirectionalLight(0xdce8ff, 0.8).translateX(4).translateY(3).translateZ(-5), ground);
+
+  // 2D layers: the studio ground behind the transparent 3D, then leaders, numbered callouts and type on top.
+  const backdrop = new Graphics().rect(0, 0, 1920, 1080).fill(new FillGradient({ start: { x: 0, y: 0 }, end: { x: 0, y: 1 }, colorStops: [{ offset: 0, color: "#e6e7e8" }, { offset: 1, color: "#b3b7bb" }] }));
+  const leaders = new Graphics();
+  const badges = parts.map((p) => {
+    const number = txt(p.number, 26, { family: "mono", weight: "700", fill: 0xffffff });
+    number.anchor.set(0.5);
+    return number;
+  });
+  const name = txt(lines[2], 34, { family: "heading", weight: "700", fill: INK });
+  const title = txt(lines[0], 60, { family: "heading", weight: "700", fill: INK });
+  title.position.set(110, 92);
+  const subtitle = txt(lines[1], 26, { family: "mono", weight: "400", fill: 0x5f666d });
+  subtitle.position.set(114, 178);
+  root.addChild(backdrop, stage.sprite, leaders, ...badges, name, title, subtitle);
+
+  const TRAVEL = 1.25, CLOSE = 6.45;
+  const start = (p: Part) => 0.8 + p.order * 0.2;
+  const amount = (p: Part, t: number) => easeInOut(win(t, start(p), TRAVEL)) * (1 - easeInOut(win(t, CLOSE + (6 - p.order) * 0.05, 0.9)));
+  const point = new THREE.Vector3();
+  await stage.warm(scene, camera);
+
+  return (t) => {
+    let open = 0;
+    for (const p of parts) { const f = amount(p, t); open = Math.max(open, f); p.group.position.y = p.lift * f; }
+    const k = easeInOut(t / 8);
+    const azimuth = lerp(-0.6, 0.48, k), elevation = lerp(0.62, 0.5, k), distance = lerp(8.2, 12.6, easeInOut(open));
+    const center = lerp(0.22, 0.4, open);
+    camera.position.set(Math.sin(azimuth) * Math.cos(elevation) * distance, center + Math.sin(elevation) * distance, Math.cos(azimuth) * Math.cos(elevation) * distance);
+    camera.lookAt(0, center, 0);
+    product.updateMatrixWorld(true);
+    show(title, clamp01(t / 0.5));
+    show(subtitle, clamp01((t - 0.3) / 0.5));
+
+    // Callouts sit just outside the stack's silhouette on their side, kept a badge apart in anchor order.
+    const box = new THREE.Box3().setFromObject(product);
+    let minX = Infinity, maxX = -Infinity;
+    for (let i = 0; i < 8; i++) {
+      point.set(i & 1 ? box.max.x : box.min.x, i & 2 ? box.max.y : box.min.y, i & 4 ? box.max.z : box.min.z);
+      const s = stage.project(point, camera);
+      minX = Math.min(minX, s.x); maxX = Math.max(maxX, s.x);
+    }
+    const placed = parts.map((p, i) => {
+      point.copy(p.anchor).applyMatrix4(p.group.matrixWorld);
+      const a = stage.project(point, camera);
+      return { p, a, y: a.y, badge: badges[i], alpha: clamp01((t - start(p) - TRAVEL * 0.7) / 0.4) * (1 - clamp01((t - CLOSE + 0.35) / 0.3)) };
+    });
+    for (const side of [-1, 1]) {
+      const column = placed.filter((l) => l.p.side === side).sort((a, b) => a.a.y - b.a.y);
+      for (let pass = 0; pass < 6; pass++) {
+        for (let i = 1; i < column.length; i++) column[i].y = Math.max(column[i].y, column[i - 1].y + 86);
+        for (let i = column.length - 2; i >= 0; i--) column[i].y = Math.min(column[i].y, column[i + 1].y - 86);
+        for (const l of column) l.y = Math.min(Math.max(l.y, 260), 1010);
+      }
+    }
+    leaders.clear();
+    show(name, 0);
+    for (const { p, a, y, badge, alpha } of placed) {
+      show(badge, alpha);
+      if (alpha <= 0.002) continue;
+      const x = p.side < 0 ? Math.min(minX - 70, a.x - 120) : Math.max(maxX + 70, a.x + 120);
+      leaders.moveTo(a.x, a.y).lineTo(x - p.side * 30, y).lineTo(x, y).stroke({ color: INK, width: 2.4, alpha: 0.8 * alpha });
+      leaders.circle(a.x, a.y, 8).fill({ color: 0xffffff, alpha }).stroke({ color: INK, width: 3, alpha });
+      leaders.circle(x + p.side * 26, y, 26).fill({ color: p.number === "5" ? ACCENT : INK, alpha });
+      badge.position.set(x + p.side * 26, y);
+      if (p.number === "5") placeName(name, x + p.side * 68, y, p.side, alpha);
+    }
+
+    stage.draw(scene, camera);
+  };
+};
+
+/** The battery's name beside its callout, on the callout's side. */
+function placeName(name: Text, x: number, y: number, side: -1 | 1, alpha: number) {
+  name.anchor.set(side < 0 ? 1 : 0, 0.5);
+  name.position.set(x, y);
+  show(name, alpha);
+}
+
+export default study;