partforge 0.86.0 → 0.87.0

package/docs/AUTHORING-PARTS.md

@@ -1770,7 +1770,7 @@ framing offscreen at a resolution independent of the window size and devicePixel
 for gallery/preview images, where grabbing the live canvas would be capped at the viewer
 pane's pixel size:
 
-- `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9 } = {}) → string | null` —
+- `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {}) → string | null` —
   one offscreen render from the live camera's pose (position, up, and orbit target — not a
   canonical pose) with the live viewport's aspect ratio, `size` px on the long edge
   (clamped into `[256, maxTextureSize]`). Renders with 4× MSAA and the same
@@ -1783,6 +1783,16 @@ pane's pixel size:
   in the scene, so a dimensioned capture needs no special handling — enable measure
   mode (`runtime.measure.setEnabled(true)`) and call `captureCurrent()`; the dims are
   just part of the rendered frame.
+  `recenter: true` centres the part: the capture becomes the largest centred
+  sub-window of the current framing that still holds every visible vertex (equal
+  margins on both axes, rendered at the full `size` resolution through a view
+  offset, so it is a pixel-exact crop of what the user framed — same
+  perspective, no re-encode). The extent is the projection of the actual mesh
+  vertices, not a bounding box, so it is exact at any angle. The framing is
+  kept as-is when the geometry runs past any frame edge (a user who zoomed in
+  past the part's silhouette cropped it on purpose), when it is already centred,
+  or when measurement dimensions are pinned (their labels sit beside the part and
+  could otherwise be cut off).
 - `runtime.captureViews(viewNames) → [{ view, dataUrl }]` — the canonical-angle
   counterpart (fixed poses, framed to the visible assembly, 1024², grid hidden). Sized
   for feeding a vision model, not for display; use `captureCurrent` for showcase images.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.86.0",
+  "version": "0.87.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

@@ -0,0 +1,118 @@
+// Framing math for the showcase capture (viewer.js captureCurrentFromScene):
+// where the visible geometry lands in the rendered frame, and the centred
+// sub-window that puts it in the middle. Pure three.js math, no GL — the
+// renderer builds its camera through makeCaptureCamera too, so what this
+// module projects through is exactly what renderOffscreen draws with.
+//
+// Why vertices and not bounding boxes: the projection of a triangle mesh is a
+// union of projected triangles, and a triangle's projected extremes are its
+// corners — so the min/max over projected VERTICES is the exact 2-D extent of
+// the rendered silhouette at any angle, where a projected 3-D bounding box
+// over-reports by up to the box's slack at diagonal views.
+//
+// Why a view offset and not a pixel crop: three's setViewOffset renders a
+// sub-window of a larger virtual frame with the same projection, so the
+// 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;
+
+// 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.
+export function makeCaptureCamera(
+  { position, up, target },
+  { aspect = 1, fov = 45, projection = "perspective", orthoHalfH = 1 } = {},
+) {
+  const cam = projection === "orthographic"
+    ? 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]);
+  cam.updateMatrixWorld(true);
+  return cam;
+}
+
+// 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
+// to project, or when ANY vertex would be clipped by the frustum's near/far
+// planes or sits behind the camera — such a vertex is not in the picture, so
+// no honest extent exists and the caller should leave the framing alone.
+export function projectedExtent(camera, meshes) {
+  const toClip = new THREE.Matrix4();
+  const v = new THREE.Vector4();
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  let any = false;
+  for (const mesh of meshes ?? []) {
+    const pos = mesh?.geometry?.attributes?.position;
+    if (!pos || !pos.count) continue;
+    mesh.updateWorldMatrix(true, false);
+    toClip.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse).multiply(mesh.matrixWorld);
+    for (let i = 0; i < pos.count; i++) {
+      v.set(pos.getX(i), pos.getY(i), pos.getZ(i), 1).applyMatrix4(toClip);
+      const w = v.w;
+      if (!(w > 0) || v.z < -w || v.z > w) return null;
+      const x = v.x / w, y = v.y / w;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+      any = true;
+    }
+  }
+  if (!any) return null;
+  return { left: (minX + 1) / 2, right: (maxX + 1) / 2, top: (1 - maxY) / 2, bottom: (1 - minY) / 2 };
+}
+
+// The largest sub-window centred on the extent's centre that still fits the
+// frame, as { x, y, width, height } fractions. Centring on the extent with
+// maximal half-extents min(c, 1 - c) gives equal margins on both sides of each
+// axis and is guaranteed to contain the extent (which always lies within
+// [0, 2c] and [2c - 1, 1]). Null — leave the framing alone — when the extent
+// runs past any edge (the user zoomed in on purpose), when it already fills the
+// frame symmetrically (nothing to do), or when there is no usable extent.
+// `eps` forgives the ~1 px feature-edge line that can overhang a vertex.
+export function centeredCropView(extent, { eps = 0.002 } = {}) {
+  if (!extent) return null;
+  const { left, top, right, bottom } = extent;
+  if (![left, top, right, bottom].every(Number.isFinite)) return null;
+  if (left < -eps || top < -eps || right > 1 + eps || bottom > 1 + eps) return null;
+  if (!(right > left) || !(bottom > top)) return null;
+  const cx = (left + right) / 2, cy = (top + bottom) / 2;
+  const hw = Math.min(cx, 1 - cx), hh = Math.min(cy, 1 - cy);
+  if (hw >= 0.5 - eps && hh >= 0.5 - eps) return null;
+  return { x: Math.max(0, cx - hw), y: Math.max(0, cy - hh), width: 2 * hw, height: 2 * hh };
+}
+
+// Turn a fractional crop of a frame with the given aspect into what
+// renderOffscreen needs: the output size (crop rendered at `long` px on its
+// long edge, so recentring costs no resolution) and the setViewOffset
+// arguments describing it as a sub-window of a larger virtual frame.
+export function cropRenderFrame(crop, { aspect, long }) {
+  const cropAspect = (crop.width * aspect) / crop.height;
+  const width = cropAspect >= 1 ? long : Math.max(1, Math.round(long * cropAspect));
+  const height = cropAspect >= 1 ? Math.max(1, Math.round(long / cropAspect)) : long;
+  const fullWidth = width / crop.width;
+  const fullHeight = height / crop.height;
+  return {
+    width, height,
+    viewOffset: { fullWidth, fullHeight, x: crop.x * fullWidth, y: crop.y * fullHeight },
+  };
+}
+
+// The whole pipeline for captureCurrentFromScene: the render frame that puts
+// the visible geometry in the middle, or null when the current framing should
+// 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 });
+  const crop = centeredCropView(projectedExtent(camera, meshes));
+  return crop ? cropRenderFrame(crop, { aspect, long }) : null;
+}

