@rig-c/parts 1.7.0 → 1.9.0

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

@@ -0,0 +1,207 @@
+/**
+ * The head's frame, read off the head run's parts (issue #250): the eye line
+ * (the bar), and the line from the eye midpoint down through the nose and the
+ * mouth (the stem) — the T construction of head-pose estimation from facial
+ * landmarks.
+ *
+ * - **Roll** is the bar's angle. It has one derivation in this package,
+ *   {@link eyeLineDegrees}: the line through the eye bones' origins as the
+ *   config writes them, image-left to image-right, in Spine degrees through
+ *   the one y flip. `propose` reads it on the origins it writes for `eye_r`
+ *   and `eye_l`; the rig stage turns the five face bones to it and declares
+ *   the `invariants.axes` entry rigc's A51 draws through those same two
+ *   origins (`src/rig.ts`, {@link eyeLineDegrees} there too). A roll read
+ *   anywhere else could disagree with the one the face bones stand on.
+ * - **Turn** (yaw), three ways: the stem's skew off the bar's perpendicular
+ *   (via the nose and via the mouth, each as a sideways and a downward
+ *   fraction of the inter-eye distance), the two eyewhites' widths along the
+ *   bar, and the face part's two halves along the bar about the eye
+ *   midpoint. Never acted on, and not written by `propose`: on a face painted
+ *   three-quarter the three readings did not agree in order
+ *   (`FRONTAL_REFERENCE` in `src/propose.ts`), so they stay readings here.
+ * - **Pitch** proportions: where the nose sits along eye midpoint -> mouth,
+ *   and the stem's length (the mouth's downward fraction) against the bar.
+ *
+ * A drawn face does not carry a human face's ratios, so no figure here is
+ * compared with a human model: the frontal reference is read off drawn
+ * frontal faces (`FRONTAL_REFERENCE` in `src/propose.ts`, with its source).
+ * Nothing is guessed: a feature with no part is named as missing, and its
+ * figures are not written.
+ *
+ * Image coordinates throughout (crop px, y down), but for the roll, which is
+ * Spine's (counter-clockwise, y up). Pure.
+ */
+import type { Point } from './config.ts';
+import { cropToSpineY } from './coords.ts';
+import type { Mask } from './raster/types.ts';
+
+/**
+ * The eye line's angle in Spine degrees (counter-clockwise, y up) through two
+ * points in crop px on a canvas `H` px tall, read from the image-left point to
+ * the image-right one, so it lies inside (−90°, 90°) and which point is which
+ * eye does not enter it. The caller refuses two points in one column.
+ */
+export function eyeLineDegrees(a: Point, b: Point, H: number): number {
+  const [l, r] = a[0] < b[0] ? [a, b] : [b, a];
+  const dx = r[0] - l[0];
+  const dy = cropToSpineY(r[1], H) - cropToSpineY(l[1], H);
+  return (Math.atan2(dy, dx) * 180) / Math.PI;
+}
+
+/**
+ * The head's two axes in crop px on a canvas `H` px tall, for a roll in Spine
+ * degrees ({@link eyeLineDegrees}; issue #249): `at(p, across, down)` is `p`
+ * moved `across` px along the eye line (image-left to image-right) and `down`
+ * px along the face's down axis (the eye line's perpendicular toward the
+ * chin), and `of(p, q)` is the inverse, q's `[across, down]` from p. The
+ * axes are taken in Spine's frame, where the roll is an angle, and every
+ * point crosses the y flip through `cropToSpineY` both ways; a roll of 0 is
+ * the page's axes.
+ */
+export interface HeadAxes {
+  at(p: readonly [number, number], across: number, down: number): [number, number];
+  of(p: readonly [number, number], q: readonly [number, number]): [number, number];
+}
+
+export function headAxes(roll: number, H: number): HeadAxes {
+  const t = (roll * Math.PI) / 180;
+  const bar: [number, number] = [Math.cos(t), Math.sin(t)];
+  // The face's up axis is the roll + 90 degrees, (−sin, cos) in Spine's frame; down is its opposite.
+  const down: [number, number] = [Math.sin(t), -Math.cos(t)];
+  return {
+    at: (p, across, d) => [p[0] + across * bar[0] + d * down[0], cropToSpineY(cropToSpineY(p[1], H) + across * bar[1] + d * down[1], H)],
+    of: (p, q) => {
+      const dx = q[0] - p[0];
+      const dy = cropToSpineY(q[1], H) - cropToSpineY(p[1], H);
+      return [dx * bar[0] + dy * bar[1], dx * down[0] + dy * down[1]];
+    },
+  };
+}
+
+/** One stem reading: a feature's point off the eye midpoint, along the bar and down it, as fractions of the inter-eye distance. */
+export interface StemReading {
+  /** The feature's tag (`nose` or `mouth`). */
+  feature: string;
+  /** The part it was read off. */
+  part: string;
+  /** The point read: the centroid of the part's biggest 8-connected blob, as the mouth bone is placed. */
+  at: [number, number];
+  /** Along the bar, positive toward image right. */
+  side: number;
+  /** Down the face (the bar's perpendicular, toward the chin), positive down. */
+  down: number;
+  /** The stem's skew off the bar's perpendicular, degrees, positive toward image right: `atan2(side, down)`. */
+  skew: number;
+}
+
+/** Two extents along the bar: a pair of widths, or the face's two halves about the eye midpoint. */
+export interface BarPair {
+  /** The parts read. */
+  parts: string[];
+  /** The image-left one, px along the bar. */
+  left: number;
+  /** The image-right one, px along the bar. */
+  right: number;
+  /** `left / right`: above 1 when the image-right side is the narrower. */
+  ratio: number;
+}
+
+/** The head's frame (issue #250). */
+export interface HeadFrame {
+  /** The eye bones' origins the bar runs through, image-left first. */
+  eyes: [Point, Point];
+  /** The eye midpoint, crop px. */
+  mid: [number, number];
+  /** The inter-eye distance, px: the bar's length and the unit of every stem fraction. */
+  bar: number;
+  /** The bar's angle in Spine degrees ({@link eyeLineDegrees}). */
+  roll: number;
+  /** The stem via the nose, or why it is not read. */
+  nose: StemReading | { missing: string };
+  /** The stem via the mouth, or why it is not read. */
+  mouth: StemReading | { missing: string };
+  /** The two eyewhites' widths along the bar, or why they are not read. */
+  eyeWidths: BarPair | { missing: string };
+  /** The face part's two halves along the bar about the eye midpoint, or why they are not read. */
+  faceHalves: BarPair | { missing: string };
+  /** Where the nose sits along eye midpoint -> mouth: the nose's `down` over the mouth's; null without both. */
+  noseAlongStem: number | null;
+}
+
+/** A feature handed to {@link headFrame}: its part's name and its point, or why there is none. */
+export type FrameFeature = { part: string; at: [number, number] } | { missing: string };
+
+/** A part's mask handed to {@link headFrame}: its name and its full-canvas mask, or why there is none. */
+export type FrameMask = { part: string; mask: Mask } | { missing: string };
+
+/** The extent of a mask's pixel centres projected on the unit direction `u` from `o`: [min, max], or null for an empty mask. */
+function extentAlong(m: Mask, o: readonly [number, number], u: readonly [number, number]): [number, number] | null {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let y = 0; y < m.height; y++) {
+    for (let x = 0; x < m.width; x++) {
+      if (m.data[y * m.width + x] === 0) continue;
+      const s = (x + 0.5 - o[0]) * u[0] + (y + 0.5 - o[1]) * u[1];
+      if (s < lo) lo = s;
+      if (s > hi) hi = s;
+    }
+  }
+  return lo === Infinity ? null : [lo, hi];
+}
+
+/**
+ * The head's frame on a canvas `H` px tall. `eyes` are the two eye bones'
+ * origins (any order; read image-left first) and must not share a column —
+ * the caller holds that. `eyewhites` are the two eyewhite masks with the eye
+ * each belongs to's origin, so each is paired with its side by its origin.
+ * A pixel's centre is `(x + 0.5, y + 0.5)`, as a box's centre is
+ * `x + w / 2`; a stem point is taken as given.
+ */
+export function headFrame(
+  eyes: [Point, Point],
+  H: number,
+  feats: { nose: FrameFeature; mouth: FrameFeature },
+  eyewhites: Array<{ part: string; mask: Mask; eye: Point }>,
+  face: FrameMask,
+): 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 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]];
+  const mid: [number, number] = [(l[0] + r[0]) / 2, (l[1] + r[1]) / 2];
+  const stem = (feature: string, f: FrameFeature): StemReading | { missing: string } => {
+    if ('missing' in f) return { missing: f.missing };
+    const v = [f.at[0] - mid[0], f.at[1] - mid[1]];
+    const side = (v[0] * u[0] + v[1] * u[1]) / bar;
+    const down = (v[0] * n[0] + v[1] * n[1]) / bar;
+    return { feature, part: f.part, at: f.at, side, down, skew: (Math.atan2(side, down) * 180) / Math.PI };
+  };
+  const nose = stem('nose', feats.nose);
+  const mouth = stem('mouth', feats.mouth);
+  let eyeWidths: BarPair | { missing: string };
+  if (eyewhites.length < 2) eyeWidths = { missing: 'there are not two eyewhite parts' };
+  else {
+    const [wl, wr] = [l, r].map((e) => eyewhites.find((w) => w.eye[0] === e[0] && w.eye[1] === e[1]));
+    const el = wl === undefined ? null : extentAlong(wl.mask, mid, u);
+    const er = wr === undefined ? null : extentAlong(wr.mask, mid, u);
+    if (wl === undefined || wr === undefined || el === null || er === null) eyeWidths = { missing: 'an eyewhite part has no opaque pixel' };
+    else {
+      const left = el[1] - el[0];
+      const right = er[1] - er[0];
+      eyeWidths = right > 0 ? { parts: [wl.part, wr.part], left, right, ratio: left / right } : { missing: `${wr.part} is one pixel column wide along the bar` };
+    }
+  }
+  let faceHalves: BarPair | { missing: string };
+  if ('missing' in face) faceHalves = { missing: face.missing };
+  else {
+    const e = extentAlong(face.mask, mid, u);
+    if (e === null) faceHalves = { missing: `${face.part} has no opaque pixel` };
+    else if (e[0] >= 0 || e[1] <= 0) faceHalves = { missing: `${face.part} lies on one side of the eye midpoint along the bar` };
+    else faceHalves = { parts: [face.part], left: -e[0], right: e[1], ratio: -e[0] / e[1] };
+  }
+  const noseAlongStem = 'missing' in nose || 'missing' in mouth || mouth.down === 0 ? null : nose.down / mouth.down;
+  return { eyes: [l, r], mid, bar, roll: eyeLineDegrees(l, r, H), nose, mouth, eyeWidths, faceHalves, noseAlongStem };
+}

