@docyrus/animaguru 0.27.0 → 0.29.0

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;

package/templates/video/src/studies/three/index.ts

@@ -0,0 +1,16 @@
+import type { Container } from "pixi.js";
+
+/**
+ * A 3D study builds its stage and Pixi layers into `root` (1920×1080 design space) and returns the frame update,
+ * a pure function of seconds that ends with stage.draw(). `lines` are its localized on-screen texts.
+ */
+export type ThreeStudy = (root: Container, lines: readonly string[]) => Promise<(seconds: number) => void>;
+
+/** Loaded on demand, so a film only bundles the study it installs. */
+export const THREE_STUDIES = {
+  "product-turntable-3d": () => import("./product-turntable-3d").then((m) => m.default),
+  "character-stage-3d": () => import("./character-stage-3d").then((m) => m.default),
+  "toy-diorama-3d": () => import("./toy-diorama-3d").then((m) => m.default),
+  "exploded-teardown-3d": () => import("./exploded-teardown-3d").then((m) => m.default),
+} satisfies Record<string, () => Promise<ThreeStudy>>;
+export type ThreeStudyId = keyof typeof THREE_STUDIES;

package/templates/video/src/studies/three/product-turntable-3d.ts

@@ -0,0 +1,160 @@
+import { Container, Graphics } from "pixi.js";
+import { THREE, ThreeStage, clamp01, easeInOut, easeOut, lerp, show, txt, vecAt, win } from "../../kit";
+import type { ThreeStudy } from ".";
+
+/*
+  3D Product Turntable study: an original product turned on a lathe in code (a ceramic body, a brushed metal band
+  and a dark cap) turns on a stone plinth in a dark studio. A macro on the band, a pull-back while the turntable
+  keeps turning, rack focus with a depth-of-field pass, a callout pinned to the band through the orbit, then a
+  push-in with the product on the right third and the title on the left. Replace the product with a supplied or
+  generated model (animaguru-3d-models) for a real film.
+*/
+
+const PLINTH = 0.16;
+const INK = 0xf3ead8, ACCENT = 0xc89a62;
+/** A constant turntable: 10° a second. */
+const turn = (t: number) => (20 + 10 * t) * Math.PI / 180;
+
+/** Radius by height for the lathe: a soft-shouldered body that narrows into a neck. */
+function bodyProfile() {
+  const points: THREE.Vector2[] = [];
+  for (let i = 0; i <= 48; i++) {
+    const y = i / 48 * 0.78;
+    const shoulder = Math.max(0, (y - 0.58) / 0.2);
+    const r = 0.2 + 0.035 * Math.sin(Math.min(1, y / 0.58) * Math.PI) - 0.07 * shoulder * shoulder;
+    points.push(new THREE.Vector2(Math.max(0.105, r), y));
+  }
+  points.unshift(new THREE.Vector2(0, 0));
+  points.push(new THREE.Vector2(0, 0.78));
+  return points;
+}
+
+function backdrop() {
+  // A seamless sweep: near black above, a warm band at the horizon, ignoring fog so the floor fades into it.
+  return new THREE.Mesh(new THREE.SphereGeometry(16, 64, 32), new THREE.ShaderMaterial({
+    side: THREE.BackSide, depthWrite: false, fog: false,
+    uniforms: { top: { value: new THREE.Color(0x040303) }, horizon: { value: new THREE.Color(0x15110e) } },
+    vertexShader: "varying vec3 vDir; void main() { vDir = normalize(position); gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }",
+    fragmentShader: "uniform vec3 top; uniform vec3 horizon; varying vec3 vDir; void main() { gl_FragColor = vec4(mix(horizon, top, smoothstep(-0.05, 0.55, vDir.y)), 1.0); }",
+  }));
+}
+
+const study: ThreeStudy = async (root, lines) => {
+  const stage = new ThreeStage({ width: 1920, height: 1080, supersample: 1.5 });
+  stage.renderer.toneMappingExposure = 1;
+  const scene = new THREE.Scene();
+  scene.environment = stage.room();
+  scene.environmentIntensity = 0.75;
+  scene.fog = new THREE.Fog(0x15110e, 3, 9);
+  scene.add(backdrop());
+
+  const floor = new THREE.Mesh(new THREE.CircleGeometry(15, 96), new THREE.MeshStandardMaterial({ color: 0x0e0c0a, roughness: 0.75 }));
+  floor.rotation.x = -Math.PI / 2;
+  floor.receiveShadow = true;
+  const plinth = new THREE.Mesh(new THREE.CylinderGeometry(0.5, 0.52, PLINTH, 128), new THREE.MeshPhysicalMaterial({ color: 0x14110f, roughness: 0.4, clearcoat: 0.5, clearcoatRoughness: 0.25 }));
+  plinth.position.y = PLINTH / 2;
+  plinth.castShadow = plinth.receiveShadow = true;
+  scene.add(floor, plinth);
+
+  // The product: ceramic body, brushed band, dark cap. All parts turn together on the plinth.
+  const product = new THREE.Group();
+  product.position.y = PLINTH;
+  const body = new THREE.Mesh(new THREE.LatheGeometry(bodyProfile(), 128), new THREE.MeshPhysicalMaterial({ color: 0xd9cfbf, roughness: 0.38, clearcoat: 0.5, clearcoatRoughness: 0.3 }));
+  const band = new THREE.Mesh(new THREE.CylinderGeometry(0.236, 0.236, 0.07, 128, 1, true), new THREE.MeshPhysicalMaterial({ color: 0xd6d9dd, metalness: 1, roughness: 0.16, side: THREE.DoubleSide }));
+  band.position.y = 0.3;
+  const cap = new THREE.Mesh(new THREE.CylinderGeometry(0.098, 0.11, 0.16, 96), new THREE.MeshPhysicalMaterial({ color: 0x2a2826, metalness: 0.85, roughness: 0.32 }));
+  cap.position.y = 0.86;
+  const seam = new THREE.Mesh(new THREE.TorusGeometry(0.106, 0.006, 12, 96), new THREE.MeshStandardMaterial({ color: 0xc89a62, metalness: 1, roughness: 0.25 }));
+  seam.rotation.x = Math.PI / 2;
+  seam.position.y = 0.785;
+  for (const part of [body, band, cap, seam]) { part.castShadow = part.receiveShadow = true; product.add(part); }
+  scene.add(product);
+
+  const key = new THREE.SpotLight(0xfff0de, 22, 12, 0.42, 0.8, 1.6);
+  key.position.set(-1.7, 3, 2.2);
+  key.target.position.set(0, 0.55, 0);
+  key.castShadow = true;
+  key.shadow.mapSize.set(2048, 2048);
+  key.shadow.radius = 6;
+  key.shadow.bias = -0.0003;
+  const rim = new THREE.SpotLight(0xffb070, 22, 10, 0.34, 0.8, 1.5);
+  rim.position.set(1.8, 2.5, -2.2);
+  rim.target.position.set(0, 0.7, 0);
+  scene.add(key, key.target, rim, rim.target);
+
+  const camera = new THREE.PerspectiveCamera(28, 1920 / 1080, 0.02, 60);
+  const depth = stage.post(scene, camera, { bokeh: { focus: 1.5, aperture: 0.005, maxblur: 0.008 } })!;
+  const focusUniforms = depth.uniforms as Record<string, { value: number }>;
+
+  // 2D layers: an eyebrow, a callout on the band, and the closing title.
+  const overlay = new Container();
+  const eyebrow = txt(lines[1].toUpperCase(), 26, { family: "mono", fill: 0xb7aa96 });
+  eyebrow.position.set(120, 96);
+  const leader = new Graphics();
+  const label = txt(lines[2], 40, { family: "heading", weight: "600", fill: INK });
+  const title = txt(lines[0], 84, { family: "heading", weight: "700", fill: INK, wordWrap: true, wordWrapWidth: 760 });
+  title.position.set(120, 420);
+  const rule = new Graphics();
+  overlay.addChild(eyebrow, leader, label, title, rule);
+  root.addChild(stage.sprite, overlay);
+
+  const centre = new THREE.Vector3(), target = new THREE.Vector3(), focus = new THREE.Vector3(), offset = new THREE.Vector3(), right = new THREE.Vector3();
+  const anchor = new THREE.Vector3(), toward = new THREE.Vector3();
+  /** The band point nearest the camera: the ring is round, so the callout stays on its front while the product turns. */
+  const bandPoint = (out: THREE.Vector3) => {
+    toward.set(camera.position.x, 0, camera.position.z).normalize();
+    return out.set(toward.x * 0.236, PLINTH + 0.3, toward.z * 0.236);
+  };
+
+  function pose(t: number) {
+    product.rotation.y = turn(t);
+    centre.set(0, PLINTH + 0.45, 0);
+    const [az, el, dist] = vecAt(t, [[0, [34, 6, 1.05]], [1.6, [26, 8, 1.15]], [3.6, [6, 13, 2.6]], [6, [-8, 15, 2.5]], [8, [-14, 16, 2.25]]], offset).toArray();
+    const macro = 1 - easeInOut(win(t, 1.4, 2.1));
+    target.set(0, PLINTH + 0.3, 0.2).lerp(centre, 1 - macro);
+    const a = az * Math.PI / 180, e = el * Math.PI / 180;
+    camera.position.set(target.x + dist * Math.cos(e) * Math.sin(a), target.y + dist * Math.sin(e), target.z + dist * Math.cos(e) * Math.cos(a));
+    camera.lookAt(target);
+    camera.updateMatrixWorld(true);
+    // The closing push-in slides the product to the right third.
+    const slide = easeInOut(win(t, 5, 1.5));
+    right.setFromMatrixColumn(camera.matrixWorld, 0);
+    camera.position.addScaledVector(right, -0.32 * slide);
+    target.addScaledVector(right, -0.32 * slide);
+    camera.lookAt(target);
+    // Rack focus: the band, then the cap, then the whole product.
+    focus.copy(bandPoint(anchor)).lerp(cap.getWorldPosition(new THREE.Vector3()), easeInOut(win(t, 2.6, 0.8))).lerp(centre, easeInOut(win(t, 4.6, 0.8)));
+    focusUniforms.focus.value = camera.position.distanceTo(focus);
+    focusUniforms.aperture.value = lerp(0.005, 0.002, easeInOut(win(t, 1.4, 2.2)));
+    // Reflections slide across the band and cap as the studio turns.
+    scene.environmentRotation.set(0, lerp(-0.6, 0.6, t / 8), 0);
+  }
+
+  function layers(t: number) {
+    show(eyebrow, clamp01(t / 0.5) * (1 - clamp01((t - 4.8) / 0.4)));
+    // The callout rides the band's front through the orbit, then gives way to the title.
+    const on = easeOut(win(t, 0.5, 0.5)) * (1 - easeOut(win(t, 4.2, 0.4)));
+    const p = stage.project(bandPoint(anchor), camera);
+    const draw = easeOut(win(t, 0.5, 0.6));
+    const elbow = { x: p.x + 90 * Math.min(1, draw * 2), y: p.y - 90 * Math.min(1, draw * 2) };
+    const end = { x: p.x + 90 + 230 * clamp01(draw * 2 - 1), y: p.y - 90 };
+    leader.clear().moveTo(p.x, p.y).lineTo(elbow.x, elbow.y).lineTo(end.x, end.y).stroke({ color: INK, width: 2.5 }).circle(p.x, p.y, 7).fill(INK);
+    show(leader, on);
+    label.position.set(p.x + 100, p.y - 146);
+    show(label, on * clamp01((t - 0.8) / 0.4));
+    const lockup = easeOut(win(t, 6, 0.8));
+    show(title, lockup);
+    title.x = 120 - 30 * (1 - lockup);
+    rule.clear().rect(122, 620, 420 * easeOut(win(t, 6.3, 0.9)), 3).fill(ACCENT);
+    show(rule, lockup);
+  }
+
+  pose(0);
+  await stage.warm(scene, camera);
+  return (t) => {
+    pose(t);
+    layers(t);
+    stage.draw(scene, camera);
+  };
+};
+export default study;

