@rig-c/parts 1.49.2 → 1.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/assemble.ts CHANGED
@@ -2701,7 +2701,18 @@ export interface LimbCount {
2701
2701
  before: number;
2702
2702
  shares: Array<{ part: string; px: number }>;
2703
2703
  /** The joints whose cap this part's segments carry, in `config.limbs` order. */
2704
- joints: Array<{ limb: string; joint: string; part: string; upper: string; cap: CapRecord }>;
2704
+ joints: Array<{
2705
+ limb: string;
2706
+ joint: string;
2707
+ part: string;
2708
+ upper: string;
2709
+ cap: CapRecord;
2710
+ /** Issue #557: the parts the lower and the upper segment take, the half-width about the joint, and the short pixels within it. */
2711
+ from?: string;
2712
+ upperFrom?: string;
2713
+ half?: number;
2714
+ shortInHalf?: number;
2715
+ }>;
2705
2716
  }
2706
2717
 
2707
2718
  /**
@@ -2720,6 +2731,41 @@ function cutPhrase(k: CapRecord, upper: string, lower: string): string {
2720
2731
  return `cut_band ${k.cut_band ?? 0}: the cut ${where}, through [${(k.cut_at ?? k.at).join(', ')}], crosses ${k.cut_crossed ?? 0} stroke px; the joint line crosses ${k.joint_crossed ?? 0} (${stroke})`;
2721
2732
  }
2722
2733
 
2734
+ /**
2735
+ * Issue #557: the `LINT` line of a short cap — one whose disc, on the upper
2736
+ * side of the cut, holds pixels no layer of the limb gives (`short_px`, by
2737
+ * side of the limb's axis: `left` where a pixel centre's offset across the
2738
+ * axis is 0 or above, the side toward smaller x when the limb hangs down the
2739
+ * rig, `right` the other) — naming the limb, the joint, the part, both
2740
+ * figures, the radius and what filled the rest; with the half-disc, how many
2741
+ * of them `cap_shape: "disc"` would keep. Null for a cap that is not short.
2742
+ */
2743
+ export function shortCapLint(j: LimbCount['joints'][number]): string | null {
2744
+ const k = j.cap;
2745
+ if (k.short_px === undefined) return null;
2746
+ const n = k.short_px.left + k.short_px.right;
2747
+ const where =
2748
+ j.from === undefined || j.upperFrom === undefined || j.upperFrom === j.from
2749
+ ? `the layer of "${j.from ?? j.part}" has no pixel of the limb`
2750
+ : `neither the layer of "${j.from}" nor that of "${j.upperFrom}" has a pixel of the limb`;
2751
+ const filled = [
2752
+ ...(k.image_px === undefined ? [] : [`${k.image_px} px from ${k.image_layer === undefined ? 'the cap image' : `the hidden-art layer ${k.image_layer}`}`]),
2753
+ `${k.layer_px} px from "${j.part}"'s layer`,
2754
+ `${k.upper_px ?? 0} px from "${j.upper}"`,
2755
+ ].join(', ');
2756
+ const half = j.half ?? 0;
2757
+ const disc =
2758
+ k.shape === 'disc' || j.shortInHalf === undefined
2759
+ ? ''
2760
+ : j.shortInHalf === 0
2761
+ ? `; under cap_shape "disc" the disc is the half-width about the joint, ${half} px, and none of them lies within it`
2762
+ : `; under cap_shape "disc" the disc is the half-width about the joint, ${half} px, and ${j.shortInHalf} of them lie within it`;
2763
+ return (
2764
+ ` LINT "${j.part}" cap at [${k.at[0]}, ${k.at[1]}] (limb "${j.limb}", joint "${j.joint}", radius ${k.radius} px): short_px left ${k.short_px.left}, right ${k.short_px.right}: ` +
2765
+ `no layer gives them — ${n} px of the disc on the upper side of the cut, where ${where}; the rest of the disc is filled, ${filled}${disc}`
2766
+ );
2767
+ }
2768
+
2723
2769
  /**
2724
2770
  * The lines `assemble` prints for the limbs (issue #349), one per part a limb
2725
2771
  * took — ` limb cut: "<of>" opaque <n> = "<part>" <px> + …` — and one per
@@ -2733,7 +2779,8 @@ export function limbLines(counts: readonly LimbCount[]): string[] {
2733
2779
  const k = j.cap;
2734
2780
  const base = k.image_px === undefined ? `${k.layer_px} px from the layer` : `${k.image_px} px from ${k.image_layer === undefined ? 'the cap image' : `the hidden-art layer ${k.image_layer}`}, ${k.layer_px} px from the layer`;
2735
2781
  // Issue #360: what cap_shape "disc" and edge "feather" did, said only when declared, so a limb without them prints what it did.
2736
- const from = k.shape === undefined ? base : `${base}, ${k.upper_px ?? 0} px from "${j.upper}"`;
2782
+ // Issue #557: the half-disc says it only when the neighbouring segment gave a pixel, so a full cap prints what it printed.
2783
+ const from = k.upper_px === undefined ? base : `${base}, ${k.upper_px} px from "${j.upper}"`;
2737
2784
  const radius =
2738
2785
  k.shape === undefined
2739
2786
  ? `a disc of radius ${k.radius} px (the limb ${k.width} px across the joint line)`
@@ -2749,6 +2796,8 @@ export function limbLines(counts: readonly LimbCount[]): string[] {
2749
2796
  out.push(
2750
2797
  ` limb cap: "${j.limb}" joint "${j.joint}" at [${k.at[0]}, ${k.at[1]}], on "${j.part}": ${radius}, box [${k.box.join(', ')}] — on the upper side of the line ${from}, ${miss}${shaped.map((q) => `; ${q}`).join('')}`,
2751
2798
  );
2799
+ const lint = shortCapLint(j);
2800
+ if (lint !== null) out.push(lint);
2752
2801
  }
2753
2802
  }
2754
2803
  return out;
@@ -3051,6 +3100,11 @@ function cutLimbs(
3051
3100
  let imagePx = 0;
3052
3101
  let upperPx = 0;
3053
3102
  let missing = 0;
3103
+ // Issue #557: the cap's shortfall by side of the limb's axis (left: across >= 0), and how much of it lies within
3104
+ // the half-width about the joint, the disc cap_shape "disc" would keep.
3105
+ let shortLeft = 0;
3106
+ let shortRight = 0;
3107
+ let shortInHalf = 0;
3054
3108
  for (let y = Math.max(0, box[1]); y < Math.min(H, box[1] + box[3]); y++) {
3055
3109
  for (let x = Math.max(0, box[0]); x < Math.min(W, box[0] + box[2]); x++) {
3056
3110
  if (!inDisc(line.at, radius, x, y) || pastJoint(cut, x, y)) continue;
@@ -3062,11 +3116,18 @@ function cutLimbs(
3062
3116
  } else if (ownLower[p] === li && lowerSrc.r.data[p * 4 + 3] > 0) {
3063
3117
  lower.data.set(lowerSrc.r.data.subarray(p * 4, p * 4 + 4), p * 4);
3064
3118
  layerPx++;
3065
- } else if (disc && upper.data[p * 4 + 3] > 0) {
3119
+ } else if (upper.data[p * 4 + 3] > 0) {
3066
3120
  // Issue #360: the disc is filled from the art — the upper segment's, where the lower's layer has none.
3121
+ // Issue #557: under either shape — the half-disc too takes the neighbouring segment's pixels, so a cap is
3122
+ // short only where no layer of the limb gives a pixel.
3067
3123
  lower.data.set(upper.data.subarray(p * 4, p * 4 + 4), p * 4);
3068
3124
  upperPx++;
3069
- } else missing++;
3125
+ } else {
3126
+ missing++;
3127
+ if (jointOffsets(line, x, y).across >= 0) shortLeft++;
3128
+ else shortRight++;
3129
+ if (inDisc(line.at, half, x, y)) shortInHalf++;
3130
+ }
3070
3131
  }
3071
3132
  }
3072
3133
  if (img !== null && imagePx === 0 && hidden === null) {
@@ -3111,7 +3172,8 @@ function cutLimbs(
3111
3172
  ...(img === null ? {} : { image_px: imagePx }),
3112
3173
  ...(hidden === null ? {} : { image_layer: hidden.layer }),
3113
3174
  missing_px: missing,
3114
- ...(disc ? { shape: 'disc' as const, upper_px: upperPx } : {}),
3175
+ ...(missing === 0 ? {} : { short_px: { left: shortLeft, right: shortRight } }),
3176
+ ...(disc ? { shape: 'disc' as const, upper_px: upperPx } : upperPx === 0 ? {} : { upper_px: upperPx }),
3115
3177
  ...(sg.edge === 'feather' ? { edge: 'feather' as const, feather_radius: band, feathered_px: featheredPx } : {}),
3116
3178
  ...(placed === undefined
3117
3179
  ? {}
@@ -3128,7 +3190,7 @@ function cutLimbs(
3128
3190
  if (hidden !== null) readHidden(hidden.layer, `config.limbs.${l}.segments[${k}].cap (part "${sg.part}")`);
3129
3191
  parts[at].record.cap = cap;
3130
3192
  const c = counts.find((q) => q.of === sg.from);
3131
- if (c !== undefined) c.joints.push({ limb: l, joint: String(sg.joint), part: sg.part, upper: segs[k - 1].part, cap });
3193
+ if (c !== undefined) c.joints.push({ limb: l, joint: String(sg.joint), part: sg.part, upper: segs[k - 1].part, cap, from: sg.from, upperFrom: upFrom, half: pyRound(half, 3), shortInHalf });
3132
3194
  });
3133
3195
  }
3134
3196
  refuseIfAny(problems);
package/src/build.ts CHANGED
@@ -40,6 +40,7 @@
40
40
  * no child process. rig-c runs as a process, but the process is injected
41
41
  * as a {@link RigcRunner}, exactly as `src/check.ts` takes it.
42
42
  */
