@rig-c/parts 1.16.0 → 1.17.0

package/src/config.ts

@@ -86,7 +86,7 @@
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { RIG_SKIN_CONSTRAINT_KEYS, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
+import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
@@ -227,6 +227,15 @@ export interface SingleBone {
   parent: string;
   at: Point;
   tip?: Point;
+  /**
+   * What the bone takes from its parent's transform (issue #348): one of rig-c's
+   * own mode names (`RIG_BONE_INHERIT`, rig-c's `RigBone.inherit`), passed to
+   * rig.json as written. Absent, rig.json carries no `inherit` and the bone
+   * takes the parent's whole transform (rig-c's default, `normal`). A spelling
+   * outside rig-c's table is refused by name (`CONFIG_BONE_INHERIT`): the
+   * runtime would fold the first letter, and this loader folds and maps nothing.
+   */
+  inherit?: RigBoneInherit;
 }
 
 export interface ChainBones {
@@ -627,12 +636,37 @@ export interface ConfigConstraint {
   [field: string]: unknown;
 }
 
+/**
+ * One segment of a limb (issue #349): the part it makes, the part whose
+ * pixels it takes (`from`: a plan part or a cut's piece), and the one bone it
+ * rides with weight 1. Every segment after the first sits below a joint at
+ * its bone's origin: `joint` names it, `range` is the bend the joint may take
+ * from rest, `[min, max]` degrees (metadata: read by the stress readers, not
+ * by rig-c), and `cap` an image, relative to the config's directory, of the
+ * cap that overlaps the joint (`limbCaps` in `src/assemble.ts`).
+ */
+export interface LimbSegment {
+  part: string;
+  from: string;
+  bone: string;
+  joint?: string;
+  range?: [number, number];
+  cap?: string;
+}
+
+/** A limb (issue #349): its segments, upper first; each segment's bone is the child of the one before. */
+export interface Limb {
+  segments: LimbSegment[];
+}
+
 export interface CharacterConfig {
   key: string;
   note?: string;
   generation?: Generation;
   seethrough?: SeeThrough;
   assemble: Assemble;
+  /** Limbs cut at their joints (issue #349): absent, no part is cut at a joint and no byte of any output moves. */
+  limbs?: Record<string, Limb>;
   bones: BoneEntry[];
   meshes: Record<string, MeshSpec>;
   regions: Record<string, string>;
@@ -925,9 +959,12 @@ export interface AssembleConfig {
   seethrough: SeeThrough;
   assemble: Assemble;
   scene?: SceneSpec;
+  /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
+  limbs?: Record<string, Limb>;
+  bones?: BoneEntry[];
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -976,8 +1013,14 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   }
   if (door === 'assemble') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
-    if ('assemble' in t) checkAssemble(c, t.assemble, door);
+    const made = 'assemble' in t ? checkAssemble(c, t.assemble, door) : { parts: [], patches: [], cuts: [] };
     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) {
+      if (!('bones' in t)) c.fail('CONFIG_FIELD_PRESENT', 'config.bones', 'is absent; config.limbs names bones, and each joint is its bone\'s origin, so assemble reads the bones with the limbs');
+      const names = 'bones' in t ? checkBones(c, t.bones) : null;
+      checkLimbs(c, t.limbs, made, names);
+    }
   }
   const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
@@ -1124,9 +1167,10 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
   const { parts, patches, cuts } = 'assemble' in t ? checkAssemble(c, t.assemble, 'full') : { parts: [], patches: [], cuts: [] };
   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);
   if ('regions' in t) checkRegions(c, t.regions, names.bones);
-  if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions);
+  if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions, limbs);
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
   if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones);
@@ -1651,8 +1695,16 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
       }
       return;
     }
-    const b = c.object(at, entry, ['name', 'parent', 'at'], ['tip']);
+    const b = c.object(at, entry, ['name', 'parent', 'at'], ['tip', 'inherit']);
     if (b === null) return;
