@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/render/depth-map.ts

@@ -0,0 +1,191 @@
+// Orthographic depth maps along a direction: the sun's shadow map, the sky-direction maps that
+// give ambient occlusion (and the soft contact shadow on the ground), and the silhouette masks the
+// review metrics compare. Stores, per texel, the highest dot(p, dir) — the surface nearest the light.
+
+import type { Scene } from './scene.ts';
+
+export interface DepthMap {
+  readonly size: number;
+  /** −Infinity where nothing was drawn. */
+  readonly data: Float32Array;
+  readonly dir: readonly [number, number, number];
+  readonly r: readonly [number, number, number];
+  readonly u: readonly [number, number, number];
+  /** Texel coordinate = (dot(p, r) − r0) · k, (u1 − dot(p, u)) · k. */
+  readonly r0: number;
+  readonly u1: number;
+  readonly k: number;
+}
+
+/** Map frame in the map's own (r, u) coordinates: centre and half-extent, metres. */
+export interface MapFrame {
+  readonly cr: number;
+  readonly cu: number;
+  readonly half: number;
+}
+
+export type MapAlpha = (tri: number, b1: number, b2: number) => boolean;
+
+export function mapAxes(dir: readonly [number, number, number]): {
+  r: [number, number, number];
+  u: [number, number, number];
+} {
+  const up: [number, number, number] = Math.abs(dir[2]) > 0.99 ? [1, 0, 0] : [0, 0, 1];
+  let r: [number, number, number] = [
+    up[1] * dir[2] - up[2] * dir[1],
+    up[2] * dir[0] - up[0] * dir[2],
+    up[0] * dir[1] - up[1] * dir[0],
+  ];
+  const l = Math.hypot(r[0], r[1], r[2]) || 1;
+  r = [r[0] / l, r[1] / l, r[2] / l];
+  const u: [number, number, number] = [
+    dir[1] * r[2] - dir[2] * r[1],
+    dir[2] * r[0] - dir[0] * r[2],
+    dir[0] * r[1] - dir[1] * r[0],
+  ];
+  return { r, u };
+}
+
+/** The frame that just contains the scene seen along `dir`, with a 2% margin. */
+export function fitFrame(s: Scene, dir: readonly [number, number, number]): MapFrame {
+  const { r, u } = mapAxes(dir);
+  let r0 = Infinity;
+  let r1 = -Infinity;
+  let u0 = Infinity;
+  let u1 = -Infinity;
+  const P = s.positions;
+  for (let i = 0; i < P.length; i += 3) {
+    const x = P[i] ?? 0;
+    const y = P[i + 1] ?? 0;
+    const z = P[i + 2] ?? 0;
+    const a = x * r[0] + y * r[1] + z * r[2];
+    const b = x * u[0] + y * u[1] + z * u[2];
+    if (a < r0) r0 = a;
+    if (a > r1) r1 = a;
+    if (b < u0) u0 = b;
+    if (b > u1) u1 = b;
+  }
+  if (!Number.isFinite(r0)) return { cr: 0, cu: 0, half: 1 };
+  return { cr: (r0 + r1) / 2, cu: (u0 + u1) / 2, half: Math.max(r1 - r0, u1 - u0, 1e-3) * 0.51 };
+}
+
+export function depthMap(
+  s: Scene,
+  dir: readonly [number, number, number],
+  size: number,
+  frame: MapFrame = fitFrame(s, dir),
+  alpha?: MapAlpha,
+): DepthMap {
+  const { r, u } = mapAxes(dir);
+  const k = size / (2 * frame.half);
+  const r0 = frame.cr - frame.half;
+  const u1 = frame.cu + frame.half;
+  const data = new Float32Array(size * size).fill(-Infinity);
+  const nv = s.positions.length / 3;
+  const X = new Float32Array(nv);
+  const Y = new Float32Array(nv);
+  const D = new Float32Array(nv);
+  const P = s.positions;
+  for (let v = 0; v < nv; v++) {
+    const x = P[v * 3] ?? 0;
+    const y = P[v * 3 + 1] ?? 0;
+    const z = P[v * 3 + 2] ?? 0;
+    X[v] = (x * r[0] + y * r[1] + z * r[2] - r0) * k;
+    Y[v] = (u1 - (x * u[0] + y * u[1] + z * u[2])) * k;
+    D[v] = x * dir[0] + y * dir[1] + z * dir[2];
+  }
+  const I = s.indices;
+  for (let t = 0; t < s.triangles; t++) {
+    const a = I[t * 3] ?? 0;
+    const b = I[t * 3 + 1] ?? 0;
+    const c = I[t * 3 + 2] ?? 0;
+    const ax = X[a] ?? 0;
+    const ay = Y[a] ?? 0;
+    const bx = X[b] ?? 0;
+    const by = Y[b] ?? 0;
+    const cx = X[c] ?? 0;
+    const cy = Y[c] ?? 0;
+    const area = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+    if (Math.abs(area) < 1e-12) continue;
+    const inv = 1 / area;
+    const da = D[a] ?? 0;
+    const db = D[b] ?? 0;
+    const dc = D[c] ?? 0;
+    const cut = alpha !== undefined && s.surface[t] === 1;
+    const lx = ax < bx ? Math.min(ax, cx) : Math.min(bx, cx);
+    const hx = ax > bx ? Math.max(ax, cx) : Math.max(bx, cx);
+    const ly = ay < by ? Math.min(ay, cy) : Math.min(by, cy);
+    const hy = ay > by ? Math.max(ay, cy) : Math.max(by, cy);
+    const minX = lx < 0 ? 0 : Math.floor(lx);
+    const maxX = hx > size - 1 ? size - 1 : Math.ceil(hx);
+    const minY = ly < 0 ? 0 : Math.floor(ly);
+    const maxY = hy > size - 1 ? size - 1 : Math.ceil(hy);
+    // Edge functions are affine in (px, py): step them instead of re-evaluating per texel.
+    const A0 = (by - cy) * inv;
+    const B0 = (cx - bx) * inv;
+    const A1 = (cy - ay) * inv;
+    const B1 = (ax - cx) * inv;
+    const C0 = (bx * cy - by * cx) * inv;
+    const C1 = (cx * ay - cy * ax) * inv;
+    for (let y = minY; y <= maxY; y++) {
+      const py = y + 0.5;
+      let w0 = C0 + A0 * (minX + 0.5) + B0 * py;
+      let w1 = C1 + A1 * (minX + 0.5) + B1 * py;
+      for (let x = minX; x <= maxX; x++, w0 += A0, w1 += A1) {
+        if (w0 < 0 || w1 < 0 || w0 + w1 > 1) continue;
+        const d = w0 * da + w1 * db + (1 - w0 - w1) * dc;
+        const i = y * size + x;
+        if (d <= (data[i] ?? 0)) continue;
+        if (cut && alpha && !alpha(t, w1, 1 - w0 - w1)) continue;
+        data[i] = d;
+      }
+    }
+  }
+  return { size, data, dir, r, u, r0, u1, k };
+}
+
+/**
+ * Fraction of `taps` (pairs of texel offsets) at which world point (x,y,z) sees past the map —
+ * 1 = fully lit/open, 0 = fully occluded. `bias` in metres along the map direction.
+ */
+export function visibility(
+  m: DepthMap,
+  x: number,
+  y: number,
+  z: number,
+  bias: number,
+  taps: Float32Array,
+): number {
+  const tx = (x * m.r[0] + y * m.r[1] + z * m.r[2] - m.r0) * m.k;
+  const ty = (m.u1 - (x * m.u[0] + y * m.u[1] + z * m.u[2])) * m.k;
+  const d = x * m.dir[0] + y * m.dir[1] + z * m.dir[2] + bias;
+  const s = m.size;
+  let lit = 0;
+  for (let i = 0; i < taps.length; i += 2) {
+    const px = Math.floor(tx + (taps[i] ?? 0));
+    const py = Math.floor(ty + (taps[i + 1] ?? 0));
+    if (px < 0 || py < 0 || px >= s || py >= s || d >= (m.data[py * s + px] ?? 0)) lit++;
+  }
+  return (lit * 2) / taps.length;
+}
+
+/**
+ * Ambient openness at (x,y,z) along the map direction, 0…1: an occluder `reach` metres or more
+ * away counts for nothing, nearer ones linearly more — AO with a falloff, so a few sky directions
+ * give a soft contact shadow instead of long streaks.
+ */
+export function openness(
+  m: DepthMap,
+  x: number,
+  y: number,
+  z: number,
+  bias: number,
+  reach: number,
+): number {
+  const px = Math.floor((x * m.r[0] + y * m.r[1] + z * m.r[2] - m.r0) * m.k);
+  const py = Math.floor((m.u1 - (x * m.u[0] + y * m.u[1] + z * m.u[2])) * m.k);
+  const s = m.size;
+  if (px < 0 || py < 0 || px >= s || py >= s) return 1;
+  const gap = (m.data[py * s + px] ?? 0) - (x * m.dir[0] + y * m.dir[1] + z * m.dir[2] + bias);
+  return gap <= 0 ? 1 : gap >= reach ? 1 : gap / reach;
+}

