spine-rigc 2.20.0 → 2.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.20.0",
+  "version": "2.20.1",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

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';
 
 // ---------------------------------------------------------------------------
@@ -1012,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;
@@ -1053,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;
@@ -1108,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;
@@ -1150,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;
@@ -1179,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 --------------------------------------------------
@@ -1233,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);
@@ -1331,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;
@@ -1407,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);

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>();