+    // Issue #348: rig-c's own mode names, as its table spells them; nothing is folded, mapped or defaulted.
+    if ('inherit' in b && c.string(`${at}.inherit`, b.inherit) && !(RIG_BONE_INHERIT as readonly string[]).includes(b.inherit)) {
+      c.fail(
+        'CONFIG_BONE_INHERIT',
+        `${at}.inherit`,
+        `is ${show(b.inherit)}; 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)`,
+      );
+    }
     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`);
     }
@@ -2087,14 +2139,139 @@ function checkRegions(c: Check, v: Json, bones: Set<string>): void {
   }
 }
 
+/** What the loader read off `config.limbs` (issue #349): each limb part with its bone, and each part a limb takes, with the first limb taking it. */
+interface LimbNames {
+  parts: Map<string, { bone: string; at: string }>;
+  consumed: Map<string, string>;
+}
+
+/**
+ * `config.limbs` (issue #349): `{<limb>: {segments: [{part, from, bone}, {part,
+ * from, bone, joint, range?, cap?}, …]}}`, upper segment first. Refused field
+ * by field: `part` a new part name (`CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE`
+ * against the plan, the patches, the cuts and every other limb part); `from`
+ * a plan part or a cut's piece (`CONFIG_NAME_RESOLVES`), the segments of one
+ * limb that take one part consecutive (`CONFIG_LIMB_FROM_RUN`: the cut
+ * between them is a joint line, and a joint line has two sides); `bone` a
+ * declared bone, each segment's bone the child of the one before
+ * (`CONFIG_LIMB_BONES_CHAIN`: a bend is a rotation of the lower bone about
+ * the joint, its origin); the first segment has no joint, every other names
+ * one (`CONFIG_KEY_KNOWN`, `CONFIG_FIELD_PRESENT`); `range` two finite
+ * degrees `[min, max]` with `min <= 0 <= max` (`CONFIG_LIMB_RANGE`: the range
+ * is measured from rest, so rest is in it); `cap` a non-empty path. A limb
+ * has two segments or more. With `names` null (no `bones`), bones are not
+ * resolved. Returns the limb parts and the parts the limbs take.
+ */
+function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[]; cuts: string[] }, names: { bones: Set<string>; parents: Map<string, string> } | null): LimbNames {
+  const out: LimbNames = { parts: new Map(), consumed: new Map() };
+  if (!isPlainObject(v)) {
+    c.fail('CONFIG_FIELD_TYPE', 'config.limbs', `is ${show(v)}; an object of limb name -> {"segments": [...]} is required`);
+    return out;
+  }
+  const sources = new Set([...made.parts, ...made.cuts]);
+  const firstAt = new Map<string, string>();
+  for (const [limb, spec] of Object.entries(v)) {
+    const at = `config.limbs.${limb}`;
+    const o = c.object(at, spec, ['segments'], []);
+    if (o === null || !('segments' in o)) continue;
+    if (!Array.isArray(o.segments) || o.segments.length < 2) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.segments`, `is ${show(o.segments)}; an array of two segments or more, upper first, is required — a limb is cut at a joint, and a joint has a segment on each side`);
+      continue;
+    }
+    const segs = o.segments as Json[];
+    const froms: Array<string | null> = [];
+    const bones: Array<string | null> = [];
+    segs.forEach((entry, i) => {
+      const sat = `${at}.segments[${i}]`;
+      const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap']);
+      froms.push(null);
+      bones.push(null);
+      if (e === null) return;
+      // The upper segment sits below no joint; every other sits below one, which it names.
+      if (i === 0) {
+        for (const k of ['joint', 'range', 'cap'].filter((q) => q in e)) c.fail('CONFIG_KEY_KNOWN', `${sat}.${k}`, `is not a field on the upper segment; it sits below no joint, so ${k} belongs to the segment below the joint it names (segments[1] and on)`);
+      } else if (!('joint' in e)) c.fail('CONFIG_FIELD_PRESENT', `${sat}.joint`, 'is absent and required; a segment after the first sits below a joint, at its bone\'s origin, and names it');
+      if ('part' in e && c.string(`${sat}.part`, e.part)) {
+        const name = e.part;
+        if (!partNameOk(name)) c.fail('CONFIG_PART_NAME', `${sat}.part`, `names the part ${show(name)}; a part name is a file name, so it may not be empty, start with "." or hold a slash`);
+        else if (made.parts.includes(name) || made.patches.includes(name) || made.cuts.includes(name)) {
+          c.fail('CONFIG_PART_UNIQUE', `${sat}.part`, `names the part "${name}", which ${made.parts.includes(name) ? 'assemble.plan' : made.patches.includes(name) ? 'assemble.patches' : 'assemble.cuts'} already makes; a limb segment makes a part of its own`);
+        } else if (firstAt.has(name)) c.fail('CONFIG_PART_UNIQUE', `${sat}.part`, `names the part "${name}" again (first at ${firstAt.get(name)})`);
+        else {
+          firstAt.set(name, sat);
+          if ('bone' in e && typeof e.bone === 'string') out.parts.set(name, { bone: e.bone, at: `config.limbs.${limb} segment ${i}` });
+        }
+      }
+      if ('from' in e) {
+        if (typeof e.from !== 'string' || !sources.has(e.from)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${sat}.from`, `is ${show(e.from)}; a part named in assemble.plan or made by an assemble.cuts entry is required — the layer the segment's pixels are cut from`);
+        } else {
+          froms[i] = e.from;
+          if (!out.consumed.has(e.from)) out.consumed.set(e.from, limb);
+        }
+      }
+      if ('bone' in e && c.string(`${sat}.bone`, e.bone)) {
+        if (names !== null && !names.bones.has(e.bone)) c.fail('CONFIG_NAME_RESOLVES', `${sat}.bone`, `is "${e.bone}"; a bone config.bones declares is required (a chain's links are <chain>0, <chain>1, …)`);
+        else bones[i] = e.bone;
+      }
+      if ('joint' in e) c.string(`${sat}.joint`, e.joint);
+      if ('range' in e) {
+        const r = e.range;
+        const ok = Array.isArray(r) && r.length === 2 && r.every((n) => typeof n === 'number' && Number.isFinite(n));
+        if (!ok) c.fail('CONFIG_FIELD_TYPE', `${sat}.range`, `is ${show(r)}; [min, max], two finite numbers of degrees from rest, is required`);
+        else {
+          const [lo, hi] = r as [number, number];
+          if (!(lo <= 0 && 0 <= hi)) c.fail('CONFIG_LIMB_RANGE', `${sat}.range`, `is [${lo}, ${hi}]; min <= 0 <= max is required — the range is the bend from rest, and rest (0) is a pose the joint takes`);
+        }
+      }
+      if ('cap' in e && !(typeof e.cap === 'string' && e.cap !== '')) {
+        c.fail('CONFIG_FIELD_TYPE', `${sat}.cap`, `is ${show(e.cap)}; a non-empty path to a PNG is required, relative to the config's directory — the cap's image over the box assemble's limb line prints`);
+      }
+    });
+    froms.forEach((f, i) => {
+      if (f === null || i === 0 || froms[i - 1] === f) return;
+      const back = froms.slice(0, i - 1).lastIndexOf(f);
+      if (back >= 0) {
+        c.fail('CONFIG_LIMB_FROM_RUN', `${at}.segments[${i}].from`, `is "${f}", which segments[${back}] takes too with another part between them; the segments that take one part must be consecutive — the cut between two of them is the joint line, and it has two sides`);
+      }
+    });
+    if (names !== null) {
+      bones.forEach((b, i) => {
+        if (i === 0 || b === null || bones[i - 1] === null) return;
+        const parent = names.parents.get(b);
+        if (parent !== bones[i - 1]) {
+          c.fail('CONFIG_LIMB_BONES_CHAIN', `${at}.segments[${i}].bone`, `is "${b}", whose parent is ${parent === undefined ? 'not declared' : `"${parent}"`}; "${bones[i - 1]}", the bone of segments[${i - 1}], is required — the lower segment turns about the joint on a bone that hangs from the upper's`);
+        }
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Every plan part — and every cut's piece, which the caller lists with them —
  * is exactly one of a mesh or a region, every patch is a region, and every
  * mesh or region is one of those parts or a patch.
  */
-function checkCoverage(c: Check, parts: string[], patches: string[], meshes: Json, regions: Json): void {
+function checkCoverage(c: Check, made: string[], patches: string[], meshes: Json, regions: Json, limbs: LimbNames | null = null): void {
   const m = typeof meshes === 'object' && meshes !== null ? Object.keys(meshes) : [];
   const r = typeof regions === 'object' && regions !== null ? Object.keys(regions) : [];
+  // Issue #349: a part a limb takes is cut into the limb's parts and is not made itself; the limb's parts are.
+  const parts = limbs === null ? made : [...made.filter((n) => !limbs.consumed.has(n)), ...limbs.parts.keys()];
+  if (limbs !== null) {
+    for (const name of [...m, ...r]) {
+      const by = limbs.consumed.get(name);
+      if (by !== undefined) {
+        c.fail('CONFIG_NAME_RESOLVES', `config.${m.includes(name) ? 'meshes' : 'regions'}.${name}`, `names "${name}", which config.limbs.${by} cuts into its parts at the joints, so no part of that name is made — attach the limb's parts instead`);
+      }
+    }
+    for (const [part, seg] of limbs.parts) {
+      const bone = isPlainObject(regions) ? regions[part] : undefined;
+      if (typeof bone === 'string' && bone !== seg.bone) {
+        c.fail('CONFIG_LIMB_BONE', `config.regions.${part}`, `is "${bone}"; "${part}" is ${seg.at}, which rides "${seg.bone}" with weight 1, so config.regions.${part} "${seg.bone}" is required`);
+      }
+    }
+  }
   for (const patch of patches) {
     if (m.includes(patch)) c.fail('CONFIG_PART_ATTACHED', `part "${patch}"`, `is an assemble.patches entry and has a meshes entry; a patch is a region — drop config.meshes.${patch} and name its bone in config.regions.${patch}`);
     else if (!r.includes(patch)) c.fail('CONFIG_PART_ATTACHED', `part "${patch}"`, `is an assemble.patches entry with no regions entry; a patch is a region, so config.regions.${patch} naming its bone is required`);
@@ -2106,8 +2283,8 @@ function checkCoverage(c: Check, parts: string[], patches: string[], meshes: Jso
     if (inM && inR) c.fail('CONFIG_PART_ATTACHED', `part "${part}"`, 'has both a meshes entry and a regions entry; exactly one is required');
   }
   for (const name of [...m, ...r]) {
-    if (!parts.includes(name) && !patches.includes(name)) {
-      c.fail('CONFIG_NAME_RESOLVES', `config.${m.includes(name) ? 'meshes' : 'regions'}.${name}`, 'names a part that neither assemble.plan nor assemble.patches makes (nor an assemble.cuts entry)');
+    if (!parts.includes(name) && !patches.includes(name) && !(limbs?.consumed.has(name) ?? false)) {
+      c.fail('CONFIG_NAME_RESOLVES', `config.${m.includes(name) ? 'meshes' : 'regions'}.${name}`, 'names a part that neither assemble.plan nor assemble.patches makes (nor an assemble.cuts entry, nor config.limbs)');
     }
   }
 }

package/src/limbs.ts

@@ -0,0 +1,188 @@
+/**
+ * Limbs cut at their joints (issue #349): the geometry `assemble` cuts a
+ * declared limb's layer by, and the cap each lower segment carries past its
+ * joint. Pure arithmetic on rig pixels (y down, origin top-left, the space of
+ * `parts.json` and of `config.bones`); no clock, no randomness.
+ *
+ * - **Where a bone is.** A single bone sits at its `at` and ends at its `tip`
+ *   (no tip: no end); a chain's link `k` sits at `points[k]` and ends at
+ *   `points[k + 1]`, the last link at `tip` ({@link bonePlaces}).
+ * - **Which limb a pixel belongs to.** Every pixel of a part a limb takes
+ *   goes to one limb: the one whose polyline — its segments' bone origins in
+ *   order, then the last bone's end when it has one — passes nearest the
+ *   pixel's centre, by squared Euclidean distance to the polyline's pieces; a
+ *   tie goes to the limb `config.limbs` declares first ({@link nearestLimb}).
+ *   Two legs in one `legwear` layer are split this way, with no polygon.
+ * - **The joint line.** The joint between segments `k − 1` and `k` is the
+ *   origin of segment `k`'s bone. Its line runs through that point,
+ *   perpendicular to the limb's axis there: the sum of the unit directions of
+ *   the upper bone (its origin to the joint) and the lower bone (the joint to
+ *   its end, when it has one; the upper's alone when it has none) — on a
+ *   straight limb the plain perpendicular, on a bent one the bisector
+ *   ({@link jointLine}). A pixel is past the line when its centre's dot
+ *   product with the axis, from the joint, is above 0; a centre on the line
+ *   stays on the upper side.
+ * - **Which segment a pixel belongs to.** Among the consecutive segments of a
+ *   limb that take one part, a pixel starts on the first and moves down one
+ *   segment for each joint line it is past, in order, stopping at the first it
+ *   is not past ({@link segmentOf}). A segment whose part is not the previous
+ *   segment's takes its limb's share of its own part whole: no line is cut
+ *   between two layers (the shin's legwear and the foot's footwear).
+ * - **The limb's width at a joint.** The pixels of the limb's art (alpha above
+ *   8, both segments' parts) whose centre lies within half a pixel of the
+ *   joint line, read along the line: the run of them through the joint — the
+ *   pixel nearest the joint must lie within 1 px of it, and the run grows while
+ *   neighbours along the line are at most 1.5 px apart (a diagonal line's
+ *   centres are up to sqrt(2) apart) — from its first to its last, plus one
+ *   pixel ({@link limbWidth}). The cap's radius is half of it.
+ * - **The cap.** The pixels whose centre lies within the radius of the joint
+ *   and on the upper side of its line, inside the box
+ *   {@link capBox} prints: the overlap the lower segment carries so a bend
+ *   shows no gap. The tool invents none of them: each is the config's cap
+ *   image's where that image is not transparent, else the layer's where the
+ *   limb has art there, else missing — counted, and named in the limb line.
+ */
+import type { BoneEntry, Limb } from './config.ts';
+
+export type Pt = [number, number];
+
+/** A bone's origin and, when it has one, its end, in rig px. */
+export interface BonePlace {
+  at: Pt;
+  end: Pt | null;
+}
+
+/** Where every bone `bones` declares sits and ends (module comment). */
+export function bonePlaces(bones: readonly BoneEntry[]): Map<string, BonePlace> {
+  const out = new Map<string, BonePlace>();
+  for (const b of bones) {
+    if ('chain' in b) {
+      b.points.forEach((p, k) => out.set(`${b.chain}${k}`, { at: [p[0], p[1]], end: k + 1 < b.points.length ? [b.points[k + 1][0], b.points[k + 1][1]] : [b.tip[0], b.tip[1]] }));
+    } else out.set(b.name, { at: [b.at[0], b.at[1]], end: b.tip === undefined ? null : [b.tip[0], b.tip[1]] });
+  }
+  return out;
+}
+
+/** A limb's polyline: its segments' bone origins in order, then the last bone's end when it has one. */
+export function limbPolyline(limb: Limb, places: ReadonlyMap<string, BonePlace>): Pt[] {
+  const pts = limb.segments.map((s) => (places.get(s.bone) as BonePlace).at);
+  const last = places.get(limb.segments[limb.segments.length - 1].bone) as BonePlace;
+  return last.end === null ? pts : [...pts, last.end];
+}
+
+/** The squared distance from `(x, y)` to the polyline `pts` (one point: to that point). */
+export function polylineDist2(pts: readonly Pt[], x: number, y: number): number {
+  if (pts.length === 1) return (x - pts[0][0]) ** 2 + (y - pts[0][1]) ** 2;
+  let best = Infinity;
+  for (let i = 0; i + 1 < pts.length; i++) {
+    const [ax, ay] = pts[i];
+    const dx = pts[i + 1][0] - ax;
+    const dy = pts[i + 1][1] - ay;
+    const len2 = dx * dx + dy * dy;
+    const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / len2));
+    const d = (x - ax - t * dx) ** 2 + (y - ay - t * dy) ** 2;
+    if (d < best) best = d;
+  }
+  return best;
+}
+
+/** The index, among `lines`, of the polyline nearest the pixel `(px, py)`'s centre; the first wins a tie. */
+export function nearestLimb(lines: ReadonlyArray<readonly Pt[]>, px: number, py: number): number {
+  let best = 0;
+  let bestD = Infinity;
+  lines.forEach((l, i) => {
+    const d = polylineDist2(l, px + 0.5, py + 0.5);
+    if (d < bestD) {
+      bestD = d;
+      best = i;
+    }
+  });
+  return best;
+}
+
+/** A joint's line: through `at`, perpendicular to the unit `axis` (pointing from the upper segment to the lower). */
+export interface JointLine {
+  at: Pt;
+  axis: Pt;
+}
+
+/** The unit vector along `(x, y)`, or null when it has no length. */
+function unit(x: number, y: number): Pt | null {
+  const l = Math.sqrt(x * x + y * y);
+  return l === 0 ? null : [x / l, y / l];
+}
+
+/**
+ * The joint line between a bone whose origin is `upper` and one whose origin
+ * is `at` and whose end is `end` (null: none) — module comment. Null when no
+ * axis exists: the upper bone has no length, or the limb folds straight back
+ * on itself.
+ */
+export function jointLine(upper: Pt, at: Pt, end: Pt | null): JointLine | null {
+  const u = unit(at[0] - upper[0], at[1] - upper[1]);
+  if (u === null) return null;
+  const w = end === null ? null : unit(end[0] - at[0], end[1] - at[1]);
+  const a = w === null ? u : unit(u[0] + w[0], u[1] + w[1]);
+  return a === null ? null : { at, axis: a };
+}
+
+/** Whether the pixel `(px, py)`'s centre lies past the line (on the lower segment's side); on the line is not past. */
+export function pastJoint(line: JointLine, px: number, py: number): boolean {
+  return (px + 0.5 - line.at[0]) * line.axis[0] + (py + 0.5 - line.at[1]) * line.axis[1] > 0;
+}
+
+/**
+ * The segment, among `first .. last` (consecutive segments taking one part),
+ * a pixel belongs to: `first`, moved down one for each joint line in order it
+ * is past, stopping at the first it is not. `lines[k]` is the line above
+ * segment `k`.
+ */
+export function segmentOf(lines: ReadonlyArray<JointLine | null>, first: number, last: number, px: number, py: number): number {
+  let k = first;
+  while (k < last && pastJoint(lines[k + 1] as JointLine, px, py)) k++;
+  return k;
+}
+
+/**
+ * The limb's width at a joint (module comment): `art(x, y)` says whether the
+ * limb has art at a pixel; the box `[x0, y0, x1, y1]` (inclusive) bounds the
+ * search. Null when no pixel of the run lies within 1 px of the joint.
+ */
+export function limbWidth(line: JointLine, art: (x: number, y: number) => boolean, box: readonly [number, number, number, number]): number | null {
+  const [ax, ay] = line.axis;
+  const ts: number[] = [];
+  for (let y = box[1]; y <= box[3]; y++) {
+    for (let x = box[0]; x <= box[2]; x++) {
+      const dx = x + 0.5 - line.at[0];
+      const dy = y + 0.5 - line.at[1];
+      if (Math.abs(dx * ax + dy * ay) > 0.5 || !art(x, y)) continue;
+      ts.push(-dx * ay + dy * ax);
+    }
+  }
+  if (ts.length === 0) return null;
+  ts.sort((a, b) => a - b);
+  let near = 0;
+  ts.forEach((t, i) => {
+    if (Math.abs(t) < Math.abs(ts[near])) near = i;
+  });
+  if (Math.abs(ts[near]) > 1) return null;
+  let lo = near;
+  let hi = near;
+  while (lo > 0 && ts[lo] - ts[lo - 1] <= 1.5) lo--;
+  while (hi + 1 < ts.length && ts[hi + 1] - ts[hi] <= 1.5) hi++;
+  return ts[hi] - ts[lo] + 1;
+}
+
+/** The box `[x, y, w, h]` (rig px) of the pixels whose centre lies within `radius` of `at`: the cap image's size and place. */
+export function capBox(at: Pt, radius: number): [number, number, number, number] {
+  const x0 = Math.ceil(at[0] - radius - 0.5);
+  const y0 = Math.ceil(at[1] - radius - 0.5);
+  const x1 = Math.floor(at[0] + radius - 0.5);
+  const y1 = Math.floor(at[1] + radius - 0.5);
+  return [x0, y0, x1 - x0 + 1, y1 - y0 + 1];
+}
+
+/** Whether the pixel `(px, py)`'s centre lies within `radius` of `at`. */
+export function inDisc(at: Pt, radius: number, px: number, py: number): boolean {
+  return (px + 0.5 - at[0]) ** 2 + (py + 0.5 - at[1]) ** 2 <= radius * radius;
+}

package/src/parts.ts

@@ -42,7 +42,10 @@
  * cut from, which shares its `from`. The record is in draw order, and a piece
  * drawn `"back"` comes before its base, so order cannot say which of two parts
  * sharing a layer is the piece; this field does. A `parts.json` written before
- * 1.6.0 has none, and still reads.
+ * 1.6.0 has none, and still reads. `limb`, written only on a part a
+ * `config.limbs` segment made (issue #349), names the limb, the segment's
+ * index (0 the upper), the part it was cut from (`of`), the one bone it rides
+ * and, below a joint, the joint and its cap ({@link LimbRecord}).
  *
  * ⭐ **A patch is 100 % source.** Every pixel of a `painting:` part is the
  * painting's own, so it is all visible (the painting shows it; nothing of it
@@ -104,6 +107,49 @@ export interface PartRecord {
   seam_override_px: number;
   /** Absent when the part had no fringe pushed back (and in a `parts.json` the reference wrote). */
   fringe_pushed_back?: Array<{ part: string; px: number }>;
+  /** Written only on a part a `config.limbs` segment made (issue #349). */
+  limb?: LimbRecord;
+}
+
+/**
+ * A limb segment's provenance (issue #349): the limb, the segment's index
+ * (0 the upper), the part its pixels were cut from (`of`), the bone it rides
+ * with weight 1, and, on a segment below a joint, the joint's name and its cap.
+ */
+export interface LimbRecord {
+  name: string;
+  segment: number;
+  of: string;
+  bone: string;
+  joint?: string;
+  cap?: CapRecord;
+}
+
+/**
+ * The cap a lower segment carries past its joint (issue #349): the disc's
+ * centre (the joint, rig px), its radius (half the limb's width across the
+ * joint line, `width`), the box its image covers `[x, y, w, h]`, and its
+ * pixels on the upper side of the joint line counted by where each came from
+ * — the layer (`layer_px`), the config's cap image (`image_px`, only with one)
+ * — or none (`missing_px`: no pixel in the layer and none in an image).
+ */
+export interface CapRecord {
+  at: [number, number];
+  width: number;
+  radius: number;
+  box: [number, number, number, number];
+  layer_px: number;
+  image_px?: number;
+  missing_px: number;
+}
+
+const LIMB_KEYS = ['name', 'segment', 'of', 'bone', 'joint', 'cap'] as const;
+const CAP_KEYS = ['at', 'width', 'radius', 'box', 'layer_px', 'image_px', 'missing_px'] as const;
+
+/** The limb record with its keys in the fixed order, so two runs write the same bytes. */
+function orderedLimb(l: LimbRecord): Record<string, unknown> {
+  const cap = l.cap === undefined ? undefined : Object.fromEntries(CAP_KEYS.filter((k) => (l.cap as CapRecord)[k] !== undefined).map((k) => [k, (l.cap as CapRecord)[k]]));
+  return Object.fromEntries(LIMB_KEYS.filter((k) => (k === 'cap' ? cap : l[k]) !== undefined).map((k) => [k, k === 'cap' ? cap : l[k]]));
 }
 
 /** One listed hole: its area, its box in rig pixels, and the parts beside it (`src/assemble.ts` `uncoveredHoles`). */
@@ -178,15 +224,18 @@ export const PART_KEYS = [
   'merged_px',
   'seam_override_px',
   'fringe_pushed_back',
+  'limb',
 ] as const;
 /** The one part field that is not a count: a list of `{part, px}`, written only when it is not empty. */
 const FRINGE_KEY = 'fringe_pushed_back';
 /** The one part field that names another part: a cut's piece names its base, written only on a piece. */
 const CUT_FROM_KEY = 'cut_from';
-const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CUT_FROM_KEY) as ReadonlyArray<(typeof PART_KEYS)[number]>;
+/** The one part field that is a record of its own: a limb segment's provenance (issue #349), written only on one. */
+const LIMB_KEY = 'limb';
+const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY) as ReadonlyArray<(typeof PART_KEYS)[number]>;
 /** The port's own counts: all three or none (none = a record the reference wrote). */
 export const VISIBILITY_KEYS = ['visible_px', 'occluded_px', 'visible_not_projected_px'] as const;
-const REQUIRED_KEYS = PART_KEYS.filter((k) => !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY);
+const REQUIRED_KEYS = PART_KEYS.filter((k) => !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY);
 
 /** Where a part came from: a See-through run and a v3 tag or an author-made layer's `author:<label>` (issue #256), or the painting itself for a patch. */
 export type From = { run: 'full' | 'head'; tag: string } | { run: 'painting'; patch: string };
@@ -214,7 +263,7 @@ export function serializeParts(file: PartsFile): string {
     rig_size: file.rig_size,
     scale_rig_per_source: file.scale_rig_per_source,
     parts: file.parts.map((p) =>
-      Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : p[k]])),
+      Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : p[k]])),
     ),
     ghost_px: Object.fromEntries(Object.keys(file.ghost_px).sort().map((k) => [k, file.ghost_px[k]])),
     ...(file.recomposite === undefined
@@ -374,6 +423,42 @@ function checkParts(raw: unknown, path: string): PartsFile {
       else if (b.from !== r.from) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", whose from is ${show(b.from)}; this piece's is ${show(r.from)}, and a piece shares its base's layer`);
     }
   }