package/src/render/font.ts

@@ -0,0 +1,76 @@
+// A 3×5 bitmap font for view labels on contact sheets, so an agent reading the PNG knows which
+// view is which and what the grid step is. Uppercase, digits and a few marks only.
+
+const GLYPHS: Readonly<Record<string, string>> = {
+  A: '010101111101101',
+  B: '110101110101110',
+  C: '011100100100011',
+  D: '110101101101110',
+  E: '111100110100111',
+  F: '111100110100100',
+  G: '011100101101011',
+  H: '101101111101101',
+  I: '111010010010111',
+  J: '001001001101010',
+  K: '101101110101101',
+  L: '100100100100111',
+  M: '101111111101101',
+  N: '110101101101101',
+  O: '010101101101010',
+  P: '110101110100100',
+  Q: '010101101110011',
+  R: '110101110101101',
+  S: '011100010001110',
+  T: '111010010010010',
+  U: '101101101101111',
+  V: '101101101101010',
+  W: '101101111111101',
+  X: '101101010101101',
+  Y: '101101010010010',
+  Z: '111001010100111',
+  '0': '111101101101111',
+  '1': '010110010010111',
+  '2': '110001010100111',
+  '3': '110001010001110',
+  '4': '101101111001001',
+  '5': '111100110001110',
+  '6': '011100111101111',
+  '7': '111001010010010',
+  '8': '111101111101111',
+  '9': '111101111001110',
+  '.': '000000000000010',
+  '/': '001001010100100',
+  '-': '000000111000000',
+  ':': '000010000010000',
+  ' ': '000000000000000',
+  '+': '000010111010000',
+  _: '000000000000111',
+  '=': '000111000111000',
+};
+
+export function drawText(
+  px: Uint8Array,
+  width: number,
+  x: number,
+  y: number,
+  text: string,
+  scale: number,
+  rgb: readonly [number, number, number],
+): void {
+  let cx = x;
+  for (const ch of text.toUpperCase()) {
+    const g = GLYPHS[ch] ?? GLYPHS[' '] ?? '';
+    for (let i = 0; i < 15; i++) {
+      if (g[i] !== '1') continue;
+      const gx = cx + (i % 3) * scale;
+      const gy = y + Math.floor(i / 3) * scale;
+      for (let dy = 0; dy < scale; dy++) {
+        for (let dx = 0; dx < scale; dx++) {
+          const o = ((gy + dy) * width + gx + dx) * 4;
+          if (o >= 0 && o + 3 < px.length) px.set([...rgb, 255], o);
+        }
+      }
+    }
+    cx += 4 * scale;
+  }
+}

