@rig-c/parts 0.0.0-stage → 1.5.4

package/src/coords.ts

@@ -0,0 +1,26 @@
+/**
+ * The one door to the coordinate conversion.
+ *
+ * Everything this package measures is in crop pixels — y down, origin at the
+ * top-left — because that is what a painting, a See-through layer and a part
+ * PNG are. Spine's world is y up with its origin at the bottom-left of the
+ * crop. rig-c owns that conversion (`src/transform.ts`: `cropToSpineY`,
+ * `toBoneLocal`, `computeWorldTransforms`) and its own doctrine forbids a
+ * second copy of it anywhere, so this package does not write one: every stage
+ * that needs Spine coordinates imports them from here, and here re-exports
+ * rigc's.
+ *
+ * A y flip written anywhere else in `src/` is the defect this file exists to
+ * prevent; the selftest holds the tree to it.
+ *
+ * The same goes for a bone's frame. Since issue #73 a chain link is turned to
+ * point along its chain, so a point under it is placed by inverting the
+ * link's setup matrix: `src/rig.ts` evaluates the setup pose with rigc's
+ * `computeExactFrameTransforms` (the textbook arithmetic, in which an
+ * unturned bone's frame is the identity exactly, so a bone that is not turned
+ * writes the very numbers it wrote before) and binds through `toBoneLocal`;
+ * `flattenRig` goes back through `toWorld`. No rotation matrix is written out
+ * by hand in this package.
+ */
+export { computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toWorld } from 'rig-c/src/transform.ts';
+export type { BoneTransform } from 'rig-c/src/transform.ts';

package/src/diagnostics.ts