+  if (Array.isArray(o.parts)) {
+    // A limb segment (issue #349) names its limb, its index, the part it was cut from, its bone, and below a joint the joint and its cap.
+    for (const p of o.parts) {
+      if (typeof p !== 'object' || p === null || Array.isArray(p) || !(LIMB_KEY in p)) continue;
+      const r = p as Record<string, unknown>;
+      const object = `part "${String(r.name)}" field "${LIMB_KEY}"`;
+      const l = r[LIMB_KEY];
+      if (typeof l !== 'object' || l === null || Array.isArray(l)) {
+        fail('PARTS_FIELD_TYPE', object, `is ${show(l)}; an object {name, segment, of, bone, joint?, cap?} is required`);
+        continue;
+      }
+      const q = l as Record<string, unknown>;
+      for (const k of Object.keys(q)) if (!(LIMB_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${object} key "${k}"`, `is not a limb field; known: ${LIMB_KEYS.join(', ')}`);
+      for (const k of ['name', 'of', 'bone'] as const) if (!(typeof q[k] === 'string' && q[k] !== '')) fail('PARTS_FIELD_TYPE', `${object} "${k}"`, `is ${show(q[k])}; a non-empty string is required`);
+      if (!isCount(q.segment)) fail('PARTS_FIELD_TYPE', `${object} "segment"`, `is ${show(q.segment)}; the segment's index, a non-negative integer, is required`);
+      const below = isCount(q.segment) && q.segment > 0;
+      if (below !== ('joint' in q) || below !== ('cap' in q)) fail('PARTS_FIELD_PRESENT', object, `segment ${show(q.segment)} with${'joint' in q ? '' : 'out'} a joint and with${'cap' in q ? '' : 'out'} a cap; a segment below a joint (index above 0) has both, the upper segment neither`);
+      if ('joint' in q && !(typeof q.joint === 'string' && q.joint !== '')) fail('PARTS_FIELD_TYPE', `${object} "joint"`, `is ${show(q.joint)}; the joint's name is required`);
+      if ('cap' in q) {
+        const c = q.cap;
+        const co = typeof c === 'object' && c !== null && !Array.isArray(c) ? (c as Record<string, unknown>) : null;
+        const pt = (v: unknown, n: number): boolean => Array.isArray(v) && v.length === n && v.every((x) => typeof x === 'number' && Number.isFinite(x));
+        const ok =
+          co !== null &&
+          Object.keys(co).every((k) => (CAP_KEYS as readonly string[]).includes(k)) &&
+          pt(co.at, 2) &&
+          typeof co.width === 'number' &&
+          typeof co.radius === 'number' &&
+          pt(co.box, 4) &&
+          isCount(co.layer_px) &&
+          isCount(co.missing_px) &&
+          (!('image_px' in co) || isCount(co.image_px));
+        if (!ok) fail('PARTS_FIELD_TYPE', `${object} "cap"`, `is ${show(c)}; {at: [x, y], width, radius, box: [x, y, w, h], layer_px, image_px?, missing_px} is required`);
+      }
+    }
+  }
   if ('scene' in o) {
     const sc = o.scene;
     if (typeof sc !== 'object' || sc === null || Array.isArray(sc)) fail('PARTS_FIELD_TYPE', `${path} field "scene"`, `is ${show(sc)}; an object is required`);