@rig-c/parts 1.8.0 → 1.9.1

package/src/config.ts

@@ -55,6 +55,11 @@
  * object the loader vouches for, and the rig stage leaves them out of what it
  * hands rigc ({@link constraintForRig}).
  *
+ * 🧭 **`turn` is this package's (issue #251, `src/turn.ts`).** An optional
+ * `{pivot, depths}`: each carried part's See-through `depth_median` and the
+ * depth that stays put, both stated — `propose --full/--head` drafts them —
+ * from which the rig stage derives every fraction ({@link checkTurn}).
+ *
  * 🔗 **`motion.animations_from` is rig-c's too, verbatim (issue #183).** An
  * optional path, relative to the config file's directory, to a file in
  * rig-c's motion-spec shape whose `animations` are written into `motion.json`
@@ -75,6 +80,7 @@ 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';
 import { acceptedTagNames, readTag } from './tags.ts';
+import { TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
 
 export type Point = [number, number];
 
@@ -604,6 +610,8 @@ export interface CharacterConfig {
   regions: Record<string, string>;
   motion: Motion;
   constraints?: ConfigConstraint[];
+  /** The turn control (issue #251, `src/turn.ts`): absent, no control is added and no byte of any output moves. */
+  turn?: TurnSpec;
 }
 
 /** The fields of one constraint kind, as rig-c's interface for that kind declares them. */
@@ -885,7 +893,7 @@ export interface AssembleConfig {
   assemble: Assemble;
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshes', 'regions', 'motion', 'constraints'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1086,6 +1094,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions);
   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);
   const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
   const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
   if (base !== null) poseBeside(c, t.generation, base);
@@ -2281,3 +2290,68 @@ function checkConstraints(c: Check, v: Json, bones: Set<string>, parents: Map<st
     }
   });
 }
+
+/** The parts `meshes` and `regions` attach, read off whatever they hold; `turn.depths` may name only these. */
+function attachedParts(meshes: Json, regions: Json): Set<string> {
+  const out = new Set<string>();
+  for (const v of [meshes, regions]) if (isPlainObject(v)) for (const k of Object.keys(v)) out.add(k);
+  return out;
+}
+
+/**
+ * `config.turn` (issue #251, `src/turn.ts`): `pivot`, the depth that stays put
+ * when the control moves, and `depths`, each carried part's See-through
+ * `depth_median` as `propose` read it. Neither has a default: a config without
+ * `turn` gets no control, and one with it states both.
+ *
+ * - `CONFIG_FIELD_TYPE` / `CONFIG_FIELD_PRESENT` / `CONFIG_KEY_KNOWN`: not an
+ *   object; `pivot` or `depths` absent; another key (records and annotations
+ *   aside); a pivot or a depth that is not a finite number; `depths` not an
+ *   object or empty.
+ * - `CONFIG_NAME_RESOLVES`: a `depths` key that names no part `meshes` or
+ *   `regions` attaches. Its keys are part names, so no annotation or record
+ *   door is open there.
+ * - `CONFIG_TURN_PIVOT_BEHIND_NEAREST`: a pivot at or in front of the nearest
+ *   part's depth. The law divides by `pivot − nearest`, so at the nearest depth
+ *   it has no value, and in front of it every part would travel against the
+ *   dial — no part would be nearer than what stays put.
+ * - `CONFIG_TURN_BONE_FREE`: `bones` declares a bone named {@link TURN_BONE},
+ *   the control the rig stage adds.
+ */
+function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>): void {
+  const at = 'config.turn';
+  const o = c.object(at, v, ['pivot', 'depths'], []);
+  if (o === null) return;
+  const pivot = 'pivot' in o && c.number(`${at}.pivot`, o.pivot) ? (o.pivot as number) : null;
+  const depths: Record<string, number> = {};
+  let depthsOk = false;
+  if ('depths' in o) {
+    const d = o.depths;
+    if (!isPlainObject(d) || Object.keys(d).length === 0) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.depths`, `is ${show(d)}; a non-empty object of part name -> See-through depth_median is required`);
+    } else {
+      depthsOk = true;
+      for (const [part, depth] of Object.entries(d)) {
+        if (!attached.has(part)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${at}.depths.${part}`, `names "${part}", which neither config.meshes nor config.regions attaches; a part the rig draws is required — a depth for a part nobody draws carries nothing`);
+          depthsOk = false;
+        }
+        if (c.number(`${at}.depths.${part}`, depth)) depths[part] = depth;
+        else depthsOk = false;
+      }
+    }
+  }
+  if (pivot !== null && depthsOk) {
+    const nearest = turnNearest(depths);
+    if (nearest !== null && !(pivot > nearest.depth)) {
+      c.fail(
+        'CONFIG_TURN_PIVOT_BEHIND_NEAREST',
+        `${at}.pivot`,
+        `is ${pivot}; the nearest part, "${nearest.part}", lies at depth ${nearest.depth}, and a pivot above that (further back) is required — each part travels (pivot − depth) / (pivot − ${nearest.depth}) of the control's offset, which has no value at the nearest depth and turns every part against the dial in front of it`,
+      );
+    }
+  }
+  if (bones.has(TURN_BONE)) {
+    c.fail('CONFIG_TURN_BONE_FREE', `bone "${TURN_BONE}"`, `is the control the rig stage adds under root for config.turn, and config.bones already declares a bone of that name; rename it`);
+  }
+}

