@rig-c/parts 1.9.0 → 1.10.0

package/src/requirements.ts

@@ -55,6 +55,7 @@ import { refuseIfAny } from './errors.ts';
 import { type BoneWorld, type GeometryPose, type MeshRest, stretchFigures, stretchSeverity } from './instruments.ts';
 import { ART_ALPHA } from './mesh.ts';
 import { alphaAbove, type Raster } from './raster/types.ts';
+import { edgeLength } from './length.ts';
 
 /** The file's `spec`. */
 export const REQUIREMENTS_SPEC = 'spine-parts-requirements/1';
@@ -169,6 +170,15 @@ export interface RequirementsFile {
    * and names each in its line. Empty when not declared: every part hangs.
    */
   rises: string[];
+  /**
+   * Issue #245: the swinging parts whose tip is at rest — a hand lying on the
+   * bed while the shoulder moves with the breath — by name. `TIP_OVER_ROOT`
+   * holds each to the opposite relation, its tip half travelling no further
+   * than its root half, and `CHAIN_LAG` holds the chain carrying each to
+   * amplitudes that do not grow toward the tip; each line names them first.
+   * Empty when not declared: every swinging part's tip swings.
+   */
+  rests: string[];
 }
 
 /** What `check --requirements` and `build --requirements` name, said once for the help and the refusals. */
@@ -204,8 +214,8 @@ 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;
+/** The lists of parts a scene excepts from a bar that assumes a standing figure (issues #231, #245), in the order they are read. */
+export const EXCEPTION_LISTS = ['not_planted', 'not_swinging', 'rises', 'rests'] as const;
 type ExceptionList = (typeof EXCEPTION_LISTS)[number];
 
 /** What each list's absence declares. */
@@ -213,14 +223,16 @@ 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',
+  rests: 'every swinging part one whose tip swings further than its root',
 };
 
 /**
  * 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), `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;
+ * and `not_planted`, `not_swinging`, `rises` and `rests` (each optional,
+ * issues #231 and #245: a non-empty list of distinct part names, no part both
+ * in `not_swinging` and in `rises` or `rests`;
  * 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
@@ -245,7 +257,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', ...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)');
+  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, rests; 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;
@@ -391,8 +403,12 @@ export function readRequirements(path: string): RequirementsFile {
   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`);
   });
+  // Issue #245: rests is a reading (the tip no further than the root) and not_swinging is none, so a part cannot be both.
+  lists.rests.forEach((n, i) => {
+    if (lists.not_swinging.includes(n)) field(`${at} field "rests"[${i}]`, `names "${n}", which "not_swinging" names too; a part declared not swinging is not measured, so there is no tip to hold at rest — leave it in one list`);
+  });
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests };
 }
 
 // ---------------------------------------------------------------------------
@@ -820,7 +836,7 @@ export function contactLine(r: ContactRequirement, p: Poses, facts: RigFacts): R
   for (let i = 0; i < p.times.length; i++) {
     const a = pointOf(track.frames[i], r.point, len);
     const b = at(i);
-    const d = Math.hypot(a[0] - b[0], a[1] - b[1]);
+    const d = edgeLength(a[0] - b[0], a[1] - b[1]);
     if (d > worst) {
       worst = d;
       wi = i;
@@ -1214,7 +1230,7 @@ export function seamLine(r: SeamRequirement, pairs: readonly SeamPair[], frames:
         continue;
       }
       read++;
-      const o = Math.hypot(da[0] - db[0], da[1] - db[1]);
+      const o = edgeLength(da[0] - db[0], da[1] - db[1]);
       if (o > worst) {
         worst = o;
         wi = i;

package/src/rig.ts

@@ -638,7 +638,8 @@ export interface ContourMeshReport {
   exponent?: number;
   /** Only when the mesh declared ribs (issue #188): what it declared and what was placed. Absent otherwise, so a mesh without ribs writes the row it always wrote. */
   ribs?: RibsRow;
-  params: { tolerance: number; margin: number; spacing: number; budget: number | null; stray: number | null };
+  /** `maxEdge` only when the mesh declared it (issue #265), so a mesh without it writes the row it always wrote. */
+  params: { tolerance: number; margin: number; spacing: number; maxEdge?: number; budget: number | null; stray: number | null };
   contour: ContourReport;
   regions: Array<{ name: string; bone: string; reached: number; whole: number }>;
   /** Only under `rule: "heat"` (issue #161), as the lattice row's. */
