@volter/editor-threejs 0.5.65 → 0.5.67

package/src/kit/asset-preview-command.ts

@@ -0,0 +1,265 @@
+/**
+ * `capture-asset-preview` — the Asset Lab's photographs of a model or an entity:
+ * the plain four views, a project shot set, the source review set, a compare
+ * against a reference GLB and the live scene stage. Registered with the
+ * viewport's relay verbs (`viewport-commands.ts`).
+ */
+import type { EditorCommandMessage, EditorCommandResult } from '@volter/editor-sdk/commands';
+import { parseForwardVector } from '@volter/editor-sdk/kit/asset-compare-core';
+import { captureEntityComparePreview, captureModelComparePreview } from './asset-compare';
+import {
+  type AssetPreviewBackground,
+  captureGlbBytesAssetPreview,
+  captureModelAssetPreview,
+  captureObjectAssetPreview,
+  captureSceneStageAssetPreview,
+  captureShotSetAssetPreview,
+  captureShotSetGlbBytesPreview,
+  captureShotSetModelPreview,
+  captureSourceReviewShotSetAssetPreview,
+  captureSourceReviewShotSetModelPreview,
+  parseShotSetDefinition,
+} from './asset-preview';
+import { activeDocumentAuthoring } from '@volter/editor-sdk/kit/authoring/shell-document-ops';
+import { parseCameraChoice, parsePoseChoice } from '@volter/editor-sdk/kit/capture-camera-pose';
+import type { EditorShellStore } from './editor-shell-store';
+import { entityObject3D } from './entity-object';
+
+export async function handleAssetPreviewCommand(
+  store: EditorShellStore,
+  cmd: EditorCommandMessage,
+): Promise<EditorCommandResult> {
+  const assetPath = cmd['assetPath'];
+  const entityId = cmd['entityId'];
+  // The THIRD source: a GLB that travels IN the command rather than being
+  // fetched or looked up — the module-look lane (`project.bake.preview`)
+  // builds an Object3D in Node, where there is no GPU, and hands the editor
+  // the exported bytes. Counted rather than XOR-ed because there are now more
+  // than two sources and "exactly one" has to stay exactly one.
+  const glbBase64 = cmd['glbBase64'];
+  const sourceCount =
+    Number(typeof assetPath === 'string') +
+    Number(typeof entityId === 'string') +
+    Number(typeof glbBase64 === 'string');
+  if (sourceCount !== 1) {
+    return {
+      ok: false,
+      error: 'capture-asset-preview requires exactly one of assetPath, entityId or glbBase64.',
+    };
+  }
+  const width = cmd['width'];
+  const height = cmd['height'];
+  const background = cmd['background'];
+  const shots = cmd['shots'];
+  const shotSet = cmd['shotSet'];
+  const forward = cmd['forward'];
+  const compare = cmd['compare'];
+  const stage = cmd['stage'];
+  const camera = cmd['camera'];
+  const pose = cmd['pose'];
+  if (
+    (width !== undefined && typeof width !== 'number') ||
+    (height !== undefined && typeof height !== 'number') ||
+    (background !== undefined && background !== 'neutral' && background !== 'transparent') ||
+    (shots !== undefined && shots !== 'source')
+  ) {
+    return { ok: false, error: 'Invalid asset preview dimensions, background, or shots mode.' };
+  }
+  if (stage !== undefined && stage !== 'lab' && stage !== 'scene') {
+    return {
+      ok: false,
+      error: `capture-asset-preview stage must be "lab" or "scene", got ${String(stage)}.`,
+    };
+  }
+  if (shotSet !== undefined && shots !== undefined) {
+    return {
+      ok: false,
+      error: 'capture-asset-preview cannot combine a shotSet definition with a shots mode.',
+    };
+  }
+  // The free capture camera and clip pose (`--azimuth/--elevation/--distance`,
+  // `--clip/--time`) belong to the plain Asset Lab legs: a shot set / source
+  // review / compare each stage their own cameras and poses, and the scene
+  // stage photographs an entity where it stands. Refused by name, never
+  // silently ignored.
+  const cameraChoice = parseCameraChoice('capture-asset-preview', camera);
+  if (typeof cameraChoice === 'string') return { ok: false, error: cameraChoice };
+  const posedClip = parsePoseChoice('capture-asset-preview', pose);
+  if (typeof posedClip === 'string') return { ok: false, error: posedClip };
+  if (
+    (cameraChoice || posedClip) &&
+    (shots !== undefined || shotSet !== undefined || compare !== undefined || stage === 'scene')
+  ) {
+    return {
+      ok: false,
+      error:
+        'capture-asset-preview cannot combine camera/pose with a shots mode, a shotSet ' +
+        'definition, compare, or stage "scene" — those legs stage their own cameras and poses.',
+    };
+  }
+  // A project-defined labeled shot set travels WITH the command (the CLI
+  // resolves `--shots <set>` through the registered
+  // `project.<set>.previewShots` tool); validate the untrusted
+  // definition at the relay boundary so a malformed contribution fails with
+  // a named reason instead of a deep three.js error.
+  let shotSetDefinition: ReturnType<typeof parseShotSetDefinition> | undefined;
+  if (shotSet !== undefined) {
+    try {
+      shotSetDefinition = parseShotSetDefinition(shotSet);
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  const parsedForward = parseForwardVector(forward);
+  if (shots === 'source' && parsedForward === null) {
+    return {
+      ok: false,
+      error: 'capture-asset-preview --shots source requires a non-degenerate forward [x,y,z].',
+    };
+  }
+  if (compare !== undefined) {
+    // B8.4 — the compare mode (`vgai screenshot <model.glb> --compare <ref.glb>`).
+    // Validated here at the relay boundary so a malformed payload fails with
+    // a named reason instead of a deep three.js error.
+    if (shots !== undefined || shotSetDefinition !== undefined) {
+      return { ok: false, error: 'capture-asset-preview cannot combine compare with shots.' };
+    }
+    if (
+      typeof compare !== 'object' ||
+      compare === null ||
+      typeof (compare as Record<string, unknown>)['glbBase64'] !== 'string' ||
+      ((compare as Record<string, unknown>)['forward'] !== undefined &&
+        parseForwardVector((compare as Record<string, unknown>)['forward']) === null)
+    ) {
+      return {
+        ok: false,
+        error:
+          'capture-asset-preview compare requires { glbBase64: string, forward?: [x, y, z] } ' +
+          'with a non-degenerate ground-plane forward.',
+      };
+    }
+  }
+  // Wire-carried GLB bytes stand NOWHERE, so they take no scene stage and no
+  // compare (whose reference is named some other way). An explicit `shotSet`
+  // definition is a different matter and is served: a shot set stages the
+  // subject itself, which is what lets `vgai screenshot <module> --orbit <n>`
+  // circle a model that only ever existed as bytes. `shots: 'source'` stays
+  // out — it is the asset-path review set, keyed to a stored forward vector.
+  if (typeof glbBase64 === 'string') {
+    if (shots !== undefined || compare !== undefined) {
+      return {
+        ok: false,
+        error: 'capture-asset-preview cannot combine glbBase64 with a named shots mode or compare.',
+      };
+    }
+    if (stage === 'scene') {
+      return {
+        ok: false,
+        error:
+          'capture-asset-preview stage "scene" photographs a live scene entity — glbBase64 bytes stand nowhere in the scene.',
+      };
+    }
+  }
+  // `stage: 'scene'` photographs a LIVE entity in the live scene (see
+  // `captureSceneStageAssetPreview`), so it is meaningful only for the plain
+  // four-view entity capture: a model loaded from `assetPath` stands nowhere,
+  // and the shot-set/source/compare modes each stage their own subject.
+  // Refused by name at this boundary rather than silently downgraded to the
+  // lab stage — a caller who asked for the scene and got the studio would
+  // never know.
+  const liveScene = stage === 'scene' ? store.scene : null;
+  if (stage === 'scene') {
+    if (typeof entityId !== 'string') {
+      return {
+        ok: false,
+        error:
+          'capture-asset-preview stage "scene" photographs a live scene entity — pass entityId, not assetPath.',
+      };
+    }
+    if (shots !== undefined || shotSetDefinition !== undefined || compare !== undefined) {
+      return {
+        ok: false,
+        error:
+          'capture-asset-preview cannot combine stage "scene" with a shots mode, a shotSet definition or compare.',
+      };
+    }
+    if (!liveScene) {
+      return {
+        ok: false,
+        error:
+          'capture-asset-preview stage "scene" requires a bound viewport scene; none is bound yet.',
+      };
+    }
+  }
+  // Resolve the screenshot subject through the SAME active-document adapter
+  // that produced `status.entities`, drives Hierarchy/Inspector selection and
+  // answers `frame-entity`. An adopted Play scene can own a stable OID in its
+  // projection without publishing that object through the shell's edit-mode
+  // `objectMap`; checking the map alone made the final door reject an id every
+  // preceding door had just accepted.
+  const entityObject =
+    typeof entityId === 'string'
+      ? entityObject3D(activeDocumentAuthoring(store.shell), store.objectMap, entityId)
+      : null;
+  if (typeof entityId === 'string' && !entityObject) {
+    return { ok: false, error: `Entity not found: ${entityId}` };
+  }
+  try {
+    const options = {
+      ...(typeof width === 'number' ? { width } : {}),
+      ...(typeof height === 'number' ? { height } : {}),
+      ...(background ? { background: background as AssetPreviewBackground } : {}),
+      ...(cameraChoice ? { camera: cameraChoice } : {}),
+      ...(posedClip ? { pose: posedClip } : {}),
+    };
+    if (compare !== undefined) {
+      const compareRecord = compare as { glbBase64: string; forward?: unknown };
+      const refForward = parseForwardVector(compareRecord.forward);
+      const compareOptions = {
+        ...(typeof width === 'number' ? { width } : {}),
+        ...(typeof height === 'number' ? { height } : {}),
+        ...(refForward ? { refForward } : {}),
+      };
+      const capture =
+        typeof assetPath === 'string'
+          ? await captureModelComparePreview(assetPath, compareRecord.glbBase64, compareOptions)
+          : await captureEntityComparePreview(
+              entityObject!,
+              compareRecord.glbBase64,
+              compareOptions,
+            );
+      return { ok: true, data: { ...capture } };
+    }
+    if (shotSetDefinition !== undefined) {
+      const capture =
+        typeof glbBase64 === 'string'
+          ? await captureShotSetGlbBytesPreview(glbBase64, shotSetDefinition, options)
+          : typeof assetPath === 'string'
+            ? await captureShotSetModelPreview(assetPath, shotSetDefinition, options)
+            : captureShotSetAssetPreview(entityObject!, shotSetDefinition, options);
+      return { ok: true, data: { ...capture } };
+    }
+    if (shots === 'source') {
+      const capture =
+        typeof assetPath === 'string'
+          ? await captureSourceReviewShotSetModelPreview(assetPath, parsedForward!, options)
+          : captureSourceReviewShotSetAssetPreview(entityObject!, parsedForward!, options);
+      return { ok: true, data: { ...capture } };
+    }
+    if (liveScene) {
+      const capture = captureSceneStageAssetPreview(entityObject!, liveScene, options);
+      return { ok: true, data: { ...capture } };
+    }
+    if (typeof glbBase64 === 'string') {
+      const capture = await captureGlbBytesAssetPreview(glbBase64, options);
+      return { ok: true, data: { ...capture } };
+    }
+    const capture =
+      typeof assetPath === 'string'
+        ? await captureModelAssetPreview(assetPath, options)
+        : captureObjectAssetPreview(entityObject!, options);
+    return { ok: true, data: { ...capture } };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/kit/asset-preview-framing.ts

@@ -0,0 +1,357 @@
+/**
+ * The asset-preview capture engine's FRAMING MATH, extracted from
+ * `asset-preview.ts` so it can be exercised without a WebGL context.
+ *
+ * Everything here is pure: it takes points, a camera basis and an output
+ * aspect, and returns frustum half-extents or a configured
+ * `THREE.OrthographicCamera`. Nothing in this module traverses a scene,
+ * renders, or allocates GPU resources — the traversal that FEEDS it
+ * (`forEachRenderableVertex`) stays in `asset-preview.ts`, because that is
+ * scene-graph knowledge rather than geometry.
+ *
+ * Two facts drove the extraction:
+ *
+ * 1. A turntable shot must be framed from the subject's ACTUAL projected
+ *    extent along that shot's own camera axes. The engine used to derive
+ *    every yaw's frame from ONE world-axis-aligned bounding box, which is a
+ *    proxy: it is conservative for a compact subject and wasteful for a
+ *    long one held in a bent pose, and it centres every yaw on the AABB's
+ *    centre rather than on what that yaw actually sees.
+ * 2. A `bone-zoom` crop needs the same freedom of angle the turntable has.
+ *    Its basis used to be hardcoded to +Z, so a crop anchored on the tail of
+ *    an 8 m quadruped photographed the hind legs standing in front of it.
+ *
+ * @see {@link turntableViewBasis} for the yaw convention both shot kinds share.
+ */
+import * as THREE from 'three';
+
+/** Frame margin: the fitted half-extents are scaled by this, so a subject
+ *  never touches the frame edge. Shared by every orthographic preview
+ *  camera — the value is the engine's one framing constant. */
+export const ASSET_PREVIEW_PADDING = 1.2;
+
+/** The smallest half-extent a fitted frame may have, so a degenerate
+ *  (single-point) subject still produces a valid frustum. */
+const MIN_HALF_EXTENT = 0.001;
+
+/** An orthonormal camera basis. `direction` points from the subject TOWARD
+ *  the camera (the convention every preview camera in this engine uses:
+ *  `position = target + direction * distance`). */
+export interface OrthographicViewBasis {
+  direction: THREE.Vector3;
+  right: THREE.Vector3;
+  up: THREE.Vector3;
+}
+
+/**
+ * The turntable yaw convention, shared by `turntable` shots and — since the
+ * `bone-zoom` yaw was added — by bone-anchored crops too, so a definition
+ * reads one angle convention rather than two.
+ *
+ * `yaw = 0` puts the camera on +Z looking at the subject's front (the
+ * direction `faceFrontSubject` normalises the model's own forward to face),
+ * and yaw increases toward +X: `PI` is the back, `-PI/2` and `+PI/2` the two
+ * sides — the angles shot sets already label 'left' and 'right'.
+ */
+export function turntableViewBasis(yaw: number): OrthographicViewBasis {
+  const direction = new THREE.Vector3(Math.sin(yaw), 0, Math.cos(yaw));
+  const worldUp = new THREE.Vector3(0, 1, 0);
+  const right = worldUp.clone().cross(direction).normalize();
+  const up = direction.clone().cross(right).normalize();
+  return { direction, right, up };
+}
+
+/**
+ * The subject's extent along one camera basis, accumulated point by point.
+ * This is an oriented (not axis-aligned) measurement: `right`/`up` are the
+ * screen axes of the shot being framed, so the span is exactly what that
+ * shot's frustum has to contain.
+ */
+export interface ProjectedSpan {
+  minRight: number;
+  maxRight: number;
+  minUp: number;
+  maxUp: number;
+  minDepth: number;
+  maxDepth: number;
+}
+
+export function createProjectedSpan(): ProjectedSpan {
+  return {
+    minRight: Number.POSITIVE_INFINITY,
+    maxRight: Number.NEGATIVE_INFINITY,
+    minUp: Number.POSITIVE_INFINITY,
+    maxUp: Number.NEGATIVE_INFINITY,
+    minDepth: Number.POSITIVE_INFINITY,
+    maxDepth: Number.NEGATIVE_INFINITY,
+  };
+}
+
+export function isProjectedSpanEmpty(span: ProjectedSpan): boolean {
+  return span.maxRight < span.minRight;
+}
+
+/** Return a span to its empty state, so one allocation can measure a long
+ *  series of small subjects (the per-primitive coverage walk measures one
+ *  span per rendered triangle and would otherwise allocate per triangle). */
+export function resetProjectedSpan(span: ProjectedSpan): void {
+  span.minRight = Number.POSITIVE_INFINITY;
+  span.maxRight = Number.NEGATIVE_INFINITY;
+  span.minUp = Number.POSITIVE_INFINITY;
+  span.maxUp = Number.NEGATIVE_INFINITY;
+  span.minDepth = Number.POSITIVE_INFINITY;
+  span.maxDepth = Number.NEGATIVE_INFINITY;
+}
+
+/** Fold one world-space point into a span. Mutates `span` — a capture walks
+ *  every rendered vertex once and folds it into every basis it needs. */
+export function expandProjectedSpan(
+  span: ProjectedSpan,
+  point: THREE.Vector3,
+  basis: OrthographicViewBasis,
+): void {
+  const right = point.dot(basis.right);
+  const up = point.dot(basis.up);
+  const depth = point.dot(basis.direction);
+  if (right < span.minRight) span.minRight = right;
+  if (right > span.maxRight) span.maxRight = right;
+  if (up < span.minUp) span.minUp = up;
+  if (up > span.maxUp) span.maxUp = up;
+  if (depth < span.minDepth) span.minDepth = depth;
+  if (depth > span.maxDepth) span.maxDepth = depth;
+}
+
+/** The world-space point at the centre of a span — where the shot's camera
+ *  looks. Reconstructed from the basis, so it is the centre of the ORIENTED
+ *  box the shot sees, not of a world-axis-aligned proxy. */
+export function projectedSpanCenter(
+  span: ProjectedSpan,
+  basis: OrthographicViewBasis,
+): THREE.Vector3 {
+  if (isProjectedSpanEmpty(span)) {
+    throw new Error('Asset preview cannot frame an empty projected span.');
+  }
+  return new THREE.Vector3()
+    .addScaledVector(basis.right, (span.minRight + span.maxRight) / 2)
+    .addScaledVector(basis.up, (span.minUp + span.maxUp) / 2)
+    .addScaledVector(basis.direction, (span.minDepth + span.maxDepth) / 2);
+}
+
+/** An orthographic frustum's half-extents, already padded and aspect-fitted. */
+export interface OrthographicFrame {
+  halfWidth: number;
+  halfHeight: number;
+}
+
+/**
+ * Fit half-extents that contain `halfRight` x `halfUp` at the output aspect,
+ * with the engine's standard padding. Height leads and width follows, so the
+ * rendered pixels are never anisotropic relative to the subject.
+ */
+export function fitOrthographicFrame(
+  halfRight: number,
+  halfUp: number,
+  aspect: number,
+  padding: number = ASSET_PREVIEW_PADDING,
+): OrthographicFrame {
+  const halfHeight = Math.max(halfUp, halfRight / aspect, MIN_HALF_EXTENT) * padding;
+  return { halfHeight, halfWidth: halfHeight * aspect };
+}
+
+/** Fit the frame a single projected span needs. */
+export function fitProjectedSpanFrame(
+  span: ProjectedSpan,
+  aspect: number,
+  padding: number = ASSET_PREVIEW_PADDING,
+): OrthographicFrame {
+  if (isProjectedSpanEmpty(span)) {
+    throw new Error('Asset preview cannot frame an empty projected span.');
+  }
+  return fitOrthographicFrame(
+    (span.maxRight - span.minRight) / 2,
+    (span.maxUp - span.minUp) / 2,
+    aspect,
+    padding,
+  );
+}
+
+/**
+ * The frame every turntable shot of one staged subject shares: the UNION of
+ * what each yaw needs.
+ *
+ * Why the union rather than a per-shot exact fit. A verify shot set is read
+ * as a SET — the reviewer compares the same junction across yaws (and, on a
+ * contact sheet, side by side). A per-shot fit silently rescales the subject
+ * between frames, so a wing that looks thicker at yaw 0 than at yaw PI/2
+ * would be a framing artefact rather than geometry, which is exactly the
+ * kind of false signal a verify render exists to eliminate. The union keeps
+ * ONE scale for every turntable shot of a staged subject while each shot is
+ * still CENTRED on its own projected span — so nothing clips and nothing
+ * rescales.
+ *
+ * The union is per staged subject (the rest scene, and each named pose's
+ * disposable snapshot) rather than across poses: poses are separately
+ * staged already, and a single extreme pose must not shrink every other
+ * frame in the set.
+ */
+export function unionOrthographicFrames(frames: readonly OrthographicFrame[]): OrthographicFrame {
+  if (frames.length === 0) {
+    throw new Error('Asset preview cannot union an empty set of frames.');
+  }
+  let halfWidth = 0;
+  let halfHeight = 0;
+  for (const frame of frames) {
+    halfWidth = Math.max(halfWidth, frame.halfWidth);
+    halfHeight = Math.max(halfHeight, frame.halfHeight);
+  }
+  return { halfWidth, halfHeight };
+}
+
+/**
+ * The frame a bone-anchored crop needs: a margin proportional to the WHOLE
+ * model's own bounding radius (never a fixed reference-human height, so a
+ * goblin's crop stays goblin-scaled), widened until it actually contains
+ * every anchor.
+ *
+ * Offsets are measured along the SHOT's basis, so a crop taken from the side
+ * frames the anchors it names from the side. At the default yaw the basis is
+ * (+X, +Y, +Z) and this reduces exactly to the world-axis arithmetic it
+ * replaced.
+ */
+export function fitBoneZoomFrame(
+  anchors: readonly THREE.Vector3[],
+  center: THREE.Vector3,
+  basis: OrthographicViewBasis,
+  overallRadius: number,
+  spanFraction: number,
+  aspect: number,
+): OrthographicFrame {
+  const margin = Math.max(overallRadius * spanFraction, MIN_HALF_EXTENT);
+  let halfWidth = margin;
+  let halfHeight = margin;
+  const offset = new THREE.Vector3();
+  for (const point of anchors) {
+    offset.copy(point).sub(center);
+    halfWidth = Math.max(halfWidth, Math.abs(offset.dot(basis.right)) + margin);
+    halfHeight = Math.max(halfHeight, Math.abs(offset.dot(basis.up)) + margin);
+  }
+  // Keep the crop's aspect consistent with the output image so neither axis
+  // is silently clipped relative to what actually got rendered.
+  halfWidth = Math.max(halfWidth, halfHeight * aspect);
+  halfHeight = Math.max(halfHeight, halfWidth / aspect);
+  return { halfWidth, halfHeight };
+}
+
+/** The mean of the anchor points a bone-zoom crop is built around. */
+export function boneZoomCenter(anchors: readonly THREE.Vector3[]): THREE.Vector3 {
+  if (anchors.length === 0) {
+    throw new Error('Asset preview cannot centre a bone-zoom crop on zero anchors.');
+  }
+  const center = new THREE.Vector3();
+  for (const point of anchors) center.add(point);
+  return center.multiplyScalar(1 / anchors.length);
+}
+
+/**
+ * What one orthographic shot actually renders, in the SAME scalar
+ * coordinates a {@link ProjectedSpan} is measured in (`point.dot(right)`,
+ * `point.dot(up)`, `point.dot(direction)`) — so a shot's frame and the
+ * subject's measured extent are directly comparable without a second
+ * projection convention.
+ *
+ * This exists for the empty-frame guard: a verify shot that frames NO
+ * geometry renders pure background, lands on a contact sheet looking like
+ * coverage, and proves nothing. Detecting that is a containment question
+ * about the vertices the capture already walks, not a question about pixels.
+ */
+export interface ShotFrameWindow {
+  minRight: number;
+  maxRight: number;
+  minUp: number;
+  maxUp: number;
+  /** Depth here is `point.dot(direction)`, which INCREASES toward the camera
+   *  (`direction` points from subject to camera), so the near plane is the
+   *  MAXIMUM depth and the far plane the minimum. */
+  minDepth: number;
+  maxDepth: number;
+}
+
+/**
+ * The window a configured orthographic shot camera renders, read back off the
+ * camera itself rather than recomputed from the inputs that built it — so the
+ * guard tests what will be drawn, including the padding and aspect fitting
+ * {@link fitOrthographicFrame} applied.
+ */
+export function orthographicShotFrameWindow(
+  camera: THREE.OrthographicCamera,
+  basis: OrthographicViewBasis,
+): ShotFrameWindow {
+  const right = camera.position.dot(basis.right);
+  const up = camera.position.dot(basis.up);
+  const depth = camera.position.dot(basis.direction);
+  const zoom = camera.zoom || 1;
+  return {
+    minRight: right + camera.left / zoom,
+    maxRight: right + camera.right / zoom,
+    minUp: up + camera.bottom / zoom,
+    maxUp: up + camera.top / zoom,
+    minDepth: depth - camera.far,
+    maxDepth: depth - camera.near,
+  };
+}
+
+/**
+ * Could anything measured into `span` appear in this shot?
+ *
+ * `span` is expected to be ONE rendered primitive (a triangle, a line
+ * segment, a sprite quad), measured in the shot's own basis — so this is an
+ * overlap test between the primitive's projected bounding box and the frame.
+ *
+ * The asymmetry is deliberate and is what makes the empty-frame warning
+ * trustworthy: a primitive whose box overlaps the frame may still miss it
+ * (a thin diagonal triangle), so "overlaps" does not prove the shot shows
+ * something — but NO primitive overlapping does prove it shows nothing. The
+ * guard only ever claims the second. Testing individual VERTICES instead
+ * would invert that: a crop sitting inside one large flat face contains no
+ * vertex while rendering solid geometry, and would be reported as empty.
+ */
+export function spanOverlapsShotFrame(span: ProjectedSpan, window: ShotFrameWindow): boolean {
+  if (isProjectedSpanEmpty(span)) return false;
+  return (
+    span.maxRight >= window.minRight &&
+    span.minRight <= window.maxRight &&
+    span.maxUp >= window.minUp &&
+    span.minUp <= window.maxUp &&
+    span.maxDepth >= window.minDepth &&
+    span.minDepth <= window.maxDepth
+  );
+}
+
+/**
+ * Build the configured orthographic camera for one shot. `distance` and
+ * `far` are the depth budget the caller derives from the subject's own
+ * bounding radius; the frame and target come from the projected measurements
+ * above.
+ */
+export function createOrthographicShotCamera(
+  target: THREE.Vector3,
+  basis: OrthographicViewBasis,
+  frame: OrthographicFrame,
+  distance: number,
+  far: number,
+): THREE.OrthographicCamera {
+  const camera = new THREE.OrthographicCamera(
+    -frame.halfWidth,
+    frame.halfWidth,
+    frame.halfHeight,
+    -frame.halfHeight,
+    0.01,
+    far,
+  );
+  camera.position.copy(target).addScaledVector(basis.direction, distance);
+  camera.up.copy(basis.up);
+  camera.lookAt(target);
+  camera.updateProjectionMatrix();
+  camera.updateMatrixWorld(true);
+  return camera;
+}