partforge 0.39.0 → 0.41.0

package/src/testing/min-wall.js

@@ -3,36 +3,96 @@
 // voxel/SDF approach on both accuracy and speed). For each surface triangle, cast a ray
 // inward (reverse of its outward normal) from the centroid; the nearest hit is the local
 // material thickness. The minimum across samples is the reported min wall.
-// Works with both Manifold non-indexed meshes and OCCT indexed meshes (via meshTriangles).
-import { buildBVH, meshTriangles } from "./bvh.js";
+// Works with both Manifold non-indexed meshes and OCCT indexed meshes (via the BVH's
+// flat vertex store — never materialize a triangle-per-object list here, that is the
+// allocation this pass exists to avoid).
+//
+// SAMPLING CONTRACT. One ray per triangle is unbounded work, and a dense mesh makes it
+// the dominant cost of the inspect job: ~1.9 s and hundreds of megabytes of transient
+// garbage at 400k triangles on a laptop, several times that on a phone. Past
+// MAX_SAMPLES triangles the pass casts from a spread subset instead, and SAYS SO —
+// the result always carries { sampled, sampledTriangles, totalTriangles }, so a
+// report consumer can tell a guaranteed minimum from a lower-confidence one. A
+// sampled reading is an upper bound on the true minimum: it can miss a thin spot,
+// never invent one. `sampledTriangles` is the SAMPLE BUDGET — how many triangles
+// the walk selected — not a count of rays actually cast: a degenerate (zero-area)
+// triangle has no normal to cast along and is skipped without a ray.
+//
+// Only an EMPTY mesh reads as no result at all (`null`). A mesh whose sampled rays
+// all miss returns the usual object with `value: null`, because the sampling
+// accounting is exactly what a reader needs in that case — "we looked at 50k of
+// 400k triangles and found no wall" is a very different statement from "nobody
+// measured", and the two used to be indistinguishable downstream.
+import { buildBVH, readTriangleInto } from "./bvh.js";
 