@@ -1335,7 +1336,7 @@ export function buildRig(
         : { name: rg.name, shape: 'polygon', points: rg.points.map(([x, y]) => [x - ox, y - oy] as [number, number]), spacing: rg.spacing, band: rg.band },
     );
     const ribs = chainRibs(ribSpec.segments, ribSpec.ribs, ox, oy);
-    const cm = contourMesh(p.name, { width: w, height: h, alpha }, { threshold: ART_ALPHA, tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, budget: spec.budget, stray: spec.stray, regions: inPart, ...(ribs.length === 0 ? {} : { ribs }) });
+    const cm = contourMesh(p.name, { width: w, height: h, alpha }, { threshold: ART_ALPHA, tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget, stray: spec.stray, regions: inPart, ...(ribs.length === 0 ? {} : { ribs }) });
     if (Array.isArray(cm)) {
       out.push(...cm);
       return null;
@@ -1401,7 +1402,7 @@ export function buildRig(
         mode: 'contour',
         ...(exponent === undefined ? {} : { exponent }),
         ...(ribSpec.ribs === undefined ? {} : { ribs: ribsRow(ribSpec.ribs, cm.ribs ?? []) }),
-        params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, budget: spec.budget ?? null, stray: spec.stray ?? null },
+        params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget ?? null, stray: spec.stray ?? null },
         contour: rep,
         regions: regions.map((rg, k) => ({ name: rg.name, bone: rg.bone, reached: reached[k], whole: whole[k] })),
         ...(heat === null ? {} : { heat: heatRow(heat) }),

package/src/skeleton.ts

@@ -35,6 +35,7 @@
  * latent size scales every point by `w / 832`, `h / 1216`.
  */
 import { newRaster, type Raster } from './raster/types.ts';
+import { edgeLength } from './length.ts';
 
 export type SkeletonName = 'stand_sides' | 'stand_clasp';
 
@@ -391,7 +392,7 @@ export function renderSkeleton(pose: SkeletonName | PosePoints, w: number, h: nu
     const [x1, y1] = kp[i1 - 1];
     const [x2, y2] = kp[i2 - 1];
     const angle = Math.atan2(y1 - y2, x1 - x2) * RAD_TO_DEG;
-    const poly = ellipsePoly((x1 + x2) / 2, (y1 + y2) / 2, Math.hypot(x1 - x2, y1 - y2) / 2, sw, angle);
+    const poly = ellipsePoly((x1 + x2) / 2, (y1 + y2) / 2, edgeLength(x1 - x2, y1 - y2) / 2, sw, angle);
     const c = COLORS[i];
     pilFillPolygon(r, poly, [Math.trunc(c[0] * 0.6), Math.trunc(c[1] * 0.6), Math.trunc(c[2] * 0.6)]);
   });

package/src/structure.ts

