spine-rigc 2.19.1 → 2.20.1

package/src/meshquality.ts

@@ -54,26 +54,22 @@
  * `MeshReductionError` is defined in `src/mesh.ts` for exactly that reason.
  */
 import {
-  artOf,
   checkHullOrder,
   distanceToSegment,
-  fillEnclosed,
   findSelfIntersection,
-  labelIslands,
   MeshError,
   MeshReductionError,
   meshEdges,
-  prunePolygon,
   r6,
   rasteriseTriangles,
   segmentsMeet,
   squaredDistanceToSet,
-  traceAlphaOutline,
   traceOutline,
   type AlphaMask,
   type MeshOutline,
 } from './mesh.ts';
 import { areaBand, triangleAreas } from './areaband.ts';
+import { artRastersOf, type ArtRasters } from './meshrasters.ts';
 import { cropToSpineY } from './transform.ts';
 
 // ---------------------------------------------------------------------------
@@ -299,6 +295,8 @@ export interface MeasureRow {
   raster?: RasterSensitivity;
   /** Sampled rows — correction 2. */
   sampling?: { domain: string; count: number };
+  /** Motion rows only (stage C, `src/meshcompare.ts`): how the row's value was taken over the schedule. */
+  motion?: MotionRowDetail;
 }
 
 /** Correction 2: the spatial grid and the value's own granularity are two fields. */