package/src/headframe.ts

@@ -34,6 +34,7 @@
 import type { Point } from './config.ts';
 import { cropToSpineY } from './coords.ts';
 import type { Mask } from './raster/types.ts';
+import { edgeLength } from './length.ts';
 
 /**
  * The eye line's angle in Spine degrees (counter-clockwise, y up) through two
@@ -167,7 +168,7 @@ export function headFrame(
   const [l, r] = eyes[0][0] < eyes[1][0] ? [eyes[0], eyes[1]] : [eyes[1], eyes[0]];
   const dx = r[0] - l[0];
   const dy = r[1] - l[1];
-  const bar = Math.hypot(dx, dy);
+  const bar = edgeLength(dx, dy);
   const u: [number, number] = [dx / bar, dy / bar];
   // The bar's perpendicular toward the chin: u turned a quarter clockwise as drawn (y down).
   const n: [number, number] = [-u[1], u[0]];

package/src/instruments.ts

@@ -23,6 +23,7 @@
  */
 import type { StageBox, Viewport } from './check.ts';
 import { cropToSpineY } from './coords.ts';
+import { edgeLength } from './length.ts';
 import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
 import { type PartRecord, type PartsFile, tagOf } from './parts.ts';
 import type { Raster } from './raster/types.ts';
@@ -446,7 +447,7 @@ export function halfTravels(art: ArtMask, box: { x: number; y: number; w: number
     for (const f of frames) {
       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]));
+      max = Math.max(max, edgeLength(c[0] - c0[0], c[1] - c0[1]));
     }
     return max;
   };
@@ -508,7 +509,7 @@ export function readSine(keys: readonly Key[], duration: number): SineReading |
     }
     a *= 2 / n;
     b *= 2 / n;
-    const mag = Math.hypot(a, b);
+    const mag = edgeLength(a, b);
     if (mag > best.mag) best = { j, a, b, mag };
   }
   if (best.j === 0) return null;
@@ -780,6 +781,9 @@ export function stretchSeverity(ratio: number): number {
   return ratio >= 1 ? ratio : 1 / ratio;
 }
 
