partforge 0.106.1 → 0.108.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.106.1",
+  "version": "0.108.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/capture-frame.js

@@ -15,22 +15,26 @@
 // recentred image is a pixel-exact crop of what the user framed — at the full
 // requested resolution and with no second JPEG encode.
 import * as THREE from "three";
-
-const NEAR = 0.1;
-const FAR = 1000;
+import { DEFAULT_NEAR, DEFAULT_FAR, depthRangeFor } from "./depth-range.js";
 
 // The temp camera an offscreen capture renders with. `aspect` is the FULL
 // frame's aspect; a recentred sub-window is applied afterwards by the caller
 // via setViewOffset, which (for a PerspectiveCamera) keeps this aspect as the
 // virtual full frame's. Matrices are updated so a caller can project through
 // matrixWorldInverse without a render having happened first.
+//
+// `near`/`far` default to the historical fixed pair, which is what a caller
+// with no bounds to offer gets. Derive them from `sceneBounds` instead — see
+// captureDepthRange — and a part large enough to reach 1000 mm keeps its far
+// corner in the picture.
 export function makeCaptureCamera(
   { position, up, target },
-  { aspect = 1, fov = 45, projection = "perspective", orthoHalfH = 1 } = {},
+  { aspect = 1, fov = 45, projection = "perspective", orthoHalfH = 1,
+    near = DEFAULT_NEAR, far = DEFAULT_FAR } = {},
 ) {
   const cam = projection === "orthographic"
-    ? new THREE.OrthographicCamera(-orthoHalfH * aspect, orthoHalfH * aspect, orthoHalfH, -orthoHalfH, NEAR, FAR)
-    : new THREE.PerspectiveCamera(fov, aspect, NEAR, FAR);
+    ? new THREE.OrthographicCamera(-orthoHalfH * aspect, orthoHalfH * aspect, orthoHalfH, -orthoHalfH, near, far)
+    : new THREE.PerspectiveCamera(fov, aspect, near, far);
   cam.position.set(position[0], position[1], position[2]);
   cam.up.set(up[0], up[1], up[2]);
   cam.lookAt(target[0], target[1], target[2]);
@@ -38,6 +42,30 @@ export function makeCaptureCamera(
   return cam;
 }
 
+// The depth range for a capture seen from `pose` that will draw everything
+// inside `sceneBounds` — `{ center, radius }`, where the radius is the one
+// ENCLOSING every visible point, not the framing radius cameraPoseForView
+// takes (that one is half the max extent, which under-reports a box's corners
+// by up to √3 and would clip exactly what this exists to stop clipping).
+//
+// It is one function, called with the
+// same arguments by the render and by the recentring math, because those two
+// must agree to the bit about which vertices are inside the frustum:
+// projectedExtent reports NO extent when any vertex falls outside it, so a
+// recentred capture measured through a different near/far than the render
+// draws with would either give up on a framing that was fine or centre on one
+// that was not. Absent bounds — an empty scene — keeps the fixed pair.
+export function captureDepthRange(pose, { sceneBounds, projection } = {}) {
+  if (!sceneBounds) return { near: DEFAULT_NEAR, far: DEFAULT_FAR };
+  const [cx, cy, cz] = sceneBounds.center;
+  const [px, py, pz] = pose.position;
+  return depthRangeFor({
+    distance: Math.hypot(px - cx, py - cy, pz - cz),
+    radius: sceneBounds.radius,
+    projection,
+  });
+}
+
 // Exact 2-D extent of the meshes' projected vertices, as fractions of the
 // frame with a top-left origin ({ left, top, right, bottom }; values outside
 // [0, 1] mean the geometry runs past that edge). Null when there is nothing
@@ -111,8 +139,9 @@ export function cropRenderFrame(crop, { aspect, long }) {
 // be kept as-is (part cropped by the viewport, already centred, or nothing to
 // measure). `meshes` are the visible sub-part meshes; the camera parameters
 // must be the same ones the render will use.
-export function recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long }) {
-  const camera = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH });
+export function recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long, sceneBounds }) {
+  const depth = captureDepthRange(pose, { sceneBounds, projection });
+  const camera = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH, ...depth });
   const crop = centeredCropView(projectedExtent(camera, meshes));
   return crop ? cropRenderFrame(crop, { aspect, long }) : null;
 }

package/src/framework/depth-range.js

