@rig-c/parts 1.15.0 → 1.17.0

package/src/autoenvelope.ts

@@ -58,7 +58,10 @@
  *   setup by; an unkeyed property is [0, 0], [1, 1] or 0. `pivot` is the
  *   bone's setup joint in the part's drawing frame (crop px less the part's
  *   padded origin, y down). `setup` is the rig's as written: this package
- *   writes no bone scale, shear or inherit mode, so `{ 1, 1, 0, 0, 'normal' }`.
+ *   writes no bone scale or shear, so `{ 1, 1, 0, 0, 'normal' }` — with the
+ *   bone's own `inherit` where config.bones declares one (issue #348), handed
+ *   to rig-c as written, which refuses any mode but `normal` by name
+ *   (`SKINNING_RANGE_UNSUPPORTED`): the residual is then not measurable.
  *   A shear key has no field in `BoneMotionRange`, so a bone keyed by one
  *   makes the residual not measurable (`ENVELOPE_SHEAR_KEYED`); a property
  *   the idle writes and none of the above names is refused the same way.
@@ -86,7 +89,7 @@ import { edgeLength } from './length.ts';
 
 /** What the derivation reads off the rig besides the part: the bones (name, parent), each bone's setup joint in crop px, the idle as written, the constraints. */
 export interface EnvelopeBasis {
-  bones: ReadonlyArray<{ name: string; parent?: string }>;
+  bones: ReadonlyArray<{ name: string; parent?: string; inherit?: string }>;
   joints: ReadonlyMap<string, readonly [number, number]>;
   motion: MotionSpec;
   constraints: readonly ConfigConstraint[];
@@ -105,8 +108,11 @@ export type EnvelopeDerivation = { envelope: SkinningEnvelope } | { stops: Envel
 /** Where a range comes from: the bone's keys, or the kind of the constraint that drives it — which rig-c refuses by name. */
 type RangeSource = 'keys' | 'ik' | 'transform' | 'path' | 'physics';
 
-/** A `BoneMotionRange` whose `source` may name a constraint kind: rig-c reads `source` at run time and certifies `'keys'` alone. */
-type DeclaredRange = Omit<BoneMotionRange, 'source'> & { source: RangeSource };
+/**
+ * A `BoneMotionRange` whose `source` may name a constraint kind, and whose `setup.inherit` may name a declared mode
+ * (issue #348): rig-c reads both at run time and certifies `'keys'` and `'normal'` alone.
+ */
+type DeclaredRange = Omit<BoneMotionRange, 'source' | 'setup'> & { source: RangeSource; setup: Omit<BoneMotionRange['setup'], 'inherit'> & { inherit: string } };
 
 /**
  * rig-c's helper over ranges whose `source` may be a constraint kind. rig-c's type admits only the one value it
@@ -136,6 +142,12 @@ function trackValues(keys: readonly MotionKey[]): number[] {
 
 const SETUP: BoneMotionRange['setup'] = { scaleX: 1, scaleY: 1, shearX: 0, shearY: 0, inherit: 'normal' };
 
+/** The bone's declared inherit mode as the rig writes it (issue #348), or nothing, so {@link SETUP}'s `normal` stands. */
+function inheritOf(basis: EnvelopeBasis, bone: string): { inherit: string } | Record<string, never> {
+  const mode = basis.bones.find((b) => b.name === bone)?.inherit;
+  return mode === undefined ? {} : { inherit: mode };
+}
+
 /** One bone's declared range off the idle, or the stop that names why it has none. */
 export function boneRange(basis: EnvelopeBasis, bone: string, origin: readonly [number, number], driven: ReadonlyMap<string, RangeSource>): DeclaredRange | EnvelopeStop {
   const joint = basis.joints.get(bone);
@@ -170,7 +182,7 @@ export function boneRange(basis: EnvelopeBasis, bone: string, origin: readonly [
     scaleX,
     scaleY,
     translate: edgeLength(tx, ty),
-    setup: { ...SETUP },
+    setup: { ...SETUP, ...inheritOf(basis, bone) },
   };
 }
 

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, driftLine, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
@@ -70,9 +70,9 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, FOLD_LINE, type FoldsLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
-import { type Cut, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
-import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
+import { besideIdleLine, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { type Cut, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
+import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
 import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
@@ -200,6 +200,36 @@ export function readUnders(configPath: string, cuts: readonly Cut[]): Array<Rast
   return out;
 }
 
+/**
+ * Each limb segment's `cap` image (issue #349), read from its path relative to
+ * the config's directory and keyed `<limb>/<segment index>`. Every one is read
+ * before one refusal names them all: no such file
+ * (`ASSEMBLE_LIMB_CAP_PRESENT`), or a file that does not decode as a PNG
+ * (`ASSEMBLE_LIMB_CAP_DECODES`). The stage holds the image to the cap's box.
+ */
+export function readCaps(configPath: string, limbs: Readonly<Record<string, Limb>>): Map<string, Raster> {
+  const problems: Problem[] = [];
+  const out = new Map<string, Raster>();
+  for (const [l, limb] of Object.entries(limbs)) {
+    limb.segments.forEach((sg, k) => {
+      if (sg.cap === undefined) return;
+      const file = resolve(dirname(resolve(configPath)), sg.cap);
+      const object = `config.limbs.${l}.segments[${k}].cap (part "${sg.part}")`;
+      if (!existsSync(file) || !statSync(file).isFile()) {
+        problems.push({ code: 'ASSEMBLE_LIMB_CAP_PRESENT', object, detail: `names ${file}, which is no such file; a PNG of the cap, its path relative to the config's directory, is required` });
+        return;
+      }
+      try {
+        out.set(`${l}/${k}`, readPng(file));
+      } catch (err) {
+        problems.push({ code: 'ASSEMBLE_LIMB_CAP_DECODES', object, detail: `${file}: ${(err as Error).message.split('\n')[0]}; a PNG is required` });
+      }
+    });
+  }
+  refuseIfAny(problems);
+  return out;
+}
+
 /** Read, assemble, and write only after every refusal has had its chance. Throws a PartsError on a refusal, having written nothing. */
 export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs, log: Log): AssembleResult {
   const src = readSource(input.source);
@@ -208,7 +238,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   // regions and motion, so it requires only what it reads (issue #20).
   const fields = stageFields(loadEarlyConfig(input.config, 'assemble'));
   const under = readUnders(input.config, fields.cuts);
-  const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, seamRule: input.seam, projectRule: input.project });
+  const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
+  const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: input.seam, projectRule: input.project });
   // Emit only after green: every refusal above has already thrown.
   mkdirSync(outs.partsDir, { recursive: true });
   mkdirSync(dirname(outs.partsJson), { recursive: true });
@@ -234,6 +265,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   for (const l of authorPartLines(result.parts.parts)) log(l);
   // One line per plan part an assemble.cuts entry cut, before the fringe lines: the cut is made first. None without cuts.
   for (const l of cutLines(result.cuts)) log(l);
+  // Issue #349: one line per part a limb took, and one per joint with its cap's pixels. None without limbs.
+  for (const l of limbLines(result.limbs)) log(l);
   for (const l of fringeLines(result.parts.parts)) log(l);
   const total = (k: 'opaque_px' | 'visible_px' | 'occluded_px' | 'source_px_taken' | 'visible_not_projected_px'): number => result.parts.parts.reduce((a, p) => a + (p[k] ?? 0), 0);
   const [op, vis, occ, taken, unproj] = (['opaque_px', 'visible_px', 'occluded_px', 'source_px_taken', 'visible_not_projected_px'] as const).map(total);
@@ -1046,6 +1079,40 @@ export function foldsLines(line: FoldsLine): string[] {
   return [head, ...line.folding.map((r) => `  folds  ${r.line}${r.declared === null ? '' : ` — declared in may_fold: ${r.declared}`}`)];
 }
 
+/**
+ * The feet-level line (issue #348) as the console prints it: the status, what was read, the bar and whose it is, then
+ * each foot on a line of its own — its bone, what that hangs from, how many frames posed it, and the worst turn with
+ * the bone that was turned and the bones it came through. A SKIP prints its reason.
+ */
+export function levelLines(line: LevelLine): string[] {
+  const physics = line.physics_left_out === 0 ? '' : `, its ${line.physics_left_out} physics constraint(s) left out`;
+  const read = `${line.animations.length} animation(s) read by rigc render --folds --geometry at ${line.fps} fps${physics} (${line.animations.join(', ')})`;
+  const head =
+    line.status === 'SKIP'
+      ? `${LEVEL_LINE}: SKIP — ${String(line.reason)}; ${read}`
+      : `${LEVEL_LINE}: ${line.status} — ${read}: each foot's drawing within ±${line.bar_degrees} degrees of its setup pose while a bone above it is turned, ${line.bar}`;
+  return [
+    head,
+    ...line.feet.map((f) => {
+      const at = `foot  "${f.part}" on "${f.bone}" (hangs from "${f.hangs_from}"): ${f.status}, ${f.frames_posed} posed frame(s)`;
+      if (f.worst === null) return `${at}, so nothing was measured`;
+      const w = f.worst;
+      return `${at}; worst ${w.degrees} degrees in "${w.animation}" frame ${w.frame} (t = ${w.time}s), "${w.turned}" turned ${w.turned_degrees}, through ${w.through.map((x) => `${x.bone} (inherit ${x.inherit})`).join(', ')}`;
+    }),
+  ];
+}
+
+/**
+ * The limb line (issue #349) as the console prints it: the status and the bar, then each limb part on a line of its
+ * own — its limb, its bone, and on a FAIL every other bone it is bound to.
+ */
+export function limbCheckLines(line: LimbLine): string[] {
+  return [
+    `${LIMB_LINE}: ${line.status} — ${line.parts.length} limb part(s), each bound in rig.json to its one bone with weight 1 (a region on it, or a mesh weighted to it alone)`,
+    ...line.parts.map((r) => `limb  "${r.part}" (${r.limb}) on "${r.bone}": ${r.status}${r.others.length === 0 ? '' : `, also weighted to ${r.others.map((b) => `"${b}"`).join(', ')}`}`),
+  ];
+}
+
 /** A requirement's line as the console prints it: its name and status, the reason first when NOT MEASURABLE, then its figures as check.json holds them. */
 export function requirementText(name: string, line: RequirementLine): string {
   const rest = Object.entries(line).filter(([k]) => k !== 'status' && k !== 'reason');
@@ -1072,7 +1139,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (r.idle === null) log(`  loop: SKIP — ${fig.skipped?.loop ?? ''}`);
   else log(`  ${loopCheckLine(r.idle, fig.loop_max_diff, fig.loop_physics?.length ?? 0)}`);
   if (r.loopPhysics !== null) log(`  ${r.loopPhysics}`);
-  const beside = besideIdleLine(r.besideIdle);
+  const beside = besideIdleLine(r.besideIdle, r.figures[LEVEL_LINE] !== undefined);
   if (beside !== null) log(`  ${beside}`);
   if (r.seamViewport === null || fig.seam_mean === null) log(`  seam: SKIP — ${fig.skipped?.seam ?? ''}`);
   else {
@@ -1086,6 +1153,12 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   for (const name of JUDGEMENT_LINES) log(`  ${judgementLine(name, fig[name])}`);
   const folds = fig[FOLD_LINE];
   if (folds !== undefined) for (const l of foldsLines(folds)) log(`  ${l}`);
+  const level = fig[LEVEL_LINE];
+  if (level !== undefined) for (const [i, l] of levelLines(level).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
+  const stress = fig[STRESS_LINE];
+  if (stress !== undefined) log(`  ${judgementLine(STRESS_LINE, stress)}`);
+  const limbs = fig[LIMB_LINE];
+  if (limbs !== undefined) for (const [i, l] of limbCheckLines(limbs).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const name of REPORTED_LINES) log(`  ${judgementLine(name, fig[name])}`);
   const vsSource = fig[SOURCE_LINE];
   if (vsSource !== undefined) log(`  ${judgementLine(SOURCE_LINE, vsSource)}`);
@@ -1095,7 +1168,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   }
   log(`  gate: spine-html ${fig.gate_spine_html_green ? 'green' : 'RED'} (${fig.rigc_entry.entry}${fig.rigc_entry.spine_core === null ? ', rigc\'s own validator' : `, the spine-core ${fig.rigc_entry.spine_core} round trip`})`);
   log(`  wrote ${r.written.map((w) => join(input.out, w)).join(', ')}, ${join(input.out, 'build')}/${r.idle === null ? '' : `, ${join(input.out, 'idle_frames')}/`}${r.requirements === null ? '' : `, ${join(input.out, REQUIREMENTS_DIR)}/`}${fig.seam_pairs === undefined ? '' : `, ${join(input.out, SEAM_DIR)}/`}${existsSync(join(input.out, STILL_DIR)) ? `, ${join(input.out, STILL_DIR)}/` : ''}`);
-  for (const p of r.problems) log(`  FAIL  ${problemLine(p)}`);
+  for (const p of r.problems) log(failLine(p));
   const reqNotPass = r.requirements === null ? 0 : r.requirements.summary.declared - r.requirements.summary.pass;
   const notMet = r.requirements === null ? `${r.problems.length} bar(s) not met` : `${r.problems.length - reqNotPass} bar(s) not met, ${reqNotPass} declared requirement(s) not PASS`;
   log(`${fig.PASS ? 'check: PASS' : `check: FAIL — ${notMet}`}; ${barsSummary(r)}`);
@@ -1466,7 +1539,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   const refused = (stage: BuildStage, err: unknown, check: CheckReport | null = null): BuildResult => {
     if (!(err instanceof PartsError)) throw err;
     const say = prefixed(stage);
-    for (const p of err.problems) say(`  FAIL  ${problemLine(p)}`);
+    for (const p of err.problems) say(failLine(p));
     say(`refused: ${err.problems.length} problem(s)`);
     log(`build: stopped at ${stage}; no later stage ran`);
     return { stoppedAt: stage, check, artifact: [] };