+/** An edge's length: {@link edgeLength} of `src/length.ts` (issues #270, #279), re-exported where the stretch reader first used it. */
+export { edgeLength } from './length.ts';
+
 /**
  * For every mesh in `rest`, every triangle's three edges in every frame that
  * shows the attachment: deformed length over rest length, the largest and the
@@ -792,7 +796,7 @@ export function stretchFigures(rest: readonly MeshRest[], frames: readonly Geome
   return rest.map((m) => {
     const t = m.triangles;
     const v0 = m.vertices;
-    const len = (v: readonly number[], a: number, b: number): number => Math.hypot(v[2 * a] - v[2 * b], v[2 * a + 1] - v[2 * b + 1]);
+    const len = (v: readonly number[], a: number, b: number): number => edgeLength(v[2 * a] - v[2 * b], v[2 * a + 1] - v[2 * b + 1]);
     const out: MeshStretch = { slot: m.slot, attachment: m.attachment, triangles: t.length / 3, frames: 0, max: null, min: null, degenerate: [] };
     const restLen: number[] = [];
     for (let i = 0; i < t.length; i += 3) {
@@ -1032,7 +1036,7 @@ export function stillReading(art: ArtMask, stage: StageBox, frames: ReadonlyArra
       const e2x = d[2 * l] - x0;
       const e2y = d[2 * l + 1] - y0;
       for (const bary of pc.pieces[t]) {
-        for (let q = 0; q < bary.length; q += 2) fmax = Math.max(fmax, Math.hypot(x0 + bary[q] * e1x + bary[q + 1] * e2x, y0 + bary[q] * e1y + bary[q + 1] * e2y));
+        for (let q = 0; q < bary.length; q += 2) fmax = Math.max(fmax, edgeLength(x0 + bary[q] * e1x + bary[q + 1] * e2x, y0 + bary[q] * e1y + bary[q + 1] * e2y));
       }
       const cx = x0 + pc.centroid[2 * t] * e1x + pc.centroid[2 * t + 1] * e2x;
       const cy = y0 + pc.centroid[2 * t] * e1y + pc.centroid[2 * t + 1] * e2y;
@@ -1101,7 +1105,7 @@ export function crossingOf(art: ArtMask, stage: StageBox, frames: ReadonlyArray<
           if (Math.max(Math.abs(u - u0), Math.abs(v - v0)) !== r || inR(u, v)) continue;
           const sx0 = stage.x + u;
           const sy1 = stage.y + cropToSpineY(v, H);
-          best = Math.min(best, Math.hypot(Math.max(sx0 - x, 0, x - sx0 - 1), Math.max(sy1 - 1 - y, 0, y - sy1)));
+          best = Math.min(best, edgeLength(Math.max(sx0 - x, 0, x - sx0 - 1), Math.max(sy1 - 1 - y, 0, y - sy1)));
         }
       }
     }

package/src/length.ts

@@ -0,0 +1,21 @@
+/**
+ * The one length this package writes (issues #270, #279): `sqrt(dx * dx + dy * dy)`.
+ *
+ * Not `Math.hypot`. The language does not promise how `Math.hypot` rounds, and
+ * Bun 1.4.2 rounds it differently on two platforms: on the demo's `earring`,
+ * edge 11-10 at idle frame 10 (dx 34.26716181006313, dy 0.5713103861783111),
+ * it is 34.27192399143071 on macOS and 34.27192399143072 on Linux, measured,
+ * with the posed vertices bit-identical on both. That last bit decided which of
+ * two edges 2 ulp apart held a mesh's largest ratio, so `TEXTURE_STRETCH`'s
+ * `max_at` named one triangle on one machine and another on the other (#276).
+ * A multiply, an add and a square root are each correctly rounded by IEEE 754,
+ * so this gives the same bits everywhere (34.27192399143071 on both, measured).
+ * At pixel scale `Math.hypot`'s guard against overflow is not needed: a
+ * coordinate would have to pass about 1e154 for the squares to overflow.
+ *
+ * The tree rule `TY15` refuses a call of `Math.hypot` anywhere under `src/` and in
+ * `cli.ts`, so every length is this one.
+ */
+export function edgeLength(dx: number, dy: number): number {
+  return Math.sqrt(dx * dx + dy * dy);
+}

package/src/propose.ts

@@ -99,8 +99,8 @@
  *
  * The idle departs from the reference's too (issue #252): it is
  * {@link IDLE_FRAMES} frames at 12 fps rather than 4 s, every period scaled
