@rig-c/parts 1.15.0 → 1.17.0

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`);