@@ -353,9 +351,10 @@ export interface MotionSchedule {
 
 /**
  * The schedule a motion section was measured under. The contract names this
- * type without defining it; until stage C does, it is the schedule as given.
+ * type without defining it; stage C (issue #1230) defines it as the schedule as
+ * given plus what was walked from it (`ScheduleWalked`, at the end of this file).
  */
-export type ScheduleUsed = MotionSchedule;
+export type ScheduleUsed = MotionSchedule & ScheduleWalked;
 
 /** One candidate's evidence — correction 1. `reduce` and `measure` carry exactly one. */
 export interface CandidateReport {
@@ -421,8 +420,8 @@ export interface EffectiveSettings {
     frame: SourceFrame;
     maskSize: [number, number];
     minArtSamples: number;
-    /** P9: each region's own floor, in the order the regions were given. */
-    regions: Array<{ name: string; minArtSamples: number }>;
+    /** P9: each region's own floor, in the order the regions were given — and, on a `compare`, its polygon. */
+    regions: Array<{ name: string; minArtSamples: number; polygon?: Array<[number, number]> }>;
   }>;
   sourceBounds: ArtFitBounds | null;
   referenceArtFit: ArtFitBounds | null;
@@ -1009,6 +1008,53 @@ function compareRows(a: MeasureRow, b: MeasureRow): number {
  */
 export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
   validateInput(input);
+  return measureValidated(input, artRastersOf(input.art));
+}
+
+/**
+ * `measureMeshQuality` over art rasters the caller already holds
+ * (`src/meshrasters.ts`) — what `reduceMesh` calls for every measurement of
+ * one call, so the quantities of the art alone are computed once per call
+ * rather than once per step (issue #1240). The report is the one
+ * `measureMeshQuality` returns for the same input, byte for byte; rasters
+ * taken from another art are refused (`REDUCE_ART_RASTERS_MISMATCH`), never
+ * read.
+ *
+ * Internal: it is on `spine-rigc/mesh` only because that entry re-exports this
+ * module with `export *`, and a symbol that is merely exported is not promised
+ * (RELEASING.md, *The import surface*).
+ */
+export function measureMeshQualityWith(input: MeshMeasureInput, rasters: ArtRasters): MeshQualityReport {
+  validateInput(input);
+  checkArtRasters(input, rasters);
+  return measureValidated(input, rasters);
+}
+
+/**
+ * Rasters are read only for the art they were taken from: the same mask
+ * array, mask size, threshold and frame. The first field that differs is
+ * refused by name, with the value the rasters were taken at and the value the
+ * input requires.
+ */
+function checkArtRasters(input: MeshMeasureInput, rasters: ArtRasters): void {
+  const want = input.art;
+  const got = rasters.art;
+  if (got === want) return;
+  const who = `attachment ${nameOf(input.attachment)}`;
+  const differs = (field: string, found: string, required: string): never =>
+    refuse('REDUCE_ART_RASTERS_MISMATCH', `${who}: the art rasters were taken at ${field} ${found}; required ${field} ${required}, the input's — rasters are read only for the art they were taken from`);
+  const size = (m: AlphaMask | undefined): string => (m === undefined ? 'undefined' : `${m.width}x${m.height}`);
+  if (size(got.mask) !== size(want.mask)) differs('art.mask size', size(got.mask), size(want.mask));
+  if (got.threshold !== want.threshold) differs('art.threshold', JSON.stringify(got.threshold), JSON.stringify(want.threshold));
+  for (const field of ['pageScale', 'width', 'height'] as const) {
+    if (got.frame?.[field] !== want.frame[field]) differs(`art.frame.${field}`, JSON.stringify(got.frame?.[field]), JSON.stringify(want.frame[field]));
+  }
+  if (got.mask.alpha !== want.mask.alpha) differs('art.mask.alpha', 'another array', 'the input\'s own array (the same object)');
+}
+
+/** The measurement proper, over an input `validateInput` accepted and rasters taken from its art. */
+function measureValidated(input: MeshMeasureInput, rasters: ArtRasters): MeshQualityReport {
+  rasters.tally.uses++;
   const { attachment, art, source, targets } = input;
   const { mask, threshold, frame } = art;
   const scale = frame.pageScale;
@@ -1050,9 +1096,8 @@ export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
   const w = mask.width;
   const h = mask.height;
   const grid = { width: w, height: h, pageScale: scale };
-  const artBits = artOf(mask, threshold);
-  let artCount = 0;
-  for (const bit of artBits) artCount += bit;
+  const artBits = rasters.artBits();
+  const artCount = rasters.artCount();
   const onGrid: Array<[number, number]> = source.points.map(([x, y]) => [x * scale, y * scale]);
   const covered = rasteriseTriangles(onGrid, source.triangles, w, h);
   const fit = targets.artFit;
@@ -1105,17 +1150,9 @@ export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
 
     // Overshoot and holes against the filled silhouette: 8-connected background over ALL art (P12) — and,
     // where the legacy 4-connected fill differs (a diagonal pinch), the labelled 4-connected reading beside it.
-    const fill8 = fillEnclosed(artBits, w, h, 8).filled;
-    const fill4 = fillEnclosed(artBits, w, h, 4).filled;
-    let fillsDiffer = false;
-    for (let i = 0; i < fill8.length; i++) {
-      if (fill8[i] !== fill4[i]) {
-        fillsDiffer = true;
-        break;
-      }
-    }
+    const { fill8, fill4, differ: fillsDiffer } = rasters.fills();
     const silhouetteRows = (filled: Uint8Array, connectivity: 4 | 8, gated: boolean): void => {
-      const toFilled = squaredDistanceToSet(filled, w, h);
+      const toFilled = rasters.toFilled(connectivity);
       let overAt = -1;
       let overSq = 0;
       let holes = 0;
@@ -1147,7 +1184,7 @@ export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
     if (fillsDiffer) silhouetteRows(fill4, 4, false);
 
     // Islands: the 4-connected art islands (the tracer's, `labelIslands`) the triangles cover a pixel of.
-    const { label } = labelIslands(artBits, w, h);
+    const { label } = rasters.islands();
     const touched = new Set<number>();
     for (let i = 0; i < label.length; i++) if (label[i] && covered[i]) touched.add(label[i]);
     let joinedAt = -1;
@@ -1176,14 +1213,12 @@ export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
     rows.push(measuredRow(boundarySpec, r6(hd.d), bound, hd.d === 0 ? NOTHING_WORSE : { at: { edge: edgeOfHull(hd.candidateEdge) } }, true));
   }
   const traceSpec = spec('MQ_TRACE_DEVIATION', 'px');
-  try {
-    const traced = traceAlphaOutline(mask, threshold);
-    const outlinePx = prunePolygon(traced.outline.map(([x, y]): [number, number] => [x / scale, y / scale]));
-    const hd = hausdorff(hullPolygon, outlinePx);
+  const traced = rasters.traced();
+  if ('outline' in traced) {
+    const hd = hausdorff(hullPolygon, traced.outline);
     rows.push(measuredRow(traceSpec, r6(hd.d), null, hd.d === 0 ? NOTHING_WORSE : { at: { edge: edgeOfHull(hd.candidateEdge) } }, false));
-  } catch (err) {
-    if (!(err instanceof MeshError)) throw err;
-    rows.push(unmeasuredRow(traceSpec, 'not-measurable', `attachment ${nameOf(attachment)}: the tracer refused the art at alpha >= ${threshold}: ${err.message}`, false));
+  } else {
+    rows.push(unmeasuredRow(traceSpec, 'not-measurable', `attachment ${nameOf(attachment)}: the tracer refused the art at alpha >= ${threshold}: ${traced.refused}`, false));
   }
 
   // --- triangles: sign, degeneracy, angle --------------------------------------------------
@@ -1230,7 +1265,7 @@ export function measureMeshQuality(input: MeshMeasureInput): MeshQualityReport {
   );
 
   // --- regions (§5) ------------------------------------------------------------------------
-  rows.push(...regionRows(input, outline, hullPolygon));
+  rows.push(...regionRows(input, outline, hullPolygon, rasters));
 
   const ordered = rows.slice().sort((a, b) => compareRows(a.row, b.row));
   const geometry = sectionOf(ordered);
@@ -1328,7 +1363,7 @@ interface Edge {
  * length most exceeds its own bound — so the row fails exactly when some edge
  * it covers is over — and the row names that edge and that bound.
  */
-function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon: readonly Pt[]): Built[] {
+function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon: readonly Pt[], rasters: ArtRasters): Built[] {
   const { attachment, source, art } = input;
   const who = `attachment ${nameOf(attachment)}`;
   const scale = art.frame.pageScale;
@@ -1404,7 +1439,7 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
 
   const floorOf = (name: string): number => input.regionArtSamples.find((f) => f.region === name)!.minArtSamples;
   const { mask, threshold } = art;
-  const artBits = artOf(mask, threshold);
+  const artBits = rasters.artBits();
 
   for (const region of input.targets.regions) {
     const refused = refusals.get(region.name);
@@ -1576,7 +1611,7 @@ function effectiveJson(e: EffectiveSettings): Json {
       frame: frameJson(a.frame),
       maskSize: pair(a.maskSize),
       minArtSamples: a.minArtSamples,
-      regions: a.regions.map((r) => ({ name: r.name, minArtSamples: r.minArtSamples })),
+      regions: a.regions.map((r): Json => (r.polygon === undefined ? { name: r.name, minArtSamples: r.minArtSamples } : { name: r.name, minArtSamples: r.minArtSamples, polygon: r.polygon.map(pair) })),
     })),
     sourceBounds: fitJson(e.sourceBounds),
     referenceArtFit: fitJson(e.referenceArtFit),
@@ -1631,6 +1666,7 @@ function rowJson(r: MeasureRow): Json {
     };
   }
   if (r.sampling !== undefined) out.sampling = { domain: r.sampling.domain, count: r.sampling.count };
+  if (r.motion !== undefined) out.motion = motionDetailJson(r.motion);
   return out;
 }
 
@@ -1651,7 +1687,7 @@ function candidateJson(c: CandidateReport): Json {
     id: c.id,
     counts: countsJson(c.counts),
     geometry: c.geometry === null ? null : sectionJson(c.geometry),
-    motion: c.motion === null ? null : { ...sectionJson(c.motion), schedule: scheduleJson(c.motion.schedule) },
+    motion: c.motion === null ? null : { ...sectionJson(c.motion), schedule: scheduleUsedJson(c.motion.schedule) },
     accepted: c.accepted,
   };
   if (c.perFrame !== undefined) out.perFrame = c.perFrame.map((p) => ({ code: p.code, frame: p.frame, value: p.value }));
@@ -1702,3 +1738,97 @@ export function writeMeshQualityReport(report: MeshQualityReport): string {
   };
   return `${JSON.stringify(doc, null, 2)}\n`;
 }
+
+// ---------------------------------------------------------------------------
+// stage C — the motion section's own fields (issue #1230, `src/meshcompare.ts`)
+// ---------------------------------------------------------------------------
+//
+// Additive: nothing above reads these, a `measure` and a `reduce` never write
+// them, and every one is written only when present.
+
+/** One group of frames a motion row was also taken over — a phase, or a role (P11). */
+export interface MotionReading {
+  /** The group's worst value; null when no frame of the group drew the attachment. */
+  value: number | null;
+  /** The value against the row's bound, by the row's own rule; `undeclared` with no bound, `not-measurable` with no value. */
+  state: MeasureState;
+  /** The frame the group's worst value was taken at, by `FrameRef.id`. */
+  frame: string | null;
+}
+
+/**
+ * How a motion row's value was taken over the schedule (stage C). The row's own
+ * `value` is the worst over every frame measured; these keep apart what the
+ * contract says must not be folded together.
+ */
+export interface MotionRowDetail {
+  /** Frames at which the attachment was drawn and measured, and the ids of those at which its slot drew something else or nothing. */
+  frames: { measured: number; notDrawn: string[] };
+  /**
+   * §4 *Transition in time*: the row taken per sample phase — `grid` and `irr`
+   * for the frames a rate generated, `null` for the setup frame and for frames
+   * the caller gave as explicit times (no phase applies to those).
+   */
+  byPhase: Array<{ phase: 'grid' | 'irr' | null } & MotionReading>;
+  /** When one phase passes and another fails: the worst frame of each, by id, and a sentence naming both. Null otherwise. */
+  phasesDisagree: { pass: string; fail: string; sentence: string } | null;
+  /** P11: the row per role. `heldOut` is null when no held-out frame was measured — no held-out claim is made. */
+  byRole: { baseline: MotionReading | null; selection: MotionReading | null; heldOut: MotionReading | null };
+  /**
+   * Correction 4, world rows: the declared setup map of the attachment's slot
+   * bone — its world 2×2 at the setup pose, `[a, b, c, d]` as the core poses it
+   * from the bones' declared fields — and its two singular scales. Never a
+   * single world-per-pixel ratio, and never fitted to output vertices.
+   */
+  setupMap?: { bone: string; linear: [number, number, number, number]; singularScales: [number, number] };
+  /** §3: samples no non-degenerate UV triangle carries, listed by UV — in the reference's mesh and in this candidate's. */
+  uncarried?: { reference: Array<[number, number]>; candidate: Array<[number, number]> };
+  /** §3, `MQ_INVERSION` on a slot `invariants.deformMayFold` names: every reversed triangle with its frame — listed, never zeroed. */
+  folds?: Array<{ triangle: number; frame: string }>;
+  /** Triangles that have no area at the setup pose (the A39 band), so no sign and no stretch is read off them. */
+  degenerateAtSetup?: number;
+}
+
+/** What a motion section walked from the schedule it was given (`ScheduleUsed`). */
+export interface ScheduleWalked {
+  /** Every frame the schedule names, in walk order, each with its role (P11). */
+  walked: FrameRef[];
+  /** The roles among those frames — what the section has evidence for. */
+  roles: Array<FrameRef['role']>;
+  /** P11: true only when at least one held-out frame, disjoint from `selection`, was walked. */
+  heldOutClaim: boolean;
+  /** P10: every walk resets physics at time 0 and steps from there, the same steps for the reference and every candidate. */
+  reset: 'physics reset at time 0';
+  /** Each walk: the animation, the phase (null for explicit times), and how many steps reached its last frame. */
+  walks: Array<{ animation: string; phase: 'grid' | 'irr' | null; steps: number }>;
+}
+
+function readingJson(r: MotionReading | null): Json {
+  return r === null ? null : { value: r.value, state: r.state, frame: r.frame };
+}
+
+function motionDetailJson(m: MotionRowDetail): Json {
+  const out: { [key: string]: Json } = {
+    frames: { measured: m.frames.measured, notDrawn: [...m.frames.notDrawn] },
+    byPhase: m.byPhase.map((p) => ({ phase: p.phase, value: p.value, state: p.state, frame: p.frame })),
+    phasesDisagree: m.phasesDisagree === null ? null : { pass: m.phasesDisagree.pass, fail: m.phasesDisagree.fail, sentence: m.phasesDisagree.sentence },
+    byRole: { baseline: readingJson(m.byRole.baseline), selection: readingJson(m.byRole.selection), heldOut: readingJson(m.byRole.heldOut) },
+  };
+  if (m.setupMap !== undefined) out.setupMap = { bone: m.setupMap.bone, linear: [...m.setupMap.linear], singularScales: pair(m.setupMap.singularScales) };
+  if (m.uncarried !== undefined) out.uncarried = { reference: m.uncarried.reference.map(pair), candidate: m.uncarried.candidate.map(pair) };
+  if (m.folds !== undefined) out.folds = m.folds.map((f) => ({ triangle: f.triangle, frame: f.frame }));
+  if (m.degenerateAtSetup !== undefined) out.degenerateAtSetup = m.degenerateAtSetup;
+  return out;
+}
+
+function scheduleUsedJson(s: ScheduleUsed): Json {
+  const given = scheduleJson(s) as { [key: string]: Json };
+  return {
+    ...given,
+    walked: s.walked.map(frameRefJson),
+    roles: [...s.roles],
+    heldOutClaim: s.heldOutClaim,
+    reset: s.reset,
+    walks: s.walks.map((w) => ({ animation: w.animation, phase: w.phase, steps: w.steps })),
+  };
+}

package/src/meshrasters.ts

@@ -0,0 +1,156 @@
+/**
+ * The art-derived rasters one mesh measurement reads — every quantity of
+ * `measureMeshQuality`'s raster rows (`src/meshquality.ts`) whose only input is
+ * the art: the art bits at the threshold, the filled silhouette at both
+ * background connectivities and each one's distance transform, the
+ * 4-connected island labels, and the traced outline in drawing pixels.
+ *
+ * ## Why it is a value and not a cache
+ *
+ * `reduceMesh` measures one candidate per step against art that never changes
+ * within the call, and recomputing these per step was nearly all of its cost
+ * (issue #1240: 98.98 % of a 1101-step call's samples in the measurement, at
+ * least 40 % in functions of the art alone). So the call takes them once, at
+ * admission, and hands this object to every measurement it makes. There is no
+ * module-level cache and no hidden state: the object is created by the caller,
+ * passed explicitly, and dropped with the call. `measureMeshQuality` itself
+ * makes a fresh one per call, so its behaviour is the uncached one.
+ *
+ * Each quantity is computed on first read and kept, so a measurement that
+ * never reaches a row (a source that is not one loop, art under its sample
+ * floor) computes no more than it did before. `tally` counts every
+ * computation and every measurement handed the object — the count a control
+ * reads to see that a reduction computed each quantity once.
+ *
+ * ## What it is taken at, and the refusal
+ *
+ * The object holds the `ArtInput` it was made from. A measurement handed it
+ * for a different art is refused, not served stale numbers: the mask array,
+ * the mask's size, the threshold and the frame's scale and size are each
+ * compared, and a difference is `REDUCE_ART_RASTERS_MISMATCH` naming the field,
+ * the value the rasters were taken at and the value the input requires
+ * (`checkArtRasters`, `src/meshquality.ts`).
+ *
+ * Not re-exported by `src/mesh.ts`: nothing here is on `spine-rigc/mesh`.
+ */
+import { artOf, fillEnclosed, labelIslands, MeshError, prunePolygon, squaredDistanceToSet, traceAlphaOutline } from './mesh.ts';
+import type { ArtInput } from './meshquality.ts';
+
+/** How many times each quantity was computed, and how many measurements were handed the object. */
+export interface ArtRasterTally {
+  /** Measurements that read the object (each after its own check). */
+  uses: number;
+  artBits: number;
+  fills: number;
+  toFilled8: number;
+  toFilled4: number;
+  islands: number;
+  traced: number;
+}
+
+/** The traced art outline in drawing pixels, pruned — or the tracer's refusal, as its message. */
+export type TracedArt = { outline: Array<[number, number]> } | { refused: string };
+
+export interface ArtRasters {
+  /** The art these were taken from: its mask array, size, threshold and frame. */
+  readonly art: ArtInput;
+  readonly tally: ArtRasterTally;
+  /** `artOf(mask, threshold)`: 1 where alpha >= threshold. */
+  artBits(): Uint8Array;
+  /** The number of art pixels in `artBits()`. */
+  artCount(): number;
+  /** `fillEnclosed` of the art at both background connectivities, and whether they differ anywhere. */
+  fills(): { fill8: Uint8Array; fill4: Uint8Array; differ: boolean };
+  /** `squaredDistanceToSet` of the filled silhouette at one connectivity. */
+  toFilled(connectivity: 4 | 8): Float64Array;
+  /** `labelIslands` of the art: 4-connected labels, 1-based, and each island's size. */
+  islands(): { label: Int32Array; sizes: number[] };
+  /** `traceAlphaOutline` at the threshold, carried to drawing pixels by `pageScale` and pruned. */
+  traced(): TracedArt;
+}
+
+/**
+ * The rasters of one art, each computed on first read. Reads nothing at
+ * construction, so it may be made before the art is validated; every reader
+ * checks it against a validated input first.
+ */
+export function artRastersOf(art: ArtInput): ArtRasters {
+  const tally: ArtRasterTally = { uses: 0, artBits: 0, fills: 0, toFilled8: 0, toFilled4: 0, islands: 0, traced: 0 };
+  let bits: { bits: Uint8Array; count: number } | null = null;
+  let fills: { fill8: Uint8Array; fill4: Uint8Array; differ: boolean } | null = null;
+  let toFilled8: Float64Array | null = null;
+  let toFilled4: Float64Array | null = null;
+  let islands: { label: Int32Array; sizes: number[] } | null = null;
+  let traced: TracedArt | null = null;
+  const artBitsOf = (): { bits: Uint8Array; count: number } => {
+    if (bits === null) {
+      tally.artBits++;
+      const b = artOf(art.mask, art.threshold);
+      let count = 0;
+      for (const bit of b) count += bit;
+      bits = { bits: b, count };
+    }
+    return bits;
+  };
+  const fillsOf = (): { fill8: Uint8Array; fill4: Uint8Array; differ: boolean } => {
+    if (fills === null) {
+      tally.fills++;
+      const { width: w, height: h } = art.mask;
+      const b = artBitsOf().bits;
+      const fill8 = fillEnclosed(b, w, h, 8).filled;
+      const fill4 = fillEnclosed(b, w, h, 4).filled;
+      let differ = false;
+      for (let i = 0; i < fill8.length; i++) {
+        if (fill8[i] !== fill4[i]) {
+          differ = true;
+          break;
+        }
+      }
+      fills = { fill8, fill4, differ };
+    }
+    return fills;
+  };
+  return {
+    art,
+    tally,
+    artBits: () => artBitsOf().bits,
+    artCount: () => artBitsOf().count,
+    fills: fillsOf,
+    toFilled: (connectivity) => {
+      const { width: w, height: h } = art.mask;
+      if (connectivity === 8) {
+        if (toFilled8 === null) {
+          tally.toFilled8++;
+          toFilled8 = squaredDistanceToSet(fillsOf().fill8, w, h);
+        }
+        return toFilled8;
+      }
+      if (toFilled4 === null) {
+        tally.toFilled4++;
+        toFilled4 = squaredDistanceToSet(fillsOf().fill4, w, h);
+      }
+      return toFilled4;
+    },
+    islands: () => {
+      if (islands === null) {
+        tally.islands++;
+        islands = labelIslands(artBitsOf().bits, art.mask.width, art.mask.height);
+      }
+      return islands;
+    },
+    traced: () => {
+      if (traced === null) {
+        tally.traced++;
+        const scale = art.frame.pageScale;
+        try {
+          const t = traceAlphaOutline(art.mask, art.threshold);
+          traced = { outline: prunePolygon(t.outline.map(([x, y]): [number, number] => [x / scale, y / scale])) };
+        } catch (err) {
+          if (!(err instanceof MeshError)) throw err;
+          traced = { refused: err.message };
+        }
+      }
+      return traced;
+    },
+  };
+}

package/src/meshreduce.ts

@@ -2,7 +2,9 @@
  * Mesh reduction and local refinement — stage B2 of the contract in
  * docs/MESH_REDUCTION.md (issue #1221, stage B: issue #1224).
  *
- * One operation is exported, `reduceMesh`, and it is two operations composed:
+ * One operation is exported, `reduceMesh` — `reduceMeshWith` is the same
+ * operation over art rasters the caller made — and it is two operations
+ * composed:
  *
  * 1. **Refinement** (`refineRegions`) inserts vertices inside the union of the
  *    declared regions and their bands until §5's `L(R)` holds on every edge
@@ -22,7 +24,9 @@
  * ## What every step is held to
  *
  * Each candidate step is measured by `measureMeshQuality` (`src/meshquality.ts`)
- * — no row is re-implemented here — and taken only when every row the caller's
+ * — no row is re-implemented here; the call reads it as `measureMeshQualityWith`
+ * over the art's rasters taken once at admission (`src/meshrasters.ts`, issue
+ * #1240), which returns the same report — and taken only when every row the caller's
  * contract requires is `pass`: the art fit at `targets.artFit`, the boundary
  * deviation from the source hull at `targets.maxBoundaryDeviation`, the minimum
  * angle when declared, orientation and degeneracy at 0, and every region's
@@ -71,8 +75,6 @@ import {
   distanceToSegment,
   earClip,
   findSelfIntersection,
-  labelIslands,
-  artOf,
   MeshError,
   MeshReductionError,
   meshEdges,
@@ -85,7 +87,7 @@ import {
 import {
   BAND_CONTACT_TOLERANCE,
   edgeIsHeldByRegion,
-  measureMeshQuality,
+  measureMeshQualityWith,
   type AttachmentRef,
   type ArtFitBounds,
   type CandidateReport,
@@ -101,6 +103,7 @@ import {
   type SourceMesh,
   type Termination,
 } from './meshquality.ts';
+import { artRastersOf, type ArtRasters } from './meshrasters.ts';
 
 // ---------------------------------------------------------------------------
 // the result
@@ -711,6 +714,8 @@ interface Run {
   protectedVertices: Set<number>;
   protectedEdges: Array<[number, number]>;
   sourceEdges: Set<string>;
+  /** The art's rasters, taken once for the call and read by every measurement in it (issue #1240). */
+  rasters: ArtRasters;
 }
 
 /** A measurement of a canonical mesh against the result's full contract. */
@@ -731,7 +736,7 @@ function measureAgainstTargets(run: Run, mesh: SourceMesh, id: string): MeshQual
     boneOrder: input.boneOrder,
     preset: input.preset,
   };
-  return measureMeshQuality(measureInput);
+  return measureMeshQualityWith(measureInput, run.rasters);
 }
 
 /** The order constraints are named in when several fail on one step: structure, then shape, then art, then density. */
@@ -1167,26 +1172,50 @@ function tryRemoval(run: Run, v: number): string | null {
  */
 export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
   validateReduction(input);
+  return reduceValidated(input, artRastersOf(input.art));
+}
+
+/**
+ * `reduceMesh` over art rasters the caller made (`artRastersOf`,
+ * `src/meshrasters.ts`) — the result is `reduceMesh`'s for the same input, byte
+ * for byte, and every measurement of the call reads the one object, so its
+ * `tally` is the count of what the call computed. Rasters taken from another
+ * art are refused at admission (`REDUCE_ART_RASTERS_MISMATCH`).
+ *
+ * Internal: it is on `spine-rigc/mesh` only because that entry re-exports this
+ * module with `export *`, and a symbol that is merely exported is not promised
+ * (RELEASING.md, *The import surface*).
+ */
+export function reduceMeshWith(input: MeshReductionInput, rasters: ArtRasters): MeshReductionResult {
+  validateReduction(input);
+  return reduceValidated(input, rasters);
+}
+
+/** The operation, over an input `validateReduction` accepted; the art's rasters are computed at most once, in `rasters`. */
+function reduceValidated(input: MeshReductionInput, rasters: ArtRasters): MeshReductionResult {
   const who = `attachment ${nameOf(input.attachment)}`;
   const src = input.source;
   const sourceHull: Array<[number, number]> = src.points.slice(0, Math.max(0, src.hull)).map(([x, y]): [number, number] => [x, y]);
 
   // The source, measured against its own admissibility bounds (correction 3) — this is also what refuses a
   // malformed art, mesh, region list or sample floor, by measureMeshQuality's own codes.
-  const admit = measureMeshQuality({
-    id: 'source',
-    attachment: input.attachment,
-    art: input.art,
-    source: src,
-    targets: { artFit: input.sourceBounds, maxBoundaryDeviation: null, regions: input.targets.regions },
-    referenceHull: null,
-    minArtSamples: input.minArtSamples,
-    regionArtSamples: input.regionArtSamples,
-    protect: input.protect,
-    influences: input.influences,
-    boneOrder: input.boneOrder,
-    preset: input.preset,
-  });
+  const admit = measureMeshQualityWith(
+    {
+      id: 'source',
+      attachment: input.attachment,
+      art: input.art,
+      source: src,
+      targets: { artFit: input.sourceBounds, maxBoundaryDeviation: null, regions: input.targets.regions },
+      referenceHull: null,
+      minArtSamples: input.minArtSamples,
+      regionArtSamples: input.regionArtSamples,
+      protect: input.protect,
+      influences: input.influences,
+      boneOrder: input.boneOrder,
+      preset: input.preset,
+    },
+    rasters,
+  );
   const effective = effectiveOf(input, admit.effective, sourceHull);
   const sourceCounts = admit.sourceCounts;
   const noMesh = (termination: Termination): MeshReductionResult => ({
@@ -1215,7 +1244,7 @@ export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
         );
       }
     }
-    checkIslands(input, who);
+    checkIslands(input, who, rasters);
     checkDeformBeforeWork(input);
 
     const boneRank = new Map((input.boneOrder ?? []).map((b, i) => [b, i]));
@@ -1243,6 +1272,7 @@ export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
       keyed: keyedSourceVertices(input),
       ...protectionOf(input, work, sourceEdges),
       sourceEdges,
+      rasters,
     };
 
     const refined = refineRegions(run);
@@ -1268,11 +1298,10 @@ export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
 }
 
 /** §4: full coverage asked of a source that touches no pixel of some art island is refused, never met by deleting art. */
-function checkIslands(input: MeshReductionInput, who: string): void {
+function checkIslands(input: MeshReductionInput, who: string, rasters: ArtRasters): void {
   if (input.targets.artFit.minCoverage !== 1) return;
-  const { mask, threshold, frame } = input.art;
-  const bits = artOf(mask, threshold);
-  const { label, sizes } = labelIslands(bits, mask.width, mask.height);
+  const { mask, frame } = input.art;
+  const { label, sizes } = rasters.islands();
   const onGrid = input.source.points.map(([x, y]): [number, number] => [x * frame.pageScale, y * frame.pageScale]);
   const covered = rasteriseTriangles(onGrid, input.source.triangles, mask.width, mask.height);
   const touched = new Set<number>();