43
+ import { createHash } from 'node:crypto';
43
44
  import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
44
45
  import { dirname, join, resolve } from 'node:path';
45
46
  import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
@@ -1347,6 +1348,8 @@ export interface CheckStageInput {
1347
1348
  packShape?: PackShape;
1348
1349
  /** The scene's declared requirements (`--requirements`, issue #93); absent, nothing is read, written or printed for them. */
1349
1350
  requirements?: string;
1351
+ /** The path `check.json`'s `requirements.file` records (issue #556): `config.requirements` as declared when build read it from the config; absent, `requirements` as given. */
1352
+ requirementsAs?: string;
1350
1353
  /**
1351
1354
  * `check --seam-pairs` (issue #202): split the seam's counted pixels by pair
1352
1355
  * and draw each pair's picture even when the bar passes. A failing seam is
@@ -1501,14 +1504,18 @@ export function limbCheckLines(line: LimbLine): string[] {
1501
1504
  * The seam over the range (issue #360) as the console prints it: the status, what was posed and the bar, then each
1502
1505
  * joint at each angle on a line of its own — its status and the seam figures there — or, not read, why.
1503
1506
  */
1504
- export function sweepCheckLines(line: SweepLine): string[] {
1507
+ export function sweepCheckLines(line: SweepLine, steps: ReadonlyMap<string, { left: number; right: number }> = new Map()): string[] {
1505
1508
  const s = line.frame_scale;
1506
1509
  return [
1507
1510
  `${SWEEP_LINE}: ${line.status} — ${line.joints.length} joint(s) bent to their declared range's ends and middle${line.physics_left_out === 0 ? '' : `, ${line.physics_left_out} physics constraint(s) left out`}; at each, the pose against the same pose with the joint's own art drawn under the limb, on the rest-pose seam's bar (mean |d| <= ${line.bar.mean.toFixed(1)}, <= ${line.bar.rig_px_over_40} rig px over ${line.bar.level})${s === null ? '' : ` at frame scale ${s}`}`,
1508
1511
  ...line.joints.flatMap((j) => {
1509
1512
  const head = `joint "${j.joint}" (${j.limb}, "${j.part}" on "${j.bone}", range [${j.range.join(', ')}]${j.shape === 'disc' ? `, cap_shape "disc": no pixel over ${line.bar.level} in the disc` : ''})`;
1510
1513
  if (j.unread !== undefined) return [`${head}: FAIL — not read: ${j.unread}`];
1511
- return j.poses.map((p) => `${head} at ${p.degrees}°: ${p.status} — mean |d| ${p.mean}/255, ${p.px_over_40} frame px over ${line.bar.level} (${p.px_over_80} over ${SEAM_PX_LEVEL_HIGH}), ${p.rig_px_over_40.toFixed(2)} rig px`);
1514
+ // Issue #557: the contour step, a reading on every row (check.json carries it only for a short cap).
1515
+ return j.poses.map((p) => {
1516
+ const st = p.step_px ?? steps.get(`${j.part} ${p.degrees}`);
1517
+ return `${head} at ${p.degrees}°: ${p.status} — mean |d| ${p.mean}/255, ${p.px_over_40} frame px over ${line.bar.level} (${p.px_over_80} over ${SEAM_PX_LEVEL_HIGH}), ${p.rig_px_over_40.toFixed(2)} rig px${st === undefined ? '' : `; contour step ${st.left} px left, ${st.right} px right (a reading)`}`;
1518
+ });
1512
1519
  }),
1513
1520
  ];
1514
1521
  }
@@ -1567,7 +1574,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
1567
1574
  const entryLine = versionLines.find((l) => l.startsWith('entry:'));
1568
1575
  log(` ${rigcIdentity(bin, v)}${entryLine === undefined ? '' : `; ${entryLine}`}`);
1569
1576
  const mode: PackMode = { pageEdges: input.pageEdges ?? DEFAULT_PAGE_EDGES, packShape: input.packShape ?? DEFAULT_PACK_SHAPE };
1570
- const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true, input.set, input.allSets === true, input.environment);
1577
+ const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true, input.set, input.allSets === true, input.environment, input.requirementsAs);
1571
1578
  if (r.figures.environment !== undefined) log(` ${environmentLine(r.figures.environment)}`);