package/src/render/ground.ts

@@ -0,0 +1,87 @@
+// The seamless studio floor as a shadow catcher: a world-space grid over the asset's footprint
+// holding how much light reaches the floor (sun shadow × sky openness, 1 = untouched). The renderer
+// multiplies the background by it, so the floor is invisible except for the shadows that ground
+// the model — the clean product-shot look, with a soft contact shadow from the AO maps.
+
+import type { PerspectiveCamera } from './camera.ts';
+import { type ShadeContext, skyOpen, sunVisible } from './shade.ts';
+
+export interface FloorGrid {
+  readonly z: number;
+  readonly x0: number;
+  readonly y0: number;
+  readonly cell: number;
+  readonly size: number;
+  readonly light: Float32Array;
+}
+
+const UP = [0, 0, 1];
+
+export function floorGrid(c: ShadeContext, size: number): FloorGrid {
+  const s = c.scene;
+  const z = s.min[2];
+  const h = s.max[2] - s.min[2];
+  const half = Math.max(s.max[0] - s.min[0], s.max[1] - s.min[1]) / 2 + Math.max(h * 1.4, 0.2);
+  const cx = (s.min[0] + s.max[0]) / 2;
+  const cy = (s.min[1] + s.max[1]) / 2;
+  const cell = (2 * half) / size;
+  const light = new Float32Array(size * size);
+  const sunUp = Math.max(0, c.rig.sun[2]);
+  // Floor radiance split: sun share vs sky share of an open floor, so shadows read as soft
+  // (sky still lights the shadow) and the contact shadow comes from the AO term alone.
+  const sunW = sunUp * (c.rig.sunColor[1] ?? 1);
+  const skyW = c.rig.sky[1] ?? 1;
+  const p = [0, 0, z];
+  for (let j = 0; j < size; j++)
+    for (let i = 0; i < size; i++) {
+      p[0] = cx - half + (i + 0.5) * cell;
+      p[1] = cy - half + (j + 0.5) * cell;
+      const sun = sunVisible(c, p, UP, (i + j * 2) & 3);
+      const open = skyOpen(c, p, UP);
+      light[j * size + i] = (sunW * sun * (0.55 + 0.45 * open) + skyW * open) / (sunW + skyW);
+    }
+  return { z, x0: cx - half, y0: cy - half, cell, size, light: blur(blur(light, size), size) };
+}
+
+/** 3 × 3 box blur (edges clamp): hides the grid's cell steps under perspective magnification. */
+function blur(src: Float32Array, n: number): Float32Array {
+  const out = new Float32Array(src.length);
+  for (let y = 0; y < n; y++)
+    for (let x = 0; x < n; x++) {
+      let s = 0;
+      for (let dy = -1; dy <= 1; dy++)
+        for (let dx = -1; dx <= 1; dx++) {
+          const yy = Math.min(n - 1, Math.max(0, y + dy));
+          const xx = Math.min(n - 1, Math.max(0, x + dx));
+          s += src[yy * n + xx] ?? 1;
+        }
+      out[y * n + x] = s / 9;
+    }
+  return out;
+}
+
+/** Floor light where the eye ray through pixel (px, py) meets the floor; 1 off the grid/above. */
+export function floorLight(g: FloorGrid, cam: PerspectiveCamera, px: number, py: number): number {
+  const sx = (px - cam.cx) / cam.focal;
+  const sy = -(py - cam.cy) / cam.focal;
+  const dx = cam.f[0] + cam.r[0] * sx + cam.u[0] * sy;
+  const dy = cam.f[1] + cam.r[1] * sx + cam.u[1] * sy;
+  const dz = cam.f[2] + cam.r[2] * sx + cam.u[2] * sy;
+  if (dz >= -1e-6) return 1;
+  const t = (g.z - cam.eye[2]) / dz;
+  const gx = (cam.eye[0] + dx * t - g.x0) / g.cell - 0.5;
+  const gy = (cam.eye[1] + dy * t - g.y0) / g.cell - 0.5;
+  const ix = Math.floor(gx);
+  const iy = Math.floor(gy);
+  if (ix < 0 || iy < 0 || ix >= g.size - 1 || iy >= g.size - 1) return 1;
+  const fx = gx - ix;
+  const fy = gy - iy;
+  const L = g.light;
+  const o = iy * g.size + ix;
+  return (
+    (L[o] ?? 1) * (1 - fx) * (1 - fy) +
+    (L[o + 1] ?? 1) * fx * (1 - fy) +
+    (L[o + g.size] ?? 1) * (1 - fx) * fy +
+    (L[o + g.size + 1] ?? 1) * fx * fy
+  );
+}