- * with it, and the chest's breath travels {@link BREATH_FRACTION} of the torso
- * part's height ({@link breathTrack}) rather than a fixed 1.3 px amplitude, so
+ * with it, and the chest's breath travels {@link BREATH_FRACTION} of the torso's
+ * length, neck to hip ({@link breathTrack}; issue #270), rather than a fixed 1.3 px amplitude, so
  * no tracked proposal is the reference's output any more in its `motion`.
  *
  * Issue #86 adds what the proposer and lint looked at, and changes nothing
@@ -117,7 +117,7 @@ import { drawText, GLYPH_H } from 'rig-c/tools/font5x7.ts';
 import { type BoneEntry, type ConfigConstraint, type MeshSpec, parseConfig, type Point, type Segment, type SkeletonSections } from './config.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
 import { eyeLineDegrees, type FrameFeature, headAxes, type HeadAxes, headFrame, type HeadFrame } from './headframe.ts';
-import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
+import { type LayerSet, OPAQUE_ALPHA_ABOVE } from './layers.ts';
 import { PAINTING_RUN, type PartRecord, type PartsFile, readParts } from './parts.ts';
 import { connectedComponents } from './raster/components.ts';
 import { dilate, morphGradient } from './raster/morph.ts';
@@ -130,6 +130,8 @@ import { IDLE_FPS } from './motion.ts';
 import { pyRound as roundTo } from './round.ts';
 import { KEYPOINT_NAMES, type KeypointName } from './skeleton.ts';
 import { configRoles, type RoleOf } from './structure.ts';
+import { TURN_BONE, turnFractions, turnNearest, turnPivot, type TurnSpec } from './turn.ts';
+import { edgeLength } from './length.ts';
 
 // ---------------------------------------------------------------------------
 // the output shape — config-shaped, key order as the reference writes it
@@ -187,20 +189,20 @@ export const IDLE_SECONDS = IDLE_FRAMES / IDLE_FPS;
  */
 export const REFERENCE_IDLE_SECONDS = 4;
 /**
- * The breath's travel, peak to peak, as a fraction of the torso part's height
- * (issue #252). The size is the height because the breath is a `translatey`:
- * its travel is read along y, against the part's extent along y. HQ's
- * calibration: about 2.5 %. On the trailer's seated character the torso part
- * (`topwear`) is 267 px tall and the reference's fixed 2.6 px peak to peak
- * (amplitude 1.3, the base 1.3 so the chest rises from its setup pose and
- * returns) was 0.97 % of it, read by its owner as a still paper doll; the
- * production scene rig that replaced it breathes 6.4 px, 2.4 %.
+ * The breath's travel, peak to peak, as a fraction of the torso (issue #252):
+ * HQ's calibration, about 2.5 %. Issue #252 took the torso as the `topwear`
+ * part's height; on the trailer's seated character that is 267 px, and the
+ * reference's fixed 2.6 px peak to peak (amplitude 1.3, the base 1.3 so the
+ * chest rises from its setup pose and returns) was 0.97 % of it, read by its
+ * owner as a still paper doll; the production scene rig that replaced it
+ * breathes 6.4 px, 2.4 %. Issue #270 measures the torso as the trunk the rig
+ * has instead — the neck bone to the hip bone, {@link breathTrack} — because a
+ * garment's box is not the body: `scarf`'s sweater runs to the thighs (690 px)
+ * and breathed 2.9 times as deep as `demo`.
  */
 export const BREATH_FRACTION = 0.025;
-/** The breath's amplitude the reference drafted on every figure, kept only where there is no torso part to scale by. */
+/** The breath's amplitude the reference drafted on every figure, kept only where the trunk has no length to scale by. */
 export const REFERENCE_BREATH_AMP = 1.3;
-/** The See-through tag of the torso part, whose height the breath is a fraction of. */
-export const BREATH_SIZE_TAG = 'topwear';
 
 export interface Proposal {
   bones: BoneEntry[];
@@ -212,6 +214,8 @@ export interface Proposal {
     /** Absent when no part feeds the `eyes` group ({@link EYE_GROUP_TAGS}): a blink with nothing to blink is not written. */
     blink?: ProposedBlink;
   };
+  /** Only with `propose --full`/`--head` (issue #251, {@link draftTurn}); absent otherwise, so a proposal without them is the one written before it. */
+  turn?: TurnSpec;
   notes: string[];
 }
 
@@ -368,6 +372,7 @@ export function checkProposal(P: PartSet, p: Proposal): void {
     meshes: p.meshes,
     regions: p.regions,
     motion: p.motion,
+    ...(p.turn === undefined ? {} : { turn: p.turn }),
   });
 }
 
@@ -376,6 +381,98 @@ export function serializeProposal(p: Proposal): string {
   return `${JSON.stringify(p, null, 2)}\n`;
 }
 
