partforge 0.54.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.54.0",
+  "version": "0.55.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/jobs.js

@@ -9,6 +9,9 @@ import { safeName } from "./safe-name.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
 import { measure } from "./oracle/measure.js";
 import { verify } from "./oracle/verify.js";
+import { buildView } from "./oracle/build.js";
+import { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./oracle/silhouette.js";
+import { matchViews } from "./oracle/match.js";
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -26,6 +29,67 @@ import { verify } from "./oracle/verify.js";
 // preview generates stay quiet (no callback) to avoid flicker during slider drags.
 const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
 
+// One caller-supplied match target as a reference mask, or null when it is not one we
+// can score. Every field here is untrusted wire data, so shape is checked rather than
+// assumed — a target the caller got wrong is skipped, never thrown, so one bad entry
+// cannot cost the others their scores (or the caller their geometry report).
+//   {kind: "profile", rings: [[[x,y], ...], ...]}  — millimetres, so it carries scale
+//   {kind: "image",   mask: {data, width, height}} — a photo, so it carries none
+function referenceMask(target) {
+  if (target?.kind === "profile") return Array.isArray(target.rings) ? rasterizeRingsMask(target.rings) : null;
+  if (target?.kind === "image") {
+    const m = target.mask;
+    if (!m?.data || !(m.width > 0) || !(m.height > 0)) return null;
+    // mmPerPx is deliberately absent: a photograph has no millimetres, which is what
+    // keeps the scale-aware comparison off for an image target no matter what is asked.
+    return { data: m.data, width: m.width, height: m.height };
+  }
+  return null;
+}
+
+// Score the part's six canonical silhouettes against each match target.
+// `built` is the view's already-built sub-parts — the meshes are JS-owned, so this
+// reads correctly after the kernel has been cleaned up.
+//
+// Total by construction: match scoring is an EXTRA on top of the geometric report, so
+// any failure here omits `match` and leaves the report itself intact. A caller who
+// asked for a score and got none can ask again; a caller who lost their measurement
+// because a mask blew up has lost the thing they actually came for.
+//
+// The six mesh masks are rasterized ONCE and shared across every target — the targets
+// are the cheap side of this (a couple of reference masks), the part is not.
+function scoreMatchTargets(built, targets, onProgress) {
+  if (!targets?.length) return null;
+  try {
+    const meshes = built.map((b) => b.mesh);
+    const viewMasks = {};
+    for (const view of MATCH_VIEWS) viewMasks[view] = rasterizeMeshMask(meshes, view);
+
+    const out = [];
+    for (const target of targets) {
+      try {
+        const reference = referenceMask(target);
+        if (!reference) continue;
+        // scaleAware is the CALLER's promise that both sides are in millimetres, and
+        // this is the caller: rings are mm and the mesh masks carry mmPerPx, so a
+        // profile target gets the absolute-size score (`iouScale`, contourDist in mm)
+        // while an image target gets the pose-normalized one.
+        const scoreOpts = { scaleAware: target.kind === "profile" };
+        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 } });
+      } catch (err) {
+        onProgress(`match target skipped: ${String(err?.message || err)}`);
+      }
+    }
+    return out.length ? out : null;
+  } catch (err) {
+    onProgress(`match scoring skipped: ${String(err?.message || err)}`);
+    return null;
+  }
+}
+
 export async function handle(kernel, part, msg, post, opts = {}) {
   const isStale = opts.isStale ?? (() => false);
   const onProgress = (phase) => post({ type: "progress", phase, jobId: msg.jobId });
@@ -147,7 +211,12 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // true }` here is what makes the seed usable by any verify run, min-wall
       // gated or not — the result says so itself (`measuredMinWall`), so this
       // call and the seed cannot drift apart.
-      const measured = measure(kernel, part, msg.view, msg.params ?? {}, { minWall: true });
+      //
+      // The view is built HERE rather than inside measure, and handed down through
+      // `opts.built`, because optional match scoring needs the same meshes: one build
+      // feeds the measurement and the six silhouette rasterizations both.
+      const built = buildView(kernel, part, msg.view, msg.params ?? {});
+      const measured = measure(kernel, part, msg.view, msg.params ?? {}, { minWall: true, built });
       const report = {
         measure: measured,
         verify: verify(kernel, part, {
@@ -155,7 +224,11 @@ export async function handle(kernel, part, msg, post, opts = {}) {
           seed: { params: msg.params ?? {}, result: measured },
         }),
       };
-      post({ type: "report", ...report });
+      // `match` is present only when the caller asked for it AND something scored, so
+      // an inspect with no `matchTargets` answers on exactly the shape it always has.
+      const match = scoreMatchTargets(built, msg.matchTargets, onProgress);
+      if (match) report.match = match;
+      post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
     }
   } catch (err) {
     if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId });

package/src/framework/oracle/match.js

@@ -0,0 +1,263 @@
+// Mask comparison: score a candidate silhouette against a reference one. Consumes the
+// masks oracle/silhouette.js produces and answers "how close is this shape?" four ways —
+// area overlap (`iou`), rim overlap (`boundaryIoU`), a mean contour separation
+// (`contourDist`), and a per-pixel `delta` map naming what is missing versus extra. No
+// kernel, no DOM, no three, no `node:`, so it runs in the geometry worker like the rest
+// of the oracle.
+//
+// Shape is compared POSE-NORMALIZED: each mask is cropped to its tight foreground bbox,
+// scaled so its longest side fills 0.92 of a 256² frame, and centroid-aligned there. So
+// `iou`, `boundaryIoU`, and `delta` are invariant to where the part sits and how big it
+// is, which is what "does it look like the picture?" means. Absolute size is a separate
+// question and only `{scaleAware: true}` asks it — and only when BOTH masks carry a
+// finite mmPerPx: `iouScale` overlays them on the reference's own mm grid,
+// centroid-aligned and never rescaled, so a part twice too big scores 0.25, and
+// `contourDist` is then a real millimetre distance instead of a fraction of the
+// reference's bbox diagonal.
+//
+// A mask with no foreground pixels — or no mask at all — is UNSCOREABLE, not
+// zero-scoring: matchMasks returns null and matchViews leaves the view out. 0/0 is
+// never a score.
+
+import { MATCH_VIEWS } from "./silhouette.js";
+
+const S = 256;            // internal normalization frame, whatever the input mask sizes
+const FILL = 0.92;        // fraction of the frame the longest bbox side occupies
+const BAND_PX = 2;        // boundary band thickness, per the Boundary IoU definition
+const BIG = 1e20;         // "unreachable" seed for the distance transform's lower envelope
+const MAX_MM_FRAME = 2048; // px ceiling on the scale-aware grid; see mmFrame
+
+// candidate/reference: Task 1 masks. opts: {scaleAware}. → null when either is unscoreable.
+export function matchMasks(candidate, reference, opts = {}) {
+  const cs = stats(candidate), rs = stats(reference);
+  if (!cs || !rs) return null;
+
+  const nc = normalize(cs), nr = normalize(rs);
+  const iou = maskIoU(nc, nr);
+  const boundaryIoU = maskIoU(band(nc), band(nr));
+  const delta = deltaMap(nc, nr);
+
+  const scaleAware = opts.scaleAware === true && scaled(candidate) && scaled(reference);
+  let contourDist, contourUnit, iouScale;
+  if (scaleAware) {
+    const [sc, sr, pitch] = mmFrame(cs, candidate.mmPerPx, rs, reference.mmPerPx);
+    iouScale = maskIoU(sc, sr);
+    contourDist = contourDistance(sc, sr) * pitch;
+    contourUnit = "mm";
+  } else {
+    const diag = Math.hypot(nr.bw, nr.bh);
+    contourDist = (contourDistance(nc, nr) / diag) * 100;
+    contourUnit = "%bbox-diag";
+  }
+
+  const out = { iou, boundaryIoU, contourDist, contourUnit, delta };
+  if (scaleAware) out.iouScale = iouScale;
+  return out;
+}
+
+// viewMasks: {front: mask|null, ...} → {best: {view, ...scores}|null, views: {view: iou}}.
+// Views are walked in MATCH_VIEWS order, so a tie on `iou` resolves to the earlier view
+// regardless of the object's own key order.
+export function matchViews(viewMasks, reference, opts = {}) {
+  const views = {};
+  let best = null;
+  for (const view of MATCH_VIEWS) {
+    const scores = matchMasks(viewMasks?.[view], reference, opts);
+    if (!scores) continue;
+    views[view] = scores.iou;
+    if (!best || scores.iou > best.iou) best = { view, ...scores };
+  }
+  return { best, views };
+}
+
+// Squared-then-rooted Euclidean distance (in px) from every pixel to the nearest non-zero
+// pixel of `data`, by Felzenszwalb–Huttenlocher: a 1D lower-envelope pass over rows, then
+// over columns. With no non-zero pixel at all every entry comes back astronomically large
+// rather than infinite, which keeps the envelope's arithmetic finite.
+export function distanceTransform(data, width, height) {
+  const n = width * height;
+  const sq = new Float64Array(n);
+  for (let i = 0; i < n; i++) sq[i] = data[i] ? 0 : BIG;
+
+  const m = Math.max(width, height);
+  const f = new Float64Array(m), d = new Float64Array(m);
+  const v = new Int32Array(m), z = new Float64Array(m + 1);
+  for (let r = 0; r < height; r++) {
+    for (let c = 0; c < width; c++) f[c] = sq[r * width + c];
+    envelope(f, width, d, v, z);
+    for (let c = 0; c < width; c++) sq[r * width + c] = d[c];
+  }
+  for (let c = 0; c < width; c++) {
+    for (let r = 0; r < height; r++) f[r] = sq[r * width + c];
+    envelope(f, height, d, v, z);
+    for (let r = 0; r < height; r++) sq[r * width + c] = d[r];
+  }
+
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) out[i] = Math.sqrt(sq[i]);
+  return out;
+}
+
+// Lower envelope of the parabolas (q - x)² + f[q]: `v` holds the parabolas in the
+// envelope and `z` the boundaries between them. d[] comes back as squared distances.
+function envelope(f, n, d, v, z) {
+  let k = 0;
+  v[0] = 0; z[0] = -Infinity; z[1] = Infinity;
+  for (let q = 1; q < n; q++) {
+    let s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+    while (s <= z[k]) {
+      k--;
+      s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+    }
+    k++; v[k] = q; z[k] = s; z[k + 1] = Infinity;
+  }
+  k = 0;
+  for (let q = 0; q < n; q++) {
+    while (z[k + 1] < q) k++;
+    d[q] = (q - v[k]) * (q - v[k]) + f[v[k]];
+  }
+}
+
+const scaled = (mask) => Number.isFinite(mask?.mmPerPx) && mask.mmPerPx > 0;
+
+// Foreground bbox, centroid, and pixel count — null when there is nothing to score.
+function stats(mask) {
+  const data = mask?.data, w = mask?.width | 0, h = mask?.height | 0;
+  if (!data || !(w > 0) || !(h > 0) || data.length < w * h) return null;
+  let c0 = w, c1 = -1, r0 = h, r1 = -1, n = 0, sc = 0, sr = 0;
+  for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) {
+    if (!data[r * w + c]) continue;
+    n++; sc += c; sr += r;
+    if (c < c0) c0 = c;
+    if (c > c1) c1 = c;
+    if (r < r0) r0 = r;
+    if (r > r1) r1 = r;
+  }
+  return n ? { data, w, h, c0, c1, r0, r1, cx: sc / n, cy: sr / n, count: n } : null;
+}
+
+// Crop to the bbox, scale the longer side to FILL*S, centroid-align into the S² frame,
+// nearest-neighbour. Sampling is done backwards from the output so the two masks share
+// one mapping form and identical shapes at different scales land on identical pixels.
+//
+// The scale is bbox-derived while the alignment is centroid-derived, so a shape whose
+// centroid sits far from its bbox centre (an L) would run past the frame edge and be
+// silently clipped. The guard shrinks such a shape to fit; it is a function of the
+// shape's own proportions, so two copies of it at different scales still normalize
+// identically and still score 1.
+function normalize(st) {
+  const bw = st.c1 - st.c0 + 1, bh = st.r1 - st.r0 + 1;
+  let s = (FILL * S) / Math.max(bw, bh);
+  const reach = Math.max(st.cx - st.c0, st.c1 - st.cx, st.cy - st.r0, st.r1 - st.cy) + 0.5;
+  const room = (S - 2) / 2;
+  if (reach * s > room) s = room / reach;
+
+  const mid = (S - 1) / 2;
+  const data = new Uint8Array(S * S);
+  for (let R = 0; R < S; R++) {
+    const r = Math.round((R - mid) / s + st.cy);
+    if (r < st.r0 || r > st.r1) continue;
+    for (let C = 0; C < S; C++) {
+      const c = Math.round((C - mid) / s + st.cx);
+      if (c < st.c0 || c > st.c1) continue;
+      if (st.data[r * st.w + c]) data[R * S + C] = 1;
+    }
+  }
+  return { data, width: S, height: S, bw: bw * s, bh: bh * s };
+}
+
+// Both masks resampled onto ONE grid at the reference's mmPerPx, centroid-aligned and
+// never rescaled — the frame where absolute size is the question. Sized to hold both, so
+// an oversized candidate is measured rather than cropped by the reference's own extent.
+// Returns the two masks and the grid's pitch in mm/px, which is the reference's own
+// except when a wildly oversized candidate would need a frame past MAX_MM_FRAME: then the
+// grid COARSENS rather than crops, since a truncated union would flatter the candidate.
+function mmFrame(cs, cmm, rs, rmm) {
+  // Half-extents in mm from each mask's own centroid, unioned so neither is cropped.
+  const span = (st, mm) => [
+    (st.cx - st.c0) * mm + mm / 2, (st.c1 - st.cx) * mm + mm / 2,
+    (st.cy - st.r0) * mm + mm / 2, (st.r1 - st.cy) * mm + mm / 2,
+  ];
+  const other = span(rs, rmm);
+  const [left, right, up, down] = span(cs, cmm).map((v, i) => Math.max(v, other[i]));
+
+  const longest = Math.max(left + right, up + down);
+  const p = Math.max(rmm, longest / MAX_MM_FRAME);
+  const gx = Math.ceil(left / p) + 1, gy = Math.ceil(up / p) + 1;
+  const width = gx + Math.ceil(right / p) + 2, height = gy + Math.ceil(down / p) + 2;
+
+  const draw = (st, mm) => {
+    const data = new Uint8Array(width * height);
+    for (let R = 0; R < height; R++) {
+      const r = Math.round(((R - gy) * p) / mm + st.cy);
+      if (r < st.r0 || r > st.r1) continue;
+      for (let C = 0; C < width; C++) {
+        const c = Math.round(((C - gx) * p) / mm + st.cx);
+        if (c < st.c0 || c > st.c1) continue;
+        if (st.data[r * st.w + c]) data[R * width + C] = 1;
+      }
+    }
+    return { data, width, height };
+  };
+  return [draw(cs, cmm), draw(rs, rmm), p];
+}
+
+function maskIoU(a, b) {
+  let inter = 0, union = 0;
+  for (let i = 0; i < a.data.length; i++) {
+    const x = a.data[i], y = b.data[i];
+    if (x && y) inter++;
+    if (x || y) union++;
+  }
+  return union ? inter / union : 0;
+}
+
+// Boundary IoU's band: the mask minus its own erosion by BAND_PX. Erosion by a disk is
+// the distance transform of the background, so the band is "foreground within BAND_PX of
+// some background pixel".
+function band(m) {
+  const inv = new Uint8Array(m.data.length);
+  for (let i = 0; i < inv.length; i++) inv[i] = m.data[i] ? 0 : 1;
+  const dt = distanceTransform(inv, m.width, m.height);
+  const data = new Uint8Array(m.data.length);
+  for (let i = 0; i < data.length; i++) if (m.data[i] && dt[i] <= BAND_PX) data[i] = 1;
+  return { data, width: m.width, height: m.height };
+}
+
+// Contour = foreground with at least one background 4-neighbour; outside the image counts
+// as background, so a shape flush with the edge still has one.
+function contour(m) {
+  const { data, width, height } = m;
+  const out = new Uint8Array(data.length);
+  for (let r = 0; r < height; r++) for (let c = 0; c < width; c++) {
+    const i = r * width + c;
+    if (!data[i]) continue;
+    if (r === 0 || r === height - 1 || c === 0 || c === width - 1
+      || !data[i - width] || !data[i + width] || !data[i - 1] || !data[i + 1]) out[i] = 1;
+  }
+  return out;
+}
+
+// Symmetric mean contour separation in px: mean distance from each mask's contour to the
+// other's, averaged both directions so neither shape's rim length dominates.
+function contourDistance(a, b) {
+  const ca = contour(a), cb = contour(b);
+  const da = distanceTransform(ca, a.width, a.height);
+  const db = distanceTransform(cb, b.width, b.height);
+  const mean = (pts, dt) => {
+    let n = 0, sum = 0;
+    for (let i = 0; i < pts.length; i++) if (pts[i]) { n++; sum += dt[i]; }
+    return n ? sum / n : 0;
+  };
+  return (mean(cb, da) + mean(ca, db)) / 2;
+}
+
+// 0 = background, 1 = overlap, 2 = missing (reference only), 3 = excess (candidate only).
+function deltaMap(c, r) {
+  const data = new Uint8Array(c.data.length);
+  for (let i = 0; i < data.length; i++) {
+    const inC = c.data[i], inR = r.data[i];
+    data[i] = inC && inR ? 1 : inR ? 2 : inC ? 3 : 0;
+  }
+  return { width: c.width, height: c.height, data };
+}