1572
1579
  log(` gate rig-play (rigc ${packedBuildLabel(mode)}), verbatim:`);
1573
1580
  for (const l of r.gateHtml) log(l);
@@ -1607,7 +1614,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
1607
1614
  const limbs = fig[LIMB_LINE];
1608
1615
  if (limbs !== undefined) for (const [i, l] of limbCheckLines(limbs).entries()) log(` ${i === 0 ? '' : ' '}${l}`);
1609
1616
  const sweep = fig[SWEEP_LINE];
1610
- if (sweep !== undefined) for (const [i, l] of sweepCheckLines(sweep).entries()) log(` ${i === 0 ? '' : ' '}${l}`);
1617
+ if (sweep !== undefined) for (const [i, l] of sweepCheckLines(sweep, r.sweepSteps).entries()) log(` ${i === 0 ? '' : ' '}${l}`);
1611
1618
  for (const [i, l] of motionSeamLines(r.motionSeam).entries()) log(` ${i === 0 ? '' : ' '}${l}`);
1612
1619
  for (const [i, l] of clothLines(r.cloth).entries()) log(` ${i === 0 ? '' : ' '}${l}`);
1613
1620
  for (const name of REPORTED_LINES) log(` ${judgementLine(name, fig[name])}`);
@@ -1885,7 +1892,7 @@ export interface BuildInput {
1885
1892
  pageEdges: PageEdges;
1886
1893
  /** `--pack-shape` for both packed builds, as `pageEdges`; {@link DEFAULT_PACK_SHAPE} when absent. */
1887
1894
  packShape?: PackShape;
1888
- /** `--requirements`, forwarded to the check (issue #93): read before assemble runs, so a file check would refuse is refused first; absent, nothing moves. */
1895
+ /** `--requirements`, forwarded to the check (issue #93): read before assemble runs, so a file check would refuse is refused first; absent, `config.requirements` is read in its place (issue #556, {@link buildRequirements}), and with neither nothing moves. */
1889
1896
  requirements?: string;
1890
1897
  /** `--idle-keys`, forwarded to the rig stage as `rig` takes it (issue #95); {@link DEFAULT_IDLE_KEYS} when absent. */
1891
1898
  idleKeys?: IdleKeys;
@@ -1936,6 +1943,39 @@ export const CHECK_FLAGS_IN_BUILD: Readonly<Record<string, CheckFlagInBuild>> =
1936
1943
  '--environment': { as: 'forwarded' },
1937
1944
  };