@@ -74,6 +74,7 @@ import { parseRigSpec, RIG_SPEC_VERSION, type RigBone as RigcBone, type RigSpec
 import { type ConfigConstraint, CONSTRAINT_FOLLOWS, parseConfig, parseProposalSections, type Point, ROOT_BONE, type SkeletonSections, weightsABone } from './config.ts';
 import { computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toWorld } from './coords.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
+import { edgeLength } from './length.ts';
 
 // ---------------------------------------------------------------------------
 // the normal form
@@ -633,16 +634,16 @@ function pairRow(l: NormalBone, r: NormalBone, left: Skeleton, right: Skeleton,
     return sides;
   };
   const originWhy = geometric(l.originWhy, r.originWhy);
-  const origin: Figure = originWhy !== null || l.origin === null || r.origin === null ? { skip: originWhy ?? '' } : { value: Math.hypot(carry(l.origin)[0] - r.origin[0], carry(l.origin)[1] - r.origin[1]) };
+  const origin: Figure = originWhy !== null || l.origin === null || r.origin === null ? { skip: originWhy ?? '' } : { value: edgeLength(carry(l.origin)[0] - r.origin[0], carry(l.origin)[1] - r.origin[1]) };
   const tipWhy = geometric(l.tipWhy, r.tipWhy);
   const lo = l.origin;
   const ro = r.origin;
   const lt = l.tip;
   const rt = r.tip;
   const both = lo !== null && ro !== null && lt !== null && rt !== null;
-  const tip: Figure = tipWhy !== null || !both ? { skip: tipWhy ?? '' } : { value: Math.hypot(carry(lt)[0] - rt[0], carry(lt)[1] - rt[1]) };
-  const ll = lo !== null && lt !== null ? Math.hypot(lt[0] - lo[0], lt[1] - lo[1]) : null;
-  const rl = ro !== null && rt !== null ? Math.hypot(rt[0] - ro[0], rt[1] - ro[1]) : null;
+  const tip: Figure = tipWhy !== null || !both ? { skip: tipWhy ?? '' } : { value: edgeLength(carry(lt)[0] - rt[0], carry(lt)[1] - rt[1]) };
+  const ll = lo !== null && lt !== null ? edgeLength(lt[0] - lo[0], lt[1] - lo[1]) : null;
+  const rl = ro !== null && rt !== null ? edgeLength(rt[0] - ro[0], rt[1] - ro[1]) : null;
   const difference: Figure = tipWhy !== null || ll === null || rl === null ? { skip: tipWhy ?? '' } : { value: rl - scale * ll };
   const dir: Figure = tipWhy !== null || !both ? { skip: tipWhy ?? '' } : { value: normaliseDegrees(direction(ro, rt) - direction(lo, lt)) };
   return { left: l.name, right: r.name, origin, parent: parentVerdict(l, r, left, right, fwd, inv), tip, length: { left: ll, right: rl, difference }, direction: dir };

package/src/tags.ts

@@ -26,6 +26,22 @@
  * Nothing downstream classifies a part by its NAME. The role of a part — what
  * a proposer may do with it — is read from the tag it came from, which is why
  * `parts.json` records `from` for every part.
+ *
+ * ⭐ **An author-made layer** (issue #256) is a layer the author split or
+ * painted by hand outside the tool — a hand laid over a hip taken out of
+ * `handwear`, a loop of hair over a shoulder taken out of `back hair` — and
+ * added to a run. It is named `author:<label>` ({@link AUTHOR_PREFIX}), the
+ * label the author's own. It is not a See-through tag and carries no role:
+ * {@link readTag} never reads it, so no rule that reads roles from tags ever
+ * sees it, and every reader that admits a layer reads it through
+ * {@link readLayerTag}, which says `group: "author"`. Why a prefix and this
+ * one: a single reserved name would let a run hold one such layer (a tag
+ * names one layer, `LAYERS_NAME_UNIQUE`, and one layer makes one part); no
+ * v3 tag holds a colon, so the prefix cannot be read as a See-through tag or
+ * as one of its `-r`/`-l` halves; and `<origin>:<name>` is already how
+ * `parts.json` says "not a See-through layer" for a patch (`painting:<name>`).
+ * Every reader of a part's `from` splits at the first colon, so
+ * `full:author:hand` is the full run's layer `author:hand`.
  */
 
 export const BODY_TAGS = [
@@ -119,3 +135,73 @@ export function pairOf(name: string): string | null {
   if (t === null || t.side === null) return null;
   return `${t.base}-${t.side === 'r' ? 'l' : 'r'}`;
 }
+
+/** The prefix of an author-made layer's name (issue #256): `author:<label>`. */
+export const AUTHOR_PREFIX = 'author:';
+
+/** An author-made layer's name read: the label after {@link AUTHOR_PREFIX}, and no tag, so no role. */
+export interface AuthorTagReading {
+  /** The name as the layer carries it: `author:hand`. */
+  name: string;
+  /** What follows the prefix: the author's own word, read by nothing as a role. */
+  label: string;
+  group: 'author';
+}
+
+/** What a layer name reads as: a See-through v3 tag, or an author-made layer's name. */
+export type LayerTagReading = TagReading | AuthorTagReading;
+
+/** What an author-made layer's label must be, as a refusal quotes it. */
+export const AUTHOR_LABEL_RULE = 'a label that is not empty, does not start with "." or whitespace, does not end with whitespace, and holds no slash, backslash or colon';
+
+/**
+ * Whether `label` may follow {@link AUTHOR_PREFIX}. It becomes part of a part
+ * name the plan proposes and of a file name the wrapper form may look for
+ * (`parts/<name>.png`), so it is held to what a part name may be, and it holds
+ * no colon, so the name keeps exactly one.
+ */
+export function authorLabelOk(label: string): boolean {
+  return label !== '' && !label.startsWith('.') && label.trim() === label && !/[\\/:]/.test(label);
+}
+
+/** Read a layer name as an author-made layer's, or `null` when it is not one (no prefix, or a label {@link authorLabelOk} refuses). */
+export function readAuthorTag(name: string): AuthorTagReading | null {
+  if (!name.startsWith(AUTHOR_PREFIX)) return null;
+  const label = name.slice(AUTHOR_PREFIX.length);
+  return authorLabelOk(label) ? { name, label, group: 'author' } : null;
+}
+
+/** Read a layer name as a v3 tag or an author-made layer's name, or `null` when it is neither. */
+export function readLayerTag(name: string): LayerTagReading | null {
+  return readTag(name) ?? readAuthorTag(name);
+}
+
+/** Whether a tag string names an author-made layer. */
+export function isAuthorTag(name: string): boolean {
+  return readAuthorTag(name) !== null;
+}
+
+/**
+ * Why `name` is no layer tag, as the detail of a `*_TAG_KNOWN` refusal: an
+ * `author:` name whose label is refused says what the label must be; any
+ * other names the accepted v3 tags and the author form.
+ */
+export function layerTagRequirement(name: string): string {
+  if (name.startsWith(AUTHOR_PREFIX)) {
+    return `is an author-made layer's name with the label ${JSON.stringify(name.slice(AUTHOR_PREFIX.length))}; ${AUTHOR_LABEL_RULE} is required after "${AUTHOR_PREFIX}"`;
+  }
+  return `is not a See-through v3 tag; one of ${acceptedTagNames().join(', ')} is required, or "${AUTHOR_PREFIX}<label>" for a layer the author made`;
+}
+
+/**
+ * What every stage says of an author-made layer (issue #256), so it never
+ * reads as a See-through layer: `layers` prints it per layer, `assemble` per
+ * part, and `--propose-plan` and `propose` carry it in their notes.
+ */
+export const AUTHOR_NO_ROLE =
+  'an author-made layer, not a See-through one: no tag, so no role — it rides the bone the config gives it (config.regions.<part>, or a mesh in config.meshes), and its draw position is its place in config.assemble.plan';
+
+/** The `layers` line for an author-made layer. */
+export function authorLayerLine(name: string): string {
+  return `author-made: layer "${name}" — ${AUTHOR_NO_ROLE}`;
+}

package/src/turn.ts

@@ -30,6 +30,37 @@
  */
 import { pyRound } from './round.ts';
 
+/**
+ * The layers that ride on the face (issue #271): See-through makes no depth
+ * of their own for them, so `propose` does not read theirs. The eye group —
+ * eyewhite, irides, eyelash, eyebrow — is cut from one depth map predicted for
+ * the combined eyes layer (`compose_list` in See-through's
+ * `common/utils/inference_utils.py`, commit df019de), which is why
+ * `eyewhite-r` and `eyewhite-l` read the same median in every run measured
+ * for #251; nose and mouth are clamped by See-through to the face's median
+ * minus {@link TURN_RIDER_OFFSET} when they read behind it (the same file,
+ * lines 528-531). Their own medians disagreed across the two runs by up to
+ * 0.474 (demo `eyebrow-r`, #251's table), and the disagreement swapped their
+ * order against the face. Matched on the layer's base tag, either side.
+ */
+export const TURN_RIDER_TAGS: readonly string[] = ['eyewhite', 'irides', 'eyelash', 'eyebrow', 'nose', 'mouth'];
+
+/** The tag of the part the riders take their depth from. */
+export const TURN_CARRIER_TAG = 'face';
+
+/** See-through's own offset between a clamped face feature and the face (`face − 0.001`, the file named at {@link TURN_RIDER_TAGS}). */
+export const TURN_RIDER_OFFSET = 0.001;
+
+/**
+ * A rider's depth: its carrier's, {@link TURN_RIDER_OFFSET} nearer when the
+ * rider is drawn after the carrier (above it) and as much further when it is
+ * drawn before (under it), so the draw order the depths imply is the one
+ * parts.json holds.
+ */
+export function turnRiderDepth(carrier: number, above: boolean): number {
+  return above ? carrier - TURN_RIDER_OFFSET : carrier + TURN_RIDER_OFFSET;
+}
+
 /** The control bone the rig stage adds under `root` when the config has `turn`: nothing keys it, and its local x is the dial. */
 export const TURN_BONE = 'turn';