@rig-c/parts 1.5.5 → 1.7.0

package/src/propose.ts

@@ -43,7 +43,13 @@
  *   including every `painting:` patch (`assemble.patches`), which has no tag,
  *   so no rule above ever reads it: it is never a mesh or a chain, it moves
  *   no bone the rules place, and the note says the bone is the config's to
- *   name in `regions.<name>`.
+ *   name in `regions.<name>`. A cut's piece (`assemble.cuts`, recorded with
+ *   `cut_from`) goes the same way (issue #230): it shares its base's tag, and
+ *   the rules that run once per part of a tag would name the base's bones and
+ *   chains a second time. The one exception is the sleeve rule, which names
+ *   its chains by side and takes a cut sleeve as a blob of its own (#199). A
+ *   `parts.json` sharing a layer between parts with no `cut_from` (an
+ *   assemble before 1.6.0) is refused, `PROPOSE_CUT_FROM_RECORDED`.
  *
  * What it cannot know is written into `notes` when it guessed, and otherwise
  * left to the person correcting: things hidden inside a layer (a sash tail
@@ -73,6 +79,14 @@
  * never moved by a joint. `lint` then reads the torso and the sleeves by the
  * relations the joints declare instead of by screen y. Without joints every
  * value, note and LINT line is the one written before the option existed.
+ * One rule runs only with joints (issue #241): a `legwear` part holding the
+ * ankle of a leg whose hip, knee and ankle are given is meshed on a leg chain
+ * (hip -> knee, tip at the ankle; one per leg, or one through the midpoints
+ * when the part's art does not separate the legs — {@link legsFromJoints}),
+ * where without them it rides `hip` as a region. And with a joint at either
+ * end of the trunk (issue #243), the trunk parts' fixed segments run along
+ * neck -> hip, the line the chest is placed on, instead of down the screen
+ * ({@link trunkLineOf}).
  *
  * Issue #86 adds what the proposer and lint looked at, and changes nothing
  * they wrote: {@link proposeWithBasis} records, at each placement, what the
@@ -236,6 +250,54 @@ function konst(name: string, value: number): BasisConstant {
   return { name, value };
 }
 
+/**
+ * The `assemble` section {@link checkProposal} hands the loader, rebuilt from
+ * parts.json: every See-through part a plan entry or a cut, every patch a
+ * patches entry. Exported so a control can read which part went back as the
+ * plan part and which as the piece (issue #230).
+ */
+export function proposalAssemble(P: PartSet): Record<string, unknown> {
+  // A patch is not a plan entry; it goes back as the patches entry it came
+  // from, so the loader holds it to its own rule (a region, never a mesh).
+  // Its box, alpha and draw are the record's own box and placeholders the
+  // loader only type-checks: nothing here is written anywhere.
+  // A part that shares another's `from` is the piece of an `assemble.cuts`
+  // entry (issue #170) — the only way two parts share a layer — and goes back
+  // as a cut of its base, its polygon the record's box, a placeholder the
+  // loader only type-checks like the patches' fields. The piece names its base
+  // (`cut_from`, issue #230); file order cannot, as a piece drawn "back" comes
+  // before its base. A file with an unmarked shared layer (an assemble before
+  // 1.6.0, which propose refuses) goes back with the first part of the layer
+  // as the plan part, as it did before the field.
+  const run = P.recs.filter((r) => splitFrom(r.from)[0] !== PAINTING_RUN);
+  const painted = P.recs.filter((r) => splitFrom(r.from)[0] === PAINTING_RUN);
+  const firstOf = new Map<string, string>();
+  for (const r of run) if (r.cut_from === undefined && !firstOf.has(r.from)) firstOf.set(r.from, r.name);
+  const baseOf = (r: PartRecord): string => r.cut_from ?? (firstOf.get(r.from) as string);
+  const planned = run.filter((r) => r.cut_from === undefined && firstOf.get(r.from) === r.name);
+  const pieces = run.filter((r) => r.cut_from !== undefined || firstOf.get(r.from) !== r.name);
+  return {
+    rig_scale: 1,
+    plan: planned.map((r) => [r.name, ...splitFrom(r.from)]),
+    patches: painted.map((r) => ({ name: r.name, box: [r.x, r.y, r.x + r.w, r.y + r.h], alpha: 'box', draw: 'front' })),
+    ...(pieces.length === 0
+      ? {}
+      : {
+          cuts: pieces.map((r) => ({
+            from: baseOf(r),
+            into: r.name,
+            polygon: [
+              [r.x, r.y],
+              [r.x + r.w, r.y],
+              [r.x + r.w, r.y + r.h],
+            ],
+            draw: 'front',
+            overlap: 0,
+          })),
+        }),
+  };
+}
+
 /**
  * Hold the proposal to the config contract before it is written: it is copied
  * into a config field by field, so a proposal the loader would refuse is a
@@ -246,42 +308,9 @@ function konst(name: string, value: number): BasisConstant {
  * refusals.
  */
 export function checkProposal(P: PartSet, p: Proposal): void {
-  // A patch is not a plan entry; it goes back as the patches entry it came
-  // from, so the loader holds it to its own rule (a region, never a mesh).
-  // Its box, alpha and draw are the record's own box and placeholders the
-  // loader only type-checks: nothing here is written anywhere.
-  // A part whose `from` an earlier part already has is the piece of an
-  // `assemble.cuts` entry (issue #170) — the only way two parts share a layer
-  // — and goes back as a cut of that earlier part, its polygon the record's
-  // box, a placeholder the loader only type-checks like the patches' fields.
-  const run = P.recs.filter((r) => splitFrom(r.from)[0] !== PAINTING_RUN);
-  const painted = P.recs.filter((r) => splitFrom(r.from)[0] === PAINTING_RUN);
-  const firstOf = new Map<string, string>();
-  for (const r of run) if (!firstOf.has(r.from)) firstOf.set(r.from, r.name);
-  const planned = run.filter((r) => firstOf.get(r.from) === r.name);
-  const pieces = run.filter((r) => firstOf.get(r.from) !== r.name);
   parseConfig({
     key: 'proposal',
-    assemble: {
-      rig_scale: 1,
-      plan: planned.map((r) => [r.name, ...splitFrom(r.from)]),
-      patches: painted.map((r) => ({ name: r.name, box: [r.x, r.y, r.x + r.w, r.y + r.h], alpha: 'box', draw: 'front' })),
-      ...(pieces.length === 0
-        ? {}
-        : {
-            cuts: pieces.map((r) => ({
-              from: firstOf.get(r.from) as string,
-              into: r.name,
-              polygon: [
-                [r.x, r.y],
-                [r.x + r.w, r.y],
-                [r.x + r.w, r.y + r.h],
-              ],
-              draw: 'front',
-              overlap: 0,
-            })),
-          }),
-    },
+    assemble: proposalAssemble(P),
     bones: p.bones,
     meshes: p.meshes,
     regions: p.regions,
@@ -312,14 +341,33 @@ export class PartSet {
     this.images = images;
   }
 
-  /** Parts whose `from` tag is exactly `tag`, optionally from one run, in parts.json order. A `painting:` patch has no tag and is never one. */
-  byTag(tag: string, run?: 'full' | 'head'): PartRecord[] {
+  /**
+   * Parts whose `from` tag is exactly `tag`, optionally from one run, in
+   * parts.json order. A `painting:` patch has no tag and is never one, and a
+   * cut's piece (`cut_from`, issue #230) is not one either unless `pieces` is
+   * set: it shares its base's layer, and a rule that runs once per part of a
+   * tag would run for its base a second time — the same chains named twice.
+   */
+  byTag(tag: string, run?: 'full' | 'head', pieces = false): PartRecord[] {
     return this.recs.filter((p) => {
       const [r, t] = splitFrom(p.from);
-      return r !== PAINTING_RUN && t === tag && (run === undefined || r === run);
+      return r !== PAINTING_RUN && t === tag && (run === undefined || r === run) && (pieces || p.cut_from === undefined);
     });
   }
 
+  /**
+   * The layers more than one part holds with no `cut_from` to tell the piece
+   * from its base: a `parts.json` an `assemble` before 1.6.0 wrote with
+   * `assemble.cuts`. parts.json is in draw order and a piece drawn `"back"`
+   * comes before its base, so which part takes the layer's rule cannot be
+   * read off the file. Each entry is the layer and its parts, in file order.
+   */
+  unmarkedShares(): Array<{ from: string; parts: string[] }> {
+    const by = new Map<string, string[]>();
+    for (const p of this.layered()) if (p.cut_from === undefined) by.set(p.from, [...(by.get(p.from) ?? []), p.name]);
+    return [...by.entries()].filter(([, names]) => names.length > 1).map(([from, parts]) => ({ from, parts }));
+  }
+
   /** The See-through parts: every part but the `painting:` patches. */
   layered(): PartRecord[] {
     return this.recs.filter((p) => splitFrom(p.from)[0] !== PAINTING_RUN);
@@ -830,6 +878,16 @@ export function propose(P: PartSet, joints?: RigJoints, wristSnap: number | null
  * alone, and every value and note is the one written before it existed.
  */
 export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: number | null = null): { proposal: Proposal; basis: ProposalBasis } {
+  // Issue #230: a piece is not given its base's rule a second time, which
+  // needs to know which part is the piece. A file that cannot say is refused
+  // here, and only here: every other reader of parts.json still takes it.
+  refuseIfAny(
+    P.unmarkedShares().map(({ from, parts }) => ({
+      code: 'PROPOSE_CUT_FROM_RECORDED',
+      object: `parts ${parts.map((n) => `"${n}"`).join(', ')} (${from})`,
+      detail: `share one layer and none of them records cut_from, so which is the plan part and which the piece an assemble.cuts entry took cannot be read off parts.json (it is in draw order, and a piece drawn "back" comes before its base); re-run assemble (1.6.0+) to record cut_from`,
+    })),
+  );
   const bones: BoneEntry[] = [];
   const records: BoneBasis[] = [];
   // No prototype: a part may be named anything file-safe, "__proto__" included.
@@ -946,6 +1004,13 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
   // down the screen, because the torso need not be upright.
   const chestAlong = neckJ !== null || hipFromJoints;
   const chest: [number, number] = chestAlong ? [(neckAt[0] + hip[0]) / 2, (neckAt[1] + hip[1]) / 2] : [hip[0], neckY + 0.5 * (hip[1] - neckY)];
+  // Issue #243: on that same line, neck -> hip, the trunk parts' fixed segments are laid too (neck, topwear,
+  // bottomwear; {@link trunkSegments}), not down the screen through the bones' x. Without a joint at either end,
+  // today's verticals; with the two ends on one point the line has no direction, and a note says the verticals stay.
+  const trunk = chestAlong ? trunkLineOf(neckAt, hip) : null;
+  if (chestAlong && trunk === null) {
+    notes.push(`trunk segments: neck and hip are one point, ${fmtAt(hip)}, so neck -> hip declares no line; the trunk parts' segments are drafted down the screen, as without keypoints`);
+  }
   // Each placement hands its basis with its value: one record per bone, in the order the bones are written.
   const B = (name: string, parent: string, at: readonly [number, number], why: Placement, tip?: readonly [number, number], tipWhy?: Placement): void => {
     bones.push(tip === undefined ? { name, parent, at: rnd(at) } : { name, parent, at: rnd(at), tip: rnd(tip) });
@@ -1018,6 +1083,8 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
   const eyeless: string[] = [];
   const eyelessSides = new Set<'r' | 'l'>();
   for (const p of P.layered()) {
+    // A cut's piece takes no tag's role (issue #230): it falls to the trunk rule below, which says so.
+    if (p.cut_from !== undefined) continue;
     const t = splitFrom(p.from)[1];
     let role: string | undefined = TAG_REGION[t];
     if (browOf.has(p.name)) role = browOf.get(p.name);
@@ -1376,14 +1443,16 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       grid: g,
       r,
       segments: [
-        ['chest', rnd([axis, neckY + 18]), rnd([axis, chest[1]])],
+        trunk === null ? ['chest', rnd([axis, neckY + 18]), rnd([axis, chest[1]])] : ['chest', rnd(along(neckAt, trunk.u, 18)), rnd(chest)],
         ['head', rnd(head), rnd([axis, head[1] - 50])],
       ],
     };
   }
 
   // ---- sleeves
-  const hw = [...P.byTag('handwear-r'), ...P.byTag('handwear-l')].filter((p) => p.opaque_px > 500);
+  // A cut's piece counts here (issue #230): the sleeve rule names its chains by side, not once per part, so a piece
+  // never repeats one, and cutting one sleeve out of a both-arms part is how #199's note says to separate them.
+  const hw = [...P.byTag('handwear-r', undefined, true), ...P.byTag('handwear-l', undefined, true)].filter((p) => p.opaque_px > 500);
   const sides = new Map<'r' | 'l', PartRecord[]>();
   for (const p of hw) {
     const s = center(p)[0] < axis ? 'r' : 'l';
@@ -1520,10 +1589,17 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
     const mask = P.alpha(p);
     const top = chest[1] - 0.3 * fh;
     const bot = p.y + p.h;
-    const segs: Segment[] = [
-      ['chest', rnd([chest[0], p.y]), rnd([chest[0], hip[1] - 20])],
-      ['hip', rnd([chest[0], hip[1] - 20]), rnd([chest[0], hip[1] + 100])],
-    ];
+    const segs: Segment[] =
+      trunk === null
+        ? [
+            ['chest', rnd([chest[0], p.y]), rnd([chest[0], hip[1] - 20])],
+            ['hip', rnd([chest[0], hip[1] - 20]), rnd([chest[0], hip[1] + 100])],
+          ]
+        : [
+            // The part's top read along the trunk: the nearest its art comes to the neck end of the line.
+            ['chest', rnd(along(hip, trunk.u, artExtent(mask, p, hip, trunk.u)[0])), rnd(along(hip, trunk.u, -20))],
+            ['hip', rnd(along(hip, trunk.u, -20)), rnd(along(hip, trunk.u, 100))],
+          ];
     if (bw.length > 0 && bot < hip[1] + 0.25 * fh) {
       // A bodice that stops at the waist: robe chains down to the hem would fall off the art.
       meshes[p.name] = { grid: g, r, segments: segs };
@@ -1577,10 +1653,19 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
     const mask = P.alpha(p);
     const bot = p.y + p.h;
     const y0 = hip[1] + 20;
-    const segs: Segment[] = [
+    let segs: Segment[] = [
       ['chest', rnd([chest[0], chest[1] - 30]), rnd([chest[0], hip[1] - 20])],
       ['hip', rnd([p.x + 0.09 * p.w, hip[1] + 5]), rnd([p.x + 0.91 * p.w, hip[1] + 5])],
     ];
+    if (trunk !== null) {
+      // The waist line runs across the trunk, 5 px down it from the hip, over 0.09 to 0.91 of the art's width across it.
+      const [s0, s1] = artExtent(mask, p, hip, trunk.v);
+      const waist = along(hip, trunk.u, 5);
+      segs = [
+        ['chest', rnd(along(chest, trunk.u, -30)), rnd(along(hip, trunk.u, -20))],
+        ['hip', rnd(along(waist, trunk.v, s0 + 0.09 * (s1 - s0))), rnd(along(waist, trunk.v, s0 + 0.91 * (s1 - s0)))],
+      ];
+    }
     for (const [tag, f, ph] of [
       ['skirt_r', 0.3, 0.3],
       ['skirt_c', 0.5, 0.34],
@@ -1604,6 +1689,41 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
     meshes[p.name] = { grid: g, r, segments: segs };
   }
 
+  // ---- legs (issue #241)
+  // Only with joints: a legwear part whose art holds the ankle of a leg whose hip, knee and ankle are all given is
+  // meshed on a leg chain hip -> knee, tip at the ankle; without them no line below runs, and the part stays the
+  // region the trunk rule gives it, its note unchanged. No idle track is written for a leg chain: the chain is
+  // drafted whatever the pose, and a standing figure's legs are planted — whether they move is the scene's.
+  const lw = P.byTag('legwear', undefined, true).filter((p) => p.opaque_px > 500);
+  const legPlan = joints !== undefined && lw.length > 0 ? legsFromJoints(P, lw, joints) : null;
+  if (legPlan !== null && legPlan.chains !== null) {
+    for (const c of legPlan.chains) {
+      const J = (joints as RigJoints).joints;
+      const used = (n: KeypointName): Placement => placement('joint', `the ${n} joint, ${usedAs(J[n])}`, { joints: [jointRef(n)] });
+      const mid = (what: string, a: KeypointName, b: KeypointName): Placement => placement('joint', `the midpoint of the ${a} and ${b} joints (${what}) — a point between two joints, not a joint`, { joints: [jointRef(a), jointRef(b)] });
+      const why =
+        c.side === null
+          ? [mid('the hips', 'r_hip', 'l_hip'), mid('the knees', 'r_knee', 'l_knee')]
+          : [used(`${c.side}_hip`), used(`${c.side}_knee`)];
+      const tipWhy = c.side === null ? mid('the ankles', 'r_ankle', 'l_ankle') : used(`${c.side}_ankle`);
+      C(c.chain, 'hip', [c.hip, c.knee], c.ankle, why, tipWhy);
+    }
+    for (const p of lw) {
+      const [g, r] = gridR(p);
+      const segs: Segment[] = [];
+      for (const c of legPlan.chains.filter((q) => q.part === p)) {
+        // The sleeve's chest stub, laid along the thigh from the hip: 14 px above the hip to 2 px below it.
+        const len = Math.hypot(c.knee[0] - c.hip[0], c.knee[1] - c.hip[1]);
+        const d: [number, number] = [(c.knee[0] - c.hip[0]) / len, (c.knee[1] - c.hip[1]) / len];
+        segs.push(['hip', rnd([c.hip[0] - 14 * d[0], c.hip[1] - 14 * d[1]]), rnd([c.hip[0] + 2 * d[0], c.hip[1] + 2 * d[1]])], c.chain);
+      }
+      meshes[p.name] = { grid: g, r, segments: segs };
+    }
+    notes.push(...legPlan.notes);
+  } else if (legPlan !== null && legPlan.why !== null) {
+    notes.push(`${lw.map((p) => p.name).join(', ')}: no leg chain — ${legPlan.why}; the trunk rule places ${lw.length === 1 ? 'it' : 'them'}`);
+  }
+
   // Anything no rule claimed rides its nearest trunk bone rigidly, so the rig stage never meets an unassigned part.
   for (const p of P.recs) {
     if (!(p.name in meshes) && !(p.name in regions)) {
@@ -1611,9 +1731,21 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       regions[p.name] = cy < neckY ? 'head' : cy < hip[1] ? 'chest' : 'hip';
       if (splitFrom(p.from)[0] === PAINTING_RUN) {
         notes.push(`${p.name} (${p.from}): a painting patch has no tag, so no rule -> region on ${regions[p.name]}, the nearest trunk bone; config.regions.${p.name} is the bone it rides`);
+      } else if (p.cut_from !== undefined) {
+        notes.push(
+          `${p.name} (${p.from}): a piece an assemble.cuts entry took from ${p.cut_from}, so not given that layer's rule a second time (it would name ${p.cut_from}'s bones and chains again) -> region on ${regions[p.name]}, the nearest trunk bone; config.regions.${p.name} is the bone it rides, and a mesh in config.meshes is the author's to give it`,
+        );
       } else notes.push(`${p.name} (${p.from}): no rule -> region on ${regions[p.name]}`);
     }
   }
+  if (trunk !== null) {
+    const laid = [...P.headFirst('neck'), ...tw, ...bw].map((p) => p.name);
+    if (laid.length > 0) {
+      notes.push(
+        `trunk segments (${laid.join(', ')}): laid along neck -> hip, the line the chest was placed on (${pyFixed((Math.atan2(trunk.u[0], trunk.u[1]) * 180) / Math.PI, 1)} degrees off the screen's downward vertical, positive towards +x): each [bone, from, to] segment the rule drafts down the screen runs along that line instead, and the waist segment across it`,
+      );
+    }
+  }
   if (joints !== undefined) {
     notes.push(
       ...jointNotes(joints, {
@@ -1622,6 +1754,7 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
         chest: chestAlong ? { neck: neckAt, hip } : null,
         sleeveRule,
         armWhy: armPlan === null ? null : armPlan.why,
+        legs: legPlan === null ? null : legPlan.chains,
         arms: armPlan === null ? null : armPlan.arms,
         wristSnap,
         eyes: (['r', 'l'] as const).map((s) => {
@@ -1638,6 +1771,55 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
 // external keypoints (issue #75)
 // ---------------------------------------------------------------------------
 
+/**
+ * The trunk's line (issue #243), from the neck bone's origin to the hip's, when a joint placed either end: `u` is
+ * its unit direction, down the trunk, and `v` the unit across it, `u` turned a quarter (`[u_y, -u_x]`). An upright
+ * trunk's `u` is `[0, 1]` and its `v` `[1, 0]`, the screen's y and x, which is what the vertical drafts read: each
+ * trunk segment is that draft with "down the screen" read as "along `u`" and "across the screen" as "along `v`".
+ * `null` when the two ends are one point: a line through one point has no direction.
+ */
+interface TrunkLine {
+  u: [number, number];
+  v: [number, number];
+}
+
+function trunkLineOf(neck: readonly [number, number], hip: readonly [number, number]): TrunkLine | null {
+  const dx = hip[0] - neck[0];
+  const dy = hip[1] - neck[1];
+  const len = Math.hypot(dx, dy);
+  if (len === 0) return null;
+  const u: [number, number] = [dx / len, dy / len];
+  return { u, v: [u[1], -u[0]] };
+}
+
+/** The point `k` px from `p` along the unit direction `d`. */
+function along(p: readonly [number, number], d: readonly [number, number], k: number): [number, number] {
+  return [p[0] + k * d[0], p[1] + k * d[1]];
+}
+
+/**
+ * The extent of a part's art along the unit direction `d`, measured from `o`: the least and the greatest
+ * projection onto `d` of its opaque pixels, each taken as the unit square it covers. An axis-aligned box tight on
+ * its art therefore projects onto `[1, 0]` as its own left and right edges and onto `[0, 1]` as its top and bottom,
+ * the values the vertical drafts read off the box. A part with no opaque pixel is read as its box.
+ */
+function artExtent(mask: Mask, p: PartRecord, o: readonly [number, number], d: readonly [number, number]): [number, number] {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let y = Math.max(0, p.y); y < Math.min(mask.height, p.y + p.h); y++) {
+    for (let x = Math.max(0, p.x); x < Math.min(mask.width, p.x + p.w); x++) {
+      if (mask.data[y * mask.width + x] !== 1) continue;
+      const t = (x - o[0]) * d[0] + (y - o[1]) * d[1];
+      if (t < lo) lo = t;
+      if (t > hi) hi = t;
+    }
+  }
+  const w = lo === Infinity ? p.w : 1;
+  const h = lo === Infinity ? p.h : 1;
+  if (lo === Infinity) lo = hi = (p.x - o[0]) * d[0] + (p.y - o[1]) * d[1];
+  return [lo + Math.min(0, d[0]) * w + Math.min(0, d[1]) * h, hi + Math.max(0, d[0]) * w + Math.max(0, d[1]) * h];
+}
+
 /**
  * How far a wrist joint may lie from a handwear part's art and still be on
  * it: the LINT's own tolerance, the part's mask dilated this many px each way
@@ -1750,6 +1932,128 @@ function armsFromJoints(P: PartSet, hw: readonly PartRecord[], joints: RigJoints
   return { arms, why: null };
 }
 
+/**
+ * One leg chain drafted from joints (issue #241): its name, the side whose
+ * joints it runs through (`null` for the one chain that carries both legs,
+ * through the midpoints of the two hips, the two knees and the two ankles),
+ * its two links and tip in rig px, and the legwear part it meshes.
+ */
+interface LegChain {
+  chain: string;
+  side: 'r' | 'l' | null;
+  hip: [number, number];
+  knee: [number, number];
+  ankle: [number, number];
+  part: PartRecord;
+}
+
+/**
+ * Whether `m`'s art breaks along the straight line from `a` to `b`: walked
+ * one pixel step at a time (the larger of the x and y gaps, in steps of at
+ * most one pixel, each point read as {@link isOn} reads it), some point with
+ * no art lies between two points with art. Art that only starts or stops
+ * along the line — an end point off the art — is no break.
+ */
+function artBreaks(m: Mask, a: readonly [number, number], b: readonly [number, number]): boolean {
+  const n = Math.ceil(Math.max(Math.abs(b[0] - a[0]), Math.abs(b[1] - a[1])));
+  let seenArt = false;
+  let gapAfterArt = false;
+  for (let i = 0; i <= n; i++) {
+    const t = n === 0 ? 0 : i / n;
+    const on = isOn(m, a[0] + t * (b[0] - a[0]), a[1] + t * (b[1] - a[1]));
+    if (on && gapAfterArt) return true;
+    if (on) seenArt = true;
+    else if (seenArt) gapAfterArt = true;
+  }
+  return false;
+}
+
+/**
+ * The leg chains a keypoint file drafts for the legwear parts, or why none
+ * is drafted (issue #241) — the sleeve's {@link armsFromJoints} for the legs.
+ * A leg is complete when its hip, knee and ankle all have a position and the
+ * hip and knee are two points; a legwear part carries a leg when the ankle
+ * lies on its art within the LINT's own tolerance ({@link WRIST_ON_PART_PX}).
+ * The joints are used only when every complete leg's ankle is on exactly one
+ * part and every legwear part carries one, as for the sleeves; when a leg is
+ * complete and they are not, `why` says so. With no complete leg nothing is
+ * drafted and `why` is `null`: the proposal is the one written before the
+ * rule existed.
+ *
+ * One chain or two is read off the part and the joints. A part carrying one
+ * leg gets that leg's chain, `leg_<side>`. A part carrying both gets one
+ * chain per leg only when its art breaks ({@link artBreaks}) along the line
+ * from r_knee to l_knee and along the line from r_ankle to l_ankle — the
+ * legs painted apart at both; otherwise the legs touch, cross or overlap in
+ * its art, two chains would pull one stretch of it two ways, and it gets one
+ * chain, `leg`, through the midpoints of the hips, the knees and the ankles.
+ * Each part gets one note saying which and why.
+ */
+function legsFromJoints(P: PartSet, lw: readonly PartRecord[], joints: RigJoints): { chains: LegChain[] | null; notes: string[]; why: string | null } {
+  const complete: Array<{ side: 'r' | 'l'; hip: [number, number]; knee: [number, number]; ankle: [number, number] }> = [];
+  const gaps: string[] = [];
+  for (const s of ['r', 'l'] as const) {
+    const hp = joints.joints[`${s}_hip`].at;
+    const kn = joints.joints[`${s}_knee`].at;
+    const an = joints.joints[`${s}_ankle`].at;
+    if (hp === null || kn === null || an === null) {
+      const absent = [hp === null ? `${s}_hip` : null, kn === null ? `${s}_knee` : null, an === null ? `${s}_ankle` : null].filter((n): n is string => n !== null);
+      gaps.push(`${absent.join(', ')} ${absent.length === 1 ? 'has' : 'have'} no position`);
+    } else if (hp[0] === kn[0] && hp[1] === kn[1]) gaps.push(`${s}_hip and ${s}_knee are one point, so the thigh has no direction`);
+    else complete.push({ side: s, hip: hp, knee: kn, ankle: an });
+  }
+  // No complete leg is the file before this rule existed: nothing is said, and the part stays the trunk rule's.
+  if (complete.length === 0) return { chains: null, notes: [], why: null };
+  const near = new Map(lw.map((p) => [p, dilate(P.alpha(p), 2 * WRIST_ON_PART_PX + 1)]));
+  const bound: Array<(typeof complete)[number] & { part: PartRecord }> = [];
+  for (const g of complete) {
+    const on = lw.filter((p) => isOn(near.get(p) as Mask, g.ankle[0], g.ankle[1]));
+    if (on.length !== 1) {
+      const where = on.length === 0 ? `the art of no legwear part within ${WRIST_ON_PART_PX} px` : `the art of ${on.length} legwear parts (${on.map((p) => p.name).join(', ')})`;
+      return { chains: null, notes: [], why: `${g.side}_ankle at ${fmtAt(g.ankle)} lies on ${where}, so it does not say which part its leg is` };
+    }
+    bound.push({ ...g, part: on[0] });
+  }
+  const idle = lw.filter((p) => !bound.some((g) => g.part === p));
+  if (idle.length > 0) {
+    const why = gaps.length > 0 ? ` (${gaps.join('; ')})` : '';
+    return { chains: null, notes: [], why: `${idle.map((p) => p.name).join(', ')} ${idle.length === 1 ? 'carries' : 'carry'} the ankle of no leg whose three joints are given${why}` };
+  }
+  const chains: LegChain[] = [];
+  const notes: string[] = [];
+  const still = 'no idle track is written for it: the chain is drafted whatever the pose, and whether the legs move is the scene\'s to key or drive';
+  for (const p of lw) {
+    const on = bound.filter((g) => g.part === p);
+    if (on.length === 1) {
+      const g = on[0];
+      chains.push({ chain: `leg_${g.side}`, side: g.side, hip: g.hip, knee: g.knee, ankle: g.ankle, part: p });
+      const other = g.side === 'r' ? 'l' : 'r';
+      const lack = complete.some((q) => q.side === other) ? `${other}_ankle lies on another part` : gaps.join('; ');
+      notes.push(`${p.name} (${p.from}): one leg chain, leg_${g.side}, hip -> knee -> ankle from the ${g.side} joints — ${g.side}_ankle lies on its art and no ${other} leg is bound to it (${lack}); ${still}`);
+      continue;
+    }
+    const [r, l] = on;
+    const m = P.alpha(p);
+    const kneesBreak = artBreaks(m, r.knee, l.knee);
+    const anklesBreak = artBreaks(m, r.ankle, l.ankle);
+    if (kneesBreak && anklesBreak) {
+      for (const g of on) chains.push({ chain: `leg_${g.side}`, side: g.side, hip: g.hip, knee: g.knee, ankle: g.ankle, part: p });
+      notes.push(
+        `${p.name} (${p.from}): one chain per leg, leg_r and leg_l, sharing its mesh — both ankles lie on its art, and its art breaks along the line from r_knee to l_knee and along the line from r_ankle to l_ankle, so the legs are painted apart; each runs hip -> knee -> ankle from its side's joints, and ${still}`,
+      );
+      continue;
+    }
+    const mid = (a: [number, number], b: [number, number]): [number, number] => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+    chains.push({ chain: 'leg', side: null, hip: mid(r.hip, l.hip), knee: mid(r.knee, l.knee), ankle: mid(r.ankle, l.ankle), part: p });
+    const unbroken = [kneesBreak ? null : 'from r_knee to l_knee', anklesBreak ? null : 'from r_ankle to l_ankle'].filter((s): s is string => s !== null);
+    notes.push(
+      `${p.name} (${p.from}): one leg chain, leg, for both legs — both ankles lie on its art, and its art runs unbroken along the line ${unbroken.join(' and along the line ')}, so the legs touch, cross or overlap in it and a chain per leg would pull one stretch of art two ways; ` +
+        `the chain runs hip -> knee -> ankle through the midpoints of the two hips, the two knees and the two ankles, and ${still}`,
+    );
+  }
+  return { chains, notes, why: null };
+}
+
 /** A rig-px point as the notes and LINT lines print it: one decimal place. */
 function fmtAt(p: readonly [number, number]): string {
   return `[${pyFixed(p[0], 1)}, ${pyFixed(p[1], 1)}]`;
@@ -1775,6 +2079,8 @@ interface JointNoteFacts {
   sleeveRule: string;
   armWhy: string | null;
   arms: JointArm[] | null;
+  /** The leg chains drafted (issue #241), or `null` when none was: then no line here names a leg joint. */
+  legs: LegChain[] | null;
   /** `propose --wrist-snap`, or `null` without it. */
   wristSnap: number | null;
   eyes: ReadonlyArray<{ bone: string; part: string; at: [number, number] } | null>;
@@ -1844,6 +2150,29 @@ function jointNotes(joints: RigJoints, f: JointNoteFacts): string[] {
         `to separate them, cut one sleeve out of ${both} with an assemble.cuts entry (a polygon round it) and propose again`,
     );
   }
+  // Issue #241: the knees and ankles a leg chain was drafted from, and the hips as its first link.
+  for (const c of f.legs ?? []) {
+    const on = `the ankle${c.side === null ? 's lie' : ' lies'} on ${c.part.name}`;
+    if (c.side === null) {
+      out.push(`chain leg: link 0 is the midpoint of r_hip and l_hip, ${fmtAt(c.hip)} — the point bone hip stands on`);
+      for (const [joint, role, pair] of [
+        ['r_knee', 'link 1', 'r_knee and l_knee'],
+        ['l_knee', 'link 1', 'r_knee and l_knee'],
+        ['r_ankle', 'the tip', 'r_ankle and l_ankle'],
+        ['l_ankle', 'the tip', 'r_ankle and l_ankle'],
+      ] as const) {
+        tell(joint, `${said(joint, J[joint])}: ${usedAs(J[joint])} for chain leg, ${role}, the midpoint of ${pair} — a point between two joints, not a joint (${on})`);
+      }
+      continue;
+    }
+    out.push(`chain leg_${c.side}: link 0 is the ${c.side}_hip joint, ${fmtAt(c.hip)}`);
+    for (const [joint, role] of [
+      [`${c.side}_knee`, 'link 1'],
+      [`${c.side}_ankle`, 'the tip'],
+    ] as const) {
+      tell(joint, `${said(joint, J[joint])}: ${usedAs(J[joint])} for chain leg_${c.side}, ${role} (${on})`);
+    }
+  }
   (['r', 'l'] as const).forEach((s, i) => {
     const n = `${s}_eye` as const;
     const j = J[n];

package/src/requirements.ts

@@ -147,6 +147,28 @@ export interface RequirementsFile {
   fps: number;
   targets: SceneTarget[];
   requirements: Requirement[];
+  /**
+   * Issue #231: the parts the scene's figure does not stand on, by name — each
+   * a part `check` would otherwise read as a planted foot (a `footwear` part),
+   * which the feet halves of `BREATH_VISIBLE` and `STILL_REGIONS_DARK` then
+   * name as declared and do not hold still. Empty when the file does not
+   * declare it: every footwear part is a planted foot, as before.
+   */
+  not_planted: string[];
+  /**
+   * Issue #231: the swinging parts (`handwear`, `bottomwear`) the scene does
+   * not mean to swing — a piece cut off and left still — by name.
+   * `TIP_OVER_ROOT` names each in its line and does not hold it to the bar.
+   * Empty when not declared.
+   */
+  not_swinging: string[];
+  /**
+   * Issue #231: the swinging parts whose tip is up — a raised forearm, its
+   * chain rising from the elbow — by name. `TIP_OVER_ROOT` reads their upper
+   * half as the tip's, after checking that the chain carrying each does rise,
+   * and names each in its line. Empty when not declared: every part hangs.
+   */
+  rises: string[];
 }
 
 /** What `check --requirements` and `build --requirements` name, said once for the help and the refusals. */
@@ -182,10 +204,24 @@ const KIND_FIELDS: Record<RequirementKind, readonly string[]> = {
 
 const NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
 
+/** The three lists of parts a scene excepts from a bar that assumes a standing figure (issue #231), in the order they are read. */
+export const EXCEPTION_LISTS = ['not_planted', 'not_swinging', 'rises'] as const;
+type ExceptionList = (typeof EXCEPTION_LISTS)[number];
+
+/** What each list's absence declares. */
+const EXCEPTION_ABSENT: Record<ExceptionList, string> = {
+  not_planted: 'every footwear part a planted foot',
+  not_swinging: 'every handwear and bottomwear part one that swings',
+  rises: 'every swinging part one that hangs',
+};
+
 /**
  * Read and shape-check a requirements file. Every problem is collected before
  * one refusal: the file, `spec`, `fps` (required, a positive number: no
- * default), `targets` (optional) and `requirements` (required, possibly empty),
+ * default), `targets` (optional), `requirements` (required, possibly empty)
+ * and `not_planted`, `not_swinging` and `rises` (each optional, issue #231: a
+ * non-empty list of distinct part names, no part in both of the last two;
+ * which parts they are is read against parts.json and the rig by `check`),
  * each entry's every field and bar by name, a key the format does not read,
  * and a name used twice. Resolving the names against the rig is
  * {@link resolveRequirements}'s.
@@ -209,7 +245,7 @@ export function readRequirements(path: string): RequirementsFile {
     problems.push({ code: 'REQUIREMENTS_FIELD', object, detail });
   };
   if (raw.spec !== REQUIREMENTS_SPEC) field(`${at} field "spec"`, `is ${JSON.stringify(raw.spec)}; ${JSON.stringify(REQUIREMENTS_SPEC)} is required`);
-  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements; note or *_note as a string; x-<name> as a record)');
+  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises; note or *_note as a string; x-<name> as a record)');
   let fps = NaN;
   if (!(finite(raw.fps) && raw.fps > 0)) field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
   else fps = raw.fps;
@@ -336,8 +372,27 @@ export function readRequirements(path: string): RequirementsFile {
       });
     }
   }
+  const lists = {} as Record<ExceptionList, string[]>;
+  for (const key of EXCEPTION_LISTS) {
+    const names: string[] = [];
+    lists[key] = names;
+    const v = raw[key];
+    if (v === undefined) continue;
+    if (!Array.isArray(v) || v.length === 0) {
+      field(`${at} field "${key}"`, `is ${JSON.stringify(v)?.slice(0, 60)}; a non-empty list of part names is required when the field is given — leave it out to declare ${EXCEPTION_ABSENT[key]}`);
+      continue;
+    }
+    v.forEach((n, i) => {
+      if (typeof n !== 'string' || n.length === 0) field(`${at} field "${key}"[${i}]`, `is ${JSON.stringify(n)?.slice(0, 40)}; a part name is required`);
+      else if (names.includes(n)) field(`${at} field "${key}"[${i}]`, `names "${n}" a second time; each part is declared once`);
+      else names.push(n);
+    });
+  }
+  lists.rises.forEach((n, i) => {
+    if (lists.not_swinging.includes(n)) field(`${at} field "rises"[${i}]`, `names "${n}", which "not_swinging" names too; a part that does not swing has no tip to read up or down`);
+  });
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises };
 }
 
 // ---------------------------------------------------------------------------