1938
1945
 
1946
+ /** The requirements file build's check reads (issue #556): `read` is where it is opened, `recorded` what `check.json` names it by. */
1947
+ export interface BuildRequirements {
1948
+ read: string;
1949
+ recorded: string;
1950
+ }
1951
+
1952
+ /**
1953
+ * Which requirements file a build reads (issue #556): the `--requirements`
1954
+ * flag as typed, else `config.requirements` resolved against the config's
1955
+ * directory and recorded as declared, else none. Both given, they must name
1956
+ * one file — the same path once resolved, or a file of the same bytes — and the
1957
+ * declaration is the one read and recorded, so the build writes what a rebuild
1958
+ * from the config alone writes; two files of different bytes are
1959
+ * `BUILD_REQUIREMENTS_CONFLICT`, naming both.
1960
+ */
1961
+ export function buildRequirements(flag: string | undefined, declared: string | undefined, configPath: string): BuildRequirements | null {
1962
+ if (declared === undefined) return flag === undefined ? null : { read: flag, recorded: flag };
1963
+ const fromConfig = resolve(dirname(resolve(configPath)), declared);
1964
+ if (flag === undefined || resolve(flag) === fromConfig) return { read: fromConfig, recorded: declared };
1965
+ const digestOf = (path: string): string | null => (existsSync(path) && statSync(path).isFile() ? createHash('sha256').update(readFileSync(path)).digest('hex') : null);
1966
+ const flagDigest = digestOf(resolve(flag));
1967
+ const configDigest = digestOf(fromConfig);
1968
+ if (flagDigest !== null && flagDigest === configDigest) return { read: fromConfig, recorded: declared };
1969
+ const shown = (d: string | null): string => (d === null ? 'no such file' : `sha256 ${d.slice(0, 16)}`);
1970
+ throw new PartsError([
1971
+ {
1972
+ code: 'BUILD_REQUIREMENTS_CONFLICT',
1973
+ object: `--requirements ${flag} and config.requirements "${declared}"`,
1974
+ detail: `the flag names ${resolve(flag)} (${shown(flagDigest)}) and the config declares ${fromConfig} (${shown(configDigest)}); a build reads one requirements file and records it, so the two must name the same file or the same bytes — drop the flag to build from the config's file, or point config.requirements at the flag's`,
1975
+ },
1976
+ ]);
1977
+ }
1978
+
1939
1979
  /** The `build` refusal of a `check` flag build supplies itself ({@link CHECK_FLAGS_IN_BUILD}), or null for any other flag. */