@@ -0,0 +1,89 @@
+// Where the camera's near and far planes go. Pure, so the one property that
+// matters — that nothing the viewer draws can fall outside them — is
+// unit-testable without a renderer.
+//
+// They used to be constants, 0.1 and 1000, from when every part was a spacer
+// or a bracket. `frameTo` frames at `2.6 * maxExtent + 6` mm, so a 300 mm box
+// is viewed from 786 mm with its far corner another 260 mm out: past 1000, and
+// the back of the box is simply not drawn. The first cube that clips is about
+// 287 mm, which is why nothing looked wrong for a year and then arrived as a
+// bug report about one particular box. Zooming out clips it away entirely, and
+// the same constants reached the offscreen captures, so a part big enough took
+// its far corner off the agent-facing renders too.
+//
+// So both planes are derived instead, from the sphere enclosing what is being
+// drawn and the camera's distance to it. Two forces pull against each other:
+//
+//   * nothing may be clipped — far must reach past the furthest visible point
+//     and near must stop short of the nearest one;
+//   * the depth buffer must stay precise — its resolution falls off with the
+//     far/near RATIO, so both planes want to hug the geometry.
+//
+// Hugging exactly would rewrite the projection matrix on every frame of every
+// orbit, and a depth buffer whose resolution changes each frame makes
+// near-coplanar surfaces (a part and the feature-edge lines drawn on it)
+// shimmer. So both are QUANTIZED to quarter-octave steps — far rounded up,
+// near rounded down. That keeps each on the safe side of the geometry, bounds
+// the waste at one step, and leaves the projection matrix untouched for as
+// long as a slow dolly stays inside a step.
+
+// Quarter-octave steps: neighbouring values differ by 2^(1/4) ≈ 1.19, so the
+// range is at most ~19% wider than it needs to be at each end.
+const STEPS_PER_OCTAVE = 4;
+const quantizeUp = (v) => 2 ** (Math.ceil(Math.log2(v) * STEPS_PER_OCTAVE) / STEPS_PER_OCTAVE);
+const quantizeDown = (v) => 2 ** (Math.floor(Math.log2(v) * STEPS_PER_OCTAVE) / STEPS_PER_OCTAVE);
+
+// The scene holds more than the meshes a caller measures its radius from: the
+// cutaway gizmo's handles, measurement dimension lines and their pins, a pick
+// marker. All of them are sized and placed relative to the part, so one
+// proportional margin covers the lot. It costs a slice of depth range and
+// nothing visible.
+export const SCENE_MARGIN = 1.25;
+
+// Depth precision is a function of far/near, never of either alone. A 24-bit
+// buffer carries 1e5 comfortably. This ceiling binds only when the camera is
+// inside the scene sphere, which is exactly where there is no true "nearest
+// visible point" to put a near plane in front of.
+const MAX_DEPTH_RATIO = 1e5;
+
+// Near plane for a camera inside the sphere, as a fraction of the scene: how
+// close you may put the lens to a surface before it starts to disappear.
+const INSIDE_NEAR_FRACTION = 1e-4;
+
+// What an empty scene keeps: the historical constants, so a viewer with
+// nothing shown behaves exactly as it always did.
+export const DEFAULT_NEAR = 0.1;
+export const DEFAULT_FAR = 1000;
+
+/**
+ * Near/far planes for a camera `distance` from the centre of a sphere of
+ * `radius` enclosing everything that will be drawn. Degenerate input (an empty
+ * scene, a non-finite pose) falls back to the historical constants rather than
+ * producing a broken projection.
+ */
+export function depthRangeFor({ distance, radius, projection = "perspective" } = {}) {
+  if (!(radius > 0) || !Number.isFinite(distance) || distance < 0) {
+    return { near: DEFAULT_NEAR, far: DEFAULT_FAR };
+  }
+  const reach = radius * SCENE_MARGIN;
+  const far = quantizeUp(distance + reach);
+  const nearest = distance - reach;
+
+  // An orthographic projection divides by nothing, so it has no precision
+  // falloff and no ratio to defend — and its camera position is a direction
+  // more than a place, which is why three allows a NEGATIVE near there. Taking
+  // it is what keeps the half of the part "behind" the camera on screen after
+  // a swap from a perspective view that had been dollied inside the part.
+  if (projection === "orthographic") {
+    if (nearest === 0) return { near: 0, far };
+    return { near: nearest > 0 ? quantizeDown(nearest) : -quantizeUp(-nearest), far };
+  }
+
+  // A perspective near plane must stay positive, and past this floor the
+  // returned near can sit a hair BEYOND the nearest point rather than in front
+  // of it. That only happens with the camera within far/1e5 of the sphere's
+  // surface — sub-micron on any real part — and the alternative is a depth
+  // buffer with no precision left.
+  const floor = Math.max(radius * INSIDE_NEAR_FRACTION, far / MAX_DEPTH_RATIO);
+  return { near: nearest > 0 ? Math.max(quantizeDown(nearest), floor) : floor, far };
+}