package/src/framework/oracle/measure.js

@@ -19,7 +19,11 @@ const unionBounds = (list) => list.reduce(
 //   → { part, view, measuredMinWall, subparts[], aggregate, overlaps[], gaps[],
 //       nearMisses[], ok }
 export function measure(kernel, part, view = Object.keys(part.views)[0], params = {}, opts = {}) {
-  const built = buildView(kernel, part, view, params);
+  // `opts.built` is a build of this view the caller already has. The inspect job
+  // needs those meshes anyway — it rasterizes them for silhouette match scoring —
+  // and a second buildView here would be a whole duplicate build of the part for
+  // nothing. Absent, this measures its own build exactly as it always did.
+  const built = opts.built ?? buildView(kernel, part, view, params);
   // ONE BVH per sub-part mesh for this call, shared by the two passes that need
   // one: min-wall (inward rays per triangle) and meshGaps (pair distances). They
   // used to index the same mesh objects independently, so every sub-part of a

package/src/framework/oracle/silhouette.js

@@ -0,0 +1,146 @@
+// Orthographic silhouette masks: project a part (or a set of 2D rings) onto one of the
+// six canonical views and scanline-fill it into a binary image. The foundation of
+// silhouette match scoring — no kernel, no DOM, no three, no `node:`, so it runs in the
+// geometry worker alongside the rest of the oracle.
+//
+// Contract: {data: Uint8Array of 0|255, width, height, mmPerPx, minX, minY}. Row 0 is
+// the TOP of the image; minX/minY are the projected-plane coordinates of the image's
+// BOTTOM-LEFT corner, so a caller maps a pixel back with
+//   x = minX + (col + 0.5) * mmPerPx,  y = minY + (height - 0.5 - row) * mmPerPx
+// Nothing to draw, or a projection with zero extent, returns null.
+
+export const MATCH_VIEWS = ["front", "back", "top", "bottom", "left", "right"];
+
+// Image axes per view as [modelAxisIndex, sign] in MODEL space (x,y,z) — the third axis
+// is dropped. Derived from the viewer's single pivot rotation (`pivot.rotation.x =
+// -Math.PI/2` in viewer.js, taking model Z-up to world Y-up) composed with each view's
+// camera basis in view-angles.js. A wrong sign here mirrors every downstream match
+// score without failing anything else, so the table is written out rather than derived.
+const VIEW_AXES = {
+  front:  { x: [0,  1], y: [2,  1] }, // drops Y
+  back:   { x: [0, -1], y: [2,  1] }, // drops Y
+  right:  { x: [1,  1], y: [2,  1] }, // drops X
+  left:   { x: [1, -1], y: [2,  1] }, // drops X
+  top:    { x: [0,  1], y: [1,  1] }, // drops Z
+  bottom: { x: [0,  1], y: [1, -1] }, // drops Z
+};
+
+const PAD = 0.04;            // blank fraction of the frame on each side
+const FILL = 1 - 2 * PAD;    // 0.92 — the fraction the content's longest extent occupies
+
+// meshes: [{positions: Float32Array|number[], indices?: Uint32Array|number[]}] — `indices`
+// optional, flat triangle soup when absent (3 verts per triangle), same as oracle/mesh.js.
+export function rasterizeMeshMask(meshes, view, size = 256) {
+  const axes = VIEW_AXES[view];
+  if (!axes) throw new Error(`unknown match view "${view}"`);
+  const [ax, sx] = axes.x, [ay, sy] = axes.y;
+  const groups = [];
+  for (const mesh of meshes || []) {
+    const P = mesh?.positions;
+    if (!P || P.length < 9) continue;
+    const idx = mesh.indices;
+    const n = idx ? idx.length : P.length / 3;
+    for (let i = 0; i + 3 <= n; i += 3) {
+      const tri = new Float64Array(6);
+      let ok = true;
+      for (let k = 0; k < 3 && ok; k++) {
+        const base = (idx ? idx[i + k] : i + k) * 3;
+        const x = P[base + ax] * sx, y = P[base + ay] * sy;
+        if (Number.isFinite(x) && Number.isFinite(y)) { tri[k * 2] = x; tri[k * 2 + 1] = y; }
+        else ok = false;
+      }
+      if (ok) groups.push([tri]); // one triangle = one even-odd group; see fillPolygons
+    }
+  }
+  return fillPolygons(groups, size);
+}
+
+// rings: [[[x,y], ...], ...] in mm. All rings share ONE even-odd group, so a ring inside
+// another is a hole.
+export function rasterizeRingsMask(rings, size = 256) {
+  const group = [];
+  for (const ring of rings || []) {
+    if (!ring || ring.length < 3) continue;
+    const flat = new Float64Array(ring.length * 2);
+    let ok = true;
+    for (let i = 0; i < ring.length && ok; i++) {
+      const x = ring[i]?.[0], y = ring[i]?.[1];
+      if (Number.isFinite(x) && Number.isFinite(y)) { flat[i * 2] = x; flat[i * 2 + 1] = y; }
+      else ok = false;
+    }
+    if (ok) group.push(flat);
+  }
+  return group.length ? fillPolygons([group], size) : null;
+}
+
+// A GROUP is one even-odd polygon set, given as rings of flat [x0,y0,x1,y1,...] pairs.
+// Groups UNION with each other, which is the whole reason for the grouping: a closed mesh
+// projects its front and back faces onto the same pixels, and even-odd across the whole
+// soup would cancel them into background. So each triangle is its own group and a ring
+// set is one group, and holes still subtract.
+function fillPolygons(groups, size) {
+  if (!groups.length) return null;
+  let loX = Infinity, loY = Infinity, hiX = -Infinity, hiY = -Infinity;
+  for (const g of groups) for (const ring of g) for (let i = 0; i < ring.length; i += 2) {
+    if (ring[i] < loX) loX = ring[i];
+    if (ring[i] > hiX) hiX = ring[i];
+    if (ring[i + 1] < loY) loY = ring[i + 1];
+    if (ring[i + 1] > hiY) hiY = ring[i + 1];
+  }
+  const extent = Math.max(hiX - loX, hiY - loY);
+  if (!(extent > 0)) return null;
+
+  // Uniform scale, tight bbox, PAD on each side, centred in a square frame.
+  const mmPerPx = extent / (FILL * size);
+  const span = size * mmPerPx;
+  const minX = (loX + hiX) / 2 - span / 2, minY = (loY + hiY) / 2 - span / 2;
+  const rowOf = (y) => size - 0.5 - (y - minY) / mmPerPx; // row 0 = top: y is flipped here
+
+  // Bucket each group by its first row and drop it once past its last, so a scanline only
+  // walks the groups that can cross it (a mesh soup is thousands of tiny groups).
+  const starts = Array.from({ length: size }, () => []);
+  const lastRow = new Int32Array(groups.length);
+  for (let g = 0; g < groups.length; g++) {
+    let gLo = Infinity, gHi = -Infinity;
+    for (const ring of groups[g]) for (let i = 1; i < ring.length; i += 2) {
+      if (ring[i] < gLo) gLo = ring[i];
+      if (ring[i] > gHi) gHi = ring[i];
+    }
+    const r0 = Math.min(size - 1, Math.max(0, Math.floor(rowOf(gHi))));
+    lastRow[g] = Math.min(size - 1, Math.max(0, Math.ceil(rowOf(gLo))));
+    starts[r0].push(g);
+  }
+
+  const data = new Uint8Array(size * size);
+  const xs = [];
+  let active = [];
+  for (let r = 0; r < size; r++) {
+    if (starts[r].length) active = active.concat(starts[r]);
+    if (!active.length) continue;
+    active = active.filter((g) => lastRow[g] >= r);
+    const y = minY + (size - 0.5 - r) * mmPerPx;
+    for (const g of active) {
+      xs.length = 0;
+      for (const ring of groups[g]) {
+        const n = ring.length;
+        // Half-open crossing test (y0 <= y) !== (y1 <= y): a vertex sitting exactly on the
+        // scanline is counted once, not twice, so parity stays sane.
+        for (let i = 0, j = n - 2; i < n; j = i, i += 2) {
+          const y0 = ring[j + 1], y1 = ring[i + 1];
+          if ((y0 <= y) === (y1 <= y)) continue;
+          xs.push(ring[j] + ((y - y0) * (ring[i] - ring[j])) / (y1 - y0));
+        }
+      }
+      if (xs.length < 2) continue;
+      xs.sort((a, b) => a - b);
+      for (let k = 0; k + 1 < xs.length; k += 2) {
+        let c0 = Math.ceil((xs[k] - minX) / mmPerPx - 0.5);      // first pixel CENTRE inside
+        let c1 = Math.floor((xs[k + 1] - minX) / mmPerPx - 0.5); // last pixel centre inside
+        if (c0 < 0) c0 = 0;
+        if (c1 > size - 1) c1 = size - 1;
+        for (let c = c0; c <= c1; c++) data[r * size + c] = 255;
+      }
+    }
+  }
+  return { data, width: size, height: size, mmPerPx, minX, minY };
+}

package/src/testing.js

@@ -23,3 +23,8 @@ export { renderViews, RENDER_VIEWS } from "./testing/render.js";
 export { verify } from "./framework/oracle/verify.js";
 export { buildBVH } from "./framework/oracle/bvh.js";
 export { minWall } from "./framework/oracle/min-wall.js";
+// Silhouette match scoring — also worker-reachable (the `inspect` job scores
+// `matchTargets` with exactly these), re-exported so a downstream harness can build
+// the same masks and reproduce a score outside the job loop.
+export { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./framework/oracle/silhouette.js";
+export { matchMasks, matchViews } from "./framework/oracle/match.js";

package/types/testing.d.ts

@@ -35,6 +35,15 @@ export function bootOcctKernel(opts?: { fonts?: Record<string, FontSource> }): P
 
 // --- the job loop -----------------------------------------------------------
 
+/**
+ * A reference shape for the `inspect` job to score the part's silhouettes against.
+ * A `profile` is millimetres and so is compared at absolute scale too; an `image`
+ * is a photo mask with no scale, compared on shape alone.
+ */
+export type MatchTarget =
+  | { kind: "profile"; rings: Array<Array<[number, number]>> }
+  | { kind: "image"; mask: { data: Uint8Array; width: number; height: number } };
+
 /** A job the worker loop accepts. */
 export interface WorkerJob {
   type: "generate" | "export-stl" | "export-step" | "export-3mf" | "inspect";
@@ -50,6 +59,16 @@ export interface WorkerJob {
   jobId?: number;
   /** Single-file export name base. */
   name?: string;
+  /**
+   * `inspect`: score the part's six canonical silhouettes against these. Absent or
+   * empty leaves `match` off the report entirely.
+   *
+   * A target that cannot be scored — malformed, or with no foreground to score
+   * against — is DROPPED rather than reported as a zero, so `report.match` is not
+   * index-aligned with this list. Attribute a result by its `kind` and by the
+   * relative order of the targets sharing that kind, never by index.
+   */
+  matchTargets?: MatchTarget[];
 }
 
 /**
@@ -272,7 +291,16 @@ export function measure(
   part: PartDefinition,
   view?: string,
   params?: ResolvedParams,
-  opts?: { minWall?: boolean; gapThreshold?: number },
+  opts?: {
+    minWall?: boolean;
+    gapThreshold?: number;
+    /**
+     * A build of this view the caller already has, measured instead of building a
+     * second time. It is trusted, not checked against `view`/`params` — hand in a
+     * build of the same view you are asking about.
+     */
+    built?: BuiltSubPart[];
+  },
 ): MeasureReport;
 
 // --- verify -----------------------------------------------------------------
@@ -339,6 +367,93 @@ export function verify(
   },
 ): VerifyReport;
 
+// --- silhouette match scoring -----------------------------------------------
+
+/**
+ * A binary silhouette. `data` is 0 or 255, one byte per pixel, row 0 at the TOP.
+ * `minX`/`minY` are the projected-plane coordinates of the image's BOTTOM-LEFT
+ * corner. A mask with no `mmPerPx` carries no scale (a photo), which is what makes
+ * the scale-aware comparison unavailable for it.
+ */
+export interface SilhouetteMask {
+  data: Uint8Array;
+  width: number;
+  height: number;
+  mmPerPx?: number;
+  minX?: number;
+  minY?: number;
+}
+
+/** The six canonical orthographic views a part is rasterized into for matching. */
+export const MATCH_VIEWS: string[];
+
+/**
+ * Project posed meshes onto one of `MATCH_VIEWS` and scanline-fill the silhouette.
+ * `null` when there is nothing to draw or the projection has zero extent.
+ */
+export function rasterizeMeshMask(
+  meshes: Array<Pick<Mesh, "positions" | "indices">>,
+  view: string,
+  size?: number,
+): SilhouetteMask | null;
+
+/**
+ * Fill a set of closed 2-D rings (millimetres) into a mask. All rings share one
+ * even-odd group, so a ring inside another is a hole. `null` when nothing fills.
+ */
+export function rasterizeRingsMask(
+  rings: Array<Array<[number, number]>>,
+  size?: number,
+): SilhouetteMask | null;
+
+/**
+ * Per-pixel comparison of the two masks: `0` background, `1` overlap, `2` missing
+ * (reference only), `3` excess (candidate only).
+ */
+export interface MatchDelta {
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+
+/**
+ * How close a candidate silhouette is to a reference one. Shape is compared
+ * pose-normalized, so `iou` and `boundaryIoU` ignore position and size. `iouScale`
+ * appears only for a scale-aware comparison, which also makes `contourDist` a real
+ * millimetre distance instead of a percentage of the reference's bbox diagonal.
+ */
+export interface MatchScores {
+  iou: number;
+  boundaryIoU: number;
+  contourDist: number;
+  contourUnit: "mm" | "%bbox-diag";
+  iouScale?: number;
+  delta: MatchDelta;
+}
+
+/**
+ * Score one candidate mask against a reference. `null` when either has no
+ * foreground at all — unscoreable is not the same as scoring zero.
+ *
+ * `scaleAware` is the caller's promise that both masks are in millimetres; it takes
+ * effect only when both actually carry a finite `mmPerPx`.
+ */
+export function matchMasks(
+  candidate: SilhouetteMask | null | undefined,
+  reference: SilhouetteMask | null | undefined,
+  opts?: { scaleAware?: boolean },
+): MatchScores | null;
+
+/**
+ * Score every view's mask against one reference and name the best. Unscoreable
+ * views are left out of `views` entirely; `best` is `null` when none scored.
+ */
+export function matchViews(
+  viewMasks: Record<string, SilhouetteMask | null>,
+  reference: SilhouetteMask | null | undefined,
+  opts?: { scaleAware?: boolean },
+): { best: ({ view: string } & MatchScores) | null; views: Record<string, number> };
+
 // --- rendering --------------------------------------------------------------
 
 /** The canonical angle names `renderViews` accepts. */