package/src/render/index.ts

@@ -0,0 +1,34 @@
+// Public API of /render: zero-GPU images an agent (and a README) can use — contact sheets,
+// thumbnails, beauty product shots, LOD strips, and the AI review pack with image metrics.
+
+export {
+  type BeautyOptions,
+  type BeautyRender,
+  beauty,
+  cameraFor,
+  renderBeauty,
+} from './beauty.ts';
+export type { PerspectiveCamera } from './camera.ts';
+export { type LodStripOptions, lodStrip } from './lod-strip.ts';
+export {
+  type ExposureStats,
+  exposure,
+  type MaskStats,
+  maskIoU,
+  maskStats,
+  poolMask,
+  type Silhouette,
+  silhouette,
+  viewFrame,
+} from './metrics.ts';
+export { checkBeautyOptions, parseSize } from './options.ts';
+export { type PhotoCamera, type PhotoMatchOptions, photoMatch } from './photo-match.ts';
+export { detailWindows, type ReviewOptions, type ReviewPack, reviewPack } from './review.ts';
+export {
+  REVIEW_THRESHOLDS,
+  type ReviewMetrics,
+  type ReviewWarning,
+  type ViewMetrics,
+} from './review-warnings.ts';
+export { contactSheet, type SheetOptions, VIEWS } from './sheet.ts';
+export { type ThumbnailOptions, thumbnail } from './thumbnail.ts';