package/src/motion.ts

@@ -19,7 +19,9 @@
  * single track without `base` oscillates about 0: `base` is the value the
  * sine is centred on, and an absent one is the sine as written.
  *
- * Times are rounded to 6 decimals and values to 4, as the reference wrote them.
+ * Times are rounded to 6 decimals and values to 4, as the reference wrote them,
+ * but for each track's last key, which is the idle's duration as given (issue
+ * #252: 40/12 s is not on the 6-decimal grid).
  *
  * ## Blink
  *
@@ -87,6 +89,18 @@ export const KEYS_PER_PERIOD = 8;
  */
 export const IDLE_FPS = 12;
 
+/**
+ * How far apart two times, in seconds, may be and still name the same moment
+ * (issue #244): one frame at {@link IDLE_FPS} is 1/12 s, and this is 10^-9 s,
+ * eight orders of magnitude below it. A time is written in seconds, and a
+ * whole number of frames is often not exact in binary — 40/12 s is
+ * 3.3333333333333335, while rigc's last frame of it sits at 40 * (1/12) =
+ * 3.333333333333333 — so two times are compared within this, never with `===`.
+ * It is the slack {@link framesInside} has always read a frame against a key
+ * time with.
+ */
+export const TIME_SLACK = 1e-9;
+
 /** The blink's fixed timing, in seconds after `blink.t`. The holds are 1/{@link IDLE_FPS} s rounded up (see the Blink section above). */
 export const BLINK = {
   shut: 0.07,
@@ -153,7 +167,10 @@ export function sineTrack(bone: string, property: string, amp: number, period: n
     raw.push([t, base + amp * Math.sin(arg), amp * w * Math.cos(arg)]);
   }
   const keys: MotionKey[] = raw.map(([t, v, m], i) => {
-    const key: MotionKey = { t: pyRound(t, 6), v: [pyRound(v, 4)] };
+    // The last key sits at the duration as given, not rounded (issue #252): 40/12 s rounds to 3.333333, 3.3e-7 s short
+    // of the loop's end, and the build's lead-in refuses a track that does not end at the duration. Bytes are unchanged
+    // for any duration already on the 6-decimal grid.
+    const key: MotionKey = { t: i === raw.length - 1 ? duration : pyRound(t, 6), v: [pyRound(v, 4)] };
     if (i < raw.length - 1) {
       const [t1, v1, m1] = raw[i + 1];
       const dt = t1 - t;
@@ -232,7 +249,7 @@ export function idleMotion(cfg: CharacterConfig, chains: ReadonlyMap<string, str
  */
 export function framesInside(from: number, to: number, fps: number, count: number): number[] {
   const out: number[] = [];
-  for (let k = 0; k < count; k++) if (k / fps >= from - 1e-9 && k / fps <= to + 1e-9) out.push(k);
+  for (let k = 0; k < count; k++) if (k / fps >= from - TIME_SLACK && k / fps <= to + TIME_SLACK) out.push(k);
   return out;
 }