+// ---------------------------------------------------------------------------
+// the turn control (issue #251)
+// ---------------------------------------------------------------------------
+
+/** The See-through runs `propose --full/--head` reads depths from, by run. */
+export type TurnRuns = Partial<Record<'full' | 'head', LayerSet>>;
+
+/**
+ * Draft `turn` (issue #251, `src/turn.ts`) from the parts and the See-through
+ * runs they came from: each part's depth is its layer's `depth_median` — the
+ * layer of its run named by its tag, a cut's piece its base's — and the pivot
+ * is {@link turnPivot} over the parts' `opaque_px`. A `painting:` patch has no
+ * layer and so no depth: it is not carried, and a note names it. What a depth
+ * cannot be read for is refused by name, every one at once:
+ *
+ * - `PROPOSE_TURN_RUN_GIVEN`: a part from a run whose layers were not given.
+ * - `PROPOSE_TURN_LAYER_PRESENT`: the run given holds no layer of the part's tag.
+ * - `PROPOSE_TURN_DEPTH_PRESENT`: the layer carries no depth (a PSD carries none).
+ *
+ * With no part to carry, or every carried part at one depth (nothing nearer
+ * than the pivot), no `turn` is drafted and a note says why. Otherwise one note
+ * states the pivot and its rule, the law, and every part's fraction with the
+ * depth it came from.
+ */
+export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null; notes: string[] } {
+  const problems: Problem[] = [];
+  const rows: Array<{ part: string; depth: number; area: number }> = [];
+  const patches: string[] = [];
+  const unread = new Map<string, string[]>();
+  for (const r of P.recs) {
+    const [run, tag] = splitFrom(r.from);
+    if (run === PAINTING_RUN) {
+      patches.push(r.name);
+      continue;
+    }
+    const set = run === 'full' || run === 'head' ? runs[run] : undefined;
+    if (set === undefined) {
+      unread.set(run, [...(unread.get(run) ?? []), r.name]);
+      continue;
+    }
+    const layer = set.layers.find((l) => l.name === tag);
+    if (layer === undefined) {
+      problems.push({ code: 'PROPOSE_TURN_LAYER_PRESENT', object: `part "${r.name}" (${r.from})`, detail: `came from the ${run} run's "${tag}" layer, and ${set.source} holds no layer of that name; the run its parts were assembled from is required` });
+      continue;
+    }
+    if (layer.depth === null) {
+      problems.push({ code: 'PROPOSE_TURN_DEPTH_PRESENT', object: `part "${r.name}" (${r.from})`, detail: `its layer in ${set.source} carries no depth_median (a ${set.form} input); the turn orders parts by See-through's per-layer depth, so a run that carries one is required` });
+      continue;
+    }
+    rows.push({ part: r.name, depth: layer.depth, area: r.opaque_px });
+  }
+  for (const [run, names] of unread) {
+    problems.push({ code: 'PROPOSE_TURN_RUN_GIVEN', object: `the ${run} run`, detail: `part(s) ${names.map((n) => `"${n}"`).join(', ')} came from it and its layers were not given; --${run} <dir | layers.json> is required to read their depth` });
+  }
+  refuseIfAny(problems);
+  const notes: string[] = [];
+  if (patches.length > 0) {
+    notes.push(`turn: painting patch(es) ${patches.map((n) => `"${n}"`).join(', ')} carry no See-through depth and are not carried — each moves only as its bone does, as the pivot depth does; a value in config.turn.depths carries one`);
+  }
+  const pivot = turnPivot(rows);
+  const depths = Object.create(null) as Record<string, number>;
+  for (const r of rows) depths[r.part] = r.depth;
+  const nearest = turnNearest(depths);
+  if (pivot === null || nearest === null) {
+    notes.push('turn: no part carries a See-through depth with any opaque pixel, so no turn control is drafted');
+    return { turn: null, notes };
+  }
+  if (!(pivot > nearest.depth)) {
+    notes.push(`turn: every carried part lies at depth ${nearest.depth}, so none is nearer than the pivot and no turn control is drafted`);
+    return { turn: null, notes };
+  }
+  const turn: TurnSpec = { pivot, depths };
+  const fr = turnFractions(turn, rows.map((r) => r.part));
+  notes.push(
+    `turn: control "${TURN_BONE}" under root, keyed by nothing — its x is the dial. Pivot depth ${pivot}: the mean of the ${rows.length} carried parts' See-through depth_median weighted by opaque_px, the one depth at which the painted pixels' centroid does not slide (correct it in turn.pivot). ` +
+      `Each part travels (pivot - depth) / (pivot - ${nearest.depth}) of the control's x, "${nearest.part}" (nearest) all of it: ${fr.map((f) => `${f.part} ${f.fraction} (depth ${f.depth})`).join(', ')}`,
+  );
+  notes.push(...TURN_DEPTH_CAVEAT);
+  return { turn, notes };
+}
+
+/** The notes beside every drafted turn (issue #251): what a See-through depth is, where it misleads, and that the two runs' axes are not reconciled. */
+export const TURN_DEPTH_CAVEAT: readonly string[] = [
+  "turn: depth is the See-through layer's median and each part takes its own run's axis; a seated or forward-reaching limb can read further back than it is (trailer legwear 0.770 sits behind the pivot)",
+  "turn: the two runs' depth axes are not reconciled (parts#271)",
+];
+
+/** The proposal with `turn` written after `motion` and `notes` extended; the proposal itself when `turn` is null. */
+export function withTurn(p: Proposal, draft: { turn: TurnSpec | null; notes: string[] }): Proposal {
+  return { bones: p.bones, meshes: p.meshes, regions: p.regions, motion: p.motion, ...(draft.turn === null ? {} : { turn: draft.turn }), notes: [...p.notes, ...draft.notes] };
+}
+
 // ---------------------------------------------------------------------------
 // the parts, as masks
 // ---------------------------------------------------------------------------