package/src/framework/mount.js

@@ -75,7 +75,15 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // Offscreen render of a named view (default when omitted, or on an unknown name).
     captureView,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
-    captureCurrent: (opts) => viewer.captureCurrent(opts),
+    // `recenter` reads the sub-part geometry only, so with measurement pins on
+    // screen the dimension labels — which sit beside the part, not on it —
+    // could land outside the centred window. A dimensioned capture therefore
+    // keeps the user's exact framing; a host wanting both re-frames first.
+    captureCurrent: (opts) => viewer.captureCurrent(
+      opts?.recenter && (measure ?? NOOP_MEASURE).isEnabled() && (measure ?? NOOP_MEASURE).pinCount() > 0
+        ? { ...opts, recenter: false }
+        : opts,
+    ),
     // Park/unpark the viewer: stops the render loop and frees the drawing
     // buffer and the cached capture target. For an embedder that hides the
     // canvas without unmounting it — `visibility: hidden`, an off-screen tab —

package/src/framework/viewer.js

@@ -9,6 +9,7 @@ import { createCameraTween } from "./camera-tween.js";
 import { orbitPose } from "./camera-orbit.js";
 import { orthoFrustum, perspectiveDistance } from "./projection.js";
 import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
+import { makeCaptureCamera, recenteredView } 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
@@ -98,9 +99,17 @@ export function thumbnailBackground(background = THUMBNAIL_BG) {
 // context: pose comes from the live camera (never a canonical pose), the output
 // long edge is `size` clamped into [256, maxTextureSize], and the short edge
 // follows the live camera's aspect so the capture matches what the user framed.
+//
+// `recenter: true` (opt-in; the default keeps the exact viewport framing) renders
+// the largest centred sub-window that still holds every visible vertex — a
+// showcase image with the part in the middle and equal margins — and leaves the
+// framing alone when the geometry runs off the frame, since a user who zoomed
+// past the part's edge framed that crop on purpose. The extent is projected
+// through the same camera the render uses (capture-frame.js), so it is exact;
+// `meshes` are the visible sub-part meshes it reads.
 export function captureCurrentFromScene(
-  { size = 2048, hideGrid = true, quality = 0.9 } = {},
-  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH },
+  { size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {},
+  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH, meshes },
 ) {
   const MIN_SIZE = 256;
   // WebGL2 guarantees MAX_TEXTURE_SIZE >= 2048; only trust a larger reported cap.
@@ -115,17 +124,20 @@ export function captureCurrentFromScene(
     || 1;
   const width = aspect >= 1 ? long : Math.max(1, Math.round(long * aspect));
   const height = aspect >= 1 ? Math.max(1, Math.round(long / aspect)) : long;
+  const pose = { position: liveCamera.position.toArray(), up: liveCamera.up.toArray(), target };
+  // fov is meaningless under an ortho camera; orthoHalfH replaces it. The
+  // CANONICAL capture path deliberately never passes either — agent-facing
+  // renders stay perspective regardless of what the user is looking at.
+  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 }))
+    || { width, height };
   const before = liveCamera.position.clone();
   const gridWasVisible = grid?.visible;
   if (grid && hideGrid) grid.visible = false;
   try {
-    return renderer.renderOffscreen(
-      { position: liveCamera.position.toArray(), up: liveCamera.up.toArray(), target },
-      // fov is meaningless under an ortho camera; orthoHalfH replaces it. The
-      // CANONICAL capture path deliberately never passes either — agent-facing
-      // renders stay perspective regardless of what the user is looking at.
-      { width, height, fov: liveCamera.fov ?? 45, quality, projection, orthoHalfH },
-    );
+    return renderer.renderOffscreen(pose, { ...frame, fov, quality, projection, orthoHalfH });
   } finally {
     if (grid && hideGrid) grid.visible = gridWasVisible;
     liveCamera.position.copy(before); // belt-and-suspenders: never leak camera state
@@ -822,9 +834,15 @@ export function createViewer(container, part) {
   // the mask silently no-ops and every cap floods its whole plane with hatch —
   // no error, live view unaffected, wrong only in the capture.
   const RT_OPTIONS = { samples: 4, stencilBuffer: true };
-  function renderOffscreen({ position, up, target },
+  //
+  // `viewOffset` ({ fullWidth, fullHeight, x, y }) renders the width×height
+  // output as that sub-window of a larger virtual frame — the recentred
+  // showcase capture (captureCurrentFromScene). The camera's aspect is then the
+  // VIRTUAL frame's, so the projection is exactly the un-offset one and the
+  // 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 } = {},
+                             projection = "perspective", orthoHalfH = 1, viewOffset } = {},
                            renderScene = scene) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
@@ -832,15 +850,13 @@ export function createViewer(container, part) {
       : new THREE.WebGLRenderTarget(width, height, RT_OPTIONS);
     _capLights = _capLights ?? createCaptureLights();
     // Canonical captures never pass `projection`, so agent-facing renders and
-    // the CLI stay perspective no matter what the user is looking at.
-    const cam = projection === "orthographic"
-      ? new THREE.OrthographicCamera(
-          -orthoHalfH * (width / height), orthoHalfH * (width / height),
-          orthoHalfH, -orthoHalfH, 0.1, 1000)
-      : new THREE.PerspectiveCamera(fov, width / height, 0.1, 1000);
-    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]);
+    // the CLI stay perspective no matter what the user is looking at. Built
+    // 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 });
+    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);
     // Swap the world-fixed key/fill for the camera-relative pair, for this one render
     // only. A DirectionalLight aims at its `target`, whose matrixWorld only updates
@@ -923,6 +939,9 @@ export function createViewer(container, part) {
       target: controls.target.toArray(),
       grid,
       maxTextureSize: renderer.capabilities?.maxTextureSize,
+      // 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),
       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

package/types/index.d.ts

@@ -146,6 +146,14 @@ export interface CaptureCurrentOptions {
   hideGrid?: boolean;
   /** JPEG quality, 0..1. */
   quality?: number;
+  /**
+   * Centre the visible geometry: render the largest centred sub-window of the
+   * current framing that still holds every visible vertex (equal margins, full
+   * `size` resolution). When the geometry runs past a frame edge — the user
+   * zoomed in on purpose — or dimensions are pinned, the framing is kept as-is.
+   * Default false.
+   */
+  recenter?: boolean;
 }
 
 export interface CaptureViewOptions {