/**
* rigc check — measure a candidate against reference **frames**, never against
* the reference file.
*
* ## The hole this closes
*
* The gate is a *validity* gate. It parses the skeleton, steps every animation,
* and refuses anything degenerate — and it has no opinion whatever about whether
* the animation is the one in the frames. Three honest ladder runs produced zero
* validator FAILs between them, and one of those runs shipped a build in which
* **every easing in the file was reversed** and came back green. Both authors
* closed the loop the same way, with a script they wrote themselves: pose the
* candidate with `spine-core`, and compare it against what they had measured off
* the pictures. This is that script, promoted, so the loop is
*
* build → validate → check against frames → fix
*
* and the last step is a command rather than something each author reinvents.
*
* ## 🔒 The invariant: this never reads the answer
*
* `check` opens exactly two things — **the candidate** (its skeleton, its atlas
* and the atlas pages) and **PNG frames** under `--frames`, plus the
* `frames.json` sidecar beside them. It has no code path that names
* `examples/`, an `export/` directory, a rung or a reference skeleton, and every
* read on the reference side goes through `readFrameFile`, which refuses a path
* that escapes `--frames` or that is neither a `.png` nor the sidecar.
*
* That is not fastidiousness. `docs/LADDER.md`'s honesty rule is the only thing
* that makes a rung's number mean anything, and a fidelity tool that quietly
* loaded the reference JSON would convert every future run from authoring into
* transcription without anybody noticing — the exact failure that is hardest to
* detect after the fact.
*
* ## What it measures
*
* Per animation, per frame:
*
* - **The framing** — where the candidate's drawn pixels sit against the
* reference's drawn pixels, as a scale ratio and a residual. It is reported
* first because it is upstream of everything else: get it wrong and every
* number below carries the error, disguised as motion (issue #34).
* - **MAE over the union alpha** — the mean absolute RGB difference between the
* candidate composited over the frames' background and the reference frame,
* averaged over the pixels either side covers. Over the union rather than the
* whole frame because most of a frame is background on both sides, and
* averaging that in makes every number small and every difference between
* numbers smaller.
* - **Per-frame change** — how much each side moved since **its own** previous
* frame, and whether those two agree. The only measure here that looks at a
* relation between two frames rather than at one, and the only one that can see
* a held pose that is not held or a one-frame event that never fired — see
* `FrameChange`.
* - **Per-slot tracking** — where each of the candidate's own slots landed
* against the reference frame. This is the part an author acts on: MAE says
* *how wrong*, a slot's drift says *which part, which way, how far*.
*
* ⚠️ Both of the last two are bounded by what a picture can attribute, and
* `src/slots.ts` owns that judgement: a slot the reference merged into a
* neighbour is template-matched against its own pixels rather than guessed at,
* and a slot nothing in its search radius matches comes back as **no match**
* rather than as a number. A drift printed beside the wrong part is worse than a
* blank, because it is actionable and wrong.
*/
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
import {
BACKGROUND,
frameGeometry,
PROTOCOL_FPS,
loadCandidate,
renderFrame,
sampleAnimation,
sampleSetupPose,
substituteTexture,
textureSubstitutionFromText,
trimmedUnionBounds,
viewportOfSize,
PAD,
FRAMES_SIDECAR,
FRAMES_SPEC,
nonFinitePoseOf,
unframeableSentence,
UnframeablePoseError,
refuseUnchosen,
throughPoser,
SHEET_COLUMNS,
SHEET_FILE,
SHEET_GAP,
type Footprint,
type Frame,
type FramesSidecar,
type FrameSet,
type MakeCorePoser,
type PoseOptions,
type Poser,
type PoserName,
type TextureSubstitution,
type Viewport,
} from './render_shared.ts';
import { hypot2 } from './numeric.ts';
// The one name here that is the runtime's: a candidate's pages, read off the shape spine-core's loader returns.
import type { Posable } from './render.ts';
import {
applyFit,
boxHeight,
boxWidth,
contentBoxOfPlate,
ContrastHistogram,
fitDistance,
fitFraming,
fitIsSettled,
fitSeparation,
frameContentBox,
offsetIsWorthApplying,
OffsetScan,
shiftViewport,
unionBoxes,
isContent,
BACKGROUND_TOLERANCE,
CYCLE_PIXELS,
REFINE_MIN_GAIN,
REFINE_MIN_GAIN_MAE,
REFINE_RADIUS,
type BoxPair,
type ContentBox,
type FramingFit,
type OffsetGain,
} from './framing.ts';
import {
componentField,
driftBound,
isAttributable,
matchSlots,
searchRadius,
SUBPIXEL_CLAMP,
type SlotTrack,
} from './slots.ts';
import { chainsOf, type BoneChain } from './chains.ts';
import { readPlate, type Plate, type RGBA } from '../tools/plate.ts';
import { GLYPH_H, textWidth } from '../tools/font5x7.ts';
export {
componentField,
componentsOf,
driftBound,
matchSlots,
searchRadius,
SUBPIXEL_CLAMP,
type Component,
type ComponentField,
type MatchMethod,
type SlotTrack,
} from './slots.ts';
export { chainsOf, chainBySlot, type BoneChain } from './chains.ts';
export type { BoxPair, ContentBox, FramingFit, OffsetGain } from './framing.ts';
// ---------------------------------------------------------------------------
// the reference side — frames only, and mechanically so
// ---------------------------------------------------------------------------
/**
* The honesty invariant, as a function: this path is a frame under `--frames`.
*
* Every reference-side read in this module goes through it, which is what makes
* "`check` reads only PNG frames" a property of the code rather than a claim in
* a comment — a path that climbs out of the frames directory, or that is neither
* a PNG nor the sidecar, throws with both paths named. It is exported so the
* selftest can make it fire: an invariant nobody has seen refuse anything is not
* an invariant.
*/
export function assertFrameReadable(framesRoot: string, path: string): void {
const abs = resolve(path);
const inside = relative(resolve(framesRoot), abs);
if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
throw new CheckError(`${abs} is outside --frames ${resolve(framesRoot)}; check reads frames and nothing else`);
}
const name = basename(abs);
if (!name.endsWith('.png') && name !== FRAMES_SIDECAR) {
throw new CheckError(
`${abs} is neither a .png frame nor ${FRAMES_SIDECAR}; check never reads a reference skeleton — see src/check.ts`,
);
}
}
function readFrameFile(framesRoot: string, path: string): Buffer {
assertFrameReadable(framesRoot, path);
return readFileSync(resolve(path));
}
export class CheckError extends Error {}
/** Where a frames directory's sidecar is, and which of its sets `--frames` selected. */
interface Located {
/** The skeleton root — where `frames.json` sits. */
root: string;
sidecar: FramesSidecar | null;
/** Set directories to compare; empty means "every set in the sidecar". */
only: string[];
}
/**
* Resolve `--frames
`: either a skeleton root holding the sidecar, or one
* animation directory inside one.
*/
export function locateFrames(framesDir: string): Located {
const dir = resolve(framesDir);
if (!existsSync(dir)) throw new CheckError(`no frames directory at ${dir}`);
if (existsSync(join(dir, FRAMES_SIDECAR))) {
return { root: dir, sidecar: readSidecar(dir), only: [] };
}
const parent = dirname(dir);
if (existsSync(join(parent, FRAMES_SIDECAR))) {
const sidecar = readSidecar(parent);
const name = basename(dir);
if (sidecar && sidecar.sets.some((s) => s.dir === name)) {
return { root: parent, sidecar, only: [name] };
}
}
return { root: dir, sidecar: null, only: [] };
}
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(
`${join(root, FRAMES_SIDECAR)} declares spec ${JSON.stringify(sidecar.spec)}; this build reads ${FRAMES_SPEC}`,
);
}
return sidecar;
}
/** The `f0000.png` frames in a directory, by index, in index order. */
function framesOnDisk(root: string, dir: string): Array<{ index: number; file: string }> {
const abs = join(root, dir);
if (!existsSync(abs)) throw new CheckError(`no frame directory at ${abs}`);
const out: Array<{ index: number; file: string }> = [];
for (const name of readdirSync(abs)) {
const m = /^f(\d+)\.png$/.exec(name);
if (!m) continue;
out.push({ index: Number(m[1]), file: join(abs, name) });
}
out.sort((a, b) => a.index - b.index);
return out;
}
// ---------------------------------------------------------------------------
// the measures
// ---------------------------------------------------------------------------
/**
* How much a frame moved since the frame before it — on **each side separately**.
*
* ## Why this is not the MAE again
*
* Every other measure here compares the candidate against the reference *at one
* moment*. This one compares each side against **itself** a frame earlier, and
* then compares those two numbers. What that catches is a class of defect the
* aggregate MAE is structurally blind to, because it is small in every single
* frame and wrong in the relationship between them:
*
* - **A held pose that is not held.** Rung 6's reference is pixel-identical across
* f64–f67. A greedy key reduction had sloped a line through that plateau —
* legal under its own per-key tolerance, invisible to `validate`, invisible to
* `diff`, and worth so little MAE per frame that nothing flagged it. Re-rendering
* the candidate and diffing **its own** f67 against **its own** f68 showed 91 px
* moving where the reference moves 3.
* - **A one-frame event that never fires.** The same run's tracker reveal landed a
* fraction of a millisecond past the animation's last sample, so it never
* happened. `diff` read `animations.deform` and `draw_order` as matching, the
* gate was green, and only looking at the last two frames found it.
*
* Both were found by that run building its own render-diff outside the tool
* (`bench/runs/2026-08-23-rung6-1/LOOP.md` §10, issue #53). `check` has both frame
* sequences in hand already, so it is the tool's job and not the author's.
*
* ⚠️ Only between **adjacent** frames. A set that commits stills rather than every
* frame — rung 2's contact sheets ship `f0000` and `f0310` — has no frame-to-frame
* delta to report, and the difference between two frames 310 apart is not one. That
* is `null` here rather than a number about the wrong thing.
*/
export interface FrameChange {
/** The frame this one is measured against; always `index - 1`. */
previous: number;
/** Pixels the candidate moved since its own previous frame. */
candidate: number;
/** Pixels the reference moved since its own previous frame. */
reference: number;
/** The same two as a mean absolute RGB difference over the whole frame, 0..255. */
candidateMae: number;
referenceMae: number;
/**
* How the two compare — see `CHANGE_RATIO`.
*
* `moves` means the candidate changed materially more than the reference did
* here, `holds` materially less. Both are diagnoses the per-frame MAE cannot
* give: a frame that is merely off by a constant offset agrees on this measure.
*/
verdict: 'agrees' | 'moves' | 'holds';
}
/**
* How much of a difference is the **texture** rather than the rig — the
* decomposition `--texture-from` measures, and the hole issue #171 filed.
*
* ## What was unattributed, and what it was worth
*
* The reference frames are rendered through the example's own **packed** atlas,
* which may carry a `scale:` line — the ladder's examples are packed at 0.4 and
* 0.5 — while a candidate samples the art at its own resolution. That stays true
* of a `--pack`ed candidate (issue #4): rigc's packer is lossless and writes no
* `scale:` line, so it rearranges texels without resampling one and the constant
* measured here is unchanged by it.
* Every edge of every part is then filtered from a different source.
* That difference is a constant of the *pipeline*: it is invisible to the content
* box, to the fit residual and to the whole-pixel refinement (a resampling
* difference is not an offset), and **no key an author writes can move it**.
*
* It was measured twice by hand before it was measured here — rung 3 read MAE
* 6.13/6.01 from the loose art against 2.25/2.30 through the supplied pack, and
* rung 5's re-climb found the same mechanism — so about two thirds of those
* figures was texture. Nothing in the report said so, which is the part that
* matters: a run that does not know it spends its budget hunting a rig that is
* already right, and two runs whose atlases differ cannot be compared at all.
*
* ## The three figures, and what relates them
*
* Everything here is measured over **the same pixels** `mae` and `maeReference`
* average, in the same box, from the same pose — the substitution changes texels
* and nothing else (`substituteTexture`). Writing `a` for the candidate's own
* render, `f` for its substituted render and `b` for the reference frame:
*
* - `mae` is `mean|a − b|` and is **unchanged** by any of this;
* - `floor` is `mean|a − f|` — the resampling on its own. Same geometry, same
* pose, same rasteriser: there is no rig content in it at all;
* - `aboveFloor` is `mean|f − b|` — the figure with the texture difference taken
* out, which is what the hand-run diagnostic was reporting.
*
* ⭐ **The floor bounds the claim rather than subtracting from it.** Absolute
* errors do not add, so `mae = floor + aboveFloor` would be false. What is true,
* per pixel and therefore of the means, is the triangle inequality:
*
* |mae − aboveFloor| ≤ floor
*
* so the floor is an upper bound on how much of the MAE the texture can explain,
* and `mae − aboveFloor` is what it actually explained on these frames. A
* `floor` near zero is a proof that the texture is *not* the story here; a
* `floor` that accounts for most of `mae` says the rest of the report is being
* read at the wrong scale.
*
* ⚠️ **`aboveFloor` is not a better number and must not be recorded as one.** The
* artifact under measurement ships its own atlas, so `mae` is the figure that
* belongs in a record and this is the explanation of where it went. And the
* coarser texture **loses** detail the finer one has: on rung 3 a one-pixel move
* the reference makes stops being visible through the half-scale pack, so a
* substituted run can miss a frame-change disagreement the graded run reports.
*/
export interface TextureFloor {
/** `mean|own − substituted|` over the union alpha — the resampling alone. */
floor: number;
/** `mean|substituted − reference|` over the same pixels — the MAE without it. */
aboveFloor: number;
/** The same two over the REFERENCE's own drawn pixels — `maeReference`'s denominator. */
floorReference: number;
aboveFloorReference: number;
}
export interface FrameCheck {
index: number;
/** The reference PNG, so a worst-frame line is directly openable. */
file: string;
/** Mean absolute RGB difference over the union alpha, 0..255. */
mae: number;
/**
* The same total difference over the REFERENCE's own drawn pixels alone.
*
* ⭐ The figure to optimise against, and the reason is the denominator. `mae`
* divides by the pixels either side drew, and the candidate owns half of that:
* drawing something large and mostly transparent adds many cheap pixels to the
* union and the *mean falls*, so an optimiser can buy a better score by growing
* (issue #119 — a muzzle flare walked its own scale to 13x doing exactly this).
* This denominator is the reference's, which nothing the candidate does can
* move, so the only way down is to draw the reference's picture.
*
* ⚠️ Not bounded by 255, and deliberately: a candidate that draws far more than
* the reference has more absolute error than the reference has pixels to carry
* it, and the figure says so instead of saturating.
*
* `mae` is still the right figure for comparing two builds of the same rig,
* where the union is near enough the same on both sides.
*/
maeReference: number;
/**
* The same difference averaged over the WHOLE frame, background included.
*
* Reported beside `mae` and never instead of it. Most of a frame is background
* on both sides, so this number is small for every candidate and the gap
* between a good one and a bad one is smaller still — but it is the number an
* ad-hoc re-render check naturally computes, so a run comparing itself against
* an older log needs it to be able to.
*/
maeFrame: number;
unionPixels: number;
candidatePixels: number;
referencePixels: number;
components: number;
/** Components no slot reached — something in the shot the candidate has not drawn. */
unmatchedComponents: number;
worstSlot: string | null;
worstDrift: number | null;
/** How many slots got an attributable drift, out of how many drew anything. */
attributed: number;
drawn: number;
slots: SlotTrack[];
/** This frame against the one before it, on each side — `null` unless adjacent. */
change: FrameChange | null;
/** What of this frame's difference is texture — `null` without `--texture-from`. */
textureFloor: TextureFloor | null;
}
/**
* One bone chain's slice of a set — the row an author reads before deciding what
* to re-key.
*
* The chains come from the CANDIDATE's bone tree (`src/chains.ts` owns the rule
* and the reasoning); the reference stays pixels, so this is a decomposition of
* your own figure and never a reading of the answer.
*/
export interface ChainCheck {
/** The chain, named as `src/chains.ts` names it. */
chain: string;
/** How many slots it owns. */
slots: number;
/** How many of those drew anything in at least one compared frame. */
drewSlots: number;
/** The worst attributable slot drift anywhere in it, in frame pixels. */
worstDrift: number;
/** Which slot that was, and in which frame — `null`/`-1` when none was attributable. */
worstDriftSlot: string | null;
worstDriftFrame: number;
/** The mean of every attributable slot drift in it, over `driftSamples` of them. */
meanDrift: number;
driftSamples: number;
/** How many frames contributed at least one of those samples. */
driftFrames: number;
/**
* The absolute RGB difference attributed to this chain, summed over the
* REFERENCE's own drawn pixels — never over the union.
*
* ⭐ The denominator lesson from issue #119, applied to a share. A reference
* pixel goes to the chain whose ink is nearest to it, so the chains partition
* the reference's drawn pixels and the shares add up to the whole. What the
* candidate controls is only *which* chain a pixel lands in, and growing a
* chain's ink pulls MORE of the reference's pixels — and their error — into it.
* There is no move here that makes a chain look better by drawing more, which is
* exactly what the union MAE could not say.
*/
error: number;
/** How many reference-drawn pixels it took, summed over frames. */
referencePixels: number;
/**
* `error` per pixel it took — the MAE *inside* this chain, 0..255.
*
* Printed beside the share because the share alone confounds being wrong with
* being big: spineboy's head, goggles, eye and mouth are one chain covering a
* lot of the figure, so it can carry a third of the error at a per-pixel figure
* below the run's own mean. The share says where the error IS; this says whether
* the chain is actually worse than the rest of the figure.
*/
mae: number;
/** `error` over the set's own total, 0..1 — see `AnimationCheck.chainDenominator`. */
maeShare: number;
}
/**
* The whole shot against the contact sheet beside it — the frames `check` has no
* file for.
*
* ## Why a sheet is a frame set and not a picture of one
*
* A long shot does not commit 311 near-duplicate PNGs. It commits a couple of
* stills and folds every sampled frame into one `contact.png`, and `check` used to
* read the two stills, say `2 compared`, and mean it — an honest number with a hole
* behind it: nothing whatever was measured about the other 309 frames, so a clean
* table said nothing about the shot (issue #36). A sheet is the same thing a frame
* is, at a smaller scale and with a frame number burned into the corner, and
* reading it reads no reference skeleton.
*
* So the candidate is sampled at the set's own rate, rendered into the same world
* box the set was framed in at the sheet's own scale, and each frame is compared
* against its own tile. The prototype this replaces was written in-run by the
* second rung-2 attempt, which found with it what the two-still table could not:
* flat MAE 4.85–4.95 over all 1,244 frames of four shots, no spikes — evidence
* that trajectories, ring rates and attachment swaps land where and when they
* should.
*
* ## What it deliberately does not measure: the per-frame change
*
* The tiles are adjacent, so `FrameChange` looks reachable here, and it is not:
* `CHANGE_EXCESS` is two dozen pixels at frame scale, and a quarter-scale tile has
* a sixteenth of the pixels to move. The thresholds would have to be re-derived
* against sheets before that column could mean anything, and a figure printed at
* the wrong scale is worse than one not printed. MAE only, and the report says so.
*/
export interface SheetCheck {
/** The sheet itself, so a worst-tile line is openable. */
file: string;
/** The grid, measured off the sheet — see `sheetGeometry`. */
columns: number;
tileWidth: number;
tileHeight: number;
/** Frame pixels per tile pixel: how much smaller a tile is than a frame. */
tileScale: number;
/** How many tiles the sheet holds, and how many the candidate could be compared on. */
tiles: number;
compared: number;
/** Mean and worst over the tiles, in the same two denominators the frames use. */
meanMae: number;
meanMaeReference: number;
worstMae: number;
worstTile: number;
/** The worst tiles by MAE, worst first — at most `WORST_FRAMES` of them. */
worst: Array<{ index: number; mae: number }>;
}
export interface AnimationCheck {
dir: string;
/** The animation the frames show, per the sidecar. */
animation: string | null;
/** The candidate animation played against it. */
candidateAnimation: string | null;
fps: number;
referenceFrames: number;
candidateFrames: number;
compared: number;
meanMae: number;
/** Mean of the per-frame reference-denominator MAE — see `FrameCheck.maeReference`. */
meanMaeReference: number;
/**
* How much this set draws, against how much the reference draws: the mean over
* its frames of `candidatePixels / referencePixels`.
*
* 1 means the two shots put ink on the same amount of the frame. Above 1 the
* candidate is drawing more than the reference does, which is the move that
* makes the union MAE cheaper — see `OVERDRAW_RATIO`, which is where the
* threshold and the corpus it came from are written down.
*/
drawnRatio: number;
/** Mean of the per-frame whole-frame MAE — see `FrameCheck.maeFrame`. */
meanMaeFrame: number;
/**
* The mean over this set's frames of each frame's own decomposition — see
* `TextureFloor`. `null` without `--texture-from`.
*/
textureFloor: TextureFloor | null;
worstMae: number;
worstMaeFrame: number;
worstDrift: number;
worstDriftFrame: number;
worstDriftSlot: string | null;
/** Frames in which no slot at all could be attributed — the drift's denominator. */
framesWithoutDrift: number;
/** Adjacent frame pairs a frame-to-frame change could be measured across. */
changePairs: number;
/** How many of those the candidate's own change disagrees with the reference's. */
changeDisagreements: number;
/** The widest of those disagreements, and `-1` when there is none. */
worstChangeFrame: number;
/**
* This set, broken down by the candidate's own bone chains — see `ChainCheck`.
*
* Chains that own no slot at all are left out: they have nothing to attribute.
* They are still in `CheckReport.chains`, so the roster stays a complete account
* of where every bone went.
*/
chains: ChainCheck[];
/**
* The set's whole difference over the reference's own drawn pixels — the
* denominator every `ChainCheck.maeShare` divides by.
*
* The same numerator `meanMaeReference` averages, kept as a total because a
* share needs the total and a mean has already divided it away.
*/
chainDenominator: number;
/** The part of it no chain could take, because the candidate drew nothing at all. */
unattributedError: number;
frames: FrameCheck[];
/**
* The box THIS set's candidate frames were rendered into.
*
* Under the default per-shot scope every set carries its own, and they are
* different boxes; under `--framing shared` they are all the same one. Either
* way it is here rather than only at the top of the report, because it is
* upstream of every number in this row.
*/
viewport: Framing;
/** How this set's box was chosen — see `FramingSource`. */
framing: FramingHow;
/** Where this set's drawn pixels ended up against the reference's. */
framingFit: FramingReport | null;
/**
* What the declared-box probe measured for this set, taken or not — see
* `DeclaredBoxProbe`. Reported either way, because "refused, and by this much,
* on this ground" is the fact issue #194 found missing.
*/
declaredBox: DeclaredBoxProbe | null;
/**
* The whole shot against the contact sheet, when the set ships one and does not
* ship every frame — see `SheetCheck`. `null` when there is nothing to add: no
* sheet, or every sampled frame already on disk as a frame of its own.
*/
sheet: SheetCheck | null;
notes: string[];
}
/** A world box and the pixel grid it was drawn into. */
export interface Framing {
x: number;
y: number;
width: number;
height: number;
/** Frame pixels per world unit. */
scale: number;
pixelWidth: number;
pixelHeight: number;
}
/**
* How the world box the candidate was rendered into was arrived at.
*
* - `derived` — fitted to the candidate's own drawn pixels, from a start taken
* from its posed geometry. The default, and the only option without a sidecar.
* - `declared` — the box `frames.json` records, reached from that same box and
* kept because the candidate's own pixels land on the reference's in it. See
* `frameByDeclaredBox` for why a measured coincidence licenses it.
* - `pinned` — `--viewport`, which is a claim by the author and is not checked.
*/
export type FramingSource = 'derived' | 'declared' | 'pinned';
/** The same three, named for the report line rather than for the code path. */
export type FramingHow = 'candidate-pixels' | 'frames-viewport' | 'viewport-flag';
/**
* Why `frames.json`'s own box was taken for a set, or was not — and the two
* numbers that decided it.
*
* ## 🎯 The clause it exists to state, and the case that made it necessary
*
* Taking the frames' own box is the single largest thing `check` decides on its
* own: it is the difference between measuring in the box the frames were drawn at
* and measuring in a fit of it, and `frameByDeclaredBox` records the MAE that
* costs. The decision used to be reported only by its *outcome* — one word on the
* `framed to` line — so a set that was refused said nothing about how far it
* missed by or on which of the two grounds.
*
* That is issue #194. Rung 7's candidate has its setup box on the reference's to
* the pixel and is refused on all twelve sets, because the test is on **extent**
* and its union content box is 15.4 px narrower at the extremes. The refusal cost
* every set 0.7–1.3 MAE against the declared box, and the run had no way to say
* whether that was a coordinate error or a silhouette — the two readings the
* numbers here separate. See `EXTENT_SPREAD` for the clause that now settles it.
*/
export interface DeclaredBoxProbe {
/**
* The correction a fit at the declared box asks for, in frame pixels — the
* worst displacement over the candidate's own content box corners.
*/
distance: number;
/** What that same fit leaves over across every edge of every frame, in px rms. */
rms: number;
/** How far the correction was allowed to reach — see `EXTENT_SPREAD_REACH`. */
reach: number;
/** How many frames the probe was made from. */
frames: number;
/** Was the box taken for this set? */
taken: boolean;
/**
* Which clause decided it.
*
* - `coincident` — the correction is under `COINCIDENT_PIXELS`. Taken; the
* original clause, and unchanged.
* - `extent-spread` — the correction is larger than that but reaches no further
* than `reach`, and `rms` says one similarity still cannot put the two shots on
* each other. Both halves are needed — see `EXTENT_SPREAD_REACH`, which records
* the fixture that proves it. Taken.
* - `coordinates` — the correction reaches too far, or the fit explains it to
* within a pixel, so the two shots are in different coordinates (a different
* origin, or different units). Refused, and framed by the fitted path where the
* blindness to units lives.
* - `no-pixels` — the candidate drew nothing at all in the declared box, which
* is the loudest possible "not these coordinates". Refused.
*/
clause: 'coincident' | 'extent-spread' | 'coordinates' | 'no-pixels';
}
/**
* Whether the framing is decided per frame set, or once across every set.
*
* ## What `per-shot` actually scopes, and why only that
*
* A framing is decided over the frames it is measured on, so pointing `check` at a
* skeleton root used to decide ONE for every set under it — and one badly-framed
* shot was then paid for by all the others. Measured on the spineboy rung, 8 shots
* and 147 frames: `idle` read **41.59** MAE at the root against the **18.77** it
* reads on its own frames, with not one key different (issue #100).
*
* `per-shot` moves exactly one decision into the set: **whether the box
* `frames.json` records is this set's box too.** That decision is a measurement
* with no floor — either the set's own drawn pixels land in the declared box or
* they do not — and over the union one shot that does not can put the pooled
* correction over `COINCIDENT_PIXELS` and take every other shot down with it. Per
* set, the ones that qualify read exactly what pinning by hand reads.
*
* ⚠️ It does NOT fit a separate chain per set, and that is a measured decision
* rather than a simplification. Per-set FITTING is worse: `fitFraming` registers
* extent, extent is not alignment, and one shot's frames do not constrain that
* enough — spineboy's `hit` reads 92.36 fitted on its own against 60.59 in the
* shared fit, and its two-frame `shoot@30fps` set reads 101.94 against 42.98. So a
* set that cannot take the declared box is measured in the shared framing, where
* every frame in the run constrains the answer.
*
* `shared` is the old behaviour, and it answers one question well: *does a single
* box serve every set?* The report prints that fit either way — see
* `CheckReport.sharedFraming`.
*
* ⚠️ The two are different measurements and their absolute numbers are not
* comparable across builds. The report says which one it did.
*/
export type FramingScope = 'per-shot' | 'shared';
/** What the framing pass concluded, and how sure it is of it. */
export interface FramingReport {
/**
* The residual fit measured at the box the framing chain chose.
*
* ⚠️ **Before** the MAE-refined pass below it, when that pass moved the box —
* and deliberately, because the two answer different questions and both are
* worth printing: this says how far the two *extents* were from registering,
* `refinement` says how far the *pictures* were from each other after that. Its
* `settled` / `agrees` / `cycled` words describe the chain that reached the box,
* which is a fact about the chain and does not change afterwards.
*/
fit: FramingFit;
/** How many render/measure/correct passes ran. */
passes: number;
/** Did the correction converge to the identity, or was it still moving? */
settled: boolean;
/** How the box was chosen — see `FramingSource`. */
source: FramingSource;
/**
* Did the correction fall into a repeating orbit instead of converging?
*
* When it did, `settled` is false and **more passes cannot help**: the loop is
* re-measuring states it has already been in. That is a fact about the fit
* having no fixed point on this shot, not about the pass budget, and the two
* used to print the same warning.
*/
cycled: boolean;
/**
* Do the two content boxes agree, at the viewport that was used?
*
* `fitDistance` under `COINCIDENT_PIXELS`. This is what separates "the loop
* fell short of its own target and the two shots are nevertheless in the same
* place" from "the loop fell short because these are different shapes" — the
* first is the tool's floor and the second is a finding.
*/
agrees: boolean;
/**
* Whether the fit was APPLIED or only measured.
*
* `--viewport` pins the box, so the fit is reported and not used — which is the
* most useful thing about pinning it: it separates "my keys are wrong" from
* "my framing is wrong", and those are two different repairs.
*/
applied: boolean;
/**
* The same two content boxes in **world units**, when the sidecar records the
* reference's scale.
*
* ⭐ This is the one place a difference of pure scale can show up at all. The
* framing deliberately absorbs it — a candidate is authored in its own
* coordinates, so "twice as big in world units" is a choice of units and not an
* error, and a tool that reported it as one would be reporting the thing it was
* built to be blind to. But an author who measured the shot off the frames IS
* working in the frames' units, and for them these two numbers are directly
* comparable and a 2 % disagreement is a real finding. So it is printed, with
* what it does and does not mean attached.
*/
units: { candidate: Extent; reference: Extent; ratio: number } | null;
/**
* What the MAE-refined final pass found, and whether it moved the box.
*
* `null` when nothing could be searched (no frame with reference ink). See
* `FramingRefinement`.
*/
refinement: FramingRefinement | null;
}
/**
* The final framing pass, which asks a different question from every pass above
* it: not *do the two extents register?* but *is a constant pixel of this set's
* MAE a framing offset?*
*
* ## Why it exists, and why it is the last thing that happens
*
* Issue #146 measured the answer on the spineboy candidates: a **constant**
* translation of one or two pixels is worth 12 % of `death`'s headline
* reference-denominator MAE and up to 30 % of a fitted set's, while what is left
* after it is taken out is per-frame and small. That is `fitFraming`'s documented
* "extent is not alignment" floor arriving as a tenth of the number an author is
* reading as motion. `OffsetScan` searches whole-pixel offsets against the MAE
* itself, so it cannot walk off the answer the way the extent refinement measured
* and rejected in `frameByDeclaredBox` did — the figure it minimises is the figure
* the report prints.
*
* ## ⭐ Where it is allowed to move the box, and where it only reports
*
* **A fitted box is an estimate and gets corrected. An exact box does not.**
*
* - `derived` — the box came from a fit of extents, so a constant pixel in it is
* the estimator's own floor. The offset is applied.
* - `declared` — `frames.json`'s box is not an estimate of where the frames were
* drawn, it is where they were drawn (`frameByDeclaredBox`). A constant pixel
* *there* is the candidate's own figure sitting a pixel off inside the right
* box, which is a finding an author can act on and the framing must not absorb.
* Searched, reported, never applied — and measured: over the committed corpus
* every declared-box set's best offset is the exact identity, so this branch
* has cost nothing so far and would only ever fire on a real offset.
* - `pinned` — `--viewport` is the author's claim about their own coordinates and
* nothing here overrides it, exactly as the fit above is measured and not
* applied.
*/
export interface FramingRefinement {
/** The best whole-pixel offset found, in frame pixels. `0, 0` means none was. */
dx: number;
dy: number;
/** Was it applied to the box the set was measured in? */
applied: boolean;
/** The set's mean reference-denominator MAE at the box the framing chose... */
before: number;
/** ...and at `dx, dy`, which is the same figure with the constant taken out. */
after: number;
/** How far the search looked, and how many frames it pooled. */
radius: number;
frames: number;
/**
* Why the offset was not applied — `null` when it was.
*
* `identity` is the answer this pass gives on a set whose framing is already
* where the picture is, and it is a measurement rather than a default: the
* search ran over the whole window and the identity won it.
*/
declined: 'identity' | 'below-threshold' | 'box-is-exact' | 'pinned' | null;
}
/** A width and a height in world units. */
export interface Extent {
width: number;
height: number;
}
/** The substitution `--texture-from` made, and what it could not reach. */
export interface TextureFromReport {
/** The atlas whose texels stood in, as it was named on the command line. */
atlas: string;
/** Every `scale:` its text declares — the line that says a pack is coarser. */
scales: number[];
/**
* The same for the CANDIDATE's own atlas, so the two are read side by side —
* `null` when the candidate has no atlas beside it to read them off (issue
* #1020), which is not the same claim as declaring none.
*/
candidateScales: number[] | null;
/**
* Regions the substituting atlas does not have, or the candidate packs rotated
* so its own corner order cannot be inverted — see `artUvsOf`. Those pieces kept
* their own texture, so a non-empty list means the floor below is a MIXTURE and
* is not the whole of the resampling.
*/
unmatched: string[];
}
export interface CheckReport {
candidate: { skeleton: string; atlas: string };
/**
* Which implementation of the posing seam posed the CANDIDATE, and why
* (issue #968): `core` — rigc's own, reading the `skeleton.model.json` a
* build writes beside the pair — or `spine` (spine-core), with the reason the
* core was not used. `note` is `render`'s `poser` line, word for word.
*
* In the report because a figure is only readable beside what produced it:
* the reference side is pixels either way, and a report that did not say
* which poser drew the candidate would be a number with two possible
* subjects. The two are measured to give the same report on every tree row;
* this field is what lets a reader see which one this is.
*/
poser: { name: PoserName; note: string };
framesDir: string;
framesRoot: string;
/**
* The skin the CANDIDATE was posed under, or `null` for no skin at all.
*
* ⭐ In the report rather than only in the run's arguments because a figure is
* only readable beside what produced it: on a multi-skin rig the same
* candidate and the same frames give a different number per skin, and a
* `check.json` that did not say which one it was is a number with no subject
* (issue #571).
*/
skin: string | null;
/**
* The skin `frames.json` records for the reference frames, or `null`.
*
* `null` covers two facts that are the same on disk — the frames set no skin,
* and the frames were rendered before the field existed — which is why a
* mismatch against it is refused and an absence is only noted. See `notes`.
*/
referenceSkin: string | null;
/** One framing per set, or one across every set — see `FramingScope`. */
framingScope: FramingScope;
/**
* How the candidate's own world box was chosen, when ONE box covers the run.
*
* `null` under a per-shot scope with more than one set compared: there is no
* single answer then, and each `AnimationCheck` carries its own. A run that
* compared exactly one set fills these in whatever the scope, because for one
* set the two scopes are the same measurement.
*/
framing: FramingHow | null;
/** The box the CANDIDATE was rendered into, at the reference's pixel size. */
viewport: Framing | null;
/** Where the candidate's drawn pixels ended up against the reference's. */
framingFit: FramingReport | null;
/**
* The declared-box probe over every set pooled — see `DeclaredBoxProbe`.
*
* The run-level answer, which is the one a shared scope is measured by. Under a
* per-shot scope each `AnimationCheck` carries its own and that is the one that
* decided its framing; this stays reported because it is the figure the shared
* box on the line beside it came from.
*/
declaredBox: DeclaredBoxProbe | null;
/**
* The framing ONE shared box gives across every set compared.
*
* Under `per-shot` it is both reported and used: every set that cannot take the
* frames' own declared box is measured in it. It is also the figure that says
* *why* a whole-root run is a different measurement — a set that reads well in
* the declared box and badly here is a set the old whole-root run was measuring
* through somebody else's silhouette, which is what `idle` reading 41.59 against
* 18.77 was (issue #100).
*
* `null` when the scope is already shared — `framingFit` is that number then —
* and when only one set was compared, where the two scopes are the same thing.
*/
sharedFraming: FramingReport | null;
/**
* The box the REFERENCE was rendered into, when the sidecar records one.
*
* Informational: the two skeletons do not share a coordinate system, so these
* numbers are not comparable term by term. The pixel dimensions are — they are
* the same grid — and a difference between them is the diagnostic.
*/
referenceViewport: Framing | null;
background: RGBA;
/**
* The candidate's bone tree, cut into chains — the roster the report prints.
*
* Printed rather than assumed, because a decomposition an author has to guess at
* is one they will read wrong: the table says `front-thigh` and the roster says
* which bones and which slots that name covers. `src/chains.ts` owns the rule.
*/
chains: BoneChain[];
animations: AnimationCheck[];
/** The texture-only substitution, when one was asked for — `null` otherwise. */
textureFrom: TextureFromReport | null;
notes: string[];
}
export interface CheckOptions {
skeletonText: string;
/**
* The candidate's atlas, or `null` when there is no file (issue #1020): a
* rigc build the core poses from a `rigc-compiled/2` document is drawn
* without one, and anything else is refused naming the file
* (`CandidateAtlasError`).
*/
atlasText: string | null;
/** Where the atlas's page paths resolve from. */
atlasDir: string;
framesDir: string;
/** Labels for the report; the texts above are what is actually read. */
labels?: { skeleton: string; atlas: string };
/** Only used when there is no sidecar to take the rate from. */
fps?: number;
/**
* Pin the candidate's world box `x,y,width,height` instead of deriving it.
*
* Two uses, and the second is the one an authoring loop wants. It is the escape
* hatch when the derivation cannot work — a candidate deliberately missing a
* part has a different content box by construction, and pinning lets the rest
* of the shot still be measured. And it is the way to hold the framing FIXED
* across builds: the framing line is still reported, so a pinned run separates
* "my keys moved" from "my framing moved" without either hiding the other.
*/
viewport?: { x: number; y: number; width: number; height: number };
/** Play this candidate animation against the frames, when the names differ. */
as?: string;
/**
* Pose the candidate under this skin — see `PoseOptions.skin` (issue #571).
*
* Absent sets no skin, which resolves every slot through the default skin
* alone: on a multi-skin rig that draws none of the art the named skins carry,
* and a `check` of it compares blank against blank and reads 0.0000. A name
* the candidate does not declare is refused with the ones it does, and the
* reference frames' own recorded skin is checked against this — see the
* `referenceSkin` field of `CheckReport` for what an absent record means.
*/
skin?: string;
/**
* Fit one framing per frame set, or one across every set compared.
*
* Defaults to `per-shot`. See `FramingScope` for what the choice costs and why
* this is the default; it has no effect when only one set is compared, and none
* when `viewport` pins the box (a pin is a claim about the candidate's own
* coordinates, and those do not change between shots).
*/
framing?: FramingScope;
/**
* Also measure the run through **this atlas's texels**, keeping the candidate's
* own geometry, and attribute the difference — see `TextureFloor`.
*
* ⚠️ Not the same thing as pointing `atlasText` at another atlas, which loads
* the skeleton against it and moves the geometry too (issue #199). Nothing about
* the graded figures changes when this is set: the framing is decided, and every
* existing measure taken, from the candidate's own atlas exactly as before, and
* 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;
/**
* The files `skeletonText` and `atlasText` were read from — what chooses the
* candidate's poser, exactly as `render` chooses its own (`candidatePosers`,
* issue #968): rigc's core when the `skeleton.model.json` beside the skeleton
* records these skeleton bytes, spine-core otherwise. They must be the files
* the texts came from; `cli.ts` reads both from them. Absent, the candidate
* is posed through spine-core and the report says why.
*/
candidatePaths?: { skeleton: string; atlas: string };
/** `--poser`: force one implementation — see `candidatePosers`. `core` on an input that cannot carry it throws `PoserChoiceError`. */
poser?: PoserName;
/**
* What builds the core poser — `candidatePosers`' own `make`. The suite's
* `CH01` passes a planted copy, and nothing else passes any.
*/
makeCorePoser?: MakeCorePoser;
}
/** Why a candidate handed to `check` as text alone is posed through spine-core — there is no directory to find a model document in. */
const UNPLACED_CANDIDATE = 'the candidate was handed to check as text, with no path to find a skeleton.model.json beside';
// ---------------------------------------------------------------------------
/**
* Compare a candidate against a set of reference frames.
*
* ## 🧭 Why the candidate is framed by its own pixels
*
* The obvious move — render the candidate into the world box the sidecar
* records — is wrong, and wrong in a way that reads as a catastrophic failure
* rather than as a mistake: on rung 3's honest candidate it reports MAE 146/255,
* because that candidate put its origin on the pendulum's pivot and the
* reference put its own somewhere else entirely. **A candidate is authored in
* its own coordinate system, and under the ladder's honesty rule it could not be
* authored in any other** — the reference's origin is in the file the author is
* not allowed to open.
*
* So the candidate is framed by its own content. What changed (issue #34) is what
* "content" means. It used to be the union of the **posed quad corners**, and a
* region attachment's quad extends past its own artwork wherever the art is
* transparent, so an outermost corner routinely sat where no pixel was. Combined
* with a mapping that read only `minX`, `maxY` and the long side, that let one
* corner of one quad in one frame set the scale for a whole run: rung 5's first
* correct build reported **MAE 39.00 instead of 4.35** on a box 0.93 % narrow, and
* rung 4 watched a rotation the pixels cannot see move the reported MAE from 27.6
* to 84.9 by swinging one corner in and out of the box.
*
* Now both sides are measured the same way, **on drawn pixels**:
*
* 1. render the candidate at the frames' own rate and grid, and take the content
* box of what it actually draws (`src/framing.ts`);
* 2. take the reference's content box off the PNGs with the same predicate;
* 3. fit the similarity transform — uniform scale plus translation, least squares
* over **both** width and height — that carries one onto the other, and render
* through it. No single corner can set the scale, and an invisible margin
* cannot move it at all.
*
* The pass repeats until the correction is the identity, because the correction
* changes the pixels it was measured on.
*
* ⚠️ What this is still not blind to: a candidate that is missing a part, or has
* an extra one, genuinely has a different content box, and one uniform scale
* cannot make two different shapes agree. That is no longer silently spent on the
* framing — it is reported as the fit's **residual** and its aspect error, which
* is the number to read before reading a drift. `--viewport` pins the box outright
* when even that is not enough.
*/
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[] = [];
// Which implementation poses the candidate (issue #968), chosen once for the
// whole run — every set, the setup pose and the non-finite sentence — so no
// two figures in one report can come from two posers: `candidatePaths` over
// the candidate's files, as `render` chooses, and spine-core alone when it
// was handed texts only. Chosen BEFORE anything is read off the candidate
// (issue #1014), so a rigc build the core poses reads its names, its stage,
// its bone tree and its pages without loading spine-core.
const { choice, facts, pages } = loadCandidate(
{ skeletonText: options.skeletonText, atlasText: options.atlasText, atlasDir: options.atlasDir, label: options.labels?.skeleton ?? 'the candidate' },
options.candidatePaths ?? null,
options.poser,
{ ...(options.makeCorePoser === undefined ? {} : { make: options.makeCorePoser }), unplaced: UNPLACED_CANDIDATE },
);
const posable: Pick = { pages };
// A candidate that declares no stage is framed exactly as one that does,
// because no framing here reads a stage: the world box is fitted from what the
// candidate draws. Said on the one candidate where a reader can ask what box
// stood in for the absent one (issue #714) — `SkeletonJson` copies the header
// fields across unconditionally (`SkeletonJson.js:70-73`), so an omitted
// extent is `undefined` there, not 0, and the header says the same.
if (!facts.declaresStage) {
notes.push(
'the candidate declares no stage (no `skeleton.width`/`height`), and nothing stands in for one: its world ' +
'box is fitted from the pixels it draws, as it is for every candidate, so the absence moves no figure below.',
);
}
// The substitution is loaded before anything is posed, because posing has to
// record each piece's original-art UVs for it and that is the one thing about
// this measure that cannot be added afterwards — see `PieceTexture`.
//
// Read by rigc's own atlas reader when the core poses the candidate, and by
// spine-core's when the runtime does (issue #1020, `SubstitutionReader`): a
// rigc build's `--texture-from` reads nothing through the runtime, and an
// export's reading is the one it always had.
const substitution = options.textureFrom
? textureSubstitutionFromText(options.textureFrom.atlasText, options.textureFrom.atlasDir, choice.core === null ? 'spine' : 'rigc')
: null;
// The skin is refused here rather than deeper in the sampler, for the reason
// every miss in this project is refused where the names are: the skeleton is
// open on this line and the alternatives can be listed.
if (options.skin !== undefined && !facts.skins.includes(options.skin)) {
throw new CheckError(
`the candidate declares no skin ${JSON.stringify(options.skin)}; it declares [${
facts.skins.join(', ') || 'none'
}]`,
);
}
// `--poser core` on an input that cannot carry it is refused here, before
// anything is posed.
refuseUnchosen(choice);
const poseOptions: PoseOptions | undefined =
substitution || options.skin !== undefined
? { ...(substitution ? { texture: true } : {}), ...(options.skin === undefined ? {} : { skin: options.skin }) }
: undefined;
let background: RGBA;
let sets: FrameSet[];
let pixelWidth: number;
let pixelHeight: number;
let referenceViewport: Framing | null = null;
if (located.sidecar) {
const s = located.sidecar;
background = s.background;
pixelWidth = s.viewport.pixelWidth;
pixelHeight = s.viewport.pixelHeight;
referenceViewport = { ...s.viewport };
sets = located.only.length > 0 ? s.sets.filter((set) => located.only.includes(set.dir)) : s.sets;
if (options.fps !== undefined && sets.some((set) => set.fps !== options.fps)) {
throw new CheckError(
`--fps ${options.fps} disagrees with ${FRAMES_SIDECAR}, which records ` +
`${[...new Set(sets.map((set) => set.fps))].join(', ')} fps. The frames' own rate is the one they were ` +
'rendered at; drop --fps, or point --frames at the set you meant',
);
}
} else {
// No sidecar: the pixel grid comes from the frames themselves, the rate from
// --fps, and the background from this build's default — and the report says
// so rather than letting a default look like a measurement.
const dir = basename(located.root);
const parent = dirname(located.root);
const disk = framesOnDisk(parent, dir);
if (disk.length === 0) throw new CheckError(`no f####.png frames in ${located.root}`);
const first = readPlateFrom(located.root, disk[0].file);
pixelWidth = first.width;
pixelHeight = first.height;
background = BACKGROUND;
const fps = options.fps ?? PROTOCOL_FPS;
const animation = dir.replace(/@\d+(\.\d+)?fps$/, '');
sets = [
{
dir,
animation: facts.animations.length === 0 ? null : animation,
fps,
sampled: disk[disk.length - 1].index + 1,
written: disk.length,
stride: 1,
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. 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(', ')}; 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 .',
);
// The set root is the animation directory itself here, so reads resolve
// against its parent the way a sidecar layout does.
located.root = parent;
located.only = [dir];
}
if (sets.length === 0) throw new CheckError(`no frame set to compare in ${options.framesDir}`);
// --- the skin the frames were rendered under, against the one asked for ----
//
// ⭐ The asymmetry is the honest part (issue #571). A sidecar that RECORDS a
// skin is a claim, and a claim that disagrees is refused by name; a sidecar
// that records none is making no claim at all — it either set no skin or was
// written before the field existed, and those are the same bytes — so the run
// proceeds and says out loud that nothing checked it. Inventing a refusal out
// of an absent field would refuse every frame set in this repository.
const referenceSkin = located.sidecar?.skin ?? null;
if (referenceSkin !== null && referenceSkin !== options.skin) {
throw new CheckError(
`${FRAMES_SIDECAR} records that these frames were rendered under skin ${JSON.stringify(referenceSkin)}, and ` +
`this run poses the candidate ${
options.skin === undefined
? 'under no skin at all (the default skin alone)'
: `under skin ${JSON.stringify(options.skin)}`
}. Two skins are two different pictures of one rig, so the comparison would be a number about the ` +
`difference between them. Pass --skin ${JSON.stringify(referenceSkin)}, or render the reference frames ` +
`${options.skin === undefined ? 'with no --skin' : `with --skin ${JSON.stringify(options.skin)}`}.`,
);
}
// A frame set drawn under `render --environment` (issue #1416) is a picture of the rig in a world `check` does not
// pose: it poses the candidate under the runtime's own wind and gravity, so the score would be a number about the
// difference between two worlds. Refused by name, as a subset is, rather than scored.
const referenceEnvironment = located.sidecar?.environment;
if (referenceEnvironment !== undefined) {
throw new CheckError(
`${FRAMES_SIDECAR} records that these frames were rendered under an environment schedule (\`rigc render ` +
`--environment\`, ${Array.isArray(referenceEnvironment) ? referenceEnvironment.length : 0} step(s)), and check poses the candidate ` +
"under none — the runtime's own wind [1, 0] and gravity [0, 1] — so the comparison would be a number about the " +
'difference between two worlds. Render the reference frames without --environment.',
);
}
if (located.sidecar?.physicsMode === 'off') {
throw new CheckError('frames.json records physicsMode off, while check poses the candidate with physics on. Render the reference with --physics on.');
}
// A frame set drawn after a pre-roll (`render --preroll`, issue #1684) shows the physics warm; check poses the
// candidate from rest, so the score would be a number about the difference between a warm loop and a cold one.
const referencePreroll = located.sidecar?.preroll;
if (referencePreroll !== undefined) {
throw new CheckError(
`${FRAMES_SIDECAR} records that these frames were rendered after a pre-roll (\`rigc render --preroll ${String(referencePreroll)}\`: ` +
'that many loops walked on a looping track before the loop recorded, the physics carried), and check poses the candidate ' +
'from rest — so the comparison would be a number about the difference between a warm loop and a cold one. ' +
'Render the reference frames without --preroll.',
);
}
if (referenceSkin === null && options.skin !== undefined) {
notes.push(
`the candidate is posed under skin ${JSON.stringify(options.skin)} and the reference frames record no skin ` +
`at all, so nothing here could check that they are the same picture. A frame set rendered by \`rigc ` +
`render --skin\` since #571 carries the name in ${FRAMES_SIDECAR} and this run would have compared it.`,
);
}
// Pose every set once. Its frames are wanted twice — to frame the candidate and
// to compare it — and posing twice is both slower and a chance for the framing
// and the comparison to disagree about what they measured.
//
// Posed through the chosen poser, and ALL of it inside one `throughPoser`
// call: a core refusal partway (`CoreInputError` — a concave clip, a
// non-finite vertex) re-poses every set on spine-core rather than leaving a
// report whose sets were posed by two implementations. The animation roster
// a set is checked against is the skeleton's, in its own order, whichever
// poser runs — the model document lists the spec's order, and a refusal that
// listed the names in another order would be a byte of the report that
// depends on the poser.
const have = [...facts.animations];
const posing = throughPoser(choice, (poser, roster) => {
const sampled = sets.map((set) => prepareSet(located.root, set, poser, have, options.as, poseOptions));
// 🔒 A pose that is not finite is refused before anything measures it (issue
// #873), in the words `render` and the geometry export use for it. Measured
// on a planted bone at x=1e309 before this: an overflowing root read "posed no
// drawable attachment", one at -1e309 "drew no pixel", and one at +1e309 or a
// rotation at 1e309 exited 0 with MAE 1.00 — the part missing from every
// frame, and nothing said why.
const posedSets = sampled.filter((p) => p.missing === null);
const overflow = posedSets.some((p) =>
p.frames.some((frame) => frame.pieces.some((piece) => piece.world.some((value) => !Number.isFinite(value)))),
);
if (overflow) {
const found = nonFinitePoseOf(
poser,
options.skin,
posedSets.map((p) => ({ animation: p.candidateAnimation, fps: p.set.fps })),
);
if (found === null) {
throw new Error('a drawn piece of the candidate is not finite and no bone or vertex of its pose is — the two were posed differently');
}
throw new CheckError(`the candidate is posed to a number that is not finite, so no frame of it can be compared: ${found}`);
}
// 🔒 A candidate whose every drawn vertex sits at one point is refused in
// `render`'s own sentence (issue #997), not measured. Measured before this on
// a rig whose one drawn slot hangs from a bone only a non-default skin poses:
// "the candidate drew no pixel in any frame that was compared" — true, and
// silent on the reason, which is a skin the run did not pose.
const unframeable = unframeableSentence(
posedSets.map((p) => p.frames),
poser.slots,
options.skin,
roster,
);
if (unframeable !== null) throw new UnframeablePoseError(unframeable);
return sampled;
});
const prepared = posing.value;
const pairs = prepared.flatMap((p) => p.pairs);
if (pairs.length === 0) {
notes.push('no reference frame has a candidate frame at the same index — nothing below was measured');
}
const maxSide = Math.max(pixelWidth, pixelHeight);
// One edge level for both sides, read off the reference frames — see
// `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, 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);
/** One per prepared set, in `prepared` order. */
const framings: SetFraming[] = [];
let topViewport: Viewport | null = null;
let topHow: FramingHow | null = null;
let topFit: FramingReport | null = null;
let topProbe: DeclaredBoxProbe | null = null;
let sharedFraming: FramingReport | null = null;
const reportFor = (fit: FramingFit, at: Viewport, over: Omit): FramingReport => ({
...over,
fit,
units: extentsOf(fit, at.scale, referenceViewport),
});
if (options.viewport) {
// A pin is a claim about the CANDIDATE's own coordinates, and those do not
// change between shots — so one box covers the run whatever the scope. The
// per-set fits below are free: every frame is measured in that one box once,
// and splitting the result per set costs nothing.
const v = options.viewport;
const pinned = viewportOfSize(v.x, v.y, v.width, v.height, maxSide / Math.max(v.width, v.height), pixelWidth, pixelHeight);
notes.push(
`the candidate's world box was pinned by --viewport ${v.x},${v.y},${v.width},${v.height} rather than derived ` +
"from its own pixels — that is a claim about the candidate's coordinates, and nothing here checks it. The " +
'framing line below is still measured, so it says what the pin cost.',
);
const pinnedShape = { passes: 1, settled: false, source: 'pinned' as const, cycled: false, applied: false };
// A pin is one claim for the whole run, so the refined pass is measured over
// the run as a whole — and never applied, for the same reason the fit is not.
const refinement = refinementOf(scanOffsets(located.root, prepared, posable.pages, pinned, background), 'pinned');
const perSet = prepared.map((p, i) =>
pairUpBoxes([p], posable.pages, pinned, background, level, slices[i]),
);
for (const boxes of perSet) {
const fit = boxes.length === 0 ? null : fitFraming(boxes);
framings.push({
viewport: pinned,
how: 'viewport-flag',
fit:
fit === null
? null
: reportFor(fit, pinned, { ...pinnedShape, agrees: fitDistance(fit) <= COINCIDENT_PIXELS, refinement }),
notes: [],
// A pin overrides the declared box outright, so there is no probe to
// report: nothing was measured about whether that box applies here.
declaredBox: null,
});
}
const all = perSet.flat();
topViewport = pinned;
topHow = 'viewport-flag';
if (all.length > 0) {
const fit = fitFraming(all);
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${nothingToFrameWhy(
prepared,
[...facts.animations],
options.as,
located.sidecar !== null,
)}`,
);
} else if (scope === 'shared' || prepared.length === 1) {
const framed = frameCandidate(
prepared,
posable.pages,
referenceBoxes,
background,
level,
pixelWidth,
pixelHeight,
referenceViewport,
);
// One box for the run, so one refined pass over every frame in it: a single
// shared framing that each set nudged its own way would not be a shared one.
const refinement = refinementOf(
scanOffsets(located.root, prepared, posable.pages, framed.viewport, background),
framed.report.source,
);
const viewport =
refinement !== null && refinement.applied
? shiftViewport(framed.viewport, refinement.dx, refinement.dy, pixelWidth, pixelHeight)
: framed.viewport;
const fit = {
...framed.report,
units: extentsOf(framed.report.fit, framed.viewport.scale, referenceViewport),
refinement,
};
const how = HOW_BY_SOURCE[framed.report.source];
for (let i = 0; i < prepared.length; i++) {
framings.push({ viewport, how, fit, notes: [], declaredBox: framed.probe });
}
topViewport = viewport;
topHow = how;
topFit = fit;
topProbe = framed.probe;
notes.push(...framingNotes(framed.report, framed.probe));
if (prepared.length > 1) {
notes.push(
`one framing was fitted across all ${prepared.length} frame set(s) (--framing shared). Its absolute numbers ` +
'are not comparable with a per-shot run, and one badly-fitted set moves every other set in it.',
);
}
} else {
// Per shot: the DECLARED BOX is decided per set, and every set that does not
// qualify for it is measured in the one shared framing.
//
// ## Why the split falls exactly there, and not "fit each set on its own"
//
// The obvious reading of issue #100 is that each set should get its own fitted
// framing. It was written that way and measured, and it is worse — on the
// spineboy rung, per-set fitting reads `hit` **92.36** against the shared
// fit's 60.59 and `shoot@30fps` **101.94** against 42.98 (a two-frame set,
// framed 24 % off). The reason is `fitFraming`'s own: it registers **extent**,
// and extent is not alignment, so on a shot whose silhouette genuinely differs
// the chain has a local minimum of the correction that is not a minimum of the
// difference. More frames constrain that; one shot's worth does not.
//
// What actually produced the good column in that run is the other half — the
// box `frames.json` records, which is not an estimate of anything and has no
// floor. Over the union it was refused, because ONE badly-fitted shot put the
// pooled correction over `COINCIDENT_PIXELS` and the whole root fell back to a
// fit. Per set, the four sets that ARE in the frames' coordinates take it and
// read exactly what pinning by hand reads: `idle` **18.77** against 41.59,
// `walk` 32.00 against 45.33.
//
// So a set is framed by the frames' own box when its OWN pixels land there,
// and by the shared fit otherwise. Every set is then at least as well framed
// as a whole-root run framed it, and four of spineboy's sixteen much better.
const shared = frameCandidate(
prepared,
posable.pages,
referenceBoxes,
background,
level,
pixelWidth,
pixelHeight,
referenceViewport,
);
const sharedShape: SetFraming = {
viewport: shared.viewport,
how: HOW_BY_SOURCE[shared.report.source],
fit: { ...shared.report, units: extentsOf(shared.report.fit, shared.viewport.scale, referenceViewport) },
notes: [],
declaredBox: shared.probe,
};
sharedFraming = sharedShape.fit;
topProbe = shared.probe;
let own = 0;
for (let i = 0; i < prepared.length; i++) {
const p = prepared[i];
const probed =
p.pairs.length === 0
? { framed: null, probe: null }
: frameByDeclaredBox(
[p],
posable.pages,
slices[i],
background,
level,
pixelWidth,
pixelHeight,
referenceViewport,
);
const declared = probed.framed;
const chosen: SetFraming = declared
? {
viewport: declared.viewport,
how: HOW_BY_SOURCE[declared.report.source],
fit: {
...declared.report,
units: extentsOf(declared.report.fit, declared.viewport.scale, referenceViewport),
},
notes: framingNotes(declared.report, probed.probe),
declaredBox: probed.probe,
}
: { ...sharedShape, notes: framingNotes(shared.report, probed.probe), declaredBox: probed.probe };
if (declared) own++;
// Per set, because the constant this pass removes is per set: issue #146
// measured spineboy's `death` wanting (−1, +1) and its `jump` (0, −1) in the
// same run and the same shared box. That is not the per-set *fitting* this
// scope rejects — the offset is measured against the MAE itself, where one
// shot's frames constrain the answer completely.
framings.push(refined(located.root, [p], posable.pages, chosen, background, pixelWidth, pixelHeight));
}
notes.push(
`the framing was decided per frame set: ${own} of ${prepared.length} set(s) were measured in ` +
`${FRAMES_SIDECAR}'s own box because their own pixels land there, and the rest in the one shared framing on ` +
'the "shared box" line. A set framed by the frames\' own box cannot be moved by any other set. --framing ' +
'shared measures every set in the shared framing instead, which is a different measurement and not ' +
'comparable with this one.',
);
}
// The candidate's own decomposition, derived once and used by every set — see
// `src/chains.ts`. Reading the CANDIDATE's tree is what keeps this on the right
// side of the honesty rule: the reference is still nothing but pixels.
const chains = chainsOf(
facts.bones.map(({ name, parent }) => ({ name, parent })),
facts.slots.map(({ name, bone }) => ({ name, bone })),
);
const chainOfSlot = new Map();
chains.forEach((chain, index) => {
for (const slot of chain.slots) chainOfSlot.set(slot, index);
});
const animations: AnimationCheck[] = [];
const unmatched = new Set();
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,
options.plates ?? null,
),
);
}
// The candidate's `scale:` lines as its facts read them: off its atlas, or —
// a build posed from a `rigc-compiled/3` document — off the pages the
// document states (issue #1026), so a build drawn with its atlas gone reports
// them as it does with the atlas there. `null` when neither was read (issue
// #1020): a `/2` or `/1` document states where each region sits and not the
// `scale:` line, so with its atlas gone the report says the line was not read
// rather than that none was declared.
const candidateScales = facts.atlasScales === null ? null : [...facts.atlasScales];
if (substitution === null) {
// ⭐ Named at the top of every report rather than only when it is measured.
// Issue #171's finding was not that the floor was mis-measured; it was that
// nothing in the report said the figures had one — so a reader could take a
// texture difference for rig error twice over, on two rungs, before anybody
// noticed the atlas.
notes.push(
'part of every MAE below is TEXTURE, not animation, and it is not attributed here. The frames were rendered ' +
"through the reference's own atlas; this candidate samples its own" +
`${
candidateScales === null
? ' (its atlas is not beside it, so whether that declares a scale: line is not read — the model document does not state one)'
: candidateScales.length > 0
? ` (declared at scale: ${[...new Set(candidateScales)].join(', ')})`
: ''
}` +
', and if the two were packed at different scales every edge of every part is filtered from a different ' +
'source in every frame. That difference is a constant no key can move and is invisible to the content box, ' +
'the fit residual and the whole-pixel refinement. Pass --texture-from to measure it: the candidate's own geometry is kept and only the texels are swapped, so the run " +
'reports the floor and what sits above it beside the figure of record.',
);
} else if (options.textureFrom) {
notes.push(
`the texture floor below was measured against ${options.textureFrom.label} — the candidate's own geometry ` +
'through that atlas\'s texels. It is a DIAGNOSTIC and not a better number: the artifact ships its own ' +
'atlas, so the MAE is still the figure of record and the floor is the account of where part of it went.',
);
}
return {
candidate: {
skeleton: options.labels?.skeleton ?? '(in memory)',
atlas: options.labels?.atlas ?? '(in memory)',
},
poser: { name: posing.poser, note: posing.note },
framesDir: resolve(options.framesDir),
framesRoot: located.root,
skin: options.skin ?? null,
referenceSkin,
framingScope: scope,
framing: topHow,
viewport: topViewport === null ? null : framingOfViewport(topViewport),
framingFit: topFit,
declaredBox: topProbe,
sharedFraming,
referenceViewport,
background,
chains,
animations,
textureFrom:
substitution === null || !options.textureFrom
? null
: {
atlas: options.textureFrom.label,
scales: substitution.scales,
candidateScales,
unmatched: [...unmatched].sort(),
},
notes,
};
}
/** The framing one prepared set was measured in. */
interface SetFraming {
viewport: Viewport;
how: FramingHow;
fit: FramingReport | null;
notes: string[];
/**
* What the declared-box probe measured for this set, taken or not — see
* `DeclaredBoxProbe`. `null` when there was no box to probe (no sidecar) or
* nothing to probe it with (`--viewport`, or a set with no compared frame).
*/
declaredBox: DeclaredBoxProbe | null;
}
/** `FramingSource` said in the report's own words. */
const HOW_BY_SOURCE: Record = {
derived: 'candidate-pixels',
declared: 'frames-viewport',
pinned: 'viewport-flag',
};
/**
* `referenceBoxes` cut into one array per prepared set, in `prepared` order.
*
* The array is built by `prepared.flatMap((p) => p.pairs)`, so this is the inverse
* of that flatten and nothing else. It exists because a per-shot framing measures
* one set at a time and `frameCandidate` indexes its boxes the flat way.
*/
function sliceBySet(prepared: PreparedSet[], referenceBoxes: Array): Array> {
const out: Array> = [];
let at = 0;
for (const p of prepared) {
out.push(referenceBoxes.slice(at, at + p.pairs.length));
at += p.pairs.length;
}
return out;
}
/** A rendering viewport as the report states it. */
function framingOfViewport(v: Viewport): Framing {
return {
x: v.minX,
y: v.minY,
width: v.maxX - v.minX,
height: v.maxY - v.minY,
scale: v.scale,
pixelWidth: v.width,
pixelHeight: v.height,
};
}
function readPlateFrom(root: string, file: string): Plate {
readFrameFile(root, file); // the guard; readPlate does the decoding
return readPlate(file);
}
// ---------------------------------------------------------------------------
// framing
// ---------------------------------------------------------------------------
/**
* How many render → measure → correct passes the framing is allowed.
*
* A faithful candidate settles on the first look. What the old ceiling of 4 read
* as "a jitter floor by the third or fourth pass" is, measured properly, an
* **orbit**: on rung 6 the correction repeats with period 4, so passes 4–7 come
* back as 8–11 and again as 12–15, to within 0.02 px. Stopping at 4 stopped
* mid-orbit, on whichever phase pass 4 happened to be — and that phase was the
* worst of the four, framed 0.063 % off the scale the frames were rendered at and
* worth **5 MAE points** on that shot (8.73 against a pinned 3.50, issue #52).
*
* One more pass reaches the orbit's closest phase and takes the same shot to 5.62;
* 6, 8, 12, 16 and 24 passes all return that same viewport, because `chosen`
* keeps the closest pass and the orbit has no better one. So the ceiling is raised
* to two full periods — enough to see every phase of an orbit this size — and
* `fitSeparation` stops the loop the moment it recognises one, which costs the
* cycling case one pass rather than four. A shot that is genuinely still
* converging is unaffected: it settles and breaks out first.
*
* ⚠️ This is not a way to reach the right framing. Nothing in an extent fit can
* be: at the box `frames.json` records — the one the frames were actually drawn
* at — rung 6's edge residual is 0.41 px rms, **worse** than the 0.23 px the orbit
* reaches, because the candidate's silhouette genuinely differs and the best fit
* of two extents is not the best alignment of two pictures (`fitFraming`, "the
* floor, stated plainly"). That is what `frameByDeclaredBox` is for.
*/
const FRAMING_PASSES = 8;
/**
* How far the candidate's drawn pixels may sit from the reference's and still be
* called the same place, in pixels.
*
* One pixel, and the margin on either side of it is enormous rather than fine.
* What this threshold has to separate is a candidate authored in the frames' own
* world coordinates from one authored in its own, and those differ by an origin
* or a unit — tens to hundreds of pixels — not by a fraction of one. Rung 6's
* candidate reads 0.45 px in the declared box; rung 3's mechanical transcription
* reads 0.07; a rig scaled by 2 % reads about 5 before the scale is taken out and
* about 0.07 after. Nothing measured so far lands between 1 and 5.
*/
export const COINCIDENT_PIXELS = 1;
/**
* How far the correction may **reach**, as a fraction of the reference's own
* content box, for the disagreement to be read as a silhouette rather than as
* coordinates.
*
* ## 🎯 The question this settles, in the terms it is decidable in
*
* `COINCIDENT_PIXELS` above answers *"is this candidate in the frames' own
* coordinates?"* with the worst corner displacement of one similarity fit, and on
* a candidate whose silhouette is right that is a clean answer: a different origin
* or a different unit is worth tens to hundreds of pixels, a right one 0.07.
*
* It is **not** clean on a candidate whose silhouette differs at the extremes,
* because `fitFraming` registers extent: a union box a few per cent narrower than
* the reference's reads as a few per cent of scale, which is arithmetically the
* same displacement a units error gives. Rung 7 is that case twice over — the
* candidate's setup box lands on the reference's **to the pixel** and it is
* refused on all twelve sets — and the refusal is not free: pinned to the declared
* box, that candidate reads better on **every one** of its twelve sets, by 0.28 to
* 2.01 MAE over the reference's own pixels (issue #194).
*
* ## Two conditions, because one is not enough — measured
*
* The fixtures that must keep being refused are `selftest` C04 (the same rig at
* 2 % different units, which the framing must stay blind to) and C06 (the same rig
* 300 units away, which is the ordinary candidate under the ladder's honesty
* rule). Probed at the declared box, per set:
*
* | candidate | correction | correction ÷ reference box | rms |
* | --- | --- | --- | --- |
* | rung 3, faithful | 0.08 px | 0.03 % | 0.10 px |
* | rung 3, x1.02 units (C04) | 2.60–3.65 px | 1.1–1.6 % | **0.20–0.27 px** |
* | rung 3, one part +20 units (C12) | 2.07–2.11 px | 0.9–1.8 % | **0.53–0.83 px** |
* | rung 3, +300 units (C06) | 40.32 px | **17.2 %** | 44.15 px |
* | rung 7, twelve sets | 1.67–13.02 px | 0.18–1.4 % | **3.32–16.85 px** |
*
* ⚠️ The obvious single clause — *"take it when the fit admits it cannot explain
* what it asks for", `rms ≥ distance`* — was written first and **is wrong**: the
* moved rig draws partly outside the declared box, so its content box is truncated
* and the fit is garbage with a 44 px residual. That reads 1.09 against the
* faithful candidate's own 1.25 and takes the box, framing a rig 300 units away as
* though it were in the frames' coordinates (MAE 144). C06 caught it, which is
* what C06 is for.
*
* ⇒ Both halves have to be asserted, and each carries its own margin:
*
* - **the correction reaches no further than `EXTENT_SPREAD_REACH` of the
* reference's own content box** — the two shots are in the same *place*. This is
* the half C06 fails: 17.2 % against a 5 % ceiling, with rung 7 at 1.4 %, so the
* line is 3.4x clear on both sides. Relative to the shot rather than in pixels,
* because a pixel count would have to be re-derived for every frame size;
* - **and one similarity still cannot put the two shots on each other**, which is
* `rms` past `COINCIDENT_PIXELS` — the same pixel the report already warns at
* (*"no single scale and offset puts the two shots on each other — they are
* different shapes, not the same shape misframed"*). This is the half that says
* *silhouette*, and it is the half C04 fails: a pure difference of units is a
* similarity, so the fit absorbs it **exactly** and leaves 0.27 px where rung 7
* leaves 3.32 at its quietest. 3.3x clear above, 3.7x clear below.
*
* ⚠️ **What this deliberately does not do is widen `COINCIDENT_PIXELS`.** A plain
* tolerance of "a few px at the extremes" accepts C04, whose whole point is that
* the framing must stay blind to units and must not pay a fit's floor for a
* candidate with no silhouette disagreement to plead. Both halves fire only on
* evidence the fit itself produced, and `DeclaredBoxProbe` makes the report say
* which clause decided, with its numbers.
*
* ⚠️ **What it leaves open, stated rather than hidden**: a candidate whose units
* are off by *less* than this reach AND whose silhouette genuinely differs is
* taken, and pays that scale error inside the declared box instead of having it
* absorbed by a fit. On the shots measured that is a few pixels either way, the
* same order as the fit's own floor — and the probe line prints the correction it
* declined to apply, so the trade is visible rather than silent. `--viewport` and
* `--framing shared` both override it.
*/
export const EXTENT_SPREAD_REACH = 0.05;
/**
* The two content boxes in world units, each divided by its own render scale.
*
* `null` without a sidecar: the reference's scale is the only thing that makes
* its pixels into units, and a frame set that predates `frames.json` does not
* record one. Inventing a default there would print a number that looks measured.
*/
function extentsOf(
fit: FramingFit,
candidateScale: number,
referenceViewport: Framing | null,
): { candidate: Extent; reference: Extent; ratio: number } | null {
if (!referenceViewport || candidateScale <= 0 || referenceViewport.scale <= 0) return null;
const candidate = {
width: boxWidth(fit.candidate) / candidateScale,
height: boxHeight(fit.candidate) / candidateScale,
};
const reference = {
width: boxWidth(fit.reference) / referenceViewport.scale,
height: boxHeight(fit.reference) / referenceViewport.scale,
};
const area = reference.width * reference.height;
// Area rather than either side: one ratio for a shot whose two axes can differ.
const ratio = area > 0 ? Math.sqrt((candidate.width * candidate.height) / area) : 1;
return { candidate, reference, ratio };
}
/** How many reference frames the edge level is estimated from. */
const LEVEL_SAMPLES = 8;
/** The edge threshold both sides are measured with — see `EDGE_FRACTION`. */
function edgeLevelOf(root: string, pairs: FramePair[], background: RGBA): number {
const histogram = new ContrastHistogram();
const step = Math.max(1, Math.ceil(pairs.length / LEVEL_SAMPLES));
for (let i = 0; i < pairs.length; i += step) histogram.add(readPlateFrom(root, pairs[i].file), background);
return histogram.level();
}
/** 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[],
background: RGBA,
level: number,
pixelWidth: number,
pixelHeight: number,
translucent: TranslucentFrame[] | null,
): Array {
return pairs.map((pair) => {
const plate = readPlateFrom(root, pair.file);
if (plate.width !== pixelWidth || plate.height !== pixelHeight) {
throw new CheckError(
`${pair.file} is ${plate.width}x${plate.height} but the viewport says ${pixelWidth}x${pixelHeight}; ` +
'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);
});
}
/**
* The two content boxes of every frame that has both, in one array.
*
* Per frame rather than unioned, because that is what the fit is made from — see
* `fitFraming`. `referenceBoxes` is indexed the same way `prepared.flatMap(pairs)`
* is, which is the order it was built in.
*/
function pairUpBoxes(
prepared: PreparedSet[],
pages: Map,
viewport: Viewport,
background: RGBA,
level: number,
referenceBoxes: Array,
): BoxPair[] {
const out: BoxPair[] = [];
let at = 0;
for (const p of prepared) {
for (const pair of p.pairs) {
const reference = referenceBoxes[at++];
const candidate = frameContentBox(pair.frame, pages, viewport, background, level);
if (candidate && reference) out.push({ candidate, reference });
}
}
return out;
}
/** One measured pass of the framing loop. */
interface FramingPass {
viewport: Viewport;
fit: FramingFit;
distance: number;
}
/** A framing for one run of sets: the box, and what it still leaves over. */
interface FramedSets {
viewport: Viewport;
report: Omit;
}
/** A chain of passes and why it stopped. */
interface FramingChain {
passes: FramingPass[];
settled: boolean;
cycled: boolean;
}
/**
* Render → measure → correct, from one starting viewport, until it stops.
*
* ## Why it iterates
*
* The correction is measured on a render, and applying it changes the render it
* was measured on. One pass leaves the candidate close; a second measures what is
* left. It stops as soon as the correction is the identity to within
* `SETTLED_PIXELS`, which for a faithful candidate is the first look.
*
* ## And why it also watches for an orbit
*
* When the fit has no fixed point on a shot — which happens whenever the
* candidate's silhouette genuinely differs, because the fit registers extent and
* extent is not alignment — the sequence does not wander and does not converge. It
* **cycles**, and every further pass re-measures a state it has already been in at
* the cost of a full re-render of every frame. `fitSeparation` recognises that in
* one comparison per pass, so a cycling shot stops one pass after its orbit closes
* instead of burning the whole budget, and the report can say which of the two
* happened. Rung 6 cycles with period 4 (issue #52).
*/
function runFramingChain(
seed: Viewport,
prepared: PreparedSet[],
pages: Map,
referenceBoxes: Array,
background: RGBA,
level: number,
pixelWidth: number,
pixelHeight: number,
cap: number,
): FramingChain {
let viewport = seed;
const passes: FramingPass[] = [];
for (let pass = 1; pass <= cap; pass++) {
const boxes = pairUpBoxes(prepared, pages, viewport, background, level, referenceBoxes);
// A viewport the candidate draws nothing into ends the chain rather than
// failing it, and both ways of reaching one are real. The declared box gets
// there on its first pass whenever the candidate is authored somewhere else
// entirely — rung 1's `drop` candidate is nowhere near the frames' own world
// box — which is the declared path being refused, not an error. And a chain
// that does not converge can walk its own box off its content later on, where
// the answer is the closest pass already measured. The caller decides what an
// empty chain means; only the fitted path treats it as a failure.
if (boxes.length === 0) return { passes, settled: false, cycled: false };
const fit = fitFraming(boxes);
const cycled = passes.some((seen) => fitSeparation(fit, seen.fit) < CYCLE_PIXELS);
passes.push({ viewport, fit, distance: fitDistance(fit) });
if (fitIsSettled(fit)) return { passes, settled: true, cycled: false };
if (cycled) return { passes, settled: false, cycled: true };
viewport = applyFit(viewport, fit, pixelWidth, pixelHeight);
}
return { passes, settled: false, cycled: false };
}
/**
* The pass whose correction is closest to the identity.
*
* ⚠️ The **closest** pass rather than the last, and the viewport handed back is
* therefore one that was actually MEASURED, with the fit beside it being what it
* still leaves over — never a correction applied on the way out and never looked
* at. Near the answer the correction can jitter or orbit instead of converging, so
* taking the last pass would hand back whichever phase the loop happened to stop
* on, and applying one more unverified correction is a coin flip. A report that
* describes a viewport nobody rendered is worse than a slightly worse viewport.
*/
function closestPass(chain: FramingChain): FramingPass {
let best = chain.passes[0];
for (const pass of chain.passes) if (pass.distance < best.distance) best = pass;
return best;
}
/**
* Put the candidate's drawn pixels on the reference's drawn pixels.
*
* Two ways in, and the second is tried first because when it applies it is exact
* rather than estimated — see `frameByDeclaredBox`. The fitted path is the general
* one and the only one available without a sidecar.
*
* ## Why the fitted start is trimmed
*
* The starting box is the union of the posed quads **trimmed to their opaque
* texels**, not the quads themselves. It is only a starting point — the framing is
* fitted on rendered pixels either way — but the fit's landing point depends on
* where it starts, so a start that moved with an invisible margin would leave the
* margin able to move the answer after all, by a fraction of a pixel instead of by
* two. With the trim, art padded on both sides is byte-identical work: same start,
* same passes, same numbers. `selftest` C03 asserts exactly that.
*/
function frameCandidate(
prepared: PreparedSet[],
pages: Map,
referenceBoxes: Array,
background: RGBA,
level: number,
pixelWidth: number,
pixelHeight: number,
referenceViewport: Framing | null,
): FramedSets & { probe: DeclaredBoxProbe | null } {
const declared = frameByDeclaredBox(
prepared,
pages,
referenceBoxes,
background,
level,
pixelWidth,
pixelHeight,
referenceViewport,
);
// The declared-box probe measures every frame in `frames.json`'s own box
// whether or not it ends up being used, and that measurement is the only one
// taken in a box every set shares. Handing it back is what lets a per-shot run
// report `sharedFit` without a second render — see `CheckReport.sharedFit`.
if (declared.framed) return { ...declared.framed, probe: declared.probe };
const chain = runFramingChain(
seedFromGeometry(prepared, pages, referenceBoxes, pixelWidth, pixelHeight),
prepared,
pages,
referenceBoxes,
background,
level,
pixelWidth,
pixelHeight,
FRAMING_PASSES,
);
if (chain.passes.length === 0) {
throw new CheckError('the candidate drew no pixel in any frame that was compared');
}
const chosen = closestPass(chain);
return {
viewport: chosen.viewport,
report: {
fit: chosen.fit,
passes: chain.passes.length,
settled: chain.settled,
source: 'derived',
cycled: chain.cycled,
agrees: chosen.distance <= COINCIDENT_PIXELS,
applied: true,
// Filled in by the refined pass, which runs once the box is decided.
refinement: null,
},
probe: declared.probe,
};
}
/**
* The starting viewport, from the candidate's own posed geometry laid onto the
* reference's own drawn extent.
*
* ## Why the reference's extent and not the frame
*
* The seed used to scale the candidate's trimmed quads to **fill the frame**, and
* that is an assumption about the reference: that the shot its frames show was
* framed around itself. Over a whole skeleton root it holds well enough, because
* the sidecar's one box was chosen to hold every set. Over one SHORT set it can be
* badly wrong — rung 3's `light` covers about half of the box its frames were
* rendered in, so filling the frame starts it near 2x too large, and the chain
* walks that back by only a few per cent a pass: `--frames /light` on a
* candidate in its own coordinates read **MAE 141** with a framing 65 % off, after
* spending its whole pass budget (issue #100).
*
* The reference's own content box is already measured, on the same frames, with
* the same predicate — it is what the fit is trying to reach. Starting there costs
* nothing and starts the chain where it used to end up: the same shot now settles
* on the first or second pass.
*
* The scale matches the two boxes by **area** rather than by either side, because
* a candidate whose silhouette differs has two different side ratios and picking
* one of them would seed the chain with that difference as a scale error.
*
* ⚠️ Falls back to filling the frame when there is no reference box to aim at —
* every frame unreadable, or a set with nothing on disk.
*/
function seedFromGeometry(
prepared: PreparedSet[],
pages: Map,
referenceBoxes: Array,
pixelWidth: number,
pixelHeight: number,
): Viewport {
const quads = trimmedUnionBounds(
prepared.map((p) => p.pairs.map((pair) => pair.frame)),
pages,
);
if (!Number.isFinite(quads.minX)) {
throw new CheckError('the candidate posed no drawable attachment in any frame that was compared');
}
const pad = Math.max(quads.maxX - quads.minX, quads.maxY - quads.minY) * PAD;
const world = {
minX: quads.minX - pad,
minY: quads.minY - pad,
maxX: quads.maxX + pad,
maxY: quads.maxY + pad,
};
const worldWidth = world.maxX - world.minX;
const worldHeight = world.maxY - world.minY;
let reference: ContentBox | null = null;
for (const box of referenceBoxes) reference = unionBoxes(reference, box);
if (reference !== null && boxWidth(reference) > 0 && boxHeight(reference) > 0) {
// The reference's box is the trimmed content, so pad it the same way the
// candidate's is before the two are matched — otherwise the pad is a scale
// error the chain then has to undo.
const refWidth = boxWidth(reference) * (1 + 2 * PAD);
const refHeight = boxHeight(reference) * (1 + 2 * PAD);
const scale = Math.sqrt((refWidth * refHeight) / (worldWidth * worldHeight));
const left = reference.left - boxWidth(reference) * PAD;
const top = reference.top - boxHeight(reference) * PAD;
// `projector` is px = (wx - minX)·k and py = (maxY - wy)·k, so putting the
// candidate's padded box on the reference's is one subtraction per axis.
const minX = world.minX - left / scale;
const maxY = world.maxY + top / scale;
return viewportOfSize(minX, maxY - pixelHeight / scale, pixelWidth / scale, pixelHeight / scale, scale, pixelWidth, pixelHeight);
}
const maxSide = Math.max(pixelWidth, pixelHeight);
return viewportOfSize(
world.minX,
world.minY,
worldWidth,
worldHeight,
maxSide / Math.max(worldWidth, worldHeight),
pixelWidth,
pixelHeight,
);
}
/**
* The box `frames.json` records, used as the candidate's own — when, and only
* when, the candidate's pixels are measured to land in it.
*
* ## 🔒 This is not reading the answer
*
* The thing the honesty rule protects is the reference **skeleton** — its bones,
* its keys, its curves — and none of that is here. `frames.json` is a sidecar
* `check` already reads, whose `viewport` it already prints, and which
* [`docs/AUTHORING.md`](../docs/AUTHORING.md) §9 already tells an author to hand
* back through `--viewport`. What changes is only that the tool now *checks* the
* condition the guide asks the author to assert, instead of requiring them to
* notice it and type it.
*
* ## Why a declared box beats a fitted one
*
* A fit is an estimate with a floor. `fitFraming` registers two shots by their
* **extent**, so when the candidate's silhouette genuinely differs the best fit of
* the extents is about a third of a pixel away from the best alignment of the
* pictures — and on a small high-contrast shot a third of a pixel is several MAE.
* Rung 6 measures that floor as a 5-point tax: 8.73 fitted against 3.50 in the box
* the frames were actually drawn at, with every content box, residual and rms
* under the method's own noise (issue #52).
*
* The declared box has no such floor. It is not an estimate of where the frames
* were drawn; it is where they were drawn. So the only question is whether it
* applies to *this* candidate, and that is one measurement: render the candidate
* into the declared box, fit, and keep the box when the correction it asks for is
* under `COINCIDENT_PIXELS`. Nothing is corrected and nothing is iterated —
* either the candidate is in the frames' coordinates or it is not.
*
* ⚠️ **Correcting the declared box makes it worse, measured.** The obvious extra
* step — accept it, then run the usual passes from there to polish — was written
* and measured, and it walks off the answer: rung 5's candidate, whose author
* matched the reference's world box by hand, reads **4.35** at the declared box and
* **6.24** after three refining passes, and 4.35 is the figure `fitFraming` records
* as this shot's correct framing. Rung 6 reads 3.50 at the box and drifts the same
* way. The refinement is the extent fit, and the extent fit is exactly what the
* declared box is here to avoid.
*
* A candidate authored in its own coordinates — the ordinary case, and the one the
* ladder's honesty rule guarantees — misses by a wide margin and is framed by the
* fitted path exactly as before. Rung 3's candidate put its origin on the pendulum's
* pivot and the reference put its own elsewhere; in the declared box that candidate
* reports MAE 146/255, and its fit says so long before the pixels are ever compared.
* Rung 1's `drop` candidate draws nothing at all in the declared box.
*
* ⚠️ So does a rig in the frames' coordinates at **different units**, which is a
* choice the framing must stay blind to (`selftest` C04). It is refused here and
* framed by the fitted path, where the blindness lives — and it therefore pays the
* fit's floor where a same-units candidate does not. Recovering the unit from the
* fit and scaling the declared box by it was measured too: on a rig scaled by 2 %
* it recovers 1.0196 against a true 1.02 and lands two thirds of the way back, which
* is more machinery for a case no candidate in the corpus has and still not exact.
*/
function frameByDeclaredBox(
prepared: PreparedSet[],
pages: Map,
referenceBoxes: Array,
background: RGBA,
level: number,
pixelWidth: number,
pixelHeight: number,
referenceViewport: Framing | null,
): { framed: FramedSets | null; probe: DeclaredBoxProbe | null } {
if (!referenceViewport || referenceViewport.scale <= 0) return { framed: null, probe: null };
const viewport = viewportOfSize(
referenceViewport.x,
referenceViewport.y,
referenceViewport.width,
referenceViewport.height,
referenceViewport.scale,
pixelWidth,
pixelHeight,
);
const boxes = pairUpBoxes(prepared, pages, viewport, background, level, referenceBoxes);
// Nothing drawn in the declared box is the loudest possible "not these
// coordinates", not a failure: rung 1's `drop` candidate is nowhere near it.
if (boxes.length === 0) {
return {
framed: null,
probe: { distance: 0, rms: 0, reach: 0, frames: 0, taken: false, clause: 'no-pixels' },
};
}
const fit = fitFraming(boxes);
const distance = fitDistance(fit);
const reach = EXTENT_SPREAD_REACH * Math.max(boxWidth(fit.reference), boxHeight(fit.reference));
// The two clauses, in the order they are decidable — see `EXTENT_SPREAD_REACH`.
// The first is a measurement of coincidence; the second needs BOTH of its halves,
// and the comment above the constant records the fixture that proves it.
const clause =
distance <= COINCIDENT_PIXELS
? 'coincident'
: distance <= reach && fit.rms > COINCIDENT_PIXELS
? 'extent-spread'
: 'coordinates';
const probe: DeclaredBoxProbe = {
distance,
rms: fit.rms,
reach,
frames: fit.frames,
taken: clause !== 'coordinates',
clause,
};
if (!probe.taken) return { framed: null, probe };
return {
framed: {
viewport,
report: {
fit,
passes: 1,
settled: fitIsSettled(fit),
source: 'declared',
cycled: false,
// A measurement, not a constant: under the extent-spread clause the two
// content boxes do NOT coincide, and a report that said they did would be
// hiding the very disagreement that clause was invoked to name.
agrees: distance <= COINCIDENT_PIXELS,
applied: true,
refinement: null,
},
},
probe,
};
}
// ---------------------------------------------------------------------------
// the MAE-refined final pass — see `FramingRefinement`
// ---------------------------------------------------------------------------
/**
* The reference-denominator MAE of these sets at every whole-pixel offset in a
* ±`REFINE_RADIUS` window, in the box they were framed in.
*
* One render per frame, whatever the window's size: `OffsetScan` owns why that is
* exact for whole pixels. The reference plates are read again here and again by
* `checkOneSet`; decoding a PNG twice is cheaper than holding a set's frames in
* memory, which on the ladder's largest set is a quarter of a gigabyte.
*/
function scanOffsets(
root: string,
prepared: PreparedSet[],
pages: Map,
viewport: Viewport,
background: RGBA,
): OffsetGain | null {
const scan = new OffsetScan(REFINE_RADIUS);
for (const p of prepared) {
for (const pair of p.pairs) {
scan.add(
renderFrame(pair.frame, pages, viewport, background),
frameGeometry(pair.frame, pages, viewport).coverage,
readPlateFrom(root, pair.file),
background,
);
}
}
return scan.best();
}
/**
* What to do with the offset a scan found, given how the box was chosen.
*
* The whole judgement of `FramingRefinement` in one function, so that "a fitted
* box is corrected and an exact one is only reported" is a single readable rule
* rather than a condition spread over three call sites.
*/
function refinementOf(gain: OffsetGain | null, source: FramingSource): FramingRefinement | null {
if (gain === null) return null;
const shape = {
dx: gain.dx,
dy: gain.dy,
before: gain.identity,
after: gain.best,
radius: gain.radius,
frames: gain.frames,
};
if (gain.dx === 0 && gain.dy === 0) return { ...shape, applied: false, declined: 'identity' };
if (!offsetIsWorthApplying(gain)) return { ...shape, applied: false, declined: 'below-threshold' };
if (source === 'pinned') return { ...shape, applied: false, declined: 'pinned' };
if (source === 'declared') return { ...shape, applied: false, declined: 'box-is-exact' };
return { ...shape, applied: true, declined: null };
}
/** One set's framing with the refined pass run over it, and applied if it may be. */
function refined(
root: string,
prepared: PreparedSet[],
pages: Map,
framing: SetFraming,
background: RGBA,
pixelWidth: number,
pixelHeight: number,
): SetFraming {
if (framing.fit === null) return framing;
const refinement = refinementOf(
scanOffsets(root, prepared, pages, framing.viewport, background),
framing.fit.source,
);
const viewport =
refinement !== null && refinement.applied
? shiftViewport(framing.viewport, refinement.dx, refinement.dy, pixelWidth, pixelHeight)
: framing.viewport;
return { ...framing, viewport, fit: { ...framing.fit, refinement } };
}
/**
* What the framing pass concluded, in the words that tell the three cases apart.
*
* The distinction the report used to be missing (issue #52): "did not settle, and
* the two shots are nevertheless in the same place" is the tool reaching its own
* floor, "did not settle, and they are not" is a finding about the candidate, and
* "the correction is cycling" says more passes cannot change either answer.
*/
function framingNotes(report: Omit, probe: DeclaredBoxProbe | null): string[] {
if (report.source === 'declared' && probe !== null && probe.clause === 'extent-spread') {
// ⭐ The tolerance states itself. A clause that widens what `check` accepts
// and says nothing about having done so would be the same defect the
// framing line was built to close: a number without its convention.
return [
`the candidate's world box was taken from ${FRAMES_SIDECAR} rather than fitted even though the two content ` +
`boxes do NOT coincide — the EXTENT-SPREAD tolerance engaged. A fit at that box asks to move the candidate ` +
`${probe.distance.toFixed(2)} px, which reaches less than the ${probe.reach.toFixed(2)} px this clause allows ` +
`(${(EXTENT_SPREAD_REACH * 100).toFixed(0)}% of the reference's own content box), and it leaves ` +
`${probe.rms.toFixed(2)} px rms across the frames' edges — so no single scale and offset puts the two shots ` +
`on each other, over ${probe.frames} frame(s). A difference of origin or of units IS a similarity and would ` +
"be absorbed exactly; a residual this size is a SILHOUETTE difference at the extremes, and the frames' own " +
"box is where the frames were drawn whatever this candidate's outline does out there. ⇒ Read the `union " +
'residual` and `aspect` on the framing line as the finding; the box below is exact and carries no fit floor. ' +
'Pass --viewport to override, or --framing shared to measure every set in the fitted box instead.',
];
}
if (report.source === 'declared') {
return [
`the candidate's world box was taken from ${FRAMES_SIDECAR} rather than fitted, because rendering it into ` +
`that box put its own drawn pixels on the reference's to within ${report.fit.rms.toFixed(2)} px rms — so ` +
"the candidate is authored in the frames' own coordinates, measured rather than assumed, and the box they " +
'were rendered at is exact where a fit of it is an estimate. The framing line below is still measured; what ' +
`it leaves over is the extent fit's own floor${report.settled ? '' : ', which is why it does not read as the identity'}. ` +
'Pass --viewport to override.',
];
}
const refused =
probe === null || probe.clause !== 'coordinates'
? []
: [
`${FRAMES_SIDECAR}'s own box was refused for this set: a fit at it asks to move the candidate ` +
`${probe.distance.toFixed(2)} px — ${probe.distance > probe.reach ? `further than the ${probe.reach.toFixed(2)} px the extent-spread tolerance reaches` : `and explains all but ${probe.rms.toFixed(2)} px rms of it, which a silhouette difference cannot be`}` +
` — over ${probe.frames} frame(s). That is what a different origin or a different unit looks like, so ` +
'this candidate is in its own coordinates and is framed by the fitted path, which is blind to units by ' +
"design and pays the extent fit's own floor for it.",
];
if (report.settled) return refused;
const how = report.cycled
? `the framing correction fell into a repeating orbit after ${report.passes} pass(es) rather than settling, so ` +
'more passes cannot help: the fit has no fixed point on this shot'
: `the framing did not settle in ${report.passes} pass(es)`;
return [
...refused,
report.agrees
? `${how}. The two content boxes nevertheless agree to within ${report.fit.rms.toFixed(2)} px rms, so this is ` +
"the fit's own floor and not a shape mismatch — the fit registers extent, and on a silhouette that differs " +
'anywhere the best fit of the extents is not the best alignment of the pictures. Pass --viewport to pin the ' +
'box when you know your own coordinates.'
: `${how}, and the two content boxes do not agree either — the correction below is what is left over after ` +
'the closest pass. A residual much larger than a pixel means the two shots are different shapes, which is ' +
'a finding about the candidate rather than about the loop.',
];
}
// ---------------------------------------------------------------------------
// posing the candidate against one frame set
// ---------------------------------------------------------------------------
/** One reference frame and the candidate frame that shares its index. */
interface FramePair {
index: number;
file: string;
frame: Frame;
}
/** One frame set, posed and paired up with the frames on disk. */
interface PreparedSet {
set: FrameSet;
candidateAnimation: string | null;
candidateFrames: number;
referenceFrames: number;
pairs: FramePair[];
/**
* Every frame the candidate sampled, in index order — not only the ones a file
* on disk pairs with.
*
* The contact sheet holds a tile for every SAMPLED frame, so a set that commits
* two stills out of 311 needs all 311 poses to be compared against it
* (`SheetCheck`). Kept as poses rather than plates: a `Frame` is geometry, and
* holding 311 rendered plates of a busy shot is a quarter of a gigabyte.
*/
frames: Frame[];
notes: string[];
/** Set when nothing could be compared at all, saying why. */
missing: string | null;
}
function prepareSet(
root: string,
set: FrameSet,
poser: Poser,
/** The skeleton's animation names in its own order — see the call. */
have: readonly string[],
as: string | undefined,
poseOptions: PoseOptions | undefined,
): PreparedSet {
const notes: string[] = [];
const wanted = as ?? set.animation;
const disk = framesOnDisk(root, set.dir);
if (wanted !== null && !have.includes(wanted)) {
return {
set,
candidateAnimation: null,
candidateFrames: 0,
referenceFrames: disk.length,
pairs: [],
frames: [],
notes: [],
missing:
`the candidate has no animation called ${JSON.stringify(wanted)} — it has [${have.join(', ') || 'none'}]. ` +
'Nothing was compared for this set; name the candidate animation with --as if it is called ' +
'something else.',
};
}
let candidateFrames: Frame[];
let candidateAnimation: string | null;
if (wanted === null) {
if (have.length > 0) {
notes.push(
`these frames are a setup pose (the skeleton that made them has no animation), but the candidate has ` +
`[${have.join(', ')}] — the setup pose is what was compared`,
);
}
candidateFrames = sampleSetupPose(poser, poseOptions);
candidateAnimation = null;
} else {
candidateFrames = sampleAnimation(poser, wanted, set.fps, poseOptions);
candidateAnimation = wanted;
}
if (candidateFrames.length !== set.sampled) {
notes.push(
`the candidate samples to ${candidateFrames.length} frame(s) at ${set.fps} fps where the reference sampled ` +
`${set.sampled} — the two animations do not last the same time, and only the frames both have were compared`,
);
}
const byIndex = new Map();
for (const frame of candidateFrames) byIndex.set(frame.index, frame);
const pairs: FramePair[] = [];
for (const { index, file } of disk) {
const frame = byIndex.get(index);
if (frame) pairs.push({ index, file, frame });
}
if (pairs.length === 0 && disk.length > 0) {
notes.push(`none of the ${disk.length} reference frame(s) has a candidate frame at the same index`);
}
return {
set,
candidateAnimation,
candidateFrames: candidateFrames.length,
referenceFrames: disk.length,
pairs,
frames: candidateFrames,
notes,
missing: null,
};
}
/**
* 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 with the one these frames show, or name the ` +
'directory after it'
);
}
function checkOneSet(
root: string,
prepared: PreparedSet,
posable: Pick,
framing: SetFraming,
background: RGBA,
chains: BoneChain[],
/** Slot name → its index in `chains`. */
chainOfSlot: Map,
/** The texture-only substitution to attribute against, when one was asked for. */
substitution: TextureSubstitution | null,
/** Region names it could not reach, unioned across every set by the caller. */
unmatched: Set,
/** 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;
const blank: AnimationCheck = {
dir: set.dir,
animation: set.animation,
candidateAnimation: prepared.candidateAnimation,
fps: set.fps,
referenceFrames: prepared.referenceFrames,
candidateFrames: prepared.candidateFrames,
compared: 0,
meanMae: 0,
meanMaeReference: 0,
drawnRatio: 1,
meanMaeFrame: 0,
textureFloor: null,
worstMae: 0,
worstMaeFrame: -1,
worstDrift: 0,
worstDriftFrame: -1,
worstDriftSlot: null,
framesWithoutDrift: 0,
changePairs: 0,
changeDisagreements: 0,
worstChangeFrame: -1,
chains: [],
chainDenominator: 0,
unattributedError: 0,
frames: [],
viewport: framingOfViewport(viewport),
framing: framing.how,
framingFit: framing.fit,
declaredBox: framing.declaredBox,
sheet: null,
notes: prepared.missing ? [prepared.missing] : [...framing.notes, ...prepared.notes],
};
if (prepared.missing !== null || prepared.pairs.length === 0) return blank;
const frames: FrameCheck[] = [];
let maeSum = 0;
let maeReferenceSum = 0;
let drawnRatioSum = 0;
let maeFrameSum = 0;
let worstMae = 0;
let worstMaeFrame = -1;
let worstDrift = 0;
let worstDriftFrame = -1;
let worstDriftSlot: string | null = null;
let framesWithoutDrift = 0;
let changePairs = 0;
let changeDisagreements = 0;
let worstChangeFrame = -1;
let worstChangeGap = 0;
// The previous frame's two plates, kept so each side can be compared against
// ITSELF a frame earlier. Both are already rendered or read for this frame, so
// holding one frame of each costs one extra plate and no extra work.
let previous: { index: number; candidate: Plate; reference: Plate } | null = null;
const tally: ChainTally = {
error: new Array(chains.length).fill(0),
pixels: new Array(chains.length).fill(0),
unattributed: 0,
total: 0,
};
// One page map for the substituted render, holding both sides: a piece whose
// region the substituting atlas does not have keeps its own page, and a page
// that happens to share a filename with one of the candidate's cannot shadow it
// 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);
const rendered = renderFrame(frame, posable.pages, viewport, background);
let floorPlate: Plate | null = null;
if (substitution !== null && floorPages !== null) {
const swapped = substituteTexture(frame, substitution);
for (const name of swapped.unmatched) unmatched.add(name);
floorPlate = renderFrame(swapped.frame, floorPages, viewport, background);
}
const { check, coverage } = checkOneFrame(
index,
file,
frame,
posable.pages,
viewport,
background,
reference,
rendered,
chainOfSlot,
tally,
floorPlate,
);
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;
if (check.textureFloor !== null) {
floorSum.floor += check.textureFloor.floor;
floorSum.aboveFloor += check.textureFloor.aboveFloor;
floorSum.floorReference += check.textureFloor.floorReference;
floorSum.aboveFloorReference += check.textureFloor.aboveFloorReference;
}
drawnRatioSum += check.referencePixels === 0 ? 1 : check.candidatePixels / check.referencePixels;
maeFrameSum += check.maeFrame;
if (check.attributed === 0) framesWithoutDrift++;
if (check.change) {
changePairs++;
if (check.change.verdict !== 'agrees') {
changeDisagreements++;
const gap = Math.abs(check.change.candidate - check.change.reference);
if (gap > worstChangeGap) {
worstChangeGap = gap;
worstChangeFrame = index;
}
}
}
if (check.mae > worstMae) {
worstMae = check.mae;
worstMaeFrame = index;
}
if (check.worstDrift !== null && check.worstDrift > worstDrift) {
worstDrift = check.worstDrift;
worstDriftFrame = index;
worstDriftSlot = check.worstSlot;
}
}
// The frames the set does not commit as files, against the sheet that holds
// them — see `SheetCheck`. After the frame loop, because it is measured in the
// box that loop was measured in.
const sheet = checkAgainstSheet(root, prepared, posable, viewport, background);
return {
...blank,
compared: frames.length,
sheet: sheet.sheet,
chains: chainChecks(chains, frames, tally),
chainDenominator: tally.total,
unattributedError: tally.unattributed,
meanMae: maeSum / frames.length,
meanMaeReference: maeReferenceSum / frames.length,
drawnRatio: drawnRatioSum / frames.length,
meanMaeFrame: maeFrameSum / frames.length,
textureFloor:
substitution === null
? null
: {
floor: floorSum.floor / frames.length,
aboveFloor: floorSum.aboveFloor / frames.length,
floorReference: floorSum.floorReference / frames.length,
aboveFloorReference: floorSum.aboveFloorReference / frames.length,
},
worstMae,
worstMaeFrame,
worstDrift,
worstDriftFrame,
worstDriftSlot,
framesWithoutDrift,
changePairs,
changeDisagreements,
worstChangeFrame,
frames,
notes: [...framing.notes, ...prepared.notes, ...sheet.notes],
};
}
/**
* How far a channel must move for a pixel to count as having **changed**.
*
* The same threshold `isContent` uses to decide there is anything there at all,
* and for the same reason: below it the difference is the rasteriser's own last
* bit, and a measure that counts those reports every frame as moving.
*/
export const CHANGE_TOLERANCE = BACKGROUND_TOLERANCE;
/**
* How many times more one side has to move than the other to be a disagreement,
* when **both** of them moved.
*
* Four, with `CHANGE_EXCESS` beside it, because a ratio alone means nothing on
* small counts. Together the two read: *four times as much, and at least two dozen
* pixels more.*
*/
export const CHANGE_RATIO = 4;
/**
* ...and how many pixels more, when both sides moved.
*
* Measured rather than picked. Across the corpus's two mechanically faithful
* transcriptions — the same skeleton on both sides, where the true answer is
* "identical" — the largest excess between two adjacent frames that clears
* `CHANGE_RATIO` at all is **12 px**, on one pair out of 152. Twenty-four is double
* that, and the case it has to keep is rung 6's broken plateau at 91 against 3.
*/
export const CHANGE_EXCESS = 24;
/**
* Did this side move materially more than that one?
*
* ⭐ **Stillness is categorical and gets no floor**, which is the reason this is a
* predicate and not a threshold. A held pose is held *exactly* — rung 6's reference
* is pixel-identical across f64-f67 — and a one-frame event is as small as the
* thing it reveals, which on that same shot is **three pixels**. A floor big enough
* to be safe about a moving frame would be big enough to hide both, so the two
* regimes are separated instead: against a still side, moving at all is the
* finding; against a moving side, `CHANGE_RATIO` and `CHANGE_EXCESS` apply.
* Measured: neither faithful transcription has a single pair where one side is
* still and the other is not.
*/
function disagrees(mine: number, theirs: number): boolean {
if (mine === 0) return false;
if (theirs === 0) return true;
return mine > theirs * CHANGE_RATIO && mine - theirs > CHANGE_EXCESS;
}
/**
* One frame against the frame before it, on each side, and what that says.
*
* ⚠️ Over the **whole frame**, and not over either side's content mask the way the
* MAE is. The omission is deliberate: a change is a change wherever it happens, and
* masking it would hide precisely the case where one side draws something the other
* does not — which is half of what this measure exists for. A one-frame reveal
* appears on background pixels by definition.
*/
function frameChange(
previous: { index: number; candidate: Plate; reference: Plate },
candidate: Plate,
reference: Plate,
): FrameChange {
const mine = plateDelta(previous.candidate, candidate);
const theirs = plateDelta(previous.reference, reference);
return {
previous: previous.index,
candidate: mine.pixels,
reference: theirs.pixels,
candidateMae: mine.mae,
referenceMae: theirs.mae,
verdict: disagrees(mine.pixels, theirs.pixels)
? 'moves'
: disagrees(theirs.pixels, mine.pixels)
? 'holds'
: 'agrees',
};
}
/**
* Changed pixels and mean absolute RGB difference between two plates of one size.
*
* Straight over `Plate.data` rather than through `Plate.get`, because this runs
* twice per compared frame over the whole grid and `get` allocates a four-element
* array per pixel. On the ladder's largest set that difference is most of what this
* measure costs.
*/
function plateDelta(before: Plate, after: Plate): { pixels: number; mae: number } {
const a = before.data;
const b = after.data;
const count = after.width * after.height;
let pixels = 0;
let sum = 0;
for (let i = 0; i < count * 4; i += 4) {
const dr = Math.abs(a[i] - b[i]);
const dg = Math.abs(a[i + 1] - b[i + 1]);
const db = Math.abs(a[i + 2] - b[i + 2]);
sum += dr + dg + db;
if (dr > CHANGE_TOLERANCE || dg > CHANGE_TOLERANCE || db > CHANGE_TOLERANCE) pixels++;
}
return { pixels, mae: sum / 3 / count };
}
/**
* Roll a set's frames up into one row per chain — the dashboard's rows.
*
* A chain that owns no slot is left out: it has nothing to attribute, and a row of
* dashes in every set is noise in a table read sixteen times. The roster at the
* foot of the report still lists it, so the account of where every bone went stays
* complete.
*/
function chainChecks(chains: BoneChain[], frames: FrameCheck[], tally: ChainTally): ChainCheck[] {
const out: ChainCheck[] = [];
chains.forEach((chain, index) => {
if (chain.slots.length === 0) return;
const own = new Set(chain.slots);
const drew = new Set();
let worstDrift = 0;
let worstDriftSlot: string | null = null;
let worstDriftFrame = -1;
let driftSum = 0;
let driftSamples = 0;
let driftFrames = 0;
for (const frame of frames) {
let sampled = false;
for (const track of frame.slots) {
if (!own.has(track.slot)) continue;
if (track.candidate !== null) drew.add(track.slot);
if (!isAttributable(track)) continue;
const drift = track.drift as number;
driftSum += drift;
driftSamples++;
sampled = true;
if (drift > worstDrift) {
worstDrift = drift;
worstDriftSlot = track.slot;
worstDriftFrame = frame.index;
}
}
if (sampled) driftFrames++;
}
out.push({
chain: chain.name,
slots: chain.slots.length,
drewSlots: drew.size,
worstDrift,
worstDriftSlot,
worstDriftFrame,
meanDrift: driftSamples === 0 ? 0 : driftSum / driftSamples,
driftSamples,
driftFrames,
error: tally.error[index],
referencePixels: tally.pixels[index],
mae: tally.pixels[index] === 0 ? 0 : tally.error[index] / tally.pixels[index],
maeShare: tally.total === 0 ? 0 : tally.error[index] / tally.total,
});
});
return out;
}
/**
* A set's error, being split between the candidate's chains as its frames are read.
*
* Carried across frames rather than parked on each `FrameCheck` because a share is
* a fact about the SET — and because a per-frame array of it would land in every
* `--json` report and every `bench.json` for a number nobody reads per frame.
*/
interface ChainTally {
/** Absolute difference over reference-drawn pixels attributed to each chain. */
error: number[];
/** How many such pixels each chain took. */
pixels: number[];
/** The same, over reference pixels no chain could take — the candidate drew nothing. */
unattributed: number;
/** Every reference-drawn pixel's difference, chain or not: the share's denominator. */
total: number;
}
/** How much a diagonal step costs the chamfer pass below. */
const DIAGONAL_STEP = Math.SQRT2;
/**
* Give every pixel of the frame the chain whose ink is nearest to it.
*
* Two chamfer passes over the owner mask — forward then backward, propagating
* (distance, label) together. It is an approximate Euclidean transform and that is
* enough: what it decides is which of a handful of well-separated regions a pixel
* belongs to, not a distance anybody reads.
*
* ⚠️ Nearest **ink the candidate drew**, so a chain that draws nothing seeds
* nothing and is handed no pixels at all — its share reads 0 % while its slots are
* missing entirely. That is why the table prints `drewSlots` beside the share: 0 %
* on `0/3 slots` is the loudest row here, not the quietest one.
*
* The distance comes back with the label because the caller bounds it — see
* `chainRadii`.
*/
function nearestOwner(owner: Int32Array, width: number, height: number): { label: Int32Array; dist: Float32Array } {
const label = Int32Array.from(owner);
const dist = new Float32Array(width * height);
for (let i = 0; i < label.length; i++) dist[i] = label[i] >= 0 ? 0 : Infinity;
const relax = (at: number, from: number, step: number): void => {
const reach = dist[from] + step;
if (reach >= dist[at]) return;
dist[at] = reach;
label[at] = label[from];
};
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const at = y * width + x;
if (x > 0) relax(at, at - 1, 1);
if (y > 0) {
relax(at, at - width, 1);
if (x > 0) relax(at, at - width - 1, DIAGONAL_STEP);
if (x + 1 < width) relax(at, at - width + 1, DIAGONAL_STEP);
}
}
}
for (let y = height - 1; y >= 0; y--) {
for (let x = width - 1; x >= 0; x--) {
const at = y * width + x;
if (x + 1 < width) relax(at, at + 1, 1);
if (y + 1 < height) {
relax(at, at + width, 1);
if (x + 1 < width) relax(at, at + width + 1, DIAGONAL_STEP);
if (x > 0) relax(at, at + width - 1, DIAGONAL_STEP);
}
}
}
return { label, dist };
}
/**
* How far each chain's attribution may reach, in frame pixels.
*
* The same judgement `src/slots.ts` makes about a slot — *past about its own long
* side a part no longer overlaps where it was, and something out there is another
* object rather than this one moved* — applied to the chain's own drawn box. Past
* it, reference ink is left **unattributed** instead of being handed to whichever
* chain happens to be nearest.
*
* ⚠️ This is the bound that keeps the dashboard honest about its own limits, and
* it is a bound rather than a fix. Nothing candidate-side can know which part of
* the REFERENCE a pixel belonged to; nearest-ink is a good guess while the figure
* is roughly in place and a bad one once a part has left. So a part displaced past
* its own size stops being blamed on its neighbour and starts showing up in the
* `(unattributed)` row, next to the `reference component(s) no slot reaches` count
* that says the same thing a different way.
*/
function chainRadii(
footprints: Map,
chainOfSlot: Map,
chains: number,
): Float64Array {
const minX = new Float64Array(chains).fill(Infinity);
const minY = new Float64Array(chains).fill(Infinity);
const maxX = new Float64Array(chains).fill(-Infinity);
const maxY = new Float64Array(chains).fill(-Infinity);
for (const [slot, foot] of footprints) {
const chain = chainOfSlot.get(slot);
if (chain === undefined || foot.pixels === 0) continue;
if (foot.minX < minX[chain]) minX[chain] = foot.minX;
if (foot.minY < minY[chain]) minY[chain] = foot.minY;
if (foot.maxX > maxX[chain]) maxX[chain] = foot.maxX;
if (foot.maxY > maxY[chain]) maxY[chain] = foot.maxY;
}
const out = new Float64Array(chains);
for (let i = 0; i < chains; i++) {
out[i] = maxX[i] < minX[i] ? -1 : searchRadius(maxX[i] - minX[i], maxY[i] - minY[i]);
}
return out;
}
function checkOneFrame(
index: number,
file: string,
frame: Frame,
pages: Map,
viewport: Viewport,
background: RGBA,
reference: Plate,
/** The candidate's own frame, rendered by the caller — it needs it too. */
rendered: Plate,
/** Slot name → chain index, for the per-chain split. */
chainOfSlot: Map,
/** Accumulated across the set by the caller — see `ChainTally`. */
tally: ChainTally,
/**
* The same frame drawn through another atlas's texels, when one was asked for —
* see `TextureFloor`. `null` is the ordinary case and costs nothing.
*/
floorPlate: Plate | null,
): { 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 =
owner !== null && owner.some((at) => at >= 0) ? nearestOwner(owner, viewport.width, viewport.height) : null;
const radii = chainRadii(footprints, chainOfSlot, tally.error.length);
let union = 0;
let candidatePixels = 0;
let referencePixels = 0;
let sum = 0;
let sumAll = 0;
// The decomposition's two numerators, over exactly the pixels `sum` runs over —
// one denominator for all three figures is what makes the triangle bound in
// `TextureFloor` hold as arithmetic rather than as an approximation.
let floorSum = 0;
let aboveSum = 0;
let floorReferenceSum = 0;
let aboveReferenceSum = 0;
for (let y = 0; y < viewport.height; y++) {
for (let x = 0; x < viewport.width; x++) {
const inCandidate = coverage[y * viewport.width + x] === 1;
const inReference = isContent(reference, x, y, background);
if (inCandidate) candidatePixels++;
if (inReference) referencePixels++;
const a = rendered.get(x, y);
const b = reference.get(x, y);
const delta = (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3;
sumAll += delta;
if (floorPlate !== null && (inCandidate || inReference)) {
const f = floorPlate.get(x, y);
const floor = (Math.abs(a[0] - f[0]) + Math.abs(a[1] - f[1]) + Math.abs(a[2] - f[2])) / 3;
const above = (Math.abs(f[0] - b[0]) + Math.abs(f[1] - b[1]) + Math.abs(f[2] - b[2])) / 3;
floorSum += floor;
aboveSum += above;
if (inReference) {
floorReferenceSum += floor;
aboveReferenceSum += above;
}
}
if (inReference) {
// The share's denominator is the reference's own drawn pixels, and the
// split is over exactly those — issue #119's lesson, as a partition.
tally.total += delta;
const at = y * viewport.width + x;
const found = nearest === null ? -1 : nearest.label[at];
const chain = found >= 0 && nearest !== null && nearest.dist[at] <= radii[found] ? found : -1;
if (chain >= 0) {
tally.error[chain] += delta;
tally.pixels[chain]++;
} else {
tally.unattributed += delta;
}
}
if (!inCandidate && !inReference) continue;
union++;
sum += delta;
}
}
const field = componentField(reference, background);
const components = field.components;
const { tracks, matchedComponents } = matchSlots(footprints, field, {
frame,
pages,
viewport,
background,
reference,
});
let worstDrift: number | null = null;
let worstSlot: string | null = null;
let attributed = 0;
let drawn = 0;
for (const track of tracks) {
if (track.candidate !== null) drawn++;
if (!isAttributable(track)) continue;
attributed++;
if (worstDrift === null || (track.drift as number) > worstDrift) {
worstDrift = track.drift;
worstSlot = track.slot;
}
}
const check: FrameCheck = {
index,
file,
mae: union === 0 ? 0 : sum / union,
// The same numerator over a denominator the candidate does not control — see
// `FrameCheck.maeReference`. Both figures are already in hand here, which is
// why the second one costs nothing to publish.
maeReference: referencePixels === 0 ? 0 : sum / referencePixels,
maeFrame: sumAll / (viewport.width * viewport.height),
unionPixels: union,
candidatePixels,
referencePixels,
components: components.length,
unmatchedComponents: components.length - matchedComponents,
worstSlot,
worstDrift,
attributed,
drawn,
slots: tracks,
// Filled in by the caller, which is the only place that has the frame before
// this one — see `frameChange`.
change: null,
textureFloor:
floorPlate === null
? null
: {
floor: union === 0 ? 0 : floorSum / union,
aboveFloor: union === 0 ? 0 : aboveSum / union,
floorReference: referencePixels === 0 ? 0 : floorReferenceSum / referencePixels,
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 };
}
// ---------------------------------------------------------------------------
// the contact sheet — see `SheetCheck`
// ---------------------------------------------------------------------------
/** A sheet's grid, in the terms the tiles are cut out with. */
interface SheetGeometry {
columns: number;
rows: number;
tileWidth: number;
tileHeight: number;
/** Tile pixels per frame pixel. */
tileScale: number;
}
/**
* A sheet's grid, **measured off the sheet** rather than taken on trust.
*
* `frames.json` records the frame count and the world box; it does not record the
* tile size, because `--tile` is a per-run choice and the sheet's own dimensions
* state the answer exactly. With `n` tiles in `c` columns the sheet is
* `c·(w+1)+1` by `ceil(n/c)·(h+1)+1`, so a column count either divides both
* dimensions exactly or is wrong — and the surviving candidate has to agree with
* the frames' own aspect ratio as well, since both tile sides came from one scale.
*
* `SHEET_COLUMNS` is tried first because it is the contract
* `bench/render_reference.ts` writes; the search behind it is what keeps a sheet
* rendered by something else readable, and what makes a mismatch a **named
* refusal** rather than a silent misread of somebody's grid.
*/
export function sheetGeometry(
sheet: Plate,
tiles: number,
pixelWidth: number,
pixelHeight: number,
): SheetGeometry | null {
if (tiles <= 0 || pixelWidth <= 0 || pixelHeight <= 0) return null;
const candidates = [SHEET_COLUMNS, ...Array.from({ length: Math.min(tiles, 64) }, (_, i) => i + 1)];
const slack = 1 / Math.max(pixelWidth, pixelHeight);
let best: { geometry: SheetGeometry; error: number } | null = null;
for (const columns of candidates) {
if (columns > tiles) continue;
const across = sheet.width - SHEET_GAP;
const rows = Math.ceil(tiles / columns);
const down = sheet.height - SHEET_GAP;
if (across % columns !== 0 || down % rows !== 0) continue;
const tileWidth = across / columns - SHEET_GAP;
const tileHeight = down / rows - SHEET_GAP;
if (tileWidth < 1 || tileHeight < 1) continue;
// Both tile sides are one scale, rounded — so the two ratios agree to within
// the rounding, and a grid that does not is a different grid.
const error = Math.abs(tileWidth / pixelWidth - tileHeight / pixelHeight);
if (error > slack) continue;
const geometry = { columns, rows, tileWidth, tileHeight, tileScale: tileWidth / pixelWidth };
if (best === null || error < best.error) best = { geometry, error };
if (columns === SHEET_COLUMNS) break;
}
return best === null ? null : best.geometry;
}
/**
* The label burned into a tile's corner, as a box to leave out of the comparison.
*
* `bench/render_reference.ts` paints the frame's index at `(2, 2)` in the tile at
* scale 1, and the candidate does not draw it. Left in, it would add the same
* constant to every tile and a bigger one to four-digit frames than to one-digit
* ones — a difference that is a fact about the labeller. The box is derived from
* the font's own metrics, with a pixel of margin, rather than measured once and
* written down.
*/
function labelBox(index: number): { width: number; height: number } {
return { width: 2 + textWidth(String(index), 1) + 1, height: 2 + GLYPH_H + 1 };
}
/**
* One frame set against its contact sheet, tile by tile.
*
* The candidate is rendered into the SAME world box the set was framed in, at the
* sheet's own scale — so a set framed by `frames.json`'s own box is compared here
* with no correction at all, and a set framed by a fit carries that fit (which,
* for a stills-plus-sheet set, was measured on the stills). The report says which.
*/
function checkAgainstSheet(
root: string,
prepared: PreparedSet,
posable: Pick,
viewport: Viewport,
background: RGBA,
): { sheet: SheetCheck | null; notes: string[] } {
const { set } = prepared;
const file = join(root, set.dir, SHEET_FILE);
if (!existsSync(file)) return { sheet: null, notes: [] };
const onDisk = framesOnDisk(root, set.dir).length;
// Every sampled frame already has a file of its own: the sheet is the same
// pictures again, smaller, and measuring them twice would just report the
// resampling.
if (onDisk >= set.sampled) return { sheet: null, notes: [] };
if (prepared.frames.length === 0) return { sheet: null, notes: [] };
const plate = readPlateFrom(root, file);
const geometry = sheetGeometry(plate, set.sampled, viewport.width, viewport.height);
if (geometry === null) {
return {
sheet: null,
notes: [
`${file} is ${plate.width}x${plate.height} px, which is not a grid of ${set.sampled} tile(s) at the ` +
`${viewport.width}x${viewport.height} aspect of these frames — so the whole shot was NOT compared, only ` +
`the ${onDisk} still(s) on disk. Re-render the set with bench/render_reference.ts if the sheet is stale.`,
],
};
}
const { columns, tileWidth, tileHeight, tileScale } = geometry;
const tileViewport = viewportOfSize(
viewport.minX,
viewport.minY,
viewport.maxX - viewport.minX,
viewport.maxY - viewport.minY,
viewport.scale * tileScale,
tileWidth,
tileHeight,
);
const compared = Math.min(set.sampled, prepared.frames.length);
let maeSum = 0;
let maeReferenceSum = 0;
let worstMae = 0;
let worstTile = -1;
const per: Array<{ index: number; mae: number }> = [];
for (let index = 0; index < compared; index++) {
const frame = prepared.frames[index];
const rendered = renderFrame(frame, posable.pages, tileViewport, background);
const ox = SHEET_GAP + (index % columns) * (tileWidth + SHEET_GAP);
const oy = SHEET_GAP + Math.floor(index / columns) * (tileHeight + SHEET_GAP);
const label = labelBox(index);
let union = 0;
let referencePixels = 0;
let sum = 0;
for (let y = 0; y < tileHeight; y++) {
for (let x = 0; x < tileWidth; x++) {
if (y < label.height && x < label.width) continue;
const sx = ox + x;
const sy = oy + y;
if (sx >= plate.width || sy >= plate.height) continue;
const inReference = isContent(plate, sx, sy, background);
const inCandidate = isContent(rendered, x, y, background);
if (inReference) referencePixels++;
if (!inReference && !inCandidate) continue;
const a = rendered.get(x, y);
const b = plate.get(sx, sy);
union++;
sum += (Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2])) / 3;
}
}
const mae = union === 0 ? 0 : sum / union;
maeSum += mae;
maeReferenceSum += referencePixels === 0 ? 0 : sum / referencePixels;
per.push({ index, mae });
if (mae > worstMae) {
worstMae = mae;
worstTile = index;
}
}
per.sort((a, b) => b.mae - a.mae);
return {
sheet: {
file,
columns,
tileWidth,
tileHeight,
tileScale,
tiles: set.sampled,
compared,
meanMae: compared === 0 ? 0 : maeSum / compared,
meanMaeReference: compared === 0 ? 0 : maeReferenceSum / compared,
worstMae,
worstTile,
worst: per.slice(0, WORST_FRAMES),
},
notes: [],
};
}
/** The sheet block, as the lines an author reads after the frame table. */
function sheetLines(sheet: SheetCheck | null): string[] {
if (sheet === null) return [];
const worst = sheet.worst
.map((tile) => `f${String(tile.index).padStart(4, '0')}=${tile.mae.toFixed(1)}`)
.join(' ');
return [
` sheet ${sheet.compared} of ${sheet.tiles} tile(s) of ${basename(sheet.file)} at ` +
`${sheet.tileWidth}x${sheet.tileHeight}px in ${sheet.columns} column(s) MAE mean ${f2(sheet.meanMae)} ` +
`worst ${f2(sheet.worstMae)} ${worstAt(sheet.worstTile, sheet.compared, 'tile(s)')} ` +
`(over the reference's own pixels, mean ${f2(sheet.meanMaeReference)})`,
' ⤷ the frames this set does not commit as files. The candidate is sampled at the set\'s own ' +
"rate and rendered into the same box the frames above were, at the sheet's scale. Read the " +
'series, not the mean: flat is framing or art, a spike is timing at that moment.',
` ⤷ worst ${sheet.worst.length}: ${worst}`,
];
}
// ---------------------------------------------------------------------------
// the report
// ---------------------------------------------------------------------------
/**
* How much more than the reference a set may draw before `check` calls it
* overdraw, as a ratio of drawn pixels.
*
* ## Why this direction needs its own warning
*
* `mae` divides by the pixels **either side drew** — the union — and the
* candidate owns half of that denominator. A large, mostly transparent sprite
* adds many cheap pixels to it and the *mean falls*, so anything optimising
* against `mae` can buy a better score by drawing more, which is the opposite of
* fidelity. Issue #119: spineboy-2's muzzle flare walked its own scale to 13x
* doing exactly this, and cost every set in that run its framing. Reproduced
* here, that candidate's `shoot` reads union MAE **39.65 against the honest
* build's 47.20** — the metric calls the flare an improvement — while the same
* difference over the reference's own pixels reads **73.06 against 52.54**.
*
* ⭐ Asymmetric on purpose. A candidate that draws LESS than the reference is
* being punished by the MAE, not rewarded, and needs no warning to find out.
*
* ## Where 1.5 comes from
*
* Measured over the corpus rather than picked. Across the twelve committed
* candidates in `bench/runs/` — 64 compared sets, 1 to 121 frames each — the
* ratio spans **0.852 … 1.069** on 62 of them, and the two above that are both
* the same shot on the same character: spineboy-1's `shoot@30fps` at 1.154 and
* spineboy-2's at **1.274**, two-frame stills sets where the muzzle flare lands
* a frame off. Rung 8's ball reads 1.041, rung 3's candidate 0.993.
*
* The 13x flare reads **1.850** on `shoot` and **3.199** on `shoot@30fps`, and
* 0.94–1.01 on the fourteen sets that do not draw it — so the warning names the
* shot the overdraw is in rather than colouring the whole run.
*
* 1.5 is the geometric middle of the gap between the widest honest reading and
* the weakest defective one (1.274 · 1.850 ≈ 1.535²): half again as much ink as
* the reference put down, which no honest candidate in the corpus approaches and
* which the case this was built for clears on both its sets.
*
* ## What was measured and rejected: the content boxes
*
* Issue #119 suggests the two content boxes, and `check` has both. Measured, that
* test is defeated by the framing it is measured through. `fitFraming` absorbs a
* uniform scale on purpose, so a candidate that draws everything too big reads a
* box growth of **−3.4 %** while its union MAE falls 137.6 → 36.0 — the fit
* simply shrinks it back. It also fires where nothing is overdrawn: the
* time-reversed fixture, whose ink is right and whose *timing* is wrong, reads
* **+14.1 %** because sampling a reversed shot lands on different poses. Counting
* ink is blind to both — that same reversed fixture draws **1.30–1.39x**, under
* the bar, and a bloated one draws what it drew whatever the framing does with it
* afterwards. C08 and C09 hold both ends of that.
*/
export const OVERDRAW_RATIO = 1.5;
/** How many worst frames a set prints when the whole set is too long to list. */
export const WORST_FRAMES = 8;
/** Sets no longer than this print every frame. */
const LIST_EVERY = 24;
const f2 = (n: number): string => n.toFixed(2);
export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }): string[] {
const lines: string[] = [];
lines.push(` candidate ${report.candidate.skeleton}`);
lines.push(` atlas ${report.candidate.atlas}`);
lines.push(` frames ${report.framesDir}`);
// Always printed, on both sides, because the reading a reader has to be able
// to make is "which picture of this rig is this" — and a line that appears
// only when a skin was named cannot say that the run used none (issue #571).
lines.push(
` skin candidate ${report.skin === null ? 'no skin set (the default skin alone)' : report.skin} ` +
`frames ${
report.referenceSkin === null ? `no skin recorded in ${FRAMES_SIDECAR}` : report.referenceSkin
}`,
);
// Always printed, like the skin line above it: which implementation posed the
// candidate, and why — `render`'s `poser` line, word for word (issue #968).
lines.push(` poser ${report.poser.note}`);
lines.push(
` scope ${
report.framingScope === 'per-shot'
? "the framing decided per frame set (--framing shared measures every set in one shared framing)"
: "one framing across every frame set (--framing per-shot lets a set take frames.json's own box instead)"
}`,
);
const v = report.viewport;
if (v !== null) lines.push(...framedToLines(v, report.framing));
const r = report.referenceViewport;
if (r) {
lines.push(
` reference ${r.pixelWidth}x${r.pixelHeight}px ${r.scale.toFixed(6)} px/unit ` +
`world x[${r.x.toFixed(1)} .. ${(r.x + r.width).toFixed(1)}] y[${r.y.toFixed(1)} .. ${(r.y + r.height).toFixed(1)}] (${FRAMES_SIDECAR})`,
);
lines.push(' ⤷ the two world boxes are different coordinate systems and do not compare; the pixel grid does.');
}
for (const line of framingLines(report.framingFit)) lines.push(line);
if (report.framingScope !== 'per-shot' || report.viewport !== null) {
for (const line of declaredBoxLines(report.declaredBox)) lines.push(line);
}
if (report.sharedFraming) {
const shared = report.sharedFraming;
const f = shared.fit;
const signed = (n: number): string => `${n >= 0 ? '+' : ''}${n.toFixed(2)}`;
lines.push(
` shared box one box for all ${report.animations.length} set(s) leaves x${f.scale.toFixed(6)} offset ` +
`${signed(f.dx)}, ${signed(f.dy)} px rms ${f.rms.toFixed(2)} px over ${f.frames * 4} edge(s) ` +
`(${shared.source}; used for every set that could not take the frames' own box)`,
);
lines.push(
" ⤷ how far one shared framing is from serving every set. A set below that took the frames' own " +
'box instead is measured with no such correction at all; --framing shared measures every set here.',
);
}
if (report.textureFrom) {
const t = report.textureFrom;
const scale = (values: number[] | null): string =>
values === null ? 'no atlas beside it to read a scale: line from' : values.length === 0 ? 'no scale: line' : `scale: ${[...new Set(values)].join(', ')}`;
lines.push(
` texture from ${t.atlas} (${scale(t.scales)}) against the candidate's own (${scale(t.candidateScales)})` +
`${t.unmatched.length === 0 ? '' : ` ⚠️ ${t.unmatched.length} region(s) not substituted`}`,
);
lines.push(
" ⤷ the candidate's own GEOMETRY through that atlas's texels — every world vertex is the " +
'candidate\'s, only the page and the UVs are swapped, and they are swapped through the drawing\'s own ' +
'coordinates so a rotated or trimmed pack re-seats nothing. What the two renders differ by is texture.',
);
if (t.unmatched.length > 0) {
lines.push(
` ⚠️ not substituted: ${t.unmatched.join(', ')}. Those pieces kept their own texture, so the ` +
'floor below is a MIXTURE and is a lower bound on the resampling rather than the whole of it.',
);
}
}
for (const note of report.notes) lines.push(` ⚠️ ${note}`);
lines.push('');
for (const anim of report.animations) {
const played =
anim.candidateAnimation !== null
? `candidate animation ${JSON.stringify(anim.candidateAnimation)}`
: anim.animation === null
? 'setup pose'
: 'nothing in the candidate to play against it';
lines.push(` ── ${anim.dir} — ${played}, ${anim.fps} fps ──`);
lines.push(
` frames ${anim.referenceFrames} on disk, candidate samples ${anim.candidateFrames}, ${anim.compared} compared`,
);
// Only when this set has a framing of its own: under a shared scope, or a pin,
// the header already printed the one box every set was measured in, and
// repeating it per set would read as though they differed.
if (report.framingScope === 'per-shot' && report.viewport === null) {
for (const line of framedToLines(anim.viewport, anim.framing, ' ')) lines.push(line);
for (const line of framingLines(anim.framingFit, ' ')) lines.push(line);
for (const line of declaredBoxLines(anim.declaredBox, ' ')) lines.push(line);
}
for (const note of anim.notes) lines.push(` ⚠️ ${note}`);
if (anim.compared === 0) {
lines.push('');
continue;
}
lines.push(
` MAE mean ${f2(anim.meanMae)} worst ${f2(anim.worstMae)} ${worstAt(anim.worstMaeFrame, anim.compared, 'frame(s)')}` +
` (0..255 over the union alpha; over the whole frame, mean ${f2(anim.meanMaeFrame)})`,
);
lines.push(
` ⤷ over the REFERENCE's own drawn pixels, mean ${f2(anim.meanMaeReference)} — the union figure ` +
'compares two builds of the same rig; this one is the one to optimise against, because the union is yours to grow.',
);
for (const line of textureFloorLines(anim)) lines.push(line);
if (anim.drawnRatio > OVERDRAW_RATIO) {
const mine = Math.round(anim.frames.reduce((sum, f) => sum + f.candidatePixels, 0) / anim.frames.length);
const theirs = Math.round(anim.frames.reduce((sum, f) => sum + f.referencePixels, 0) / anim.frames.length);
lines.push(
` ⚠️ overdraw: this shot draws ${mine.toLocaleString('en-US')} px a frame where the reference ` +
`draws ${theirs.toLocaleString('en-US')} — ${anim.drawnRatio.toFixed(2)}x as much ink, past the ` +
`${OVERDRAW_RATIO}x no committed candidate reaches. Most of that excess lands in the MAE's own ` +
'denominator and makes the figure above cheaper without moving a pixel closer, so read the one under it. ' +
'Something here is drawn that should not be, or is far too big.',
);
}
const blind =
anim.framesWithoutDrift === 0
? ''
: ` (${anim.framesWithoutDrift} of ${anim.compared} frame(s) attributed no slot at all)`;
lines.push(
anim.worstDriftFrame < 0
? ` slot drift no slot could be attributed in any of the ${anim.compared} frame(s) — read the MAE instead`
: ` slot drift worst ${anim.worstDrift.toFixed(1)} px ${JSON.stringify(anim.worstDriftSlot)} at ` +
`f${String(anim.worstDriftFrame).padStart(4, '0')}${blind}`,
);
const boundLine = driftBoundLine(anim);
if (boundLine !== null) lines.push(boundLine);
lines.push(changeSummary(anim));
for (const line of sheetLines(anim.sheet)) lines.push(line);
for (const line of chainTable(anim)) lines.push(line);
lines.push('');
const listed = framesToList(anim, opts?.allFrames === true);
const heading =
listed.length === anim.frames.length
? 'every frame'
: `the ${listed.length} frames worth reading — worst by MAE, plus every frame whose own change disagrees`;
lines.push(` ${heading}, in index order`);
lines.push(' frame MAE union px Δpx ref Δ worst slot drift how slots note');
for (const frame of listed) {
const worst = frame.slots.find((s) => s.slot === frame.worstSlot) ?? null;
const drift = frame.worstDrift === null ? ' —' : `${frame.worstDrift.toFixed(1).padStart(5)}`;
const how =
worst === null
? '— '
: worst.method === 'template'
? `tmpl ${(worst.confidence ?? 0).toFixed(2)}`
: 'component ';
const note = [changeNote(frame.change), frame.unmatchedComponents > 0 ? `${frame.unmatchedComponents} reference component(s) no slot reaches` : '']
.filter(Boolean)
.join('; ');
const change = frame.change
? `${String(frame.change.candidate).padStart(7)}${String(frame.change.reference).padStart(7)}`
: `${'—'.padStart(7)}${'—'.padStart(7)}`;
lines.push(
` f${String(frame.index).padStart(4, '0')} ${f2(frame.mae).padStart(8)} ${String(frame.unionPixels).padStart(9)} ${change} ` +
`${(frame.worstSlot ?? '—').padEnd(20)} ${drift} ${how.padEnd(9)} ${String(frame.attributed)}/${String(frame.drawn)}` +
`${note ? ` ${note}` : ''}`,
);
}
lines.push('');
}
for (const line of chainFoot(report)) lines.push(line);
lines.push(' MAE is the mean absolute RGB difference over the pixels either side covers, so it is');
lines.push(' read against 255 and not against a threshold: there is no pass mark here any more than');
lines.push(' there is one in `diff`. The figure under it divides the same difference by the pixels the');
lines.push(' REFERENCE drew — a denominator you cannot grow, which is what makes it the one to author');
lines.push(' against; it is not bounded by 255. Read the framing line first: it is upstream of every number');
lines.push(' below, and a residual much wider than a pixel moves all of them at once.');
lines.push(' The slots column is how many of the drawn slots could be attributed at all. A drift');
lines.push(' marked `tmpl` was correlated against the slot’s own pixels because the reference');
lines.push(' merged it into a neighbour; the number beside it is how much better that match was');
lines.push(' than its best rival, and a slot that matched nothing at all is left out of the count.');
lines.push(' Only the pixels of a slot that its own composite lets show are correlated — one it');
lines.push(' draws over itself matches nothing at any offset, so leaving it in moves the answer');
lines.push(' rather than costing it. A slot covered everywhere reports no drift and says so. The');
lines.push(' `⤷ bounded by` line under a drift is what that figure could have reached: for a');
lines.push(` template match, its whole-pixel winner plus ${SUBPIXEL_CLAMP} px on each axis — so a winner at`);
lines.push(
` the offset you drew bounds the whole figure at ${hypot2(SUBPIXEL_CLAMP, SUBPIXEL_CLAMP).toFixed(2)} px ` +
'and says the drift is the',
);
lines.push(' instrument, not the rig. Read every drift against its own line and not against a page.');
lines.push(' A `sheet` line is the frames a set does not commit as files: the candidate sampled at the');
lines.push(" set's own rate against the tiles of its contact.png, in the same box the frame table used.");
lines.push(' Read it as a series — flat is framing or art, a spike is timing at that moment — and note');
lines.push(' that it is MAE only: the change columns below are pixel counts at frame scale.');
lines.push(' `Δpx` and `ref Δ` are how many pixels each side moved since ITS OWN previous frame —');
lines.push(' not against each other. They are the only columns that can see a held pose that is');
lines.push(' not held, or a one-frame event that never fired: both are small in every frame and');
lines.push(' wrong only in the relation between two, which is where the MAE cannot look.');
return lines;
}
/**
* One set's texture decomposition, as the two lines under its MAE — see
* `TextureFloor`.
*
* ⭐ The **bound** is printed as arithmetic and not as prose. `mae − aboveFloor`
* is what the texture explained on these frames and `floor` is the most it could
* have; a reader who is given only the second is one subtraction away from
* treating it as the first, which is the error `TextureFloor`'s own doc exists to
* head off.
*/
function textureFloorLines(anim: AnimationCheck): string[] {
const t = anim.textureFloor;
if (t === null) return [];
const explained = anim.meanMae - t.aboveFloor;
const share = anim.meanMae > 0 ? ` (${((explained / anim.meanMae) * 100).toFixed(1)}% of the figure above)` : '';
return [
` ⭐ texture floor ${f2(t.floor)} above it ${f2(t.aboveFloor)} (over the reference's own ` +
`pixels, ${f2(t.floorReference)} and ${f2(t.aboveFloorReference)})`,
` ⤷ the same geometry through the other atlas's texels reads ${f2(t.aboveFloor)}, so the ` +
`texture accounts for ${f2(explained)} of this set's MAE${share} and cannot account for more than ` +
`${f2(t.floor)} — |MAE − above| ≤ floor, because absolute errors bound rather than add. A floor near zero ` +
'is proof the texture is not the story here. 🚫 The figure of record is the MAE above, not this.',
];
}
/**
* Which frame carried the worst MAE — or that none did.
*
* `AnimationCheck.worstMaeFrame` and `SheetCheck.worstTile` are `-1` when **no
* compared frame differs from the reference at all**, because each worst is
* tracked with a strict `>` from zero. That is the identity run, which is the run
* an author calibrates on, and until issue #678 the sentinel went straight
* through `padStart(4, '0')` and printed as `at f00-1` — a frame index that
* cannot exist, on the two reports that are supposed to read as *nothing to
* report*.
*
* ⚠️ The same sentinel is carried by `worstDriftFrame` and `worstChangeFrame`,
* and both of those were already guarded where they print. Two of the four sites
* had the idiom and two did not, which is the whole defect.
*/
function worstAt(frame: number, compared: number, unit: string): string {
if (frame >= 0) return `at f${String(frame).padStart(4, '0')}`;
return `(exact: none of the ${compared} compared ${unit} differs from the reference)`;
}
/**
* What bounds the drift the summary line just printed.
*
* ⭐ A drift figure is unreadable on its own, and issue #698 is the bill for that:
* §9.2 told an author to read one against `hypot(0.5, 0.5) = 0.71 px`, and four of
* the seven shipped examples printed more than that against frames rendered from
* themselves. The bound is per match and it is derived: a template match's
* whole-pixel winner says how much of the figure is a *displacement*, and the
* sub-pixel step can add at most `SUBPIXEL_CLAMP` on each axis to it. So a reader
* comparing 0.4 px to a floor now sees the floor the match itself carries rather
* than one read off a page about another rig.
*
* A component match has no such bound — the distance between two centroids is
* bounded by nothing but how far this slot was allowed to have moved — and the
* line says that instead of inventing one.
*/
function driftBoundLine(anim: AnimationCheck): string | null {
if (anim.worstDriftFrame < 0 || anim.worstDriftSlot === null) return null;
const frame = anim.frames.find((f) => f.index === anim.worstDriftFrame);
const track = frame?.slots.find((s) => s.slot === anim.worstDriftSlot) ?? null;
if (track === null) return null;
if (track.method === 'component') {
return (
' ⤷ a component match: the distance between two centroids, bounded by nothing but the ' +
`${String(track.searchRadius)} px this slot could have moved and still be itself`
);
}
const bound = driftBound(track);
if (bound === null || track.wholePixel === null) return null;
const { dx, dy } = track.wholePixel;
return dx === 0 && dy === 0
? ` ⤷ bounded by ${bound.toFixed(2)} px — the correlation put this slot where the candidate ` +
`drew it, so the whole figure is the sub-pixel step, clamped to ${SUBPIXEL_CLAMP} px on each axis`
: ` ⤷ bounded by ${bound.toFixed(2)} px — the correlation moved this slot by (${dx}, ${dy}) ` +
`whole pixel(s), plus a sub-pixel step clamped to ${SUBPIXEL_CLAMP} px on each axis`;
}
/** One drift, as the table says it: distance, slot, frame. */
function driftPhrase(drift: number, slot: string | null, frame: number): string {
if (slot === null) return 'no slot attributable';
return `${drift.toFixed(1)} px ${JSON.stringify(slot)} f${String(frame).padStart(4, '0')}`;
}
/** One set, broken down by chain — see `ChainCheck`. */
function chainTable(anim: AnimationCheck): string[] {
if (anim.chains.length === 0) return [];
const out: string[] = [];
out.push(
` chains ${anim.chains.length} from the candidate's own bone tree — the roster is at the foot of the report`,
);
out.push(
` ${'chain'.padEnd(20)} ${'slots'.padStart(6)} ${'worst slot drift'.padEnd(33)} ` +
`${'mean'.padStart(8)} ${'MAE in it'.padStart(9)} ${'share'.padStart(6)}`,
);
// Derivation order rather than worst-first, so the same row is in the same place
// in every set's table and a run can be read down a column.
for (const chain of anim.chains) {
const mean = chain.driftSamples === 0 ? '—' : `${chain.meanDrift.toFixed(1)} px`;
out.push(
` ${chain.chain.padEnd(20)} ${`${chain.drewSlots}/${chain.slots}`.padStart(6)} ` +
`${driftPhrase(chain.worstDrift, chain.worstDriftSlot, chain.worstDriftFrame).padEnd(33)} ` +
`${mean.padStart(8)} ${f2(chain.mae).padStart(9)} ${`${(chain.maeShare * 100).toFixed(1)}%`.padStart(6)}`,
);
}
if (anim.unattributedError > 0 && anim.chainDenominator > 0) {
const share = (anim.unattributedError / anim.chainDenominator) * 100;
out.push(
` ${'(unattributed)'.padEnd(20)} ${'—'.padStart(6)} ${'—'.padEnd(33)} ${'—'.padStart(8)} ` +
`${'—'.padStart(9)} ${`${share.toFixed(1)}%`.padStart(6)}`,
);
}
out.push(
" ⤷ share is of this set's own difference over the REFERENCE's drawn pixels, split by nearest ink; " +
'`MAE in it` is that same error per pixel. The rule, the denominator and what a 0 % row means are under ' +
'"chains" at the foot of the report.',
);
return out;
}
/** One line per chain across every set, plus the roster the names refer to. */
function chainFoot(report: CheckReport): string[] {
if (report.chains.length === 0) return [];
const out: string[] = [];
out.push(' ── chains ──');
out.push(
" Cut from the CANDIDATE's own bone tree at every branch point: a chain runs from a root or a fork down to the",
);
out.push(
' next fork, a single-bone chain that is itself a fork folds into its parent, and each is named after the first',
);
out.push(
' bone in it that carries a slot. The reference is still nothing but pixels — this is your figure decomposed,',
);
out.push(' not the reference’s, which is what keeps it inside the ladder’s honesty rule.');
out.push('');
out.push(" MAE share divides the difference over the REFERENCE's own drawn pixels — the denominator from the MAE");
out.push(' line above, which nothing you draw can grow — and splits it by giving each of those pixels to the chain');
out.push(' whose ink is NEAREST it. So the shares are a partition and add to the whole, and no chain can look');
out.push(' better by drawing more: growing its ink only pulls more of the reference’s pixels, and their error,');
out.push(' into it. `MAE in it` is the same error per pixel it took, and it is the column that separates a chain');
out.push(' that is WRONG from one that is merely large — a head and its features cover a lot of a figure and can');
out.push(' carry a third of the error at a below-average figure per pixel.');
out.push('');
out.push(' ⚠️ Two things the split cannot do, both of which show rather than hide. Reference ink further from your');
out.push(' ink than the part’s own size is left `(unattributed)` instead of blamed on a neighbour, so a part that');
out.push(' has left its place stops being charged to whatever is next to it. And a chain that draws NOTHING seeds');
out.push(' nothing and reads 0 % — which is why the slots column is beside the share: 0 % on 0 slots drawn is the');
out.push(' loudest row here, not the quietest.');
out.push(` ${'chain'.padEnd(20)} ${'bones'.padEnd(57)} slots`);
for (const chain of report.chains) {
out.push(
` ${chain.name.padEnd(20)} ${chain.bones.join(', ').padEnd(57)} ` +
`${chain.slots.length === 0 ? '(draws nothing)' : chain.slots.join(', ')}`,
);
}
const rows = chainRollup(report);
if (rows.length === 0) return out;
out.push('');
out.push(
` ${'chain'.padEnd(20)} ${'worst slot drift across every set'.padEnd(56)} ` +
`${'mean'.padStart(8)} ${'MAE in it'.padStart(9)} ${'share'.padStart(6)}`,
);
for (const row of rows) {
const where = row.set === null ? '' : ` in ${row.set}/f${String(row.frame).padStart(4, '0')}`;
const worst =
row.slot === null ? 'no slot attributable in any set' : `${row.drift.toFixed(1)} px ${JSON.stringify(row.slot)}${where}`;
const mean = row.samples === 0 ? '—' : `${row.mean.toFixed(1)} px`;
out.push(
` ${row.chain.padEnd(20)} ${worst.padEnd(56)} ${mean.padStart(8)} ` +
`${(row.pixels === 0 ? 0 : row.error / row.pixels).toFixed(2).padStart(9)} ` +
`${`${(row.share * 100).toFixed(1)}%`.padStart(6)}`,
);
}
out.push('');
return out;
}
interface ChainRollup {
chain: string;
drift: number;
slot: string | null;
set: string | null;
frame: number;
mean: number;
samples: number;
error: number;
pixels: number;
share: number;
}
/**
* Each chain's worst reading anywhere in the run, worst share first.
*
* Worst-first here and derivation order in the per-set tables, deliberately: this
* is the line a run’s README quotes, so it is ranked by what to fix, while a table
* printed once per set is ranked so the sets line up.
*/
function chainRollup(report: CheckReport): ChainRollup[] {
const rows = new Map();
let denominator = 0;
for (const anim of report.animations) {
if (anim.compared === 0) continue;
denominator += anim.chainDenominator;
for (const chain of anim.chains) {
const row = rows.get(chain.chain) ?? {
chain: chain.chain,
drift: 0,
slot: null,
set: null,
frame: -1,
mean: 0,
samples: 0,
error: 0,
pixels: 0,
share: 0,
};
if (chain.worstDriftSlot !== null && chain.worstDrift > row.drift) {
row.drift = chain.worstDrift;
row.slot = chain.worstDriftSlot;
row.set = anim.dir;
row.frame = chain.worstDriftFrame;
}
row.mean = row.mean * row.samples + chain.meanDrift * chain.driftSamples;
row.samples += chain.driftSamples;
row.mean = row.samples === 0 ? 0 : row.mean / row.samples;
row.error += chain.error;
row.pixels += chain.referencePixels;
rows.set(chain.chain, row);
}
}
const out = [...rows.values()];
for (const row of out) row.share = denominator === 0 ? 0 : row.error / denominator;
return out.sort((a, b) => b.share - a.share);
}
/**
* The frames worth printing: the worst by MAE, plus every change disagreement.
*
* The union matters rather than being tidy. The defects `FrameChange` exists to
* catch are **cheap in MAE by construction** — a plateau sloped through by a
* fraction of a pixel, a three-pixel reveal that did not fire — so a listing
* ranked by MAE is exactly the listing that leaves them out. Rung 6's f65–f68 sit
* near the bottom of that ranking.
*/
export function framesToList(anim: AnimationCheck, allFrames: boolean): FrameCheck[] {
if (allFrames || anim.frames.length <= LIST_EVERY) return anim.frames;
const chosen = new Set(
[...anim.frames]
.sort((a, b) => b.mae - a.mae)
.slice(0, WORST_FRAMES)
.map((f) => f.index),
);
for (const frame of anim.frames) if (frame.change && frame.change.verdict !== 'agrees') chosen.add(frame.index);
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>();
/** Per set: whether the whole set will be listed, so everything is kept. */
private readonly whole = new Map();
/** Per set: the running worst by MAE, worst first, at most `WORST_FRAMES`. */
private readonly ranked = new Map>();
/** Per set: frames kept because their change disagrees, whatever their MAE. */
private readonly disagreeing = new Map>();
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, 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, 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) {
return (
' per-frame no two compared frames are adjacent, so nothing was measured about how much this shot ' +
'changes from frame to frame'
);
}
if (anim.changeDisagreements === 0) {
return ` per-frame all ${anim.changePairs} adjacent pair(s) change by as much as the reference's own frames do`;
}
const worst = anim.frames.find((f) => f.index === anim.worstChangeFrame);
const at =
worst && worst.change
? `; worst f${String(worst.index).padStart(4, '0')}, yours moved ${worst.change.candidate} px where the ` +
`reference moved ${worst.change.reference}`
: '';
return (
` per-frame ${anim.changeDisagreements} of ${anim.changePairs} adjacent pair(s) change by a different ` +
`amount than the reference does${at}`
);
}
/** What one frame's change disagreement says, in the words that name the defect. */
function changeNote(change: FrameChange | null): string {
if (!change || change.verdict === 'agrees') return '';
if (change.verdict === 'moves') {
return change.reference === 0
? 'the reference holds still here and yours does not'
: `yours moves ${(change.candidate / Math.max(1, change.reference)).toFixed(0)}x the reference`;
}
return change.candidate === 0
? 'the reference moves here and yours holds still'
: `yours moves ${(change.reference / Math.max(1, change.candidate)).toFixed(0)}x less than the reference`;
}
/**
* What the fit did, in one word.
*
* The declared box is never "unsettled" — it was not being iterated towards, it
* was measured and kept, and `coincident` says the measurement that kept it.
*/
function convergence(framing: FramingReport): string {
if (framing.settled) return 'settled';
// `extent-spread` cannot collide with `settled` above: it is only reached when
// the correction is over `COINCIDENT_PIXELS`, and settled is under a tenth of one.
if (framing.source === 'declared') return framing.agrees ? 'coincident' : 'extent-spread';
return framing.cycled ? 'cycling' : 'unsettled';
}
/**
* The declared-box probe, as the one line that says which clause decided and by
* how much — see `DeclaredBoxProbe`.
*
* Printed whether the box was taken or refused. A refusal used to be legible only
* as the *absence* of `frames.json's own box` from the line above it, which is
* exactly the shape of report a reader cannot check: rung 7 was refused on twelve
* sets and the run had to reconstruct why from a diagnostic re-run (issue #194).
*/
function declaredBoxLines(probe: DeclaredBoxProbe | null, indent = ''): string[] {
if (probe === null) return [];
if (probe.clause === 'no-pixels') {
return [
`${indent} declared ${FRAMES_SIDECAR}'s own box: REFUSED — the candidate draws no pixel at all in it, ` +
'which is the loudest possible "not these coordinates".',
];
}
const asks = `a fit there asks for ${probe.distance.toFixed(2)} px`;
const said =
probe.clause === 'coincident'
? `TAKEN, coincident — ${asks}, under the ${COINCIDENT_PIXELS} px that separates a candidate in the frames' ` +
'coordinates from one in its own'
: probe.clause === 'extent-spread'
? `TAKEN, extent-spread — ${asks}, within the ${probe.reach.toFixed(2)} px this tolerance reaches ` +
`(${(EXTENT_SPREAD_REACH * 100).toFixed(0)}% of the reference's box), and leaves ${probe.rms.toFixed(2)} ` +
'px rms no similarity can absorb, which is a silhouette and not a transform'
: `REFUSED, coordinates — ${asks}, ` +
(probe.distance > probe.reach
? `past the ${probe.reach.toFixed(2)} px the extent-spread tolerance reaches`
: `and explains all but ${probe.rms.toFixed(2)} px rms of it`) +
' — a different origin or a different unit';
return [`${indent} declared ${FRAMES_SIDECAR}'s own box: ${said}, over ${probe.frames} frame(s).`];
}
/** The framing, as the line an author reads before anything else. */
/** The `framed to` line: the box that was rendered into, and how it was chosen. */
function framedToLines(v: Framing, how: FramingHow | null, indent = ''): string[] {
const said =
how === 'candidate-pixels'
? "fitted to the candidate's own drawn pixels"
: how === 'frames-viewport'
? `${FRAMES_SIDECAR}'s own box — the candidate measured into it`
: '--viewport';
return [
`${indent} framed to ${v.pixelWidth}x${v.pixelHeight}px ${v.scale.toFixed(6)} px/unit ` +
`world x[${v.x.toFixed(1)} .. ${(v.x + v.width).toFixed(1)}] y[${v.y.toFixed(1)} .. ${(v.y + v.height).toFixed(1)}] (${said})`,
];
}
/**
* What the MAE-refined pass found, in the words that separate its four answers.
*
* All four are printed, the identity included, because "the framing is already
* where the picture is" is a measurement this pass makes and not a default it
* falls back to — the same reason an assertion with nothing to measure reports
* SKIP here rather than a pass. The two that decline a real offset are the loud
* ones: they say the constant pixel is in the candidate rather than in the box.
*/
function refinementLines(refinement: FramingRefinement | null, indent = ''): string[] {
if (refinement === null) return [];
const { dx, dy, before, after, radius, frames } = refinement;
const at = `${dx >= 0 ? '+' : ''}${dx}, ${dy >= 0 ? '+' : ''}${dy} px`;
const worth =
`${f2(before)} → ${f2(after)} over the reference's own pixels` +
(before > 0 ? ` (${(((before - after) / before) * 100).toFixed(1)}% of the figure)` : '');
const searched = `±${radius} px over ${frames} frame(s)`;
if (refinement.declined === 'identity') {
return [
`${indent} ⤷ MAE-refined pass: searched ${searched} and the identity won, so no part of this set's ` +
'figure is a constant offset.',
];
}
if (refinement.declined === 'below-threshold') {
return [
`${indent} ⤷ MAE-refined pass: the best offset in ${searched} was ${at}, worth ${worth} — under the ` +
`${(REFINE_MIN_GAIN * 100).toFixed(0)}% / ${REFINE_MIN_GAIN_MAE.toFixed(2)} MAE this pass moves a box for, so ` +
'the box was left alone.',
];
}
if (refinement.declined === 'box-is-exact') {
return [
`${indent} ⚠️ a constant ${at} would take this set ${worth} — and it was NOT applied, because this ` +
`box is ${FRAMES_SIDECAR}'s own and is not an estimate of anything. A constant pixel inside the box the ` +
'frames were drawn at is your own figure sitting a pixel off, which is a thing to fix rather than to frame ' +
'away. Read it beside the drift below.',
];
}
if (refinement.declined === 'pinned') {
return [
`${indent} ⤷ a constant ${at} would take this set ${worth} — measured, NOT applied, because ` +
'--viewport pinned the box.',
];
}
return [
`${indent} ⭐ MAE-refined by ${at}: ${worth}. The fit above registers the two extents, and the best ` +
'fit of two extents is not the best alignment of two pictures — this pass takes that difference out, so the ' +
'figures below are what is left after it rather than a constant offset read as motion.',
];
}
function framingLines(framing: FramingReport | null, indent = ''): string[] {
if (!framing) return [];
const { fit } = framing;
const c = fit.candidate;
const r = fit.reference;
const percent = (n: number): string => `${n >= 0 ? '+' : ''}${(n * 100).toFixed(2)}%`;
const box = (b: ContentBox): string =>
`${boxWidth(b).toFixed(1)}x${boxHeight(b).toFixed(1)}px at (${b.left.toFixed(1)}, ${b.top.toFixed(1)})`;
const signed = (n: number): string => `${n >= 0 ? '+' : ''}${n.toFixed(2)}`;
const out = [
`${indent} content candidate ${box(c)} reference ${box(r)} (union over ${fit.frames} frame(s))`,
`${indent} ⤷ fit x${fit.scale.toFixed(6)} offset ${signed(fit.dx)}, ${signed(fit.dy)} px ` +
`rms ${fit.rms.toFixed(2)} px over ${fit.frames * 4} edge(s) ` +
`union residual ${signed(fit.residualWidth)} x ${signed(fit.residualHeight)} px ` +
`aspect ${percent(fit.aspectError)}` +
(framing.applied
? ` (${framing.source}, ${framing.passes} pass(es), ${convergence(framing)})`
: ' (measured, NOT applied — --viewport pinned)'),
];
out.push(...refinementLines(framing.refinement, indent));
const spread = Math.max(Math.abs(fit.residualWidth), Math.abs(fit.residualHeight));
if (spread > 1) {
const axis = fit.residualWidth > 0 ? 'wider' : 'narrower';
out.push(
`${indent} ⚠️ after the fit your shot still covers ${Math.abs(fit.residualWidth).toFixed(1)} px ` +
`${axis} and ${Math.abs(fit.residualHeight).toFixed(1)} px ` +
`${fit.residualHeight > 0 ? 'taller' : 'shorter'} than the reference's. One uniform scale cannot absorb ` +
'that: something reaches somewhere nothing in the frames does, or is a different size. Read it before ' +
'reading a drift.',
);
}
if (fit.rms > 1) {
out.push(
`${indent} ⚠️ the fit leaves ${fit.rms.toFixed(2)} px rms across the frames' edges, so no single ` +
'scale and offset puts the two shots on each other — they are different shapes, not the same shape ' +
'misframed.',
);
}
const units = framing.units;
if (units) {
out.push(
`${indent} in units candidate ${units.candidate.width.toFixed(1)} x ${units.candidate.height.toFixed(1)} ` +
`reference ${units.reference.width.toFixed(1)} x ${units.reference.height.toFixed(1)} ` +
`x${units.ratio.toFixed(4)}`,
);
out.push(
`${indent} ⤷ the same two boxes in world units. The framing absorbs a difference of pure scale on ` +
'purpose — a rig is authored in its own coordinates — so this is the only place one shows. It compares ' +
'only if you measured the shot in the frames’ own units.',
);
}
return out;
}