@@ -1174,10 +1271,12 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
     if (Object.keys(still).length > 0) blink.still = still;
     if (browBonesProposed.length === 0) notes.push(`blink without brows: no eyebrow part (looked for: ${BROW_GROUP_TAGS.join(', ')}), so the blink has no brows group and no brow_drop`);
   }
-  // Issue #252: the breath's travel is BREATH_FRACTION of the torso part's height, not the reference's fixed 1.3 px
-  // amplitude. Its base stays its amplitude (the chest rises from the setup pose and returns). The other three tracks
-  // are an angle and a ratio and stay as drafted. A rig with no torso part keeps the reference's amplitude, and a note.
-  const breath = breathTrack(P);
+  // Issue #252: the breath's travel is BREATH_FRACTION of the torso, not the reference's fixed 1.3 px amplitude; issue
+  // #270: the torso is the neck -> hip run as the two bones are written above, not a garment's height. Its base stays
+  // its amplitude (the chest rises from the setup pose and returns). The other three tracks are an angle and a ratio
+  // and stay as drafted. A trunk of no length (neck and hip on one point) keeps the reference's amplitude, and a note.
+  const writtenAt = (n: string): Point => (bones.find((b) => 'name' in b && b.name === n) as { at: Point }).at;
+  const breath = breathTrack(writtenAt('neck'), writtenAt('hip'));
   notes.push(breath.note);
   tracks.push(
     breath.track,
@@ -1584,7 +1683,7 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       const [g, r] = gridR(p);
       const segs: Segment[] = [];
       for (const a of armPlan.arms.filter((q) => q.part === p)) {
-        const len = Math.hypot(a.elbow[0] - a.shoulder[0], a.elbow[1] - a.shoulder[1]);
+        const len = edgeLength(a.elbow[0] - a.shoulder[0], a.elbow[1] - a.shoulder[1]);
         const d: [number, number] = [(a.elbow[0] - a.shoulder[0]) / len, (a.elbow[1] - a.shoulder[1]) / len];
         segs.push(['chest', rnd([a.shoulder[0] - 14 * d[0], a.shoulder[1] - 14 * d[1]]), rnd([a.shoulder[0] + 2 * d[0], a.shoulder[1] + 2 * d[1]])], `sleeve_${a.side}`);
       }
@@ -1762,6 +1861,20 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
         ['hip', rnd(along(waist, trunk.v, s0 + 0.09 * (s1 - s0))), rnd(along(waist, trunk.v, s0 + 0.91 * (s1 - s0)))],
       ];
     }