package/templates/video/src/studies/three/toy-diorama-3d.ts

@@ -0,0 +1,245 @@
+import { Graphics } from "pixi.js";
+import { RoundedBoxGeometry } from "three/addons/geometries/RoundedBoxGeometry.js";
+import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js";
+import { THREE, ThreeStage, clamp01, inOut, lerp, rng, show, txt } from "../../kit";
+import type { ThreeStudy } from ".";
+
+/*
+  3D Toy Diorama study: a block-toy harbour town on a round birch base, built in code. Cars run a road loop and
+  boats a bay loop, each a CatmullRom curve sampled by film time; the camera glides along its own curve; a
+  separable tilt-shift pass keeps one band sharp around the point the camera looks at. A production film swaps
+  the blocks for generated toy models (animaguru-3d-models) placed on the same base and paths.
+*/
+
+const R = 3.3, WATER = 0.15, LAND = 0.27, TABLE = -0.24;
+/** The bay's shoreline: land behind it (smaller z), water in front. */
+const shore = (x: number) => 0.25 + 0.17 * x * x;
+
+const vertex = "varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }";
+/** One direction of the tilt-shift blur: sharp inside a band around `center` (0 bottom, 1 top), up to `amount` pixels outside it. */
+const tiltShift = (direction: THREE.Vector2) => ({
+  uniforms: { tDiffuse: { value: null }, center: { value: 0.5 }, band: { value: 0.07 }, falloff: { value: 0.32 }, amount: { value: 22 }, texel: { value: new THREE.Vector2() }, direction: { value: direction } },
+  vertexShader: vertex,
+  fragmentShader: `
+    uniform sampler2D tDiffuse; uniform float center, band, falloff, amount; uniform vec2 texel, direction; varying vec2 vUv;
+    void main() {
+      float d = smoothstep(band, band + falloff, abs(vUv.y - center));
+      float radius = amount * d * d;
+      vec4 sum = vec4(0.0); float weight = 0.0;
+      for (int i = -7; i <= 7; i++) { float k = float(i) / 7.0, w = exp(-3.0 * k * k); sum += texture2D(tDiffuse, vUv + direction * texel * radius * k) * w; weight += w; }
+      gl_FragColor = sum / weight;
+    }`,
+});
+/** Toy-photo grade before tone mapping: more saturation, a warm cast. */
+const grade = {
+  uniforms: { tDiffuse: { value: null } },
+  vertexShader: vertex,
+  fragmentShader: "uniform sampler2D tDiffuse; varying vec2 vUv; void main() { vec4 c = texture2D(tDiffuse, vUv); float l = dot(c.rgb, vec3(0.2126, 0.7152, 0.0722)); c.rgb = mix(vec3(l), c.rgb, 1.2) * vec3(1.05, 1.0, 0.93); gl_FragColor = c; }",
+};
+
+/** A flat ribbon along a curve (road, promenade). */
+function ribbon(curve: THREE.Curve<THREE.Vector3>, width: number, y: number, samples = 300) {
+  const positions: number[] = [], index: number[] = [];
+  for (let i = 0; i <= samples; i++) {
+    const u = (i / samples) % 1, p = curve.getPointAt(u), tangent = curve.getTangentAt(u);
+    const side = new THREE.Vector3(-tangent.z, 0, tangent.x).normalize().multiplyScalar(width / 2);
+    positions.push(p.x - side.x, y, p.z - side.z, p.x + side.x, y, p.z + side.z);
+    if (i < samples) { const a = i * 2; index.push(a, a + 1, a + 2, a + 1, a + 3, a + 2); }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+  geometry.setIndex(index);
+  geometry.computeVertexNormals();
+  return geometry;
+}
+
+/** The land behind the shoreline, extruded up from the base; its sides are the quay wall. */
+function land() {
+  let edge = 0;
+  for (let x = 0; x < R; x += 0.001) if (x * x + shore(x) ** 2 > R * R) { edge = x; break; }
+  const shape = new THREE.Shape(), steps = 100;
+  for (let i = 0; i <= steps; i++) { const x = lerp(-edge, edge, i / steps); if (i) shape.lineTo(x, -shore(x)); else shape.moveTo(x, -shore(x)); }
+  const a0 = Math.atan2(-shore(edge), edge), a1 = Math.atan2(-shore(-edge), -edge) + Math.PI * 2;
+  for (let i = 1; i <= steps; i++) { const a = lerp(a0, a1, i / steps); shape.lineTo(Math.cos(a) * R, Math.sin(a) * R); }
+  const geometry = new THREE.ExtrudeGeometry(shape, { depth: LAND - WATER + 0.03, bevelEnabled: true, bevelThickness: 0.012, bevelSize: 0.012, bevelSegments: 3, curveSegments: 48 });
+  geometry.rotateX(-Math.PI / 2);
+  // The bevel adds thickness on both faces: put the top exactly at land level.
+  geometry.computeBoundingBox();
+  geometry.translate(0, LAND - geometry.boundingBox!.max.y, 0);
+  return geometry;
+}
+
+const study: ThreeStudy = async (root, lines) => {
+  const stage = new ThreeStage({ width: 1920, height: 1080, supersample: 1.5 });
+  const scene = new THREE.Scene();
+  const room = new THREE.Color(0x2b2119);
+  scene.background = room;
+  scene.fog = new THREE.Fog(room, 11, 22);
+  scene.environment = stage.room(0.05);
+  scene.environmentIntensity = 0.45;
+  const camera = new THREE.PerspectiveCamera(30, 1920 / 1080, 0.1, 60);
+  const sun = new THREE.DirectionalLight(0xffe2b8, 3.2);
+  sun.position.set(-5.5, 7, 3.5);
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(2048, 2048);
+  Object.assign(sun.shadow.camera, { left: -4.2, right: 4.2, top: 4.2, bottom: -4.2, near: 1, far: 20 });
+  sun.shadow.radius = 3;
+  sun.shadow.bias = -0.0004;
+  scene.add(sun, new THREE.HemisphereLight(0xcfe0ff, 0x7a5a3a, 0.9));
+
+  const paint = (color: number, roughness = 0.42) => new THREE.MeshStandardMaterial({ color, roughness });
+  const add = <T extends THREE.Mesh>(mesh: T) => { mesh.castShadow = mesh.receiveShadow = true; scene.add(mesh); return mesh; };
+  const table = add(new THREE.Mesh(new THREE.PlaneGeometry(40, 40), paint(0x7a4e2c, 0.65)));
+  table.rotation.x = -Math.PI / 2;
+  table.position.y = TABLE;
+  add(new THREE.Mesh(new THREE.LatheGeometry([new THREE.Vector2(0, TABLE), new THREE.Vector2(R + 0.02, TABLE), new THREE.Vector2(R + 0.09, TABLE + 0.04), new THREE.Vector2(R + 0.1, WATER - 0.05), new THREE.Vector2(R + 0.06, WATER - 0.01), new THREE.Vector2(0, WATER - 0.01)], 96), paint(0xdcbc8f, 0.5)));
+  const water = add(new THREE.Mesh(new THREE.CircleGeometry(R + 0.02, 96), new THREE.MeshPhysicalMaterial({ color: 0x2d8fa3, roughness: 0.1, clearcoat: 1, clearcoatRoughness: 0.05 })));
+  water.rotation.x = -Math.PI / 2;
+  water.position.y = WATER;
+  add(new THREE.Mesh(land(), [paint(0x9fc27a, 0.85), paint(0xbfb39b, 0.8)]));
+  const promenade = new THREE.CatmullRomCurve3(Array.from({ length: 9 }, (_, i) => { const x = lerp(-2.2, 2.2, i / 8); return new THREE.Vector3(x, 0, shore(x) - 0.27); }));
+  add(new THREE.Mesh(ribbon(promenade, 0.3, LAND + 0.002), paint(0xe6dcc6, 0.8)));
+  const road = new THREE.CatmullRomCurve3([
+    ...Array.from({ length: 9 }, (_, i) => { const x = lerp(-2.2, 2.2, i / 8); return new THREE.Vector3(x, 0, shore(x) - 0.62); }),
+    new THREE.Vector3(2.6, 0, -0.55), new THREE.Vector3(2.05, 0, -1.75), new THREE.Vector3(0.8, 0, -2.45), new THREE.Vector3(-0.8, 0, -2.45), new THREE.Vector3(-2.05, 0, -1.75), new THREE.Vector3(-2.6, 0, -0.55),
+  ], true, "centripetal");
+  add(new THREE.Mesh(ribbon(road, 0.34, LAND + 0.004), paint(0x5a6470, 0.7)));
+
+  // Block-toy houses with pitched roofs, a tower, a lighthouse and lollipop trees.
+  const next = rng(11);
+  const house = (x: number, z: number, w: number, h: number, wall: number, roof: number, yaw: number) => {
+    const group = new THREE.Group();
+    const body = new THREE.Mesh(new RoundedBoxGeometry(w, h, 0.34, 3, 0.025), paint(wall));
+    body.position.y = h / 2;
+    // A pitched roof: a triangle extruded across the house's width.
+    const gable = new THREE.Shape([new THREE.Vector2(-0.21, 0), new THREE.Vector2(0.21, 0), new THREE.Vector2(0, 0.2)]);
+    const roofGeometry = new THREE.ExtrudeGeometry(gable, { depth: w + 0.04, bevelEnabled: true, bevelThickness: 0.01, bevelSize: 0.01, bevelSegments: 2 });
+    roofGeometry.translate(0, 0, -(w + 0.04) / 2);
+    roofGeometry.rotateY(Math.PI / 2);
+    const top = new THREE.Mesh(roofGeometry, paint(roof, 0.5));
+    top.position.y = h - 0.005;
+    for (const side of [-1, 1]) {
+      const window = new THREE.Mesh(new RoundedBoxGeometry(0.08, 0.08, 0.02, 2, 0.008), paint(0xfff6e0, 0.3));
+      window.position.set(side * w * 0.24, h * 0.68, 0.175);
+      window.castShadow = true;
+      group.add(window);
+    }
+    const door = new THREE.Mesh(new RoundedBoxGeometry(0.08, 0.14, 0.02, 2, 0.01), paint(0x2f3b59));
+    door.position.set(0, 0.07, 0.175);
+    for (const mesh of [body, top, door]) { mesh.castShadow = mesh.receiveShadow = true; group.add(mesh); }
+    group.position.set(x, LAND, z);
+    group.rotation.y = yaw;
+    scene.add(group);
+  };
+  const colours = [0xe8705f, 0xf2c14e, 0x6fa8dc, 0xf3e3c3, 0x8fcfb3, 0xe58fb0];
+  for (let i = 0; i < 9; i++) {
+    const x = lerp(-2.15, 2.15, i / 8), z = -0.85 - Math.abs(x) * 0.08;
+    house(x, z, 0.38 + next() * 0.12, 0.38 + next() * 0.3, colours[i % colours.length], i % 2 ? 0xc0553a : 0xa64230, -x * 0.12);
+  }
+  const tower = add(new THREE.Mesh(new RoundedBoxGeometry(0.42, 1.05, 0.42, 3, 0.03), paint(0xf3e3c3)));
+  tower.position.set(-0.1, LAND + 0.525, -1.75);
+  const spire = add(new THREE.Mesh(new THREE.ConeGeometry(0.32, 0.45, 4), paint(0x3a9c9a)));
+  spire.position.set(-0.1, LAND + 1.27, -1.75);
+  spire.rotation.y = Math.PI / 4;
+  for (let i = 0; i < 4; i++) {
+    const band = add(new THREE.Mesh(new THREE.CylinderGeometry(0.17 - i * 0.012, 0.18 - i * 0.012, 0.22, 32), paint(i % 2 ? 0xf6f1e7 : 0xd7473b)));
+    band.position.set(-2.72, LAND + 0.11 + i * 0.22, 1.25);
+  }
+  const lantern = add(new THREE.Mesh(new THREE.SphereGeometry(0.13, 24, 16), new THREE.MeshStandardMaterial({ color: 0xfff3d6, emissive: 0xffc46b, emissiveIntensity: 1.6 })));
+  lantern.position.set(-2.72, LAND + 1.0, 1.25);
+  for (let i = 0; i < 16; i++) {
+    const a = (i / 16) * Math.PI * 2, rr = 2.45 + next() * 0.6, x = Math.cos(a) * rr, z = Math.min(Math.sin(a) * rr, -1.25 - next() * 0.4);
+    if (Math.abs(x) > 2.9 && z > -1) continue;
+    const trunk = add(new THREE.Mesh(new THREE.CylinderGeometry(0.025, 0.03, 0.18, 12), paint(0x8a5a35)));
+    trunk.position.set(x, LAND + 0.09, z);
+    const crown = add(new THREE.Mesh(new THREE.SphereGeometry(0.15 + next() * 0.06, 24, 16), paint(i % 3 ? 0x5fae5a : 0x3f8f4f, 0.55)));
+    crown.position.set(x, LAND + 0.3, z);
+  }
+
+  // Cars on the road loop, boats on the bay.
+  const vehicle = (colour: number, length: number) => {
+    const group = new THREE.Group();
+    const body = new THREE.Mesh(new RoundedBoxGeometry(0.15, 0.09, length, 3, 0.035), paint(colour, 0.3));
+    body.position.y = 0.075;
+    const cabin = new THREE.Mesh(new RoundedBoxGeometry(0.12, 0.07, length * 0.5, 3, 0.03), paint(0xf6f1e7, 0.35));
+    cabin.position.set(0, 0.145, -length * 0.08);
+    group.add(body, cabin);
+    for (const [x, z] of [[-0.075, length * 0.32], [0.075, length * 0.32], [-0.075, -length * 0.32], [0.075, -length * 0.32]]) {
+      const wheel = new THREE.Mesh(new THREE.CylinderGeometry(0.035, 0.035, 0.03, 20), paint(0x1d2327, 0.6));
+      wheel.rotation.z = Math.PI / 2;
+      wheel.position.set(x, 0.035, z);
+      group.add(wheel);
+    }
+    group.traverse((node) => { if ((node as THREE.Mesh).isMesh) node.castShadow = true; });
+    scene.add(group);
+    return group;
+  };
+  const car = vehicle(0xd23b30, 0.3), van = vehicle(0xf2c14e, 0.36);
+  const boat = (hull: number, sail: boolean) => {
+    const group = new THREE.Group();
+    const body = new THREE.Mesh(new RoundedBoxGeometry(0.2, 0.1, 0.5, 3, 0.045), paint(hull, 0.3));
+    body.position.y = 0.04;
+    group.add(body);
+    const top = sail ? new THREE.Mesh(new THREE.ConeGeometry(0.12, 0.42, 3), paint(0xf6efe0, 0.6)) : new THREE.Mesh(new RoundedBoxGeometry(0.14, 0.12, 0.16, 2, 0.02), paint(0xf6f1e7));
+    top.position.set(0, sail ? 0.3 : 0.15, sail ? 0.02 : -0.06);
+    if (sail) top.scale.set(0.25, 1, 1);
+    group.add(top);
+    group.traverse((node) => { if ((node as THREE.Mesh).isMesh) node.castShadow = true; });
+    scene.add(group);
+    return group;
+  };
+  const fishing = boat(0x2f4f8f, false), sailing = boat(0xf6f1e7, true);
+  const bay = new THREE.CatmullRomCurve3(Array.from({ length: 12 }, (_, i) => { const a = (i / 12) * Math.PI * 2; return new THREE.Vector3(Math.cos(a) * 1.45, 0, 1.75 + Math.sin(a) * 0.62); }), true);
+  const drive = (object: THREE.Object3D, curve: THREE.Curve<THREE.Vector3>, u: number, y: number) => {
+    const at = ((u % 1) + 1) % 1, p = curve.getPointAt(at), tangent = curve.getTangentAt(at);
+    object.position.set(p.x, y, p.z);
+    object.rotation.y = Math.atan2(tangent.x, tangent.z);
+  };
+
+  const cameraPath = new THREE.CatmullRomCurve3([new THREE.Vector3(-6.2, 5.6, 9.4), new THREE.Vector3(-2.6, 4.8, 9.2), new THREE.Vector3(1.2, 4.1, 8.6), new THREE.Vector3(4.2, 3.6, 7.2)]);
+  const targetPath = new THREE.CatmullRomCurve3([new THREE.Vector3(-1.2, 0.35, 0.15), new THREE.Vector3(-0.3, 0.32, 0.0), new THREE.Vector3(0.55, 0.3, -0.2), new THREE.Vector3(1.05, 0.3, -0.42)]);
+  const tiltH = new ShaderPass(tiltShift(new THREE.Vector2(1, 0))), tiltV = new ShaderPass(tiltShift(new THREE.Vector2(0, 1)));
+  for (const pass of [tiltH, tiltV]) pass.uniforms.texel.value.set(1 / (1920 * 1.5), 1 / (1080 * 1.5));
+  stage.post(scene, camera, { passes: [new ShaderPass(grade), tiltH, tiltV] });
+
+  // Type: a title, a bracket marking the sharp band, and a label riding the red car.
+  // A soft dark shadow keeps the light type readable over pale houses and water.
+  const shadow = { color: 0x2b2119, alpha: 0.55, blur: 8, distance: 0, angle: 0 };
+  const title = txt(lines[0], 64, { family: "heading", weight: "700", fill: 0xfff6e8, dropShadow: shadow });
+  title.position.set(110, 92);
+  const bandLabel = txt(lines[1], 30, { family: "heading", weight: "700", fill: 0xfff6e8, dropShadow: shadow });
+  const carLabel = txt(lines[2], 30, { family: "heading", weight: "700", fill: 0xfff6e8, dropShadow: shadow });
+  const marks = new Graphics();
+  root.addChild(stage.sprite, marks, title, bandLabel, carLabel);
+  const look = new THREE.Vector3();
+
+  const update = (t: number) => {
+    const u = 0.5 - 0.5 * Math.cos(Math.PI * clamp01(t / 8));
+    camera.position.copy(cameraPath.getPoint(u));
+    camera.lookAt(targetPath.getPoint(u, look));
+    drive(car, road, 0.9 + t * 0.05, LAND + 0.004);
+    drive(van, road, 0.12 + t * 0.03, LAND + 0.004);
+    drive(fishing, bay, 0.18 + t * 0.022, WATER - 0.02 + Math.sin(t * 2.1) * 0.006);
+    drive(sailing, bay, 0.68 + t * 0.016, WATER - 0.02 + Math.sin(t * 1.6 + 1) * 0.006);
+    const focus = stage.project(look, camera);
+    const center = Math.min(0.8, Math.max(0.2, 1 - focus.y / 1080));
+    for (const pass of [tiltH, tiltV]) pass.uniforms.center.value = center;
+    // The bracket spans the sharp band on the left edge of the frame; a leader rides the red car.
+    const top = (1 - center - 0.07) * 1080, bottom = (1 - center + 0.07) * 1080;
+    const bandAlpha = inOut(t, 1.6, 7.6);
+    marks.clear().moveTo(84, top).lineTo(64, top).lineTo(64, bottom).lineTo(84, bottom).stroke({ color: 0xfff6e8, width: 3, alpha: bandAlpha });
+    bandLabel.position.set(100, (top + bottom) / 2 - 20);
+    show(bandLabel, bandAlpha);
+    const c = stage.project(car.position.clone().add(new THREE.Vector3(0, 0.22, 0)), camera);
+    const carAlpha = inOut(t, 3.2, 7.6) * (c.behind || c.x < 40 || c.x > 1560 || c.y < 200 || c.y > 1000 ? 0 : 1);
+    if (carAlpha > 0) marks.moveTo(c.x, c.y).lineTo(c.x + 60, c.y - 70).lineTo(c.x + 110, c.y - 70).stroke({ color: 0xfff6e8, width: 3, alpha: carAlpha }).circle(c.x, c.y, 6).fill({ color: 0xfff6e8, alpha: carAlpha });
+    carLabel.position.set(c.x + 122, c.y - 92);
+    show(carLabel, carAlpha);
+    show(title, inOut(t, 0.4, 7.6));
+    stage.draw(scene, camera);
+  };
+  update(0);
+  await stage.warm(scene, camera);
+  return update;
+};
+export default study;