-export function minWall(mesh, { maxThickness } = {}) {
-  const pos = mesh.positions;
-  const tris = meshTriangles(mesh);
-  if (tris.length === 0) return null;
+// Triangle budget above which minWall samples. Chosen so the parts people actually
+// author stay exact: everything in src/parts/ is 200–10,000 triangles, and a
+// preview-quality mesh of a fairly ornate part lands in the low tens of thousands.
+// 50,000 is comfortably above both while capping the pass at roughly a quarter
+// second — dense enough meshes (a high-facet lathe, a big imported STEP tessellation)
+// are the only ones that engage it. Override per call with `{ maxSamples }`.
+const MAX_SAMPLES = 50_000;
 
-  // bbox diagonal as the default cap (a ray exiting into open air gets no hit anyway).
+const gcd = (a, b) => { while (b) { const t = a % b; a = b; b = t; } return a; };
+
+// Stride for the sampling walk: near n/φ and coprime to n, so stepping by it visits
+// a permutation of the triangle list — the first `budget` steps are distinct and, by
+// the three-distance theorem, near-uniformly spread over the WHOLE mesh (measured
+// max gap on a 480-triangle mesh sampled 100 times: 8). A contiguous slice would
+// read one region of the surface, and a plain n/budget stride can beat against a
+// mesh's own periodicity (a lathed part's segment count) and sample one side of it.
+// No RNG anywhere, so the same mesh always reads the same wall.
+function sampleStride(n) {
+  let s = Math.max(1, Math.round(n * 0.6180339887498949)) % n || 1;
+  while (gcd(s, n) !== 1) s = s + 1 < n ? s + 1 : 1;
+  return s;
+}
+
+// `bvh` is an already-built index for THIS mesh — one mesh, one index, so there is
+// nothing to key here: measure() resolves it out of the Map it shares with meshGaps
+// (see cachedBVH for why that Map is the caller's) and passes the value. Omit it and
+// one is built. It does not interact with sampling — sampling picks WHICH rays to
+// cast, not how the index is built, so a shared BVH is equally valid sampled or exact.
+export function minWall(mesh, { maxThickness, maxSamples = MAX_SAMPLES, bvh = buildBVH(mesh) } = {}) {
+  const n = bvh.triangleCount;
+  if (n === 0) return null;
+  const V = bvh.vertices;
+
+  // bbox diagonal as the default cap (a ray exiting into open air gets no hit
+  // anyway). The BVH's root node bounds ARE that box, already computed — rescanning
+  // mesh.positions would be an O(n) pass on the hot path for a number we have. (On
+  // an indexed mesh they are also marginally tighter, since unreferenced vertices
+  // are not in the tree; that only shrinks a ray cap, never a reading.)
   if (maxThickness == null) {
-    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
-    for (let i = 0; i < pos.length; i += 3) for (let a = 0; a < 3; a++) { if (pos[i + a] < min[a]) min[a] = pos[i + a]; if (pos[i + a] > max[a]) max[a] = pos[i + a]; }
-    maxThickness = Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) + 1;
+    const rb = bvh.rootBounds;
+    maxThickness = Math.hypot(rb[3] - rb[0], rb[4] - rb[1], rb[5] - rb[2]) + 1;
   }
 
-  const bvh = buildBVH(mesh);
-  let best = Infinity, loc = null;
-  for (let t = 0; t < tris.length; t++) {
-    const [v0, v1, v2] = tris[t];
-    const e1 = [v1[0] - v0[0], v1[1] - v0[1], v1[2] - v0[2]];
-    const e2 = [v2[0] - v0[0], v2[1] - v0[1], v2[2] - v0[2]];
-    let nx = e1[1] * e2[2] - e1[2] * e2[1], ny = e1[2] * e2[0] - e1[0] * e2[2], nz = e1[0] * e2[1] - e1[1] * e2[0];
+  // `maxSamples: 0` (or any non-positive) is the explicit "no cap, cast everything"
+  // escape hatch — the exact reading, however long it takes.
+  const budget = maxSamples > 0 && n > maxSamples ? Math.floor(maxSamples) : n;
+  const sampled = budget < n;
+  const stride = sampled ? sampleStride(n) : 1;   // stride 1 = every triangle, in mesh order
+
+  let best = Infinity, loc = null, t = 0;
+  const tri = new Float64Array(9);                  // reused per triangle; no per-ray garbage
+  for (let s = 0; s < budget; s++, t = t + stride < n ? t + stride : t + stride - n) {
+    readTriangleInto(V, t, tri);
+    const v0x = tri[0], v0y = tri[1], v0z = tri[2];
+    const e1x = tri[3] - v0x, e1y = tri[4] - v0y, e1z = tri[5] - v0z;
+    const e2x = tri[6] - v0x, e2y = tri[7] - v0y, e2z = tri[8] - v0z;
+    let nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x;
     const len = Math.hypot(nx, ny, nz);
-    if (len < 1e-9) continue;                       // degenerate triangle
+    if (len < 1e-9) continue;                       // degenerate triangle: no normal, no ray
     nx /= len; ny /= len; nz /= len;                // outward normal (manifold winding)
-    const c = [(v0[0] + v1[0] + v2[0]) / 3, (v0[1] + v1[1] + v2[1]) / 3, (v0[2] + v1[2] + v2[2]) / 3];
+    const c = [(v0x + tri[3] + tri[6]) / 3, (v0y + tri[4] + tri[7]) / 3, (v0z + tri[5] + tri[8]) / 3];
     const dir = [-nx, -ny, -nz];                    // inward
     const origin = [c[0] + dir[0] * 1e-4, c[1] + dir[1] * 1e-4, c[2] + dir[2] * 1e-4];
     const hit = bvh.raycast(origin, dir, { tMax: maxThickness, skipTri: t });
     if (hit && hit.t < best) { best = hit.t; loc = c; }
   }
-  return best === Infinity ? null : { value: best, location: loc };
+  // No hit anywhere still reports HOW it looked (see the header): a `value: null`
+  // with the sampling accounting intact, never a bare null that reads downstream as
+  // "min wall was never measured".
+  return { value: best === Infinity ? null : best, location: loc, sampled, sampledTriangles: budget, totalTriangles: n };
 }

package/src/testing/verify.js

@@ -118,14 +118,23 @@ function check(scope, subpart, metric, spec, registry, factsObj) {
   if (actual === null || actual === undefined) {
     if (reg.manifoldOnly) return { ...base, actual, status: "skip", pass: null, message: "n/a (OCCT backend)" };
     if (metric === "minWall") {
-      return { ...base, actual, status: "warn", pass: null, message: "min wall unavailable",
+      const out = { ...base, actual, status: "warn", pass: null, message: "min wall unavailable",
         hint: partHint ?? "no min-wall reading for this mesh — treat thin features as unverified" };
+      // A missing reading still has a HOW: a sampled run whose rays all missed says
+      // so here, rather than reading like a mesh min-wall never looked at.
+      const note = reg.note?.(factsObj);
+      if (note) out.note = note;
+      return out;
     }
     return { ...base, actual, status: "skip", pass: null, message: "unavailable" };
   }
   const { pass, message } = evaluateAssertion(parseAssertion(expr), actual);
   const status = pass ? "pass" : reg.kind === "warn" ? "warn" : "fail";
   const out = { ...base, actual, status, pass, message };
+  // A measurement caveat rides along whatever the verdict — a min-wall reading
+  // taken from a sample still passed, but the reader should know it was a sample.
+  const note = reg.note?.(factsObj);
+  if (note) out.note = note;
   if (!pass) {
     out.hint = partHint ?? reg.hint;
     if (reg.pattern) out.pattern = reg.pattern;
@@ -158,7 +167,10 @@ export function evaluateCase(facts, { profile, expect, subPartNames }) {
   return checks;
 }
 
-export function verify(kernel, part, { process, view, measureFn = defaultMeasure } = {}) {
+// `seed` lets a caller that has ALREADY measured this part hand the result in so
+// verify does not recompute it — see the seeding block below for the shape and
+// the one correctness rule that governs it.
+export function verify(kernel, part, { process, view, measureFn = defaultMeasure, seed } = {}) {
   view = view ?? Object.keys(part.views)[0];
   const profileSpec = process ?? part.verify?.process;
   const profile = profileSpec ? resolveProfile(profileSpec) : null;
@@ -185,6 +197,50 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
       : [...readKeys.entries()].map(([name, keys]) => `${name}:${relevanceHash([...keys], params)}`).join("|");
 
   const memo = new Map();
+
+  // SEEDING. expandCases always yields a "defaults" case, and the inspect job
+  // (framework/jobs.js) measures those exact params immediately before calling
+  // verify — so without this the oracle rebuilds the same geometry, casts the
+  // same min-wall rays and re-indexes the same meshes a second time. On a
+  // single-case part that is half the job.
+  //   seed = { params, result } — the params the result was measured with, and
+  //   the measure() output itself. Nothing else: every fact the rule below needs
+  //   is read off the artifact, so a caller cannot assert it wrongly.
+  //
+  // THE MIN-WALL SUPERSET RULE, which is the trap here. measureCase asks for
+  // `{ minWall: needMinWall }`, and needMinWall is false whenever no profile and
+  // no expectation mentions min wall. A result measured WITH min wall is a strict
+  // superset of one measured without: the extra fields are only ever read by the
+  // minWall metric, which by definition this run never checks. Reuse in that
+  // direction is free. The reverse is NOT safe — a seed taken without min wall
+  // carries `minWall: null` on every sub-part, which the registry reports as
+  // "min wall unavailable", silently downgrading a real gate to a warning. So the
+  // seed is consulted only when `seed.result.measuredMinWall || !needMinWall` —
+  // and `measuredMinWall` is stamped by measure() itself, not claimed by whoever
+  // holds the result. Otherwise the seed is ignored and the case measured properly.
+  //
+  // ALIASING. A consulted seed is memoized BY REFERENCE, so the caller's result
+  // and every case that hits it are the same object — the inspect job's
+  // `report.measure` and `report.verify.cases[0]`'s facts included. Nothing here
+  // mutates facts (evaluateCase only reads), and that is what makes the sharing
+  // safe; a future check that wants to annotate a fact must copy first.
+  //
+  // Keyed through the SAME signature() the memo uses, never a JSON compare of the
+  // raw params — a separate compare would miss cases that share a signature (a
+  // preset touching only params the build never reads) and, worse, could hit on
+  // params that merely look equal. The seed's params are layered over
+  // part.defaults first because a caller's `{}` and the defaults case's
+  // `{...part.defaults}` build identical geometry but hash differently
+  // (JSON.stringify({}) is not JSON.stringify(defaults), and relevanceHash reads
+  // params[k] straight through). The view is checked too: measure()'s output is
+  // per-view, and a seed from another view would be a silent wrong answer.
+  //
+  // Non-default measure options (a custom `gapThreshold`) are the caller's
+  // responsibility: seed only a measurement taken the way verify would take it.
+  if (seed?.result && (seed.result.measuredMinWall || !needMinWall) && seed.result.view === view) {
+    memo.set(signature({ ...part.defaults, ...(seed.params ?? {}) }), seed.result);
+  }
+
   const measureCase = (params) => {
     const key = signature(params);
     if (!memo.has(key)) memo.set(key, measureFn(kernel, part, view, params, { minWall: needMinWall }));