spine-rigc 1.1.0 → 1.2.1

package/src/check.ts

@@ -214,6 +214,17 @@ function readSidecar(root: string): FramesSidecar | null {
   const raw = readFrameFile(root, join(root, FRAMES_SIDECAR)).toString('utf8');
   const parsed: unknown = JSON.parse(raw);
   if (typeof parsed !== 'object' || parsed === null) return null;
+  // Before the spec, because it is the more specific answer: a `check --out`
+  // directory carries this build's own spec, and what is wrong with it is not
+  // its version but what it is a picture OF — see `COMPARISON_FIELD`.
+  if (Object.prototype.hasOwnProperty.call(parsed, COMPARISON_FIELD)) {
+    throw new CheckError(
+      `${join(root, FRAMES_SIDECAR)} carries ${JSON.stringify(COMPARISON_FIELD)}: it was written by \`rigc check ` +
+        '--out`, and a check\'s pictures are a comparison, not a reference frame set — each one holds a reference ' +
+        'pane, but the file is four panes and a table. Point --frames at the frames that comparison was made ' +
+        `against, which its ${JSON.stringify(COMPARISON_FIELD)}.frames names.`,
+    );
+  }
   const sidecar = parsed as FramesSidecar;
   if (sidecar.spec !== FRAMES_SPEC) {
     throw new CheckError(
@@ -1006,6 +1017,12 @@ export interface CheckOptions {
    * this adds a second render per compared frame beside them.
    */
   textureFrom?: { atlasText: string; atlasDir: string; label: string };
+  /**
+   * Keep the rasters behind the frames the report will list, for `--out` — see
+   * `CheckPlates`. Nothing about the report changes when this is set: it is filled
+   * in beside the comparison, from the plates the comparison was computed on.
+   */
+  plates?: CheckPlates;
 }
 
 // ---------------------------------------------------------------------------
@@ -1056,6 +1073,22 @@ export interface CheckOptions {
  */
 export function checkAgainstFrames(options: CheckOptions): CheckReport {
   const located = locateFrames(options.framesDir);
+  // A frame set `render --slot`/`--hide` wrote is a picture of PART of a rig
+  // (issue #835), and it is refused before anything is posed. The clause is the
+  // skin mismatch's below, one step stronger: there two skins are two pictures
+  // of one rig, here the reference is not a picture of a whole rig at all, so a
+  // whole candidate compared against it would print a real figure about art the
+  // reference leaves out. No flag makes that comparable — a warning would still
+  // print the figure — so there is no remedy here but the reference's own.
+  const subsetKey = located.sidecar?.slots !== undefined ? 'slots' : located.sidecar?.hidden !== undefined ? 'hidden' : null;
+  if (subsetKey !== null) {
+    const recorded = located.sidecar?.[subsetKey];
+    throw new CheckError(
+      `--frames ${options.framesDir} records a slot subset (${subsetKey}: ${
+        Array.isArray(recorded) ? recorded.join(', ') : JSON.stringify(recorded)
+      }) in ${FRAMES_SIDECAR}; a partial render is not a reference set — render the reference without --slot/--hide`,
+    );
+  }
   const notes: string[] = [];
 
   const posable = posableFromText(options.skeletonText, options.atlasText, options.atlasDir);
@@ -1136,11 +1169,20 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         duration: disk[disk.length - 1].index / fps,
       },
     ];
+    // Two sources write a set like this, and they need opposite advice (issue
+    // #842): a rigc render older than the sidecar is fixed by rendering it again,
+    // while a foreign player's frames predate nothing and no rigc tool renders
+    // their source — what they need is the three things the sidecar would have
+    // said, supplied by whoever made them.
     notes.push(
-      `no ${FRAMES_SIDECAR} at ${located.root} or beside it — this frame set predates the sidecar. The rate is ` +
+      `no ${FRAMES_SIDECAR} at ${located.root} or beside it. The rate is ` +
         `--fps ${fps}${options.fps === undefined ? ' (the protocol default, not a measurement of these frames)' : ''} ` +
-        `and the background is this build's default (${BACKGROUND.join(', ')}). Re-render the set with ` +
-        'bench/render_reference.ts and both become facts about the frames.',
+        `and the background is this build's default, ${BACKGROUND.join(', ')}; neither is read from the frames. ` +
+        'A set with no sidecar is one of two things. A rigc render older than the sidecar: re-render it with ' +
+        '`rigc render` (bench/render_reference.ts for an editor export) and both become facts about the frames. ' +
+        `A foreign source — a Live2D, Unity or video player: render it onto an opaque background of ` +
+        `${BACKGROUND.join(', ')}, pass --fps at the rate it was rendered, and name the directory after the ` +
+        'candidate animation it shows, or pass --as <that animation>.',
     );
     // The set root is the animation directory itself here, so reads resolve
     // against its parent the way a sidecar layout does.
@@ -1193,8 +1235,36 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   // `EDGE_FRACTION`. A handful of frames is enough: the level is a property of the
   // palette, not of a pose, and reading every frame twice to learn it is waste.
   const level = pairs.length === 0 ? BACKGROUND_TOLERANCE : edgeLevelOf(located.root, pairs, background);
+  // Without a sidecar the background is an assumption, and it is an assumption
+  // about a COLOUR: the box and the union alpha are found against it with alpha
+  // unread. So a reference that is not opaque is refused rather than scored
+  // (issue #842). Measured on gallery/look's `turn` with its background made
+  // transparent and the candidate pinned by --viewport to the box the frames were
+  // drawn in — where the same set over the assumed grey reads MAE 0.00 exactly —
+  // it read 32.90 on every one of the 24 frames, which is the transparent area's
+  // share of the frame times its distance from the grey: a figure about the
+  // background, not the rig, and no framing moves it. A frame set WITH a sidecar
+  // is `render`'s, which composites onto the colour it records, so it is not asked.
+  const translucent: TranslucentFrame[] | null = located.sidecar ? null : [];
   const referenceBoxes =
-    pairs.length === 0 ? [] : referenceContentBoxes(located.root, pairs, background, level, pixelWidth, pixelHeight);
+    pairs.length === 0
+      ? []
+      : referenceContentBoxes(located.root, pairs, background, level, pixelWidth, pixelHeight, translucent);
+  if (translucent !== null && translucent.length > 0) {
+    const first = translucent[0];
+    const shown = translucent.slice(0, TRANSLUCENT_NAMED).map((t) => basename(t.file));
+    throw new CheckError(
+      `--frames ${options.framesDir} has no ${FRAMES_SIDECAR}, and ${translucent.length} of its ${pairs.length} ` +
+        `compared reference frame(s) are not opaque (${shown.join(', ')}${
+          translucent.length > shown.length ? `, and ${translucent.length - shown.length} more` : ''
+        }): ${basename(first.file)} has alpha ${first.alpha} at (${first.x}, ${first.y}), where every pixel must ` +
+        `be 255. Without a sidecar the frames are read against the background colour ${BACKGROUND.join(', ')} ` +
+        'with alpha unread, so a pixel that is not opaque counts by its colour bytes alone: a transparent ' +
+        'background counts as drawn and puts the figure over the whole frame, a number about the transparent ' +
+        'area and not the rig, which --viewport does not change. Render the frames onto an opaque background of ' +
+        `${BACKGROUND.join(', ')}.`,
+    );
+  }
 
   const scope: FramingScope = options.framing ?? 'per-shot';
   const slices = sliceBySet(prepared, referenceBoxes);
@@ -1254,7 +1324,14 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
       topFit = reportFor(fit, pinned, { ...pinnedShape, agrees: fitDistance(fit) <= COINCIDENT_PIXELS, refinement });
     }
   } else if (referenceBoxes.every((b) => b === null)) {
-    throw new CheckError('no reference frame could be compared, so there is nothing to frame against');
+    throw new CheckError(
+      `no reference frame could be compared, so there is nothing to frame against${nothingToFrameWhy(
+        prepared,
+        posable.data.animations.map((a) => a.name),
+        options.as,
+        located.sidecar !== null,
+      )}`,
+    );
   } else if (scope === 'shared' || prepared.length === 1) {
     const framed = frameCandidate(
       prepared,
@@ -1404,7 +1481,18 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   for (let i = 0; i < prepared.length; i++) {
     const f = framings[i];
     animations.push(
-      checkOneSet(located.root, prepared[i], posable, f, background, chains, chainOfSlot, substitution, unmatched),
+      checkOneSet(
+        located.root,
+        prepared[i],
+        posable,
+        f,
+        background,
+        chains,
+        chainOfSlot,
+        substitution,
+        unmatched,
+        options.plates ?? null,
+      ),
     );
   }
 
@@ -1681,7 +1769,38 @@ function edgeLevelOf(root: string, pairs: FramePair[], background: RGBA): number
   return histogram.level();
 }
 
-/** Each reference frame's own content box, and a check that they are one grid. */
+/** How many translucent reference frames the refusal names before it counts the rest. */
+const TRANSLUCENT_NAMED = 3;
+
+/** The first pixel of a reference frame that is not fully opaque — see `referenceContentBoxes`. */
+interface TranslucentFrame {
+  file: string;
+  x: number;
+  y: number;
+  alpha: number;
+}
+
+/** The first pixel whose alpha is not 255, in row order, or null when the frame is opaque. */
+function firstTranslucentPixel(plate: Plate): { x: number; y: number; alpha: number } | null {
+  for (let i = 3; i < plate.data.length; i += 4) {
+    if (plate.data[i] !== 255) {
+      const at = (i - 3) / 4;
+      return { x: at % plate.width, y: Math.floor(at / plate.width), alpha: plate.data[i] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Each reference frame's own content box, and a check that they are one grid.
+ *
+ * `translucent`, when given, collects every frame that is not fully opaque. The
+ * content box and the union alpha are found against the background COLOUR and
+ * alpha is never read (`backgroundDistance`), so a transparent pixel is drawn to
+ * both of them whatever its colour bytes say. It is collected here rather than in
+ * a pass of its own because this is where every compared frame is already
+ * decoded, and a frame that is not compared cannot move a figure.
+ */
 function referenceContentBoxes(
   root: string,
   pairs: FramePair[],
@@ -1689,6 +1808,7 @@ function referenceContentBoxes(
   level: number,
   pixelWidth: number,
   pixelHeight: number,
+  translucent: TranslucentFrame[] | null,
 ): Array<ContentBox | null> {
   return pairs.map((pair) => {
     const plate = readPlateFrom(root, pair.file);
@@ -1698,6 +1818,10 @@ function referenceContentBoxes(
           'the frames and the sidecar disagree about their own size',
       );
     }
+    if (translucent !== null) {
+      const at = firstTranslucentPixel(plate);
+      if (at !== null) translucent.push({ file: pair.file, ...at });
+    }
     return contentBoxOfPlate(plate, background, level);
   });
 }
@@ -2354,6 +2478,46 @@ function prepareSet(
   };
 }
 
+/**
+ * What the "nothing to frame against" refusal adds when the sets can say why.
+ *
+ * The one reason a whole run has no reference box that a reader can act on is a
+ * name that matched no candidate animation, and `prepareSet` already composed
+ * that per set — then the refusal fired before any set was reported, so the one
+ * sentence that named the fix never reached the reader (issue #842). This says
+ * where each name came from, because the fix differs: a directory name is
+ * renamed or overridden, an `--as` is corrected. Empty when every set matched,
+ * so the refusal's other causes keep the sentence they had.
+ */
+function nothingToFrameWhy(
+  prepared: PreparedSet[],
+  have: string[],
+  as: string | undefined,
+  sidecar: boolean,
+): string {
+  const unmatched = prepared.filter((p) => p.missing !== null);
+  if (unmatched.length === 0) return '';
+  const declared = `it declares [${have.join(', ') || 'none'}]`;
+  if (as !== undefined) {
+    return (
+      `: --as ${JSON.stringify(as)} names no animation of the candidate — ${declared}. --as takes one candidate ` +
+      'animation name, the one these frames show'
+    );
+  }
+  const tried = unmatched.map((p) => {
+    const name = JSON.stringify(p.set.animation);
+    if (sidecar) return `${name} (what ${FRAMES_SIDECAR} records for set ${JSON.stringify(p.set.dir)})`;
+    return p.set.dir === p.set.animation
+      ? `${name} (the directory's own name)`
+      : `${name} (the directory ${JSON.stringify(p.set.dir)}, its @fps suffix dropped)`;
+  });
+  return (
+    `: the frames were matched to a candidate animation by name, and the candidate has no animation called ` +
+    `${tried.join(', ')} — ${declared}. Pass --as <name> with the one these frames show, or name the ` +
+    'directory after it'
+  );
+}
+
 function checkOneSet(
   root: string,
   prepared: PreparedSet,
@@ -2367,6 +2531,8 @@ function checkOneSet(
   substitution: TextureSubstitution | null,
   /** Region names it could not reach, unioned across every set by the caller. */
   unmatched: Set<string>,
+  /** Where to keep the rasters of the frames the report will list — `null` keeps none. */
+  plates: CheckPlates | null,
 ): AnimationCheck {
   const { set } = prepared;
   const viewport = framing.viewport;
@@ -2437,6 +2603,7 @@ function checkOneSet(
   // because `substituteTexture` prefixes every name it writes.
   const floorPages = substitution === null ? null : new Map([...posable.pages, ...substitution.pages]);
   const floorSum = { floor: 0, aboveFloor: 0, floorReference: 0, aboveFloorReference: 0 };
+  plates?.begin(set.dir, prepared.pairs.length);
 
   for (const { index, file, frame } of prepared.pairs) {
     const reference = readPlateFrom(root, file);
@@ -2447,7 +2614,7 @@ function checkOneSet(
       for (const name of swapped.unmatched) unmatched.add(name);
       floorPlate = renderFrame(swapped.frame, floorPages, viewport, background);
     }
-    const check = checkOneFrame(
+    const { check, coverage } = checkOneFrame(
       index,
       file,
       frame,
@@ -2462,6 +2629,9 @@ function checkOneSet(
     );
     check.change = previous && previous.index === index - 1 ? frameChange(previous, rendered, reference) : null;
     previous = { index, candidate: rendered, reference };
+    // After the change is known, because whether a frame will be listed depends
+    // on it — see `CheckPlates.offer`.
+    plates?.offer(set.dir, check, { reference, candidate: rendered, coverage });
     frames.push(check);
     maeSum += check.mae;
     maeReferenceSum += check.maeReference;
@@ -2827,7 +2997,7 @@ function checkOneFrame(
    * see `TextureFloor`. `null` is the ordinary case and costs nothing.
    */
   floorPlate: Plate | null,
-): FrameCheck {
+): { check: FrameCheck; coverage: Uint8Array } {
   const { coverage, footprints, owner } = frameGeometry(frame, pages, viewport, chainOfSlot);
   // Only worth the transform when something was drawn to be nearest TO.
   const nearest =
@@ -2911,7 +3081,7 @@ function checkOneFrame(
     }
   }
 
-  return {
+  const check: FrameCheck = {
     index,
     file,
     mae: union === 0 ? 0 : sum / union,
@@ -2943,6 +3113,9 @@ function checkOneFrame(
             aboveFloorReference: referencePixels === 0 ? 0 : aboveReferenceSum / referencePixels,
           },
   };
+  // The coverage goes back beside the figures because the union it defines is the
+  // one a `--out` difference pane is drawn over — see `CheckPlates`.
+  return { check, coverage };
 }
 
 // ---------------------------------------------------------------------------
@@ -3653,7 +3826,7 @@ function chainRollup(report: CheckReport): ChainRollup[] {
  * ranked by MAE is exactly the listing that leaves them out. Rung 6's f65–f68 sit
  * near the bottom of that ranking.
  */
-function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
+export function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
   if (allFrames || anim.frames.length <= LIST_EVERY) return anim.frames;
   const chosen = new Set(
     [...anim.frames]
@@ -3665,6 +3838,129 @@ function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
   return anim.frames.filter((f) => chosen.has(f.index));
 }
 
+/**
+ * The field of a `frames.json` that says the directory is `check --out`'s
+ * pictures and not a frame set — see `src/checkpics.ts`. `check --frames`
+ * refuses a sidecar carrying it, by this name.
+ */
+export const COMPARISON_FIELD = 'comparison';
+
+/** The three rasters one frame's figures were computed on. */
+export interface ComparedPlates {
+  /** The reference frame, as read from `--frames`. */
+  reference: Plate;
+  /** The candidate, rendered onto the reference's grid over the frames' background. */
+  candidate: Plate;
+  /** Which pixels the candidate's geometry covers, 1 or 0 — half of the union alpha. */
+  coverage: Uint8Array;
+}
+
+/**
+ * The rasters behind the frames a report will list, kept at the moment they were
+ * compared — what `check --out` draws its pictures from.
+ *
+ * ## Why they have to be kept, and why not all of them
+ *
+ * `checkOneSet` holds a frame's two plates for exactly one iteration (and the
+ * previous frame's for the change measure); the difference is never a raster at
+ * all, only a running sum. And which frames are *worth reading* is not known
+ * until the set is finished, because it is the worst by MAE over all of them —
+ * `framesToList` decides it at print time. So the choice is between re-rendering
+ * the listed frames afterwards and keeping them now, and re-rendering is rejected:
+ * a second render that agreed with the first would be a claim about the picture,
+ * and this is meant to be the record of it.
+ *
+ * Keeping every frame is the other simple answer and it does not scale: one
+ * frame at 256x116 is 261 KiB of plates and coverage, and a 300-frame set at
+ * 512x512 would hold 675 MiB. So a set longer than the listing threshold keeps a
+ * running top `WORST_FRAMES` by MAE — ties to the earlier index, which is the
+ * order `framesToList`'s stable sort gives them — plus every frame whose change
+ * disagrees, and drops the rest as it goes. `--all-frames` keeps everything,
+ * because then everything is listed.
+ *
+ * 🔒 `framesToList` stays the one derivation of the listing. This only has to
+ * keep a superset of it, and `writeCheckPictures` refuses by name a listed frame
+ * it finds nothing kept for, so the two cannot disagree in silence.
+ */
+export class CheckPlates {
+  /** Whether every compared frame is kept — `--all-frames`. */
+  readonly every: boolean;
+  private readonly kept = new Map<string, Map<number, ComparedPlates>>();
+  /** Per set: whether the whole set will be listed, so everything is kept. */
+  private readonly whole = new Map<string, boolean>();
+  /** Per set: the running worst by MAE, worst first, at most `WORST_FRAMES`. */
+  private readonly ranked = new Map<string, Array<{ index: number; mae: number }>>();
+  /** Per set: frames kept because their change disagrees, whatever their MAE. */
+  private readonly disagreeing = new Map<string, Set<number>>();
+  private held = 0;
+  /** The most bytes of raster this held at any one time — the cost `--out` adds. */
+  peakBytes = 0;
+
+  constructor(opts: { allFrames: boolean }) {
+    this.every = opts.allFrames;
+  }
+
+  /** A set is about to be compared, over this many frame pairs. */
+  begin(dir: string, compared: number): void {
+    this.kept.set(dir, new Map());
+    this.whole.set(dir, this.every || compared <= LIST_EVERY);
+    this.ranked.set(dir, []);
+    this.disagreeing.set(dir, new Set());
+  }
+
+  /** One frame has been compared: keep its plates if it can be listed. */
+  offer(dir: string, check: FrameCheck, plates: ComparedPlates): void {
+    const kept = this.kept.get(dir);
+    const ranked = this.ranked.get(dir);
+    const disagreeing = this.disagreeing.get(dir);
+    if (kept === undefined || ranked === undefined || disagreeing === undefined) {
+      throw new Error(`CheckPlates: set ${JSON.stringify(dir)} was offered a frame before it began`);
+    }
+    if (this.whole.get(dir) === true) {
+      this.keep(kept, check.index, plates);
+      return;
+    }
+    const disagrees = check.change !== null && check.change.verdict !== 'agrees';
+    if (disagrees) disagreeing.add(check.index);
+    // Frames arrive in index order, so a later frame that only ties the last
+    // ranked one loses to it — exactly as the stable sort would place them.
+    const enters = ranked.length < WORST_FRAMES || check.mae > ranked[ranked.length - 1].mae;
+    if (enters) {
+      let at = ranked.findIndex((r) => check.mae > r.mae);
+      if (at < 0) at = ranked.length;
+      ranked.splice(at, 0, { index: check.index, mae: check.mae });
+      if (ranked.length > WORST_FRAMES) {
+        const out = ranked.pop() as { index: number; mae: number };
+        if (!disagreeing.has(out.index)) this.drop(kept, out.index);
+      }
+    }
+    if (enters || disagrees) this.keep(kept, check.index, plates);
+  }
+
+  /** The plates kept for one frame of one set, if any. */
+  of(dir: string, index: number): ComparedPlates | undefined {
+    return this.kept.get(dir)?.get(index);
+  }
+
+  private keep(kept: Map<number, ComparedPlates>, index: number, plates: ComparedPlates): void {
+    if (kept.has(index)) return;
+    kept.set(index, plates);
+    this.held += bytesOf(plates);
+    if (this.held > this.peakBytes) this.peakBytes = this.held;
+  }
+
+  private drop(kept: Map<number, ComparedPlates>, index: number): void {
+    const plates = kept.get(index);
+    if (plates === undefined) return;
+    kept.delete(index);
+    this.held -= bytesOf(plates);
+  }
+}
+
+function bytesOf(plates: ComparedPlates): number {
+  return plates.reference.data.length + plates.candidate.data.length + plates.coverage.length;
+}
+
 /** The per-frame change measure, as the animation's own summary line. */
 function changeSummary(anim: AnimationCheck): string {
   if (anim.changePairs === 0) {