package/src/render/lighting.ts

@@ -0,0 +1,121 @@
+// The studio rig every beauty render shares: a warm key sun placed relative to the camera, a cool
+// sky hemisphere fill with a warm ground bounce, sky directions for ambient occlusion, PCF tap
+// patterns, and the filmic tone curve. Constants live here so every shot is lit the same way.
+
+export type V3 = [number, number, number];
+
+export interface Rig {
+  /** Unit vector toward the sun. */
+  readonly sun: V3;
+  readonly sunColor: V3;
+  readonly sky: V3;
+  readonly bounce: V3;
+  /** Unit vectors toward the sky, upper hemisphere, for the AO maps. */
+  readonly skyDirs: readonly V3[];
+  readonly exposure: number;
+}
+
+const unit = (az: number, el: number): V3 => {
+  const a = (az * Math.PI) / 180;
+  const e = (el * Math.PI) / 180;
+  return [Math.cos(e) * Math.cos(a), Math.cos(e) * Math.sin(a), Math.sin(e)];
+};
+
+/** Rings of sky directions: elevations and how many azimuths each ring holds (12 total). */
+const RINGS: readonly (readonly [number, number])[] = [
+  [14, 5],
+  [38, 4],
+  [64, 2],
+  [88, 1],
+];
+
+export function studioRig(cameraAzDeg: number): Rig {
+  const skyDirs: V3[] = [];
+  RINGS.forEach(([el, n], ring) => {
+    for (let i = 0; i < n; i++) skyDirs.push(unit((360 * (i + ring * 0.37)) / n, el));
+  });
+  return {
+    // Key light from camera-left and above: the near flank is lit, the front falls to fill, and
+    // the shadow lands behind and to the right where it grounds the model without hiding it.
+    sun: unit(cameraAzDeg - 50, 55),
+    // Calibrated so an open, sun-facing surface receives ≈ 1.0 irradiance: the output pixel is
+    // the albedo itself (vertex colour × sheet), not a lifted version of it.
+    sunColor: [0.95, 0.91, 0.84],
+    sky: [0.3, 0.33, 0.4],
+    bounce: [0.16, 0.15, 0.13],
+    skyDirs,
+    exposure: 1,
+  };
+}
+
+const HORIZON: V3 = [0.82, 0.8, 0.76];
+const ZENITH: V3 = [0.3, 0.34, 0.44];
+const FLOOR: V3 = [0.3, 0.28, 0.26];
+const BAND = 0.12;
+
+/**
+ * The studio environment a reflection sees, channel `k`, along a reflection vector with up
+ * component `rz`: a bright cyclorama horizon fading to a cooler zenith, a dark band where the
+ * floor meets the wall, the lit floor below. Roughness pre-blurs it toward its mean, so polished
+ * metal shows the horizon line and rough metal a soft gradient — what makes metal read as metal.
+ */
+export function envRadiance(rz: number, rough: number, k: number): number {
+  const h = HORIZON[k] ?? 0;
+  const sharp =
+    rz >= 0
+      ? h + ((ZENITH[k] ?? 0) - h) * Math.sqrt(rz)
+      : rz > -0.3
+        ? h * BAND + ((FLOOR[k] ?? 0) - h * BAND) * Math.min(1, -rz / 0.3) ** 0.5
+        : (FLOOR[k] ?? 0);
+  const blurred = 0.5 * h + 0.25 * (ZENITH[k] ?? 0) + 0.25 * (FLOOR[k] ?? 0);
+  // Above the horizon the blur keeps a little of the up/down split so rough metal still shades.
+  const tilt = 1 + 0.25 * Math.max(-1, Math.min(1, rz * 2));
+  const t = Math.min(1, rough * 1.6);
+  return sharp + (blurred * tilt - sharp) * t;
+}
+
+/** Poisson-ish disc of 12 taps (texel offsets), radius ~1.6, rotated four ways for dithering. */
+const DISC: readonly (readonly [number, number])[] = [
+  [-0.94, -0.4],
+  [0.95, -0.77],
+  [-0.09, -0.93],
+  [0.34, 0.29],
+  [-0.92, 0.46],
+  [-0.38, -0.06],
+  [0.79, 0.19],
+  [-0.24, 0.78],
+  [0.44, -0.3],
+  [0.55, 0.85],
+  [-0.66, -0.87],
+  [0.06, 0.37],
+];
+
+export function pcfTaps(radius: number): Float32Array[] {
+  return [0, 1, 2, 3].map((k) => {
+    const a = (k * Math.PI) / 8;
+    const c = Math.cos(a) * radius;
+    const s = Math.sin(a) * radius;
+    const out = new Float32Array(DISC.length * 2);
+    DISC.forEach(([x, y], i) => {
+      out[i * 2] = x * c - y * s;
+      out[i * 2 + 1] = x * s + y * c;
+    });
+    return out;
+  });
+}
+
+/**
+ * Tone curve, linear in → linear display out: identity up to 0.6 (mid-tones and the palette stay
+ * true), then a smooth exponential shoulder that rolls highlights into 1 without clipping.
+ */
+export function tone(x: number): number {
+  if (x <= 0) return 0;
+  if (x <= 0.6) return x;
+  return 0.6 + 0.4 * (1 - Math.exp(-(x - 0.6) / 0.4));
+}
+
+export const toSrgb8 = (v: number): number =>
+  Math.round(255 * (v <= 0.0031308 ? v * 12.92 : 1.055 * Math.min(1, v) ** (1 / 2.4) - 0.055));
+
+export const fromSrgb = (v: number): number =>
+  v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;

