@volter/editor-threejs 0.5.211 → 0.5.212

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

@@ -1,27 +1,8 @@
 /**
- * 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.
+ * Pure asset-preview framing math: take projected points, a camera basis and output aspect, and
+ * return frustum extents or an orthographic camera. Each shot measures the subject in its own view
+ * basis, including angled bone crops. Scene traversal and GPU rendering belong to asset-preview.ts.
+ * See turntableViewBasis for the shared yaw convention.
  */
 import * as THREE from 'three';
 
@@ -43,16 +24,7 @@ export interface OrthographicViewBasis {
   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'.
- */
+/** Shared turntable and bone-crop yaw convention: zero faces +Z and increasing yaw moves toward +X; PI is the back and ±PI/2 are the sides. */
 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);
@@ -152,9 +124,8 @@ 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;
+  const halfHeight = Math.max(halfUp, halfRight / aspect, MIN_HALF_EXTENT) * ASSET_PREVIEW_PADDING;
   return { halfHeight, halfWidth: halfHeight * aspect };
 }
 
@@ -162,7 +133,6 @@ export function fitOrthographicFrame(
 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.');
@@ -171,29 +141,10 @@ export function fitProjectedSpanFrame(
     (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.
- */
+/** Use the union of all yaw projections for one staged subject’s scale while centring each shot on its own span. Stage poses independently so one extreme pose does not shrink other subjects. */
 export function unionOrthographicFrames(frames: readonly OrthographicFrame[]): OrthographicFrame {
   if (frames.length === 0) {
     throw new Error('Asset preview cannot union an empty set of frames.');
@@ -207,17 +158,7 @@ export function unionOrthographicFrames(frames: readonly OrthographicFrame[]): O
   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.
- */
+/** Fit bone crops with a margin proportional to the whole model’s bounding radius. Measure offsets in the shot’s own basis and widen until every anchor fits. */
 export function fitBoneZoomFrame(
   anchors: readonly THREE.Vector3[],
   center: THREE.Vector3,