package/src/framework/jobs.js

@@ -112,7 +112,12 @@ async function scoreMatchTargets(built, targets, onProgress) {
         const { best, views } = matchViews(viewMasks, reference, scoreOpts);
         if (!best) continue; // nothing scoreable — a dropped target, never a zero score
         const { delta, ...scores } = best;
-        out.push({ kind: target.kind, best: scores, views, delta: { view: best.view, ...delta } });
+        // The caller's own label for this target, echoed verbatim when it sent one.
+        // Opaque here: a downstream that sends several photographs needs to know
+        // which score is whose, and order cannot say — an unscoreable target is
+        // dropped above and everything after it shifts.
+        const id = typeof target.id === "string" ? { id: target.id } : {};
+        out.push({ kind: target.kind, ...id, best: scores, views, delta: { view: best.view, ...delta } });
       } catch (err) {
         onProgress(`match target skipped: ${String(err?.message || err)}`);
       }

package/src/framework/viewer.js

@@ -10,8 +10,9 @@ import { flashWorldRadius, projectToScreen, anchorMoved } from "./pick-flash.js"
 import { createCameraTween } from "./camera-tween.js";
 import { orbitPose } from "./camera-orbit.js";
 import { orthoFrustum, perspectiveDistance } from "./projection.js";
+import { depthRangeFor } from "./depth-range.js";
 import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
-import { makeCaptureCamera, recenteredView } from "./capture-frame.js";
+import { makeCaptureCamera, recenteredView, captureDepthRange } from "./capture-frame.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
 // three renders into a render target in the LINEAR working colour space: as of r184