1940
1980
  export function suppliedCheckFlag(flag: string): string | null {
1941
1981
  const row = Object.hasOwn(CHECK_FLAGS_IN_BUILD, flag) ? CHECK_FLAGS_IN_BUILD[flag] : undefined;
@@ -2019,14 +2059,16 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
2019
2059
  const idleKeys = input.idleKeys ?? DEFAULT_IDLE_KEYS;
2020
2060
  log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? `, with the idle loop${input.leadIn === undefined ? '' : ` after a lead-in of ${input.leadIn} period(s)`}` : ''}`);
2021
2061
 
2062
+ let req: BuildRequirements | null = null;
2022
2063
  try {
2023
2064
  // build runs rig next, which needs the whole config, so the full loader is
2024
2065
  // asked first: a config rig would refuse is refused before assemble writes
2025
2066
  // anything, and under [assemble], as it was before the stage had its own
2026
2067
  // narrower door.
2027
- loadConfig(input.config);
2068
+ // Issue #556: the flag, or the config's declaration when there is none; both naming other bytes is refused here.
2069
+ req = buildRequirements(input.requirements, loadConfig(input.config).requirements, input.config);
2028
2070
  // The same for the requirements file's own shape; its names resolve against the rig, in the check, before it builds.
2029
- if (input.requirements !== undefined) readRequirements(input.requirements);
2071
+ if (req !== null) readRequirements(req.read);
2030
2072
  // And the schedule (issue #538), by rigc's own reader, as check reads it.
2031
2073
  if (input.environment !== undefined) readCheckEnvironment(input.environment);
2032
2074
  assembleStage(
@@ -2046,7 +2088,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
2046
2088
 
2047
2089
  let report: CheckReport;
2048
2090
  try {
2049
- report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(input.requirements === undefined ? {} : { requirements: input.requirements }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true, ...(input.set === undefined ? {} : { set: input.set }), allSets: input.allSets === true, ...(input.environment === undefined ? {} : { environment: input.environment }) }, run.check, run.checkBin, prefixed('check'));
2091
+ report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(req === null ? {} : { requirements: req.read, requirementsAs: req.recorded }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true, ...(input.set === undefined ? {} : { set: input.set }), allSets: input.allSets === true, ...(input.environment === undefined ? {} : { environment: input.environment }) }, run.check, run.checkBin, prefixed('check'));
2050
2092
  } catch (err) {
2051
2093
  return refused('check', err);
2052
2094
  }
package/src/check.ts CHANGED
@@ -1905,8 +1905,9 @@ export interface SetCheckFigures {
1905
1905
  PASS: boolean;
1906
1906
  }
1907
1907
 
1908
- /** `check.json`'s `requirements` block: the fps every named animation was sampled at, the summary, and each line by its name, in the file's order. */
1908
+ /** `check.json`'s `requirements` block: which file was read, the fps every named animation was sampled at, the summary, and each line by its name, in the file's order. */
1909
1909
  export interface RequirementsBlock {
1910
+ file: RequirementsFileRecord;
1910
1911
  fps: number;
1911
1912
  summary: RequirementsSummary;
1912
1913
  lines: Record<string, RequirementLine>;
@@ -2140,6 +2141,11 @@ export interface CheckReport {
2140
2141
  motionSeam: MotionSeamLine;
2141
2142
  /** `CLOTH_SETTLES` (issue #501): a warning, never a bar — in `check.json` only when the rig declares a physics constraint and has an idle; its SKIP is printed either way. */
2142
2143
  cloth: ClothLine;
2144
+ /**
2145
+ * Issue #557: the contour step at each pose `SEAM_OVER_RANGE` read, by `<part> <degrees>` ({@link contourStep}) —
2146
+ * printed on every row; `check.json` carries it only for a joint whose cap is short ({@link SweepPose}).
2147
+ */
2148
+ sweepSteps?: Map<string, { left: number; right: number }>;
2143
2149
  }
2144
2150
 
2145
2151
  /**
@@ -2979,6 +2985,10 @@ export interface SweepJoint {
2979
2985
  radius: number;
2980
2986
  /** Issue #360: the cap's record says `shape: "disc"` — the disc is held to no pixel uncovered ({@link sweepLine}). */
2981
2987
  disc?: true;
2988
+ /** Issue #557: the upper segment's bone (the limb record one segment up), whose direction the contour step is read across; null when parts.json has none. */
2989
+ upperBone?: string | null;
2990
+ /** Issue #557: the cap's record carries `short_px` — the step is then written into check.json ({@link SweepPose}). */
2991
+ short?: { left: number; right: number };
2982
2992
  }
2983
2993
 
2984
2994
  /** Every limb record in `parts.json` that declares a `range`, in `parts.json`'s order. */
@@ -2987,7 +2997,20 @@ export function sweepJoints(parts: PartsFile): SweepJoint[] {
2987
2997
  for (const p of parts.parts) {
2988
2998
  const l = p.limb;
2989
2999
  if (l === undefined || l.range === undefined || l.cap === undefined || l.joint === undefined) continue;
2990
- out.push({ part: p.name, limb: l.name, segment: l.segment, joint: l.joint, bone: l.bone, range: [l.range[0], l.range[1]], at: [l.cap.at[0], l.cap.at[1]], radius: l.cap.radius, ...(l.cap.shape === 'disc' ? { disc: true as const } : {}) });
3000
+ const up = parts.parts.find((q) => q.limb?.name === l.name && q.limb.segment === l.segment - 1)?.limb?.bone ?? null;
3001
+ out.push({
3002
+ part: p.name,
3003
+ limb: l.name,
3004
+ segment: l.segment,
3005
+ joint: l.joint,
3006
+ bone: l.bone,
3007
+ range: [l.range[0], l.range[1]],
3008
+ at: [l.cap.at[0], l.cap.at[1]],
3009
+ radius: l.cap.radius,
3010
+ ...(l.cap.shape === 'disc' ? { disc: true as const } : {}),
3011
+ upperBone: up,
3012
+ ...(l.cap.short_px === undefined ? {} : { short: { left: l.cap.short_px.left, right: l.cap.short_px.right } }),
3013
+ });
2991
3014
  }
2992
3015
  return out;
2993
3016
  }
@@ -3051,6 +3074,90 @@ export function sweepUnread(j: SweepJoint, rig: Record<string, unknown>, limbSlo
3051
3074
  return null;
3052
3075
  }
3053
3076
 
3077
+ /** The setup pose's world transform of every bone `rig.json` declares (rigc's `computeExactFrameTransforms`, through `src/coords.ts`). */
3078
+ function setupWorld(rig: Record<string, unknown>): Map<string, BoneTransform> {
3079
+ const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord);
3080
+ const posable: Parameters<typeof computeExactFrameTransforms>[0][number][] = bones.map((b) => ({
3081
+ name: String(b.name),
3082
+ ...(typeof b.parent === 'string' && b.parent !== '' ? { parent: b.parent } : {}),
3083
+ ...Object.fromEntries((['x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY'] as const).filter((k) => typeof b[k] === 'number').map((k) => [k, b[k] as number])),
3084
+ ...(typeof b.inherit === 'string' ? { inherit: b.inherit } : {}),
3085
+ }));
3086
+ return computeExactFrameTransforms(posable);
3087
+ }
3088
+
3089
+ /**
3090
+ * Issue #557: the direction the contour step is read across — the upper
3091
+ * segment's, from its bone's origin to the joint's bone's origin at the setup
3092
+ * pose (the first of the two directions `src/limbs.ts` `jointLine` sums), as a
3093
+ * unit vector in rig px, y down: the Spine world's difference with its y
3094
+ * turned. The upper segment does not move while the joint bends, so lines
3095
+ * across it are the same lines at every pose. Null when either bone is not in
3096
+ * `rig.json` or the two origins coincide.
3097
+ */
3098
+ export function sweepAxis(rig: Record<string, unknown>, j: Pick<SweepJoint, 'bone' | 'upperBone'>): [number, number] | null {
3099
+ if (j.upperBone === undefined || j.upperBone === null) return null;
3100
+ const world = setupWorld(rig);
3101
+ const up = world.get(j.upperBone);
3102
+ const me = world.get(j.bone);
3103
+ if (up === undefined || me === undefined) return null;
3104
+ const dx = me.worldX - up.worldX;
3105
+ const dy = up.worldY - me.worldY;
3106
+ const l = edgeLength(dx, dy);
3107
+ return l === 0 ? null : [dx / l, dy / l];
3108
+ }
3109
+
3110
+ /** Issue #557: how far the contour step's lines run out from the axis, in cap radii — past the limb's edge on either side, which lies at one radius. */
3111
+ export const STEP_REACH_RADII = 2;
3112
+
3113
+ /**
3114
+ * Issue #557: the contour step at a bent pose — the step the eye sees in the
3115
+ * limb's outline where the cut meets it. On the frame `image` (rigc's render,
3116
+ * over `background`), lines across the limb perpendicular to `axis` (rig px,
3117
+ * unit, y down) at every frame pixel along it from one cap radius before the
3118
+ * joint line to one radius past it; on each, from the axis outward on each
3119
+ * side, the silhouette's extent: the distance, in rig px, of the first sample
3120
+ * whose largest channel lies within {@link SEAM_PX_LEVEL} of the background
3121
+ * (samples one frame pixel apart, out to {@link STEP_REACH_RADII} radii; a
3122
+ * sample is the frame pixel `map` carries the rig point onto, nearest). The
3123
+ * step on a side is the largest change in that extent between two adjacent
3124
+ * lines, to 3 places. `left` is the side the cap's `short_px` calls left
3125
+ * (across the axis at or above 0, `src/limbs.ts` `jointOffsets`), `right` the
3126
+ * other. A straight full limb reads about one frame pixel — the sampling's
3127
+ * own; a notch the bend opens in the outline reads its depth.
3128
+ */
3129
+ export function contourStep(image: Raster, background: readonly number[], map: ScaleTranslate, at: readonly [number, number], axis: readonly [number, number], radius: number): { left: number; right: number } {
3130
+ const d = 1 / map.sx;
3131
+ const across: [number, number] = [-axis[1], axis[0]];
3132
+ const solid = (px: number, py: number): boolean => {
3133
+ const fx = Math.round(map.sx * (px - 0.5) + map.tx);
3134
+ const fy = Math.round(map.sy * (py - 0.5) + map.ty);
3135
+ if (fx < 0 || fy < 0 || fx >= image.width || fy >= image.height) return false;
3136
+ const o = (fy * image.width + fx) * 4;
3137
+ return Math.max(Math.abs(image.data[o] - background[0]), Math.abs(image.data[o + 1] - background[1]), Math.abs(image.data[o + 2] - background[2])) > SEAM_PX_LEVEL;
3138
+ };
3139
+ const along = Math.floor(radius * map.sx);
3140
+ const out = Math.ceil(STEP_REACH_RADII * radius * map.sx);
3141
+ const extent = (k: number, side: 1 | -1): number => {
3142
+ const cx = at[0] + k * d * axis[0];
3143
+ const cy = at[1] + k * d * axis[1];
3144
+ let m = 0;
3145
+ while (m <= out && solid(cx + side * m * d * across[0], cy + side * m * d * across[1])) m++;
3146
+ return m * d;
3147
+ };
3148
+ const step = (side: 1 | -1): number => {
3149
+ let best = 0;
3150
+ let prev = extent(-along, side);
3151
+ for (let k = -along + 1; k <= along; k++) {
3152
+ const e = extent(k, side);
3153
+ best = Math.max(best, Math.abs(e - prev));
3154
+ prev = e;
3155
+ }
3156
+ return round3(best);
3157
+ };
3158
+ return { left: step(1), right: step(-1) };
3159
+ }
3160
+
3054
3161
  /**
3055
3162
  * The throwaway copy (see {@link SWEEP_LINE}): `rig` with one underlay slot per
3056
3163
  * read joint — a region on the parent of the joint's bone, centred on its box
@@ -3075,13 +3182,7 @@ export function sweepCopy(
3075
3182
  files: ReadonlySet<string> = new Set(),
3076
3183
  ): { rig: Record<string, unknown>; motion: Record<string, unknown>; slots: string[]; images: Array<[string, Raster]> } {
3077
3184
  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord);
3078
- const posable: Parameters<typeof computeExactFrameTransforms>[0][number][] = bones.map((b) => ({
3079
- name: String(b.name),
3080
- ...(typeof b.parent === 'string' && b.parent !== '' ? { parent: b.parent } : {}),
3081
- ...Object.fromEntries((['x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY'] as const).filter((k) => typeof b[k] === 'number').map((k) => [k, b[k] as number])),
3082
- ...(typeof b.inherit === 'string' ? { inherit: b.inherit } : {}),
3083
- }));
3084
- const world = computeExactFrameTransforms(posable);
3185
+ const world = setupWorld(rig);
3085
3186
  const slots = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).map((s) => ({ ...s }));
3086
3187
  const skins = isRecord(rig.skins) ? rig.skins : {};
3087
3188
  const skin: Record<string, unknown> = { ...(isRecord(skins.default) ? skins.default : {}) };
@@ -3118,6 +3219,13 @@ export interface SweepPose {
3118
3219
  px_over_40: number;
3119
3220
  px_over_80: number;
3120
3221
  rig_px_over_40: number;
3222
+ /**
3223
+ * Issue #557, written only for a joint whose cap record carries `short_px`:
3224
+ * the contour step at this pose ({@link contourStep}), rig px, per side of
3225
+ * the limb. A reading, never a bar; a full cap's row prints it and writes
3226
+ * what it wrote.
3227
+ */
3228
+ step_px?: { left: number; right: number };
3121
3229
  }
3122
3230
 
3123
3231
  /** One joint's row: its limb record, its disc, how many of the joint's own art pixels the disc holds, and each pose — or, not read, why. */
@@ -3162,6 +3270,8 @@ export function sweepLine(
3162
3270
  frames: (animation: string) => { under: FrameSet; bare: FrameSet },
3163
3271
  physicsLeftOut: number,
3164
3272
  problems: Problem[],
3273
+ step: (j: SweepJoint, bare: FrameSet) => { left: number; right: number } | null = () => null,
3274
+ printed: Map<string, { left: number; right: number }> = new Map(),
3165
3275
  ): SweepLine {
3166
3276
  const seen: { grid: FrameSet | null } = { grid: null };
3167
3277
  const rows: SweepRow[] = joints.map((j, i) => {
@@ -3211,7 +3321,10 @@ export function sweepLine(
3211
3321
  `mean <= ${SEAM_MEAN_BAR.toFixed(1)} and <= ${SEAM_PX_BAR} rig px over ${SEAM_PX_LEVEL} are required, the rest-pose seam's bar — the bend uncovers the joint, and a cap that covers the turn (the limb's art within that radius on the upper side of the joint line, carried by "${j.part}") keeps it covered`,
3212
3322
  });
3213
3323
  }
3214
- return { degrees: a, status: fail ? 'FAIL' : 'PASS', mean, px_over_40: f.over40, px_over_80: f.over80, rig_px_over_40: Number(seamRigPxText(f.over40, scale)) };
3324
+ // Issue #557: the contour step on the bent frame — a reading, recorded only where the cap is short.
3325
+ const st = step(j, bare);
3326
+ if (st !== null) printed.set(`${j.part} ${a}`, st);
3327
+ return { degrees: a, status: fail ? 'FAIL' : 'PASS', mean, px_over_40: f.over40, px_over_80: f.over80, rig_px_over_40: Number(seamRigPxText(f.over40, scale)), ...(st === null || j.short === undefined ? {} : { step_px: st }) };
3215
3328
  });
3216
3329
  return { ...head, status: poses.some((p) => p.status === 'FAIL') ? 'FAIL' : 'PASS', poses };
3217
3330
  });
@@ -3722,9 +3835,10 @@ export function environmentLine(env: CheckEnvironment): string {
3722
3835
  * MEASURABLE is a problem. Without it nothing here reads, writes or prints
3723
3836
  * anything it did not before.
3724
3837
  */
3725
- export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome?: string, mode: PackMode = DEFAULT_PACK_MODE, source?: string, requirements?: string, seamPairsAsked = false, keepStills = false, set?: string, allSets = false, environment?: string): CheckReport {
3838
+ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome?: string, mode: PackMode = DEFAULT_PACK_MODE, source?: string, requirements?: string, seamPairsAsked = false, keepStills = false, set?: string, allSets = false, environment?: string, requirementsAs: string | undefined = requirements): CheckReport {
3726
3839
  let inp: CheckInputs;
3727
3840
  let reqFile: RequirementsFile | null = null;
3841
+ let reqRecord: RequirementsFileRecord | null = null;
3728
3842
  let seams: Map<string, SeamPair[]> | null = null;
3729
3843
  // Every reader collects every problem; one refusal names every set.
3730
3844
  const refused: Problem[] = [];
@@ -3747,6 +3861,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
3747
3861
  const got = take(() => readCheckInputs(rigDir, partsHome, source, set, allSets));
3748
3862
  reqFile = take(() => readRequirements(requirements));
3749
3863
  refuseIfAny(refused);
3864
+ reqRecord = requirementsFileRecord(requirements, requirementsAs ?? requirements);
3750
3865
  inp = got as CheckInputs;
3751
3866
  const file = reqFile as RequirementsFile;
3752
3867
  const ready = inp;
@@ -4065,6 +4180,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4065
4180
  // joints' own art under the limbs, physics left out, rendered twice by rigc on one grid — none without a range
4066
4181
  let sweep: SweepLine | null = null;
4067
4182
  const sweepProblems: Problem[] = [];
4183
+ const sweepSteps = new Map<string, { left: number; right: number }>();
4068
4184
  const joints = inp.parts === null ? [] : sweepJoints(inp.parts);
4069
4185
  if (joints.length > 0) {
4070
4186
  const parts = inp.parts as PartsFile;
@@ -4123,7 +4239,13 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4123
4239
  }
4124
4240
  });
4125
4241
  }
4126
- sweep = sweepLine(joints, under.map((u) => u.px), unread, (a) => sets.get(a) as { under: FrameSet; bare: FrameSet }, stripped === null ? 0 : stripped.physics.length, sweepProblems);
4242
+ // Issue #557: the contour step, read across the upper segment on each bent frame without the underlays.
4243
+ const axes = joints.map((j) => sweepAxis(base, j));
4244
+ const stepOf = (j: SweepJoint, bare: FrameSet): { left: number; right: number } | null => {
4245
+ const axis = axes[joints.indexOf(j)];
4246
+ return axis === null ? null : contourStep(bare.frames[0].image, bare.background, rigToFrameMap(inp.stage, parts.rig_size[1], bare.viewport), j.at, axis, j.radius);
4247
+ };
4248
+ sweep = sweepLine(joints, under.map((u) => u.px), unread, (a) => sets.get(a) as { under: FrameSet; bare: FrameSet }, stripped === null ? 0 : stripped.physics.length, sweepProblems, stepOf, sweepSteps);
4127
4249
  } finally {
4128
4250
  rmSync(sweepDir, { recursive: true, force: true });
4129
4251
  }
@@ -4331,7 +4453,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4331
4453
 
4332
4454
  // 5. the scene's declared requirements (issue #93), only under --requirements
4333
4455
  const reqProblems: Problem[] = [];
4334
- const reqBlock = reqFile === null ? null : measureRequirements(inp, reqFile, buildDir, out, rigc, reqProblems, seams ?? new Map(), measured);
4456
+ const reqBlock = reqFile === null || reqRecord === null ? null : { file: reqRecord, ...measureRequirements(inp, reqFile, buildDir, out, rigc, reqProblems, seams ?? new Map(), measured) };
4335
4457
 
4336
4458
  const skipped: { loop?: string; seam?: string } = {};
4337
4459
  if (inp.noIdle !== null) skipped.loop = inp.noIdle;
@@ -4447,6 +4569,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4447
4569
  besideIdle: named,
4448
4570
  motionSeam,
4449
4571
  cloth,
4572
+ ...(sweepSteps.size === 0 ? {} : { sweepSteps }),
4450
4573
  };
4451
4574
  }
4452
4575
 
@@ -4457,6 +4580,27 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
4457
4580
  /** Where `check` writes the requirement renders, under `--out`: `as-declared/<animation>/`, `released/<name>/`, `full/<name>/`. */
4458
4581
  export const REQUIREMENTS_DIR = 'requirements';
4459
4582
 
4583
+ /**
4584
+ * Issue #556: the requirements file a check read, first in `check.json`'s
4585
+ * `requirements` block — the path as the caller wrote it (the `--requirements`
4586
+ * flag as typed, or `config.requirements` as declared; never resolved, so the
4587
+ * bytes do not move with the directory the build ran in), the sha256 of the
4588
+ * bytes read, and the file's top-level keys in its order, so a reader sees
4589
+ * what the file asked (a `not_swinging`, a `may_fold`) without opening it.
4590
+ */
4591
+ export interface RequirementsFileRecord {
4592
+ path: string;
4593
+ sha256: string;
4594
+ keys: string[];
4595
+ }
4596
+
4597
+ /** The {@link RequirementsFileRecord} of a file {@link readRequirements} has passed, read at `path` and recorded as `recorded`. */
4598
+ export function requirementsFileRecord(path: string, recorded: string): RequirementsFileRecord {
4599
+ const bytes = readFileSync(resolve(path));
4600
+ const raw = JSON.parse(bytes.toString('utf8')) as Record<string, unknown>;
4601
+ return { path: recorded, sha256: createHash('sha256').update(bytes).digest('hex'), keys: Object.keys(raw) };
4602
+ }
4603
+
4460
4604
  /** The throwaway copies' specs and builds, under `--out`; removed before the stage returns. */
4461
4605
  const REQUIREMENTS_SCRATCH = '_requirements';
4462
4606
 
@@ -4478,7 +4622,7 @@ const REQUIREMENTS_SCRATCH = '_requirements';
4478
4622
  * `CHECK_RIGC_GREEN`, quoting rigc. Lines go into the returned block; each
4479
4623
  * FAIL and NOT MEASURABLE into `problems`.
4480
4624
  */
4481
- export function measureRequirements(inp: CheckInputs, file: RequirementsFile, buildDir: string, out: string, rigc: RigcRunner, problems: Problem[], seams: ReadonlyMap<string, readonly SeamPair[]> = new Map(), render: RigcRunner = rigc): RequirementsBlock {
4625
+ export function measureRequirements(inp: CheckInputs, file: RequirementsFile, buildDir: string, out: string, rigc: RigcRunner, problems: Problem[], seams: ReadonlyMap<string, readonly SeamPair[]> = new Map(), render: RigcRunner = rigc): Omit<RequirementsBlock, 'file'> {
4482
4626
  const reqDir = join(out, REQUIREMENTS_DIR);
4483
4627
  const scratch = join(out, REQUIREMENTS_SCRATCH);
4484
4628
  for (const d of [reqDir, scratch]) rmSync(d, { recursive: true, force: true });