package/src/render/lod-strip.ts

@@ -0,0 +1,34 @@
+// LOD strip: LOD0 · LOD1 · LOD2 beauty renders side by side from ONE camera (framed on LOD0), so
+// popping — a silhouette that jumps, a part that vanishes, a colour that shifts — reads at a glance.
+
+import { type CompiledAsset, encodePng } from '../core/index.ts';
+import { type BeautyOptions, renderBeauty } from './beauty.ts';
+import { drawText } from './font.ts';
+
+export interface LodStripOptions extends Omit<BeautyOptions, 'frameFrom' | 'window'> {}
+
+const tris = (a: CompiledAsset): number =>
+  a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+
+export function lodStrip(lods: readonly CompiledAsset[], o: LodStripOptions = {}): Uint8Array {
+  const w = o.width ?? 640;
+  const h = o.height ?? 480;
+  const first = lods[0];
+  const n = lods.length;
+  const out = new Uint8Array(w * n * h * 4);
+  lods.forEach((a, k) => {
+    const r = renderBeauty(a, {
+      ...o,
+      width: w,
+      height: h,
+      ...(first ? { frameFrom: first } : {}),
+    });
+    for (let y = 0; y < h; y++)
+      out.set(r.rgba.subarray(y * w * 4, (y + 1) * w * 4), (y * w * n + k * w) * 4);
+    if (k > 0)
+      for (let y = 0; y < h; y++)
+        out.fill(255, (y * w * n + k * w) * 4, (y * w * n + k * w + 2) * 4);
+    drawText(out, w * n, k * w + 12, 12, `LOD${a.lod}  ${tris(a)} TRIS`, 3, [40, 44, 52]);
+  });
+  return encodePng(w * n, h, out);
+}

