@rig-c/parts 1.25.0 → 1.27.0

package/src/config.ts

@@ -256,6 +256,8 @@ export interface ChainBones {
   parent: string;
   points: Point[];
   tip: Point;
+  /** Expanded link name -> rig-c inherit mode (issue #369); absent links keep normal inheritance. */
+  link_inherit?: Record<string, RigBoneInherit>;
 }
 
 export type BoneEntry = SingleBone | ChainBones;
@@ -725,6 +727,8 @@ export interface CharacterConfig {
   scene?: SceneSpec;
   /** The cloth and hair recipe `propose --cloth` drafts from (issue #364, `src/cloth.ts`): read by propose only, so no byte of any rig output moves with it. */
   cloth?: ClothRecipes;
+  /** The `assemble.rig_scale` (`parts.json`'s `scale_rig_per_source`) `propose` drafted the rig sections at (issue #354): absent on a hand-authored config, held equal to `assemble.rig_scale` when present. */
+  proposed_rig_scale?: number;
 }
 
 /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -1029,9 +1033,11 @@ export interface AssembleConfig {
   /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
   limbs?: Record<string, Limb>;
   bones?: BoneEntry[];
+  /** Issue #354: the `rig_scale` `propose` drafted the rig sections at, held equal to `assemble.rig_scale` when present. */
+  proposed_rig_scale?: number;
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1081,6 +1087,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'assemble') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     const made = 'assemble' in t ? checkAssemble(c, t.assemble, door) : { parts: [], patches: [], cuts: [] };
+    checkProposedRigScale(c, t);
     if ('scene' in t) checkScene(c, t.scene);
     // Issue #349: the limbs' joints are their bones' origins, so the bones are read with them, and only then.
     if ('limbs' in t) {
@@ -1234,6 +1241,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('generation' in t) checkGeneration(c, t.generation);
   if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
   const { parts, patches, cuts } = 'assemble' in t ? checkAssemble(c, t.assemble, 'full') : { parts: [], patches: [], cuts: [] };
+  checkProposedRigScale(c, t);
   const names = 'bones' in t ? checkBones(c, t.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
   const limbs = 'limbs' in t ? checkLimbs(c, t.limbs, { parts, patches, cuts }, 'bones' in t ? names : null) : null;
   if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
@@ -1252,6 +1260,29 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   return { config: raw as CharacterConfig, animations };
 }
 
+/**
+ * Issue #354: `propose` records `parts.json`'s `scale_rig_per_source` on the
+ * proposal as `proposed_rig_scale`, and pasting the proposal into `config.json`
+ * carries it. When present, `assemble`, `rig` and `build` compare it against
+ * `assemble.rig_scale` and refuse a mismatch: the bones, mesh spacings, segment
+ * coordinates and motion amplitudes are in the proposed rig canvas's pixels and
+ * do not scale when `assemble.rig_scale` changes. A hand-authored config with
+ * no `proposed_rig_scale` is not refused.
+ */
+function checkProposedRigScale(c: Check, t: Record<string, Json>): void {
+  if (!('proposed_rig_scale' in t)) return;
+  if (!c.number('config.proposed_rig_scale', t.proposed_rig_scale, 'positive')) return;
+  const a = isPlainObject(t.assemble) ? t.assemble : null;
+  if (a === null || !('rig_scale' in a) || !(typeof a.rig_scale === 'number' && Number.isFinite(a.rig_scale) && a.rig_scale > 0)) return;
+  if (t.proposed_rig_scale !== a.rig_scale) {
+    c.fail(
+      'CONFIG_PROPOSED_RIG_SCALE',
+      'config.proposed_rig_scale',
+      `is ${t.proposed_rig_scale}, and config.assemble.rig_scale is ${a.rig_scale} — the bones, meshes, limbs and motion were proposed at rig_scale ${t.proposed_rig_scale} and are in that rig canvas's pixels, so they do not scale when assemble.rig_scale changes; re-run assemble and propose at rig_scale ${a.rig_scale} and paste the new proposal, or restore config.assemble.rig_scale to ${t.proposed_rig_scale}`,
+    );
+  }
+}
+
 function isPlainObject(v: Json): v is Record<string, Json> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -1404,9 +1435,9 @@ export interface SkeletonSections {
 /**
  * A `proposal.json` as `propose` writes it — `bones`, `meshes`, `regions`,
  * `motion` and `notes` (strings), `limbs` when `propose --keypoints` drafted
- * them (issue #349) and `constraints` when `propose --cloth` did (issue #364;
+ * them (issue #349), `constraints` when `propose --cloth` did (issue #364;
  * both read here since issue #372, whose `wind` example tracks such a
- * proposal) — under the full loader's own rules for those sections (issue
+ * proposal), and `proposed_rig_scale` (issue #354) — under the full loader's own rules for those sections (issue
  * #85). There is no plan to hold the meshes, regions and limbs against, so
  * the coverage rule (every plan part exactly one of a mesh or a region) is
  * not run, and a limb segment's `from` is held to no plan part (the parts
@@ -1414,9 +1445,9 @@ export interface SkeletonSections {
  * both before writing (`checkProposal`). A key the loader would not take is
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
  */
-export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[] } {
+export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number } {
   const c = new Check();
-  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops']);
+  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale']);
   if (top !== null) {
     const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
     if ('limbs' in top) {
@@ -1430,10 +1461,11 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
     if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
     if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
     if ('stops' in top) checkStops(c, top.stops, names.bones, names.chains);
+    if ('proposed_rig_scale' in top) c.number('config.proposed_rig_scale', top.proposed_rig_scale, 'positive');
     if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
   }
   refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
-  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[] };
+  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number };
 }
 
 /**
@@ -1761,7 +1793,7 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
     const at = `config.bones[${i}]`;
     const isChain = typeof entry === 'object' && entry !== null && 'chain' in entry;
     if (isChain) {
-      const b = c.object(at, entry, ['chain', 'parent', 'points', 'tip'], []);
+      const b = c.object(at, entry, ['chain', 'parent', 'points', 'tip'], ['link_inherit']);
       if (b === null) return;
       if ('parent' in b && c.string(`${at}.parent`, b.parent) && !bones.has(b.parent)) {
         c.fail('CONFIG_NAME_RESOLVES', `${at}.parent`, `names "${b.parent}", which is not "${ROOT_BONE}" or a bone declared above it; parents come first`);
@@ -1779,6 +1811,21 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
           else if (typeof b.parent === 'string' && !parents.has(`${name}0`)) parents.set(`${name}0`, b.parent);
         });
         chains.set(name, points.length);
+        if ('link_inherit' in b) {
+          const path = `${at}.link_inherit`;
+          const links = points.map((_, k) => `${name}${k}`);
+          if (!isPlainObject(b.link_inherit)) {
+            c.fail('CONFIG_FIELD_TYPE', path, `is ${show(b.link_inherit)}; an object mapping this chain's expanded link names to rig-c inherit modes is required`);
+          } else {
+            for (const [link, mode] of Object.entries(b.link_inherit)) {
+              const field = `${path}.${link}`;
+              if (!links.includes(link)) c.fail('CONFIG_NAME_RESOLVES', field, `names "${link}", which is not a link of chain "${name}"; its declared links are ${links.map((n) => `"${n}"`).join(', ')}`);
+              if (c.string(field, mode) && !(RIG_BONE_INHERIT as readonly string[]).includes(mode)) {
+                c.fail('CONFIG_BONE_INHERIT', field, `is ${show(mode)}; one of rig-c's inherit modes, spelled as its table spells them, is required — ${RIG_BONE_INHERIT.join(', ')} (rig-c's RigBone.inherit; nothing here folds a case or maps a name)`);
+              }
+            }
+          }
+        }
       }
       return;
     }
@@ -2766,7 +2813,7 @@ function attachedParts(meshes: Json, regions: Json): Set<string> {
  * - `part` on a tag other than `bottomwear` (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`):
  *   the field hands the skirt's recipe to a part of another tag (issue #402),
  *   and only the skirt has a recipe that part can take; whether the part
- *   exists, and is a `topwear` that hangs below the hip, is read off the parts
+ *   exists, and is a `topwear` part or its cut piece hanging below the hip, is read off the assembled parts
  *   by `propose` (`PROPOSE_CLOTH_PART`);
  * - a strength, declared or the recipe's default, whose spring is unstable at
  *   a damping the recipe runs at — k = strength·massInverse·step² at or past
@@ -2795,8 +2842,9 @@ function checkCloth(c: Check, v: Json): void {
   for (const tag of CLOTH_TARGETS) {
     if (!(tag in v)) continue;
     const path = `${at}.${JSON.stringify(tag)}`;
-    const r = c.object(path, v[tag], ['chains', 'links', 'wind', 'gravity'], ['split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing', 'part']);
+    const r = c.object(path, v[tag], ['links', 'wind', 'gravity'], ['chains', 'split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing', 'part', 'parts']);
     if (r === null) continue;
+    if (tag !== 'back hair' && !('chains' in r)) c.fail('CONFIG_FIELD_PRESENT', `${path}.chains`, 'is absent and required');
     const chains = 'chains' in r && c.int(`${path}.chains`, r.chains, 1) ? (r.chains as number) : null;
     const links = 'links' in r && c.int(`${path}.links`, r.links, 1) ? (r.links as number) : null;
     if ('split' in r) {
@@ -2849,11 +2897,32 @@ function checkCloth(c: Check, v: Json): void {
     if ('translate' in r && c.number(`${path}.translate`, r.translate, 'unit') && r.translate === 0) {
       c.fail('CONFIG_FIELD_TYPE', `${path}.translate`, 'is 0; a mix above 0 and at most 1 is required (leave translate out for none)');
     }
+    const checkPartList = (fieldPath: string, list: Json): void => {
+      if (!c.array(fieldPath, list, true)) return;
+      const seen = new Set<string>();
+      (list as Json[]).forEach((item, i) => {
+        if (c.string(`${fieldPath}[${i}]`, item)) {
+          const s = item as string;
+          if (seen.has(s)) {
+            c.fail('CONFIG_CLOTH_PARTS_UNIQUE', `${fieldPath}[${i}]`, `repeats "${s}"; each part in the list must be named once, in order from root to tip`);
+          }
+          seen.add(s);
+        }
+      });
+    };
+    if ('part' in r && 'parts' in r) {
+      c.fail('CONFIG_CLOTH_PARTS_UNIQUE', `${path}.parts`, 'is declared beside part; declare either parts (a list of parts from root to tip) or part, not both');
+    }
     if ('part' in r) {
-      if (tag !== 'bottomwear') {
-        c.fail('CONFIG_CLOTH_PART_ON_BOTTOMWEAR', `${path}.part`, `is declared on "${tag}"; part hands the skirt's recipe (bottomwear) to a topwear part that holds a skirt (a dress) — leave it out here`);
+      if (Array.isArray(r.part)) {
+        checkPartList(`${path}.part`, r.part);
+      } else if (tag !== 'bottomwear') {
+        c.fail('CONFIG_CLOTH_PART_ON_BOTTOMWEAR', `${path}.part`, `is declared on "${tag}"; part hands the skirt's recipe (bottomwear) to a topwear part or its cut skirt piece (a dress) — leave it out here`);
       } else c.string(`${path}.part`, r.part);
     }
+    if ('parts' in r) {
+      checkPartList(`${path}.parts`, r.parts);
+    }
     if ('swing' in r) {
       if (tag !== 'bottomwear') {
         c.fail('CONFIG_CLOTH_SWING_SCALE_PER_TREE', `${path}.swing`, `is declared on "${tag}"; the shared swing is the skirt's (bottomwear) — leave it out here`);

package/src/headbox.ts

@@ -42,6 +42,20 @@ export const HEAD_LAYER_MIN_PX = 150;
 
 export type Box = [number, number, number, number];
 
+export interface HeadBoxOptions {
+  /** Whether `"back hair"` is included in the union (issue #351); default `true`. */
+  backHair?: boolean;
+}
+
+export interface HeadBoxWithoutBackHair {
+  /** The square box's side in source px without `"back hair"`. */
+  edge: number;
+  /** The box without `"back hair"` before clamping to the painting. */
+  unclamped: Box;
+  /** The box without `"back hair"` held inside the painting, or `null` when `edge` exceeds a canvas side. */
+  head_box: Box | null;
+}
+
 export interface HeadBoxProposal {
   /** The square box, inside the painting: what goes into `seethrough.head_box`. */
   head_box: Box;
@@ -49,8 +63,10 @@ export interface HeadBoxProposal {
   unclamped: Box;
   /** How far the box was moved to stay inside, in source px. */
   shift: [number, number];
-  /** The layers that contributed, with their opaque pixel counts after the clean-up. */
+  /** The layers that contributed, with their opaque pixel counts after the ghost clean-up. */
   layers: Array<[string, number]>;
+  /** Present when `"back hair"` contributed (with `backHair !== false`, issue #351): the box without `"back hair"`. */
+  without_back_hair?: HeadBoxWithoutBackHair;
 }
 
 /**
@@ -90,7 +106,7 @@ function cleanedOpaque(pixels: { width: number; height: number; data: Uint8Clamp
  * `source.w` x `source.h` pixels. Every refusal names the value found and the
  * value required.
  */
-export function proposeHeadBox(full: LayerSet, source: { w: number; h: number }): HeadBoxProposal {
+export function proposeHeadBox(full: LayerSet, source: { w: number; h: number }, opts?: HeadBoxOptions): HeadBoxProposal {
   const problems: Problem[] = [];
   if (!(Number.isInteger(source.w) && Number.isInteger(source.h) && source.w > 0 && source.h > 0)) {
     problems.push({ code: 'HEADBOX_CANVAS_SIZE', object: '--canvas', detail: `is ${source.w}x${source.h}; the painting's size in positive integer pixels is required` });
@@ -102,12 +118,14 @@ export function proposeHeadBox(full: LayerSet, source: { w: number; h: number })
 
   const pad = squarePad(source.w, source.h);
   const k = pad.side / full.canvas.w;
+  const includeBackHair = opts?.backHair !== false;
   // The union does not depend on the order the layers are read in; a name
   // that appears twice is last-wins in draw order (the reference's dict was
   // last-wins in manifest order, and no wrapper output read so far repeats one).
   const boxes = new Map<string, { left: number; top: number; xs: number[]; ys: number[] }>();
   for (const L of full.layers) {
     if (!(HEAD_LAYERS as readonly string[]).includes(L.name)) continue;
+    if (!includeBackHair && L.name === 'back hair') continue;
     const { xs, ys } = cleanedOpaque(L.pixels);
     if (xs.length < HEAD_LAYER_MIN_PX) continue;
     boxes.set(L.name, { left: L.left, top: L.top, xs, ys });
@@ -130,44 +148,60 @@ export function proposeHeadBox(full: LayerSet, source: { w: number; h: number })
     if (f.top + y > fy1) fy1 = f.top + y;
   }
   const cut = fy1 + 0.35 * (fy1 - fy0);
-  let x0 = Infinity;
-  let x1 = -Infinity;
-  let y0 = Infinity;
-  let y1 = -Infinity;
-  for (const b of boxes.values()) {
-    for (let i = 0; i < b.xs.length; i++) {
-      const y = b.top + b.ys[i];
-      if (y > cut) continue;
-      const x = b.left + b.xs[i];
-      if (x < x0) x0 = x;
-      if (x > x1) x1 = x;
-      if (y < y0) y0 = y;
-      if (y > y1) y1 = y;
+  const measureUnion = (entries: Iterable<{ left: number; top: number; xs: number[]; ys: number[] }>): { edge: number; unclamped: Box; shift: [number, number]; head_box: Box | null } => {
+    let x0 = Infinity;
+    let x1 = -Infinity;
+    let y0 = Infinity;
+    let y1 = -Infinity;
+    for (const b of entries) {
+      for (let i = 0; i < b.xs.length; i++) {
+        const y = b.top + b.ys[i];
+        if (y > cut) continue;
+        const x = b.left + b.xs[i];
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+      }
     }
-  }
-  const size = Math.max(x1 - x0, y1 - y0) * 1.12;
-  const cx = (x0 + x1) / 2;
-  const cy = (y0 + y1) / 2;
-  // Each edge rounded as the reference rounds it; then the side is the larger
-  // of the two rounded extents, so the box is square, never holds less than
-  // the reference's, and equals it wherever the reference's was square.
-  const ex = [pyRound((cx - size / 2) * k), pyRound((cx + size / 2) * k)];
-  const ey = [pyRound((cy - size / 2) * k), pyRound((cy + size / 2) * k)];
-  const edge = Math.max(ex[1] - ex[0], ey[1] - ey[0]);
-  const bx = ex[0] - pad.left;
-  const by = ey[0] - pad.top;
-  const unclamped: Box = [bx, by, bx + edge, by + edge];
-  if (edge > source.w || edge > source.h) {
+    const size = Math.max(x1 - x0, y1 - y0) * 1.12;
+    const cx = (x0 + x1) / 2;
+    const cy = (y0 + y1) / 2;
+    // Each edge rounded as the reference rounds it; then the side is the larger
+    // of the two rounded extents, so the box is square, never holds less than
+    // the reference's, and equals it wherever the reference's was square.
+    const ex = [pyRound((cx - size / 2) * k), pyRound((cx + size / 2) * k)];
+    const ey = [pyRound((cy - size / 2) * k), pyRound((cy + size / 2) * k)];
+    const edge = Math.max(ex[1] - ex[0], ey[1] - ey[0]);
+    const bx = ex[0] - pad.left;
+    const by = ey[0] - pad.top;
+    const unclamped: Box = [bx, by, bx + edge, by + edge];
+    if (edge > source.w || edge > source.h) return { edge, unclamped, shift: [0, 0], head_box: null };
+    const hold = (lo: number, extent: number): number => (lo < 0 ? -lo : lo + edge > extent ? extent - edge - lo : 0);
+    const shift: [number, number] = [hold(bx, source.w), hold(by, source.h)];
+    const head_box: Box = [bx + shift[0], by + shift[1], bx + shift[0] + edge, by + shift[1] + edge];
+    return { edge, unclamped, shift, head_box };
+  };
+  const main = measureUnion(boxes.values());
+  const without = includeBackHair && boxes.has('back hair') ? measureUnion([...boxes.entries()].filter(([n]) => n !== 'back hair').map(([, b]) => b)) : null;
+  if (main.head_box === null) {
+    const hairNote =
+      without !== null && without.edge < main.edge
+        ? ` ("back hair" grew the side from ${without.edge} to ${main.edge} px; without it${without.head_box !== null ? `, [${without.head_box.join(', ')}] (${without.edge}x${without.edge}) fits —` : ''} pass --no-back-hair)`
+        : '';
     refuseIfAny([
       {
         code: 'HEADBOX_FITS_CANVAS',
         object: 'head box',
-        detail: `is ${edge}x${edge} source px, proposed at [${unclamped.join(', ')}]; the ${source.w}x${source.h} painting cannot hold it at that size, and shrinking it would cut the head`,
+        detail: `is ${main.edge}x${main.edge} source px, proposed at [${main.unclamped.join(', ')}]; the ${source.w}x${source.h} painting cannot hold it at that size, and shrinking it would cut the head${hairNote}`,
       },
     ]);
   }
-  const hold = (lo: number, extent: number): number => (lo < 0 ? -lo : lo + edge > extent ? extent - edge - lo : 0);
-  const shift: [number, number] = [hold(bx, source.w), hold(by, source.h)];
-  const head_box: Box = [bx + shift[0], by + shift[1], bx + shift[0] + edge, by + shift[1] + edge];
-  return { head_box, unclamped, shift, layers: [...boxes.entries()].map(([n, b]) => [n, b.xs.length]) };
+  return {
+    head_box: main.head_box as Box,
+    unclamped: main.unclamped,
+    shift: main.shift,
+    layers: [...boxes.entries()].map(([n, b]) => [n, b.xs.length]),
+    ...(without === null ? {} : { without_back_hair: { edge: without.edge, unclamped: without.unclamped, head_box: without.head_box } }),
+  };
 }