@@ -44,7 +45,7 @@ export function srgbEncodeInPlace(data) {
 // `renderer.renderOffscreen(pose)` does the GL work (temp camera → offscreen
 // target → readback → JPEG data URL); injected so this is unit-testable without
 // a GL context. The grid is hidden for the whole synchronous pass and restored.
-export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, bounds, hidden = [] }) {
+export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, bounds, sceneBounds, hidden = [] }) {
   const views = (viewNames?.length ? viewNames : ["iso", "front", "top"])
     .filter((v) => CANONICAL_VIEWS.includes(v))
     .slice(0, CANONICAL_VIEWS.length);
@@ -54,10 +55,13 @@ export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, b
   const hiddenWas = hidden.map((o) => o.visible);
   for (const o of hidden) o.visible = false;
   try {
-    return views.map((view) => ({
-      view,
-      dataUrl: renderer.renderOffscreen(cameraPoseForView(view, bounds)),
-    }));
+    return views.map((view) => {
+      const pose = cameraPoseForView(view, bounds);
+      // `bounds` frames (half the max extent, by cameraPoseForView's contract);
+      // `sceneBounds` is the sphere the depth planes must hold. The grid is
+      // hidden for this whole pass, so the part alone is in the second one.
+      return { view, dataUrl: renderer.renderOffscreen(pose, { sceneBounds }) };
+    });
   } finally {
     if (grid) grid.visible = gridWasVisible;
     hidden.forEach((o, i) => { o.visible = hiddenWas[i]; });
@@ -111,7 +115,7 @@ export function thumbnailBackground(background = THUMBNAIL_BG) {
 // `meshes` are the visible sub-part meshes it reads.
 export function captureCurrentFromScene(
   { size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {},
-  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH, meshes },
+  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH, meshes, sceneBounds },
 ) {
   const MIN_SIZE = 256;
   // WebGL2 guarantees MAX_TEXTURE_SIZE >= 2048; only trust a larger reported cap.
@@ -133,13 +137,13 @@ export function captureCurrentFromScene(
   const fov = liveCamera.fov ?? 45;
   // Null means "keep the viewport framing": part cropped by the viewport,
   // already centred, or nothing to measure.
-  const frame = (recenter && recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long }))
+  const frame = (recenter && recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long, sceneBounds }))
     || { width, height };
   const before = liveCamera.position.clone();
   const gridWasVisible = grid?.visible;
   if (grid && hideGrid) grid.visible = false;
   try {
-    return renderer.renderOffscreen(pose, { ...frame, fov, quality, projection, orthoHalfH });
+    return renderer.renderOffscreen(pose, { ...frame, fov, quality, projection, orthoHalfH, sceneBounds });
   } finally {
     if (grid && hideGrid) grid.visible = gridWasVisible;
     liveCamera.position.copy(before); // belt-and-suspenders: never leak camera state
@@ -380,6 +384,56 @@ export function createViewer(container, part) {
     return _worldBounds;
   }
 
+  // --- depth range ------------------------------------------------------------
+  // The sphere the near/far planes are sized against: everything a render will
+  // actually draw, as `{ center, radius }`. `withGrid` is a parameter rather
+  // than a read of `grid.visible` because the offscreen captures hide the grid
+  // for the duration of their render and ask for their bounds either side of
+  // that — and the grid is the bigger half of the answer for a small part
+  // (300 mm across a 12 mm spacer), so getting it wrong is not a rounding
+  // error. Null when there is nothing to draw.
+  const _depthBounds = new THREE.Box3();
+  const _depthCenter = new THREE.Vector3();
+  const _depthSize = new THREE.Vector3();
+  const _gridCorner = new THREE.Vector3();
+  function sceneDepthBounds({ withGrid } = {}) {
+    // getVisibleWorldBounds returns a SHARED Box3 that the cutaway also reads,
+    // so copy before touching it.
+    _depthBounds.copy(getVisibleWorldBounds());
+    if (withGrid) {
+      const half = GRID_SIZE / 2;
+      _depthBounds.expandByPoint(_gridCorner.set(-half, floorY, -half));
+      _depthBounds.expandByPoint(_gridCorner.set(half, floorY, half));
+    }
+    if (_depthBounds.isEmpty()) return null;
+    return {
+      center: _depthBounds.getCenter(_depthCenter).toArray(),
+      radius: _depthBounds.getSize(_depthSize).length() / 2,
+    };
+  }
+
+  // Re-size the live camera's depth range to the scene, once per frame. Cheap
+  // by construction — the bounds are a union of already-computed per-mesh
+  // boxes, and depthRangeFor quantizes, so the projection matrix is rebuilt
+  // only when the answer actually moves a step. Only the ACTIVE camera is
+  // written: the two projections take different near planes (an orthographic
+  // one may legitimately be negative, which would be a broken perspective
+  // matrix), and setProjection re-runs this on the camera it swaps in.
+  function updateDepthRange() {
+    const bounds = sceneDepthBounds({ withGrid: grid.visible });
+    if (!bounds) return; // nothing shown — leave the planes where they are
+    const { near, far } = depthRangeFor({
+      // _depthCenter is the vector sceneDepthBounds just wrote its centre into.
+      distance: activeCamera.position.distanceTo(_depthCenter),
+      radius: bounds.radius,
+      projection: projectionMode,
+    });
+    if (activeCamera.near === near && activeCamera.far === far) return;
+    activeCamera.near = near;
+    activeCamera.far = far;
+    activeCamera.updateProjectionMatrix();
+  }
+
   const cutaway = createCutaway({
     renderer,
     scene,
@@ -576,21 +630,24 @@ export function createViewer(container, part) {
       // The bound exists because ortho zoom is UNBOUNDED and zooming a long way
       // out costs nothing there (an ortho projection has no depth falloff) —
       // while the recovered distance goes as 1/zoom, so a zoom near nothing would
-      // fling the perspective camera past its own far plane and blank the viewer
-      // with no cue as to why. `far * 0.9` alone would be too eager: frameTo
-      // frames at 2.6r + 6 MILLIMETRES, so an everyday 300mm part sits at 786mm
-      // and a plain toggle would silently reframe it closer. Hence the max with
-      // the distance the camera is already at, which makes an untouched round
-      // trip (zoom === 1, where orthoFrustum/perspectiveDistance are exact
-      // inverses) lossless for a part of ANY size, and still never lets a
-      // degenerate zoom move the camera further out than it already was.
+      // fling the perspective camera an absurd distance out and leave the part a
+      // speck, with no cue as to why. The far plane is the yardstick because it
+      // is by definition past everything worth looking at; read off `from`,
+      // which is the camera that is still live and therefore the one
+      // updateDepthRange has been keeping current. `far * 0.9` alone would be
+      // too eager: frameTo frames at 2.6r + 6 MILLIMETRES, so an everyday 300mm
+      // part sits at 786mm and a plain toggle would silently reframe it closer.
+      // Hence the max with the distance the camera is already at, which makes an
+      // untouched round trip (zoom === 1, where orthoFrustum/perspectiveDistance
+      // are exact inverses) lossless for a part of ANY size, and still never lets
+      // a degenerate zoom move the camera further out than it already was.
       // `|| 1` on the zoom for the same reason captureCurrent guards it: a zero
       // would make this non-finite.
       const halfH = (orthoCamera.top - orthoCamera.bottom) / 2 || 1;
       const offset = from.position.clone().sub(controls.target);
       const distance = Math.min(
         perspectiveDistance({ halfH, zoom: orthoCamera.zoom || 1, fovDeg: camera.fov }),
-        Math.max(camera.far * 0.9, offset.length()),
+        Math.max(from.far * 0.9, offset.length()),
       );
       camera.position.copy(controls.target).addScaledVector(offset.normalize(), distance);
     }
@@ -598,6 +655,11 @@ export function createViewer(container, part) {
     activeCamera = to;
     controls.object = to;
     controls.update();
+    // The incoming camera's depth range is whatever it was left with when it
+    // was last live, and the two projections do not take the same near plane.
+    // Everything below reads a projection matrix, so re-derive it here rather
+    // than waiting for the next frame.
+    updateDepthRange();
     // The projection matrix is not the world matrix, and `to` has never been
     // rendered — nothing has composed its matrixWorld, which WebGLRenderer would
     // not fix up until the NEXT frame. Two readers get there first: the listener
@@ -854,7 +916,7 @@ export function createViewer(container, part) {
   // output is a pixel-exact crop of what the user framed.
   function renderOffscreen(pose,
                            { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9,
-                             projection = "perspective", orthoHalfH = 1, viewOffset } = {},
+                             projection = "perspective", orthoHalfH = 1, viewOffset, sceneBounds } = {},
                            renderScene = scene) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
@@ -866,7 +928,12 @@ export function createViewer(container, part) {
     // through the same helper the recentring math projects through, so the two
     // can never disagree about where a vertex lands.
     const aspect = viewOffset ? viewOffset.fullWidth / viewOffset.fullHeight : width / height;
-    const cam = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH });
+    // `sceneBounds` encloses what this render will draw; without it the camera
+    // keeps the fixed historical planes, which is right for a caller with
+    // nothing to measure and wrong for a part 300 mm across.
+    const cam = makeCaptureCamera(pose, {
+      aspect, fov, projection, orthoHalfH, ...captureDepthRange(pose, { sceneBounds, projection }),
+    });
     if (viewOffset) cam.setViewOffset(viewOffset.fullWidth, viewOffset.fullHeight, viewOffset.x, viewOffset.y, width, height);
     const { position, up, target } = pose;
     const buf = new Uint8Array(width * height * 4);
@@ -948,6 +1015,10 @@ export function createViewer(container, part) {
       grid,
       hidden: [...canonicalCaptureHidden],
       bounds: { center, radius },
+      // The ENCLOSING radius, which is a different number from the framing one
+      // above: a box's corners reach √3 further than half its max extent, and
+      // the depth planes have to clear the corners.
+      sceneBounds: { center, radius: size.length() / 2 || 10 },
     });
   }
 
@@ -967,6 +1038,9 @@ export function createViewer(container, part) {
       // For `recenter`: the geometry that is actually in the picture. Sub-part
       // meshes only — dimension labels and section caps are overlays on them.
       meshes: Object.values(subMesh).filter((m) => m.visible),
+      // For the depth planes. `hideGrid` is the capture's own default-on option,
+      // so ask whether the grid will still be there when the render happens.
+      sceneBounds: sceneDepthBounds({ withGrid: grid.visible && opts?.hideGrid === false }),
       projection: projectionMode,
       // Divided by zoom, because OrbitControls dollies an ortho camera with
       // `zoom` and leaves the frustum alone: the raw frustum is the un-dollied
@@ -1039,7 +1113,13 @@ export function createViewer(container, part) {
       // camera is live: thumbnails are canonical captures and stay perspective
       // however the user has the projection toggled. cameraPoseForView's distance
       // is tuned to this fov, so a narrower one would crop long, thin parts.
-      return renderOffscreen(pose, { width: size, height: size, fov: camera.fov, quality }, tmpScene);
+      return renderOffscreen(
+        pose,
+        // The throwaway scene holds these meshes and nothing else — no grid, no
+        // gizmo — so its own bounds are the whole of what the planes must hold.
+        { width: size, height: size, fov: camera.fov, quality, sceneBounds: { center, radius } },
+        tmpScene,
+      );
     } finally {
       for (const mesh of built) {
         mesh.geometry.userData.edges?.dispose();
@@ -1073,6 +1153,10 @@ export function createViewer(container, part) {
     for (const cb of [...frameListeners]) {
       try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
     }
+    // After the frame listeners, before anything reads the camera to draw with:
+    // a playback frame may have moved sub-parts or the camera itself, and both
+    // change where the planes belong.
+    updateDepthRange();
     if (cutaway.isEnabled) cutaway.updateForCamera();
     // Re-size the pick markers against the pose this frame will actually draw:
     // a dot is only alive for about a second, but orbiting or zooming inside