package/src/render/metrics.ts

@@ -0,0 +1,147 @@
+// Image metrics an agent gets without any model: orthographic silhouette masks per contact-sheet
+// view, coverage and bounding-box fill, silhouette IoU (LOD0 ↔ LOD2 = LOD popping; model ↔ photo
+// mask = photo match), and the hero's exposure — mean, contrast, crushed blacks, blown whites.
+
+import { type CompiledAsset, Ts23dError } from '../core/index.ts';
+import { depthMap, fitFrame, type MapFrame } from './depth-map.ts';
+import type { View } from './raster.ts';
+import { sceneOf } from './scene.ts';
+
+export interface Silhouette {
+  readonly size: number;
+  /** 1 = asset, 0 = empty. */
+  readonly mask: Uint8Array;
+}
+
+export interface MaskStats {
+  /** Fraction of the image the silhouette covers. */
+  readonly coverage: number;
+  /** Fraction of the silhouette's own bounding box it fills (low = spindly or scattered). */
+  readonly bboxFill: number;
+}
+
+const towardCamera = (v: View): [number, number, number] => {
+  const l = Math.hypot(v.dir[0], v.dir[1], v.dir[2]) || 1;
+  return [-v.dir[0] / l, -v.dir[1] / l, -v.dir[2] / l];
+};
+
+/** The frame that fits `asset` seen along `view` — pass it to silhouettes of other LODs. */
+export function viewFrame(asset: CompiledAsset, view: View): MapFrame {
+  return fitFrame(sceneOf(asset), towardCamera(view));
+}
+
+export function silhouette(
+  asset: CompiledAsset,
+  view: View,
+  size = 256,
+  frame: MapFrame = viewFrame(asset, view),
+): Silhouette {
+  const m = depthMap(sceneOf(asset), towardCamera(view), size, frame);
+  const mask = new Uint8Array(size * size);
+  for (let i = 0; i < mask.length; i++) mask[i] = (m.data[i] ?? -Infinity) > -Infinity ? 1 : 0;
+  return { size, mask };
+}
+
+/** Intersection over union of two same-sized masks (nonzero = inside). Two empty masks → 1. */
+export function maskIoU(a: Uint8Array, b: Uint8Array): number {
+  if (a.length !== b.length)
+    throw new Ts23dError('T3D_RENDER_OPTIONS', {
+      cause: `masks differ in size (${a.length} vs ${b.length} pixels)`,
+      fix: 'render both silhouettes at the same size and frame (pass the LOD0 frame to both)',
+    });
+  let inter = 0;
+  let union = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = (a[i] ?? 0) !== 0;
+    const y = (b[i] ?? 0) !== 0;
+    if (x && y) inter++;
+    if (x || y) union++;
+  }
+  return union === 0 ? 1 : inter / union;
+}
+
+/** Max-pool a mask by `f` (any covered texel covers the block): the silhouette as seen from afar,
+ * where lattice gaps and leaf holes close up — what LOD2 has to match. */
+export function poolMask(s: Silhouette, f: number): Silhouette {
+  const size = Math.floor(s.size / f);
+  const mask = new Uint8Array(size * size);
+  for (let y = 0; y < s.size; y++)
+    for (let x = 0; x < s.size; x++)
+      if (s.mask[y * s.size + x]) {
+        const i = Math.floor(y / f) * size + Math.floor(x / f);
+        if (i < mask.length) mask[i] = 1;
+      }
+  return { size, mask };
+}
+
+export function maskStats(s: Silhouette): MaskStats {
+  let n = 0;
+  let x0 = s.size;
+  let y0 = s.size;
+  let x1 = -1;
+  let y1 = -1;
+  for (let y = 0; y < s.size; y++)
+    for (let x = 0; x < s.size; x++) {
+      if (!s.mask[y * s.size + x]) continue;
+      n++;
+      if (x < x0) x0 = x;
+      if (x > x1) x1 = x;
+      if (y < y0) y0 = y;
+      if (y > y1) y1 = y;
+    }
+  const box = x1 < 0 ? 0 : (x1 - x0 + 1) * (y1 - y0 + 1);
+  return { coverage: n / (s.size * s.size), bboxFill: box ? n / box : 0 };
+}
+
+export interface ExposureStats {
+  /** Fraction of the frame the asset covers. */
+  readonly coverage: number;
+  /** The asset's screen bounding box as a fraction of the frame, larger axis (≈ 0.8 when framed). */
+  readonly span: number;
+  /** Mean relative luminance (0–1, sRGB-encoded values) over asset pixels. */
+  readonly mean: number;
+  /** Standard deviation of that luminance — low = flat, unreadable shading. */
+  readonly contrast: number;
+  readonly nearBlack: number;
+  readonly nearWhite: number;
+}
+
+/** Exposure of a rendered RGBA image (`width` px wide) over the pixels where `mask` ≥ 128. */
+export function exposure(rgba: Uint8Array, mask: Uint8Array, width: number): ExposureStats {
+  const height = Math.max(1, Math.floor(mask.length / Math.max(1, width)));
+  let x0 = width;
+  let x1 = -1;
+  let y0 = height;
+  let y1 = -1;
+  let n = 0;
+  let sum = 0;
+  let sq = 0;
+  let black = 0;
+  let white = 0;
+  for (let i = 0; i < mask.length; i++) {
+    if ((mask[i] ?? 0) < 128) continue;
+    const x = i % width;
+    const y = Math.floor(i / width);
+    if (x < x0) x0 = x;
+    if (x > x1) x1 = x;
+    if (y < y0) y0 = y;
+    if (y > y1) y1 = y;
+    const o = i * 4;
+    const l =
+      (0.2126 * (rgba[o] ?? 0) + 0.7152 * (rgba[o + 1] ?? 0) + 0.0722 * (rgba[o + 2] ?? 0)) / 255;
+    n++;
+    sum += l;
+    sq += l * l;
+    if (l < 0.06) black++;
+    if (l > 0.97) white++;
+  }
+  const mean = n ? sum / n : 0;
+  return {
+    coverage: n / Math.max(1, mask.length),
+    span: x1 < 0 ? 0 : Math.max((x1 - x0 + 1) / width, (y1 - y0 + 1) / height),
+    mean,
+    contrast: n ? Math.sqrt(Math.max(0, sq / n - mean * mean)) : 0,
+    nearBlack: n ? black / n : 0,
+    nearWhite: n ? white / n : 0,
+  };
+}