+    // Issue #262: a skirt whose art starts below the chest bone hangs from the waist. Its root is the hip line's,
+    // and the chest segment goes: with it the breath carries the waistband (a vertex near the chest segment's
+    // lower end takes chest weight), so the root travels with the breath while the hem, on the skirt's chains,
+    // does not. A bottomwear reaching up past the chest (the long robe the hip rule above reads the waist for) has
+    // art on the chest and keeps the segment. Read along the trunk where there is one, down the screen otherwise.
+    const down: readonly [number, number] = trunk === null ? [0, 1] : trunk.u;
+    const artTop = artExtent(mask, p, hip, down)[0];
+    const chestAt = (chest[0] - hip[0]) * down[0] + (chest[1] - hip[1]) * down[1];
+    if (artTop >= chestAt) {
+      segs = segs.filter((s) => typeof s === 'string' || s[0] !== 'chest');
+      notes.push(
+        `${p.name} (${p.from}): its art starts ${pyFixed(artTop - chestAt, 1)} px below chest's origin, so it hangs from the waist — its mesh takes the hip line and its skirt chains, no chest segment, and the breath does not carry its root`,
+      );
+    }
     for (const [tag, f, ph] of [
       ['skirt_r', 0.3, 0.3],
       ['skirt_c', 0.5, 0.34],
@@ -1809,7 +1922,7 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
       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 len = edgeLength(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);
       }
@@ -1868,31 +1981,32 @@ export function proposeWithBasis(P: PartSet, joints?: RigJoints, wristSnap: numb
 }
 
 /**
- * The drafted breath (issue #252): `chest` `translatey`, its travel peak to
- * peak {@link BREATH_FRACTION} of the height of the {@link BREATH_SIZE_TAG}
- * layer — the box around every part from it, cut pieces included, since a cut
- * does not shorten the torso — amplitude half of it to two decimals, and the
- * base the amplitude. With no such part there is no height to take a fraction
- * of, and inventing one is not done: the track keeps the reference's
- * amplitude, {@link REFERENCE_BREATH_AMP}, and the note says so.
+ * The drafted breath (issues #252, #270): `chest` `translatey`, its travel peak
+ * to peak {@link BREATH_FRACTION} of the torso's length — the distance from the
+ * `neck` bone's origin to the `hip` bone's, as the proposal writes them (so the
+ * figure can be recomputed from proposal.json): the run the chest is placed
+ * half way along and the trunk segments are laid along (issue #243), whichever
+ * rule placed the two ends (joints, the face and bottomwear, the waist, or the
+ * figure's proportion — the hip's own note names it). Amplitude half of it to
+ * two decimals, and the base the amplitude. When neck and hip are one point the
+ * trunk has no length to take a fraction of, and inventing one is not done: the
+ * track keeps the reference's amplitude, {@link REFERENCE_BREATH_AMP}, and the
+ * note says so.
  */
-export function breathTrack(P: PartSet): { track: ProposedSingleTrack; note: string } {
-  const parts = P.byTag(BREATH_SIZE_TAG, undefined, true);
-  if (parts.length === 0) {
+export function breathTrack(neck: readonly [number, number], hip: readonly [number, number]): { track: ProposedSingleTrack; note: string } {
+  const length = edgeLength(hip[0] - neck[0], hip[1] - neck[1]);
+  const run = `neck ${pyIntList(neck)} -> hip ${pyIntList(hip)}`;
+  if (length === 0) {
     const a = REFERENCE_BREATH_AMP;
     return {
       track: { bone: 'chest', prop: 'translatey', amp: a, period: REFERENCE_IDLE_SECONDS, phase: 0.0, base: a },
-      note: `breath: no ${BREATH_SIZE_TAG} part, so no torso height to take a fraction of: chest translatey keeps the reference's amplitude ${a} (${pyFixed(2 * a, 2)} px peak to peak), not ${pyFixed(BREATH_FRACTION * 100, 1)} % of a torso — scale it to the figure`,
+      note: `breath: ${run} are one point, so the trunk has no length to take a fraction of: chest translatey keeps the reference's amplitude ${a} (${pyFixed(2 * a, 2)} px peak to peak), not ${pyFixed(BREATH_FRACTION * 100, 1)} % of a torso — scale it to the figure`,
     };
   }
-  const top = Math.min(...parts.map((p) => p.y));
-  const bottom = Math.max(...parts.map((p) => p.y + p.h));
-  const height = bottom - top;
-  const amp = roundTo((BREATH_FRACTION * height) / 2, 2);
-  const layers = [...new Set(parts.map((p) => p.from))].join(', ');
+  const amp = roundTo((BREATH_FRACTION * length) / 2, 2);
   return {
     track: { bone: 'chest', prop: 'translatey', amp, period: REFERENCE_IDLE_SECONDS, phase: 0.0, base: amp },
-    note: `breath: chest translatey ${pyFixed(2 * amp, 2)} px peak to peak (amp ${pyFixed(amp, 2)}, base ${pyFixed(amp, 2)}) = ${pyFixed(BREATH_FRACTION * 100, 1)} % of the torso's height, ${height} px (layer ${layers}, y ${top}..${bottom}), once per ${IDLE_FRAMES}-frame idle at ${IDLE_FPS} fps`,
+    note: `breath: chest translatey ${pyFixed(2 * amp, 2)} px peak to peak (amp ${pyFixed(amp, 2)}, base ${pyFixed(amp, 2)}) = ${pyFixed(BREATH_FRACTION * 100, 1)} % of the torso's length, ${pyFixed(length, 1)} px (${run}), once per ${IDLE_FRAMES}-frame idle at ${IDLE_FPS} fps`,
   };
 }
 
@@ -1915,7 +2029,7 @@ interface TrunkLine {
 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);
+  const len = edgeLength(dx, dy);
   if (len === 0) return null;
   const u: [number, number] = [dx / len, dy / len];
   return { u, v: [u[1], -u[0]] };
@@ -2308,7 +2422,7 @@ function jointNotes(joints: RigJoints, f: JointNoteFacts): string[] {
     if (j.at === null) return;
     const e = f.eyes[i];
     if (e === null) tell(n, `${said(n, j)}: no bone takes it — an eye bone comes only from an eyewhite part`);
-    else tell(n, `${said(n, j)}: bone ${e.bone} is measured off ${e.part} (its box centre ${fmtAt(e.at)}) and is not moved; the joint is ${pyFixed(Math.hypot(j.at[0] - e.at[0], j.at[1] - e.at[1]), 1)} px from it`);
+    else tell(n, `${said(n, j)}: bone ${e.bone} is measured off ${e.part} (its box centre ${fmtAt(e.at)}) and is not moved; the joint is ${pyFixed(edgeLength(j.at[0] - e.at[0], j.at[1] - e.at[1]), 1)} px from it`);
   });
   const rest = KEYPOINT_NAMES.filter((n) => !told.has(n));
   if (rest.length > 0) out.push(`no rule reads ${rest.map((n) => said(n, J[n])).join(', ')} — no bone is authored from them`);
@@ -2875,8 +2989,8 @@ export function lint(
     if (chest !== null && !(along(chest) > 0 && along(chest) < 1)) findings.push({ kind: 'chest-not-between', chest, t: along(chest), neck: T.neck, hips: T.hips });
     if (hip !== null && chest !== null && along(hip) <= along(chest)) findings.push({ kind: 'hip-not-past-chest', hip, chest, tHip: along(hip), tChest: along(chest) });
     if (hip !== null) {
-      const dNeck = Math.hypot(hip[0] - T.neck[0], hip[1] - T.neck[1]);
-      const dHips = Math.hypot(hip[0] - T.hips[0], hip[1] - T.hips[1]);
+      const dNeck = edgeLength(hip[0] - T.neck[0], hip[1] - T.neck[1]);
+      const dHips = edgeLength(hip[0] - T.hips[0], hip[1] - T.hips[1]);
       if (dNeck < dHips) findings.push({ kind: 'hip-nearer-neck', hip, neck: T.neck, hips: T.hips, dNeck, dHips });
     }
   } else {
@@ -2893,7 +3007,7 @@ export function lint(
     for (const c of basis.chains) {
       if (c.line === null) continue;
       const { from, to } = c.line;
-      const len = Math.hypot(to[0] - from[0], to[1] - from[1]);
+      const len = edgeLength(to[0] - from[0], to[1] - from[1]);
       const e = spec.bones.find((b) => 'chain' in b && b.chain === c.chain);
       if (e === undefined || !('chain' in e)) continue;
       const pts: Array<[string, Point]> = [...e.points.map((q, i): [string, Point] => [`${c.chain}${i}`, q]), [`${c.chain} tip`, e.tip]];
@@ -3105,7 +3219,7 @@ export function compare(proposal: readonly BoneEntry[], config: readonly BoneEnt
   const rows: Array<[string, number]> = [];
   for (const [n, cb] of b) {
     const pb = a.get(n);
-    if (pb !== undefined) rows.push([n, Math.hypot(pb.x - cb.x, pb.y - cb.y)]);
+    if (pb !== undefined) rows.push([n, edgeLength(pb.x - cb.x, pb.y - cb.y)]);
   }
   return { rows, onlyConfig: [...b.keys()].filter((n) => !a.has(n)), onlyProposal: [...a.keys()].filter((n) => !b.has(n)) };
 }
@@ -3174,7 +3288,7 @@ function line(r: Raster, a: readonly [number, number], b: readonly [number, numb
 function dot(r: Raster, cx: number, cy: number): void {
   for (let dy = -4; dy <= 4; dy++) {
     for (let dx = -4; dx <= 4; dx++) {
-      const d = Math.hypot(dx, dy);
+      const d = edgeLength(dx, dy);
       if (d <= 3.5) setPx(r, Math.round(cx) + dx, Math.round(cy) + dy, [255, 0, 0]);
       else if (d <= 4.5) setPx(r, Math.round(cx) + dx, Math.round(cy) + dy, [0, 0, 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';
@@ -820,7 +821,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 +1215,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;