@rig-c/parts 1.5.5 → 1.7.0

package/src/instruments.ts

@@ -186,6 +186,23 @@ export interface HalfTravels {
   tip: number | null;
 }
 
+/** Where a chain's tip lies from its root on the screen (issue #231). */
+export type Toward = 'down' | 'up' | 'left' | 'right';
+
+/**
+ * Where a chain's tip is from its root (issue #231): the vector from its first
+ * link's origin to its last link's at the setup pose, in the world (y up),
+ * read along whichever axis it runs further on — `down`/`up` when |dy| > |dx|,
+ * `left`/`right` when |dx| > |dy|. Null when it runs as far on both, which
+ * includes a chain whose links share one origin. `check` holds a part the
+ * scene declares `rises` to it: the chain carrying it must read `up`.
+ */
+export function chainToward(dx: number, dy: number): Toward | null {
+  if (Math.abs(dy) > Math.abs(dx)) return dy < 0 ? 'down' : 'up';
+  if (Math.abs(dx) > Math.abs(dy)) return dx > 0 ? 'right' : 'left';
+  return null;
+}
+
 /** A polygon as x, y pairs. */
 type Polygon = number[];
 
@@ -348,17 +365,24 @@ function artPieces(art: ArtMask, a: PosedTriangles, stage: StageBox): ArtPieces
  * Art outside every rest triangle is not drawn by the runtime and is not
  * counted. A frame on which the slot shows nothing (null) is skipped; a half
  * with no art on frame 0 is null. Each distinct rest attachment is cut once.