@@ -0,0 +1,198 @@
+/**
+ * What `propose` looked at, said (issue #86): the coverage lines lint's
+ * per-bone record prints, and the basis file written beside the proposal.
+ *
+ * ## Coverage
+ *
+ * `lint` (`src/propose.ts`) returns, beside its findings, one record per bone
+ * of the spec: the checks that read it, or why none did. {@link coverageLines}
+ * prints one line per bone and a summary that counts "checked, clean",
+ * "checked, LINT" and "not checked" apart, with the roles
+ * (`src/structure.ts`'s {@link configRoles}, imported, never derived again).
+ * The lines are printed after every line `propose` printed before them, so
+ * nothing that was printed before changes.
+ *
+ * ## The basis file
+ *
+ * `basis.json` (spec {@link BASIS_SPEC}) records, for every bone the proposal
+ * places, what its origin — and its tip, where the proposal states one —
+ * rests on: a joint (`joint`), a measurement off a part (`mask`), a rule of
+ * proportion (`ratio`) or other bones (`derived`), recorded in `propose()`
+ * where the placement happens. Under `propose --compare <config>` each bone
+ * also says whether the config's bone differs from the proposal's and by how
+ * far, through `src/structure.ts`'s comparison (origin, tip and parent); a
+ * bone only one side has is said to be that, and nothing more is inferred —
+ * a difference is a fact, not a verdict on either side. No confidence figure
+ * is computed anywhere; a score a keypoint file carried is recorded as the
+ * file's.
+ *
+ * The file is written only after green: {@link checkBasis} holds it to the
+ * proposal and the parts before anything is written, and refuses by name.
+ * Fixed key order, two-space indent, trailing newline — the same inputs
+ * write the same bytes.
+ */
+import { type Problem, refuseIfAny } from './errors.ts';
+import { BASIS_KINDS, type BasisKind, type BoneBasis, type BoneCoverage, COVERAGE_OUTCOMES, coverageOutcome, expand, FRAME_KEYS, type FrameBasis, type FrameKey, type PartSet, type Placement, type Proposal, type ProposalBasis } from './propose.ts';
+import { BONE_ROLES, type BoneRole, compareStructure, readSkeleton } from './structure.ts';
+
+export const BASIS_SPEC = 'spine-parts-basis/1';
+
+/** The file's name, beside `proposal.json`. */
+export const BASIS_FILE = 'basis.json';
+
+/**
+ * Under `--compare`: the config's bone against the proposal's. `status` is
+ * `differs` when its origin or tip is anywhere else, or its parent is another
+ * bone, or one side states a tip the other does not; `proposal only` when the
+ * config has no bone of that name.
+ */
+export interface ConfigDelta {
+  status: 'same' | 'differs' | 'proposal only';
+  /** Rig px between the two origins; `null` for a bone the config does not have. */
+  origin_px: number | null;
+  /** Rig px between the two tips; `null` with `tip_why` when it is not a figure. */
+  tip_px: number | null;
+  tip_why: string | null;
+  parent: { proposal: string; config: string | null };
+}
+
+export interface BasisRecord extends BoneBasis {
+  /** `null` without `--compare`. */
+  config: ConfigDelta | null;
+}
+
+export interface BasisFile {
+  spec: typeof BASIS_SPEC;
+  frame: Record<FrameKey, FrameBasis>;
+  /** The config `--compare` named, as `structure.ts` labels it; `null` without `--compare`. */
+  compared_with: string | null;
+  bones: BasisRecord[];
+  /** Under `--compare`, the config's bones the proposal does not have; `null` without it. */
+  config_only: string[] | null;
+}
+
+/**
+ * Hold the record to the proposal before it is written: one record per
+ * proposed bone, in the proposal's order, and every name it gives resolves —
+ * each part to a part of the set, each bone to a bone of the proposal. A
+ * `joint` placement names at least one joint and every other kind none; a
+ * `derived` placement names at least one bone; a constant is a finite number.
+ */
+export function checkBasis(P: PartSet, proposal: Proposal, basis: ProposalBasis): void {
+  const problems: Problem[] = [];
+  const names = [...expand(proposal.bones).byName.keys()];
+  const bones = new Set(names);
+  const parts = new Set(P.recs.map((p) => p.name));
+  const recorded = basis.bones.map((b) => b.bone);
+  if (recorded.join('\n') !== names.join('\n')) {
+    const missing = names.filter((n) => !recorded.includes(n));
+    const extra = recorded.filter((n) => !bones.has(n));
+    const twice = recorded.filter((n, i) => recorded.indexOf(n) !== i);
+    problems.push({
+      code: 'BASIS_RECORDS_EVERY_BONE',
+      object: BASIS_FILE,
+      detail:
+        `records ${recorded.length} bone(s) for the proposal's ${names.length}; one record per proposed bone, in the proposal's order, is required` +
+        `${missing.length > 0 ? `; none for ${missing.join(', ')}` : ''}${extra.length > 0 ? `; records ${extra.join(', ')}, which the proposal does not place` : ''}${twice.length > 0 ? `; twice: ${twice.join(', ')}` : ''}` +
+        `${missing.length === 0 && extra.length === 0 && twice.length === 0 ? ' (the same bones in another order)' : ''}`,
+    });
+  }
+  for (const [k, f] of Object.entries(basis.frame)) {
+    for (const p of f.parts) if (!parts.has(p)) problems.push({ code: 'BASIS_NAMES_RESOLVE', object: `${BASIS_FILE} frame.${k}`, detail: `names the part "${p}", which parts.json does not hold` });
+  }
+  const hold = (b: BoneBasis, which: 'origin' | 'tip', pl: Placement): void => {
+    const object = `${BASIS_FILE} bone "${b.bone}" ${which}`;
+    if (!BASIS_KINDS.includes(pl.kind)) problems.push({ code: 'BASIS_KIND_KNOWN', object, detail: `has the kind ${JSON.stringify(pl.kind)}; one of ${BASIS_KINDS.join(', ')} is required` });
+    for (const p of pl.parts) if (!parts.has(p)) problems.push({ code: 'BASIS_NAMES_RESOLVE', object, detail: `names the part "${p}", which parts.json does not hold` });
+    for (const n of pl.bones) if (!bones.has(n)) problems.push({ code: 'BASIS_NAMES_RESOLVE', object, detail: `names the bone "${n}", which the proposal does not place` });
+    for (const f of pl.frame) if (!FRAME_KEYS.includes(f)) problems.push({ code: 'BASIS_NAMES_RESOLVE', object, detail: `names the frame quantity "${f}"; one of ${FRAME_KEYS.join(', ')} is required` });
+    if (pl.kind === 'joint' && pl.joints.length === 0) problems.push({ code: 'BASIS_KIND_HOLDS', object, detail: 'is a joint placement that names no joint; a joint placement names the joints it took' });
+    if (pl.kind !== 'joint' && pl.joints.length > 0) problems.push({ code: 'BASIS_KIND_HOLDS', object, detail: `is a ${pl.kind} placement that names the joint(s) ${pl.joints.map((j) => j.name).join(', ')}; only a joint placement takes a joint` });
+    if (pl.kind === 'derived' && pl.bones.length === 0) problems.push({ code: 'BASIS_KIND_HOLDS', object, detail: 'is a derived placement that names no bone; a derived placement names the bones it is derived from' });
+    for (const c of pl.constants) if (!Number.isFinite(c.value)) problems.push({ code: 'BASIS_KIND_HOLDS', object, detail: `carries the constant ${c.name} = ${c.value}; a finite number is required` });
+  };
+  for (const b of basis.bones) {
+    hold(b, 'origin', b.origin);
+    if (b.tip !== null) hold(b, 'tip', b.tip);
+  }
+  refuseIfAny(problems);
+}
+
+/**
+ * The basis file: the proposal's record held by {@link checkBasis} and, given
+ * the config `--compare` read, each bone against the config's through
+ * `src/structure.ts` (equal names; the proposal is the left side).
+ */
+export function basisFile(P: PartSet, proposal: Proposal, basis: ProposalBasis, compared: { where: string; config: unknown } | null): BasisFile {
+  checkBasis(P, proposal, basis);
+  if (compared === null) return { spec: BASIS_SPEC, frame: basis.frame, compared_with: null, bones: basis.bones.map((b) => ({ ...b, config: null })), config_only: null };
+  const left = readSkeleton(proposal, 'proposal');
+  const right = readSkeleton(compared.config, compared.where);
+  const c = compareStructure(left, right, null);
+  const rows = new Map(c.rows.map((r) => [r.left, r]));
+  const bones = basis.bones.map((b): BasisRecord => {
+    const l = left.byName.get(b.bone);
+    const r = right.byName.get(b.bone);
+    const row = rows.get(b.bone);
+    if (l === undefined || r === undefined || row === undefined) {
+      return { ...b, config: { status: 'proposal only', origin_px: null, tip_px: null, tip_why: 'the config has no bone of this name', parent: { proposal: l?.parent ?? '', config: null } } };
+    }
+    const origin = 'value' in row.origin ? row.origin.value : null;
+    const tip = 'value' in row.tip ? row.tip.value : null;
+    // structure.ts names the sides left and right; here the left is the proposal and the right the config.
+    const tipWhy = 'skip' in row.tip ? row.tip.skip.replace(/^left: /, 'proposal: ').replace(/(^|; )right: /, '$1config: ') : null;
+    const differs = origin !== 0 || row.parent.kind !== 'same' || (tip !== null && tip !== 0) || (l.tip === null) !== (r.tip === null);
+    return { ...b, config: { status: differs ? 'differs' : 'same', origin_px: origin, tip_px: tip, tip_why: tipWhy, parent: { proposal: l.parent ?? '', config: r.parent } } };
+  });
+  const placed = new Set(basis.bones.map((b) => b.bone));
+  // `root` is every rig's and states no position on either side: not a bone either one placed.
+  const configOnly = right.bones.map((b) => b.name).filter((n) => n !== 'root' && !placed.has(n));
+  return { spec: BASIS_SPEC, frame: basis.frame, compared_with: right.label, bones, config_only: configOnly };
+}
+
+/** Fixed key order, two-space indent, trailing newline. */
+export function serializeBasis(f: BasisFile): string {
+  return `${JSON.stringify(f, null, 2)}\n`;
+}
+
+/** Bones per basis kind of their origin, in {@link BASIS_KINDS} order. */
+export function basisCounts(f: BasisFile): Record<BasisKind, number> {
+  const out: Record<BasisKind, number> = { joint: 0, mask: 0, ratio: 0, derived: 0 };
+  for (const b of f.bones) out[b.origin.kind]++;
+  return out;
+}
+
+/** The line `propose` prints after writing the file. */
+export function basisLine(f: BasisFile, out: string): string {
+  const k = basisCounts(f);
+  const kinds = BASIS_KINDS.map((x) => `${k[x]} ${x}`).join(', ');
+  let cmp = '';
+  if (f.compared_with !== null) {
+    const n = (s: ConfigDelta['status']): number => f.bones.filter((b) => b.config?.status === s).length;
+    cmp = `; against ${f.compared_with}: ${n('differs')} differ, ${n('same')} same, ${n('proposal only')} in the proposal only, ${(f.config_only ?? []).length} in the config only`;
+  }
+  return `wrote ${BASIS_FILE} (${f.bones.length} bone record(s) by the basis of their origin: ${kinds}${cmp}) under ${out}`;
+}
+
+/** One coverage line per bone, then the summary. Every line starts `coverage`. */
+export function coverageLines(coverage: readonly BoneCoverage[]): string[] {
+  const out: string[] = [];
+  for (const c of coverage) {
+    const role = c.role === null ? 'role not read' : c.role.role;
+    const outcome = coverageOutcome(c);
+    if (outcome === 'not checked') out.push(`coverage ${c.bone} [${role}]: not checked — ${c.why.join('; ')}`);
+    else out.push(`coverage ${c.bone} [${role}]: ${outcome} — read by ${c.read.join(', ')}${c.lint > 0 ? `; named by ${c.lint} LINT line(s)` : ''}`);
+  }
+  const by = (o: (typeof COVERAGE_OUTCOMES)[number]): number => coverage.filter((c) => coverageOutcome(c) === o).length;
+  const roles: Record<BoneRole, number> = { target: 0, deforms: 0, control: 0, unclassified: 0 };
+  let unread = 0;
+  for (const c of coverage) {
+    if (c.role === null) unread++;
+    else roles[c.role.role]++;
+  }
+  out.push(
+    `coverage: ${coverage.length} bone(s) — ${by('checked, clean')} checked and clean, ${by('checked, LINT')} checked with a LINT line, ${by('not checked')} not checked; ` +
+      `roles ${BONE_ROLES.map((r) => `${roles[r]} ${r}`).join(', ')}${unread > 0 ? `, ${unread} not read` : ''}`,
+  );
+  return out;
+}

package/src/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * The one error shape every stage refuses with.
+ *
+ * An agent that cannot see the image reads these and nothing else, so a
+ * problem carries three things the reader can act on without guessing: the
+ * CODE it can grep for, the OBJECT it concerns (a layer, a config field, a
+ * file), and a sentence naming the value found and the value required. A
+ * refusal that says only "invalid" is not a refusal this repository writes.
+ *
+ * A reader collects every problem it can find before it throws, so one run
+ * names every missing field rather than one per attempt.
+ */
+export interface Problem {
+  /** Upper-snake name of the rule that refused, e.g. `LAYERS_PNG_PRESENT`. */
+  code: string;
+  /** The thing refused, spelled the way the input spells it: `layer "face"`, `config.bones[3].parent`. */
+  object: string;
+  /** What was found and what was required. */
+  detail: string;
+}
+
+export function problemLine(p: Problem): string {
+  return `${p.code}: ${p.object} — ${p.detail}`;
+}
+
+export class PartsError extends Error {
+  readonly problems: readonly Problem[];
+
+  constructor(problems: readonly Problem[]) {
+    super(problems.map(problemLine).join('\n'));
+    this.name = 'PartsError';
+    this.problems = problems;
+  }
+}
+
+/** Throw once, with every problem, if there are any. */
+export function refuseIfAny(problems: readonly Problem[]): void {
+  if (problems.length > 0) throw new PartsError(problems);
+}

package/src/gif.ts

@@ -0,0 +1,213 @@
+/**
+ * Animated GIF encoder — GIF89a, one global palette chosen by median cut,
+ * LZW, a NETSCAPE2.0 block that loops forever.
+ *
+ * Pure: bytes in, bytes out, no dependency, no clock, no randomness, and
+ * deterministic — every sort has a total order, so the same frames write the
+ * same bytes.
+ *
+ * What the encoder does:
+ *
+ * - **One palette for every frame**, 255 colours cut from the histogram of all
+ *   frames together, plus one transparent index. A per-frame palette would make
+ *   a still background shimmer between frames and would forbid the next step.
+ *   The cut is `src/palette.ts`'s variance-driven median cut, the one the
+ *   indexed APNG uses too, so the two files' palette errors are one figure;
+ *   every colour maps to its nearest entry. **No dithering**: it would add
+ *   noise the frame differencing below has to pay for, and the palette error is
+ *   reported instead of hidden.
+ * - **Consecutive frames whose quantised pixels are identical are merged**,
+ *   and every later frame is cropped to the box of indices that changed, with
+ *   the unchanged ones written as the transparent index over the previous frame
+ *   (disposal 1, "do not dispose").
+ * - **Delays are in centiseconds and the fps is not**: 12 fps is 8.33 cs. So
+ *   each frame's delay is the difference of its rounded start and end times,
+ *   `round(100 * end / fps) - round(100 * start / fps)` — 8, 9, 8, 8, 9, 8, …
+ *   at 12 fps, which keeps the loop's total length exact rather than drifting
+ *   by 4 % as a flat 8 cs would.
+ *
+ * GIF holds no partial alpha. Frames with a translucent pixel are refused by
+ * name rather than thresholded: rig-c renders over an opaque background,
+ * so a translucent frame is not one this encoder was built for.
+ *
+ * ⚠️ Animated WebP is out of scope: it needs a VP8 or VP8L bitstream encoder,
+ * and none ships here.
+ */
+import { type AnimFrame, checkFrames, EncodeError } from './apng.ts';
+import { histogram, mapToPalette, medianCut, type PaletteError, paletteError } from './palette.ts';
+
+export const PALETTE_COLOURS = 255;
+export const TRANSPARENT_INDEX = 255;
+
+export type { PaletteError };
+
+export interface GifStats {
+  frames: number;
+  colours: number;
+  /** Distinct RGB colours across every input frame. */
+  distinct: number;
+  frame0: PaletteError;
+  all: PaletteError;
+  bytes: number;
+}
+
+/** GIF has one bit of alpha: a translucent pixel is refused by name, not thresholded. */
+function refuseTranslucent(frames: readonly AnimFrame[]): void {
+  frames.forEach((f, fi) => {
+    const d = f.image.data;
+    for (let i = 0; i < d.length; i += 4) {
+      if (d[i + 3] !== 255) {
+        const p = i / 4;
+        throw new EncodeError(`frame ${fi} pixel ${p % f.image.width},${Math.floor(p / f.image.width)} has alpha ${d[i + 3]}; GIF holds no partial alpha, so every pixel must be opaque (255)`);
+      }
+    }
+  });
+}
+
+/** LZW-compress palette indices the way GIF wants it, with `minCode` bits for the root alphabet. */
+export function lzw(indices: Uint8Array, minCode: number): Uint8Array {
+  const clear = 1 << minCode;
+  const eoi = clear + 1;
+  const out: number[] = [];
+  let acc = 0;
+  let bits = 0;
+  let size = minCode + 1;
+  const emit = (code: number): void => {
+    acc |= code << bits;
+    bits += size;
+    while (bits >= 8) {
+      out.push(acc & 255);
+      acc >>>= 8;
+      bits -= 8;
+    }
+  };
+  let table = new Map<number, number>();
+  let next = eoi + 1;
+  emit(clear);
+  if (indices.length === 0) {
+    emit(eoi);
+    if (bits > 0) out.push(acc & 255);
+    return new Uint8Array(out);
+  }
+  let prefix = indices[0];
+  for (let i = 1; i < indices.length; i++) {
+    const k = indices[i];
+    const key = (prefix << 8) | k;
+    const hit = table.get(key);
+    if (hit !== undefined) {
+      prefix = hit;
+      continue;
+    }
+    emit(prefix);
+    if (next === 4096) {
+      emit(clear);
+      table = new Map();
+      next = eoi + 1;
+      size = minCode + 1;
+    } else {
+      if (next >= 1 << size) size++;
+      table.set(key, next++);
+    }
+    prefix = k;
+  }
+  emit(prefix);
+  emit(eoi);
+  if (bits > 0) out.push(acc & 255);
+  return new Uint8Array(out);
+}
+
+function subBlocks(data: Uint8Array): number[] {
+  const out: number[] = [];
+  for (let at = 0; at < data.length; at += 255) {
+    const n = Math.min(255, data.length - at);
+    out.push(n);
+    for (let i = 0; i < n; i++) out.push(data[at + i]);
+  }
+  out.push(0);
+  return out;
+}
+
+function le16(n: number): number[] {
+  return [n & 255, (n >>> 8) & 255];
+}
+
+/** Encode frames as a looping GIF, each frame shown for `ticks / fps` seconds. */
+export function encodeGif(input: readonly AnimFrame[], fps: number): { bytes: Uint8Array; stats: GifStats } {
+  checkFrames(input, fps);
+  refuseTranslucent(input);
+  const images = input.map((f) => f.image);
+  const colours = histogram(images);
+  const palette = medianCut(colours, PALETTE_COLOURS);
+  const { width, height } = input[0].image;
+  const indexed = mapToPalette(images, palette, false);
+  const frame0 = paletteError([images[0]], [indexed[0]], palette);
+  const all = paletteError(images, indexed, palette);
+
+  // Merge neighbours that quantise to the same indices.
+  const runs: Array<{ ix: Uint8Array; ticks: number }> = [];
+  indexed.forEach((ix, i) => {
+    const last = runs[runs.length - 1];
+    if (last !== undefined && last.ix.every((v, p) => v === ix[p])) last.ticks += input[i].ticks;
+    else runs.push({ ix, ticks: input[i].ticks });
+  });
+
+  const out: number[] = [];
+  for (const ch of 'GIF89a') out.push(ch.charCodeAt(0));
+  out.push(...le16(width), ...le16(height), 0xf7, 0, 0);
+  for (let i = 0; i < 256; i++) {
+    const c = palette[i] ?? [0, 0, 0];
+    out.push(c[0], c[1], c[2]);
+  }
+  out.push(0x21, 0xff, 0x0b);
+  for (const ch of 'NETSCAPE2.0') out.push(ch.charCodeAt(0));
+  out.push(0x03, 0x01, 0, 0, 0);
+
+  let tick = 0;
+  runs.forEach((run, i) => {
+    const start = Math.round((100 * tick) / fps);
+    tick += run.ticks;
+    const delay = Math.round((100 * tick) / fps) - start;
+    let x0 = 0;
+    let y0 = 0;
+    let w = width;
+    let h = height;
+    let body = run.ix;
+    let transparent = false;
+    if (i > 0) {
+      const prev = runs[i - 1].ix;
+      let bx0 = width;
+      let by0 = height;
+      let bx1 = -1;
+      let by1 = -1;
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          if (prev[y * width + x] !== run.ix[y * width + x]) {
+            if (x < bx0) bx0 = x;
+            if (x > bx1) bx1 = x;
+            if (y < by0) by0 = y;
+            if (y > by1) by1 = y;
+          }
+        }
+      }
+      x0 = bx0;
+      y0 = by0;
+      w = bx1 - bx0 + 1;
+      h = by1 - by0 + 1;
+      body = new Uint8Array(w * h);
+      for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+          const p = (y0 + y) * width + x0 + x;
+          body[y * w + x] = prev[p] === run.ix[p] ? TRANSPARENT_INDEX : run.ix[p];
+        }
+      }
+      transparent = true;
+    }
+    out.push(0x21, 0xf9, 0x04, (1 << 2) | (transparent ? 1 : 0), ...le16(delay), TRANSPARENT_INDEX, 0);
+    out.push(0x2c, ...le16(x0), ...le16(y0), ...le16(w), ...le16(h), 0);
+    out.push(8);
+    for (const v of subBlocks(lzw(body, 8))) out.push(v);
+  });
+  out.push(0x3b);
+  const bytes = new Uint8Array(out);
+  return { bytes, stats: { frames: runs.length, colours: palette.length, distinct: colours.length, frame0, all, bytes: bytes.length } };
+}