+ *
+ * `toward` is where the tip is from the root (issue #231): `down` — the upper
+ * half is the root's and the lower the tip's, the reading before #231 and the
+ * default — or `up`, the two swapped, for a part the scene declares `rises`.
  */
-export function halfTravels(art: ArtMask, box: { x: number; y: number; w: number; h: number }, stage: StageBox, frames: ReadonlyArray<PosedTriangles | null>): HalfTravels {
+export function halfTravels(art: ArtMask, box: { x: number; y: number; w: number; h: number }, stage: StageBox, frames: ReadonlyArray<PosedTriangles | null>, toward: 'down' | 'up' = 'down'): HalfTravels {
   const H = stage.height;
   const bx0 = stage.x + box.x;
   const bx1 = stage.x + box.x + box.w;
   const top = stage.y + cropToSpineY(box.y, H);
   const mid = stage.y + cropToSpineY(box.y + box.h / 2, H);
   const bottom = stage.y + cropToSpineY(box.y + box.h, H);
-  const bands = { root: [mid, top], tip: [bottom, mid] } as const;
+  // Each band is a rectangle of the world, [x0, y0, x1, y1] (y up).
+  const upper = [bx0, mid, bx1, top] as const;
+  const lower = [bx0, bottom, bx1, mid] as const;
+  const bands = toward === 'down' ? { root: upper, tip: lower } : { root: lower, tip: upper };
   const cut = new Map<readonly number[], ArtPieces>();
-  const centroidIn = (a: PosedTriangles, y0: number, y1: number): [number, number] | null => {
+  const centroidIn = (a: PosedTriangles, x0: number, y0: number, x1: number, y1: number): [number, number] | null => {
     let pc = cut.get(a.rest);
     if (pc === undefined) {
       pc = artPieces(art, a, stage);
@@ -384,13 +408,13 @@ export function halfTravels(art: ArtMask, box: { x: number; y: number; w: number
       const xmax = Math.max(px, px + e1x, px + e2x);
       const ymin = Math.min(py, py + e1y, py + e2y);
       const ymax = Math.max(py, py + e1y, py + e2y);
-      if (xmax <= bx0 || xmin >= bx1 || ymax <= y0 || ymin >= y1) continue;
+      if (xmax <= x0 || xmin >= x1 || ymax <= y0 || ymin >= y1) continue;
       const R = a.rest;
       const restDet = (R[2 * j] - R[2 * i]) * (R[2 * k + 1] - R[2 * i + 1]) - (R[2 * k] - R[2 * i]) * (R[2 * j + 1] - R[2 * i + 1]);
       const posedDet = e1x * e2y - e2x * e1y;
       // The posed area of a rest area: |posed det / rest det| times it.
       const scale = Math.abs(posedDet / restDet);
-      if (xmin >= bx0 && xmax <= bx1 && ymin >= y0 && ymax <= y1) {
+      if (xmin >= x0 && xmax <= x1 && ymin >= y0 && ymax <= y1) {
         const w = pc.area[t] * scale;
         const l1 = pc.centroid[2 * t];
         const l2 = pc.centroid[2 * t + 1];
@@ -402,7 +426,7 @@ export function halfTravels(art: ArtMask, box: { x: number; y: number; w: number
       for (const bary of pc.pieces[t]) {
         const poly: Polygon = [];
         for (let q = 0; q < bary.length; q += 2) poly.push(px + bary[q] * e1x + bary[q + 1] * e2x, py + bary[q] * e1y + bary[q + 1] * e2y);
-        const c = clipRect(poly, bx0, y0, bx1, y1);
+        const c = clipRect(poly, x0, y0, x1, y1);
         if (c.length < 6) continue;
         const [pa, pmx, pmy] = polygonMoments(c);
         // A triangle the pose turns over winds its pieces the other way; what is drawn is the area either way.
@@ -414,19 +438,19 @@ export function halfTravels(art: ArtMask, box: { x: number; y: number; w: number
     }
     return A > 0 ? [MX / A, MY / A] : null;
   };
-  const travel = (y0: number, y1: number): number | null => {
+  const travel = (band: readonly [number, number, number, number]): number | null => {
     const first = frames[0];
-    const c0 = first === null ? null : centroidIn(first, y0, y1);
+    const c0 = first === null ? null : centroidIn(first, ...band);
     if (c0 === null) return null;
     let max = 0;
     for (const f of frames) {
-      const c = f === null ? null : centroidIn(f, y0, y1);
+      const c = f === null ? null : centroidIn(f, ...band);
       if (c === null) continue;
       max = Math.max(max, Math.hypot(c[0] - c0[0], c[1] - c0[1]));
     }
     return max;
   };
-  return { root: travel(bands.root[0], bands.root[1]), tip: travel(bands.tip[0], bands.tip[1]) };
+  return { root: travel(bands.root), tip: travel(bands.tip) };
 }
 
 // ---------------------------------------------------------------------------

package/src/parts.ts

@@ -35,6 +35,13 @@
  *   issue #119). They are not in `opaque_px`: the counts above are taken
  *   after it.
  *
+ * One field names a part rather than counting pixels: `cut_from`, written only
+ * on a piece an `assemble.cuts` entry made (issue #230) — the plan part it was
+ * 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.
+ *
  * ⭐ **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
  * is synthesis), all candidates and all taken: `visible_px =
@@ -71,6 +78,12 @@ import { readTag } from './tags.ts';
 export interface PartRecord {
   name: string;
   from: string;
+  /**
+   * Written only on a piece an `assemble.cuts` entry made (issue #230): the
+   * name of the plan part it was cut from, which has the same `from`. Absent
+   * on every other part, and in a `parts.json` written before 1.6.0.
+   */
+  cut_from?: string;
   x: number;
   y: number;
   w: number;
@@ -132,6 +145,7 @@ const BORDER_KEYS = ['part', 'px'] as const;
 export const PART_KEYS = [
   'name',
   'from',
+  'cut_from',
   'x',
   'y',
   'w',
@@ -149,10 +163,12 @@ export const PART_KEYS = [
 ] 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';
-const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY) as ReadonlyArray<(typeof PART_KEYS)[number]>;
+/** 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 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);
+const REQUIRED_KEYS = PART_KEYS.filter((k) => !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY);
 
 /** Where a part came from: a See-through run and a v3 tag, or the painting itself for a patch. */
 export type From = { run: 'full' | 'head'; tag: string } | { run: 'painting'; patch: string };
@@ -318,6 +334,27 @@ function checkParts(raw: unknown, path: string): PartsFile {
       }
     });
   }
+  if (Array.isArray(o.parts)) {
+    // A cut's piece (issue #230) names its base: a part of this file, with the
+    // same "<run>:<tag>", that is not itself a piece (a cut of a cut has no
+    // single plan part behind it; the config loader refuses one).
+    const recs = o.parts.filter((p): p is Record<string, unknown> => typeof p === 'object' && p !== null && !Array.isArray(p));
+    const byName = new Map<unknown, Record<string, unknown>>(recs.map((r) => [r.name, r]));
+    for (const r of recs) {
+      if (!(CUT_FROM_KEY in r)) continue;
+      const object = `part "${String(r.name)}" field "${CUT_FROM_KEY}"`;
+      const base = r[CUT_FROM_KEY];
+      if (typeof base !== 'string' || base === '') {
+        fail('PARTS_FIELD_TYPE', object, `is ${show(base)}; the name of the part the cut took it from is required (the field is absent on a part no cut made)`);
+        continue;
+      }
+      const b = byName.get(base);
+      if (b === undefined) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", which is no part of this file; the plan part the cut took this piece from is required`);
+      else if (base === r.name) fail('PARTS_CUT_FROM_KNOWN', object, `names the piece itself; the plan part the cut took it from is required`);
+      else if (CUT_FROM_KEY in b) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", which is itself a piece (cut from ${show(b[CUT_FROM_KEY])}); a plan part is required, as a cut of a cut has no single layer behind it`);
+      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 ('recomposite' in o && sizeOk) {
     const names = Array.isArray(o.parts) ? new Set(o.parts.map((p) => (typeof p === 'object' && p !== null ? (p as Record<string, unknown>).name : undefined)).filter((n): n is string => typeof n === 'string')) : new Set<string>();
     checkRecomposite(o.recomposite, path, size as [number, number], names, fail);