@rig-c/parts 1.6.0 → 1.8.0

package/src/rig.ts

@@ -27,9 +27,45 @@
  *   numbers the reference wrote. A key the turn would re-aim — a translate
  *   key under a turned parent, a scale or shear key on a turned bone — is
  *   refused (`RIG_KEY_FRAME_UNTURNED`); rotate keys mean what they meant.
- *   A single bone with a `tip` is not turned (its tip is still a segment
- *   end for the weights); giving it a lever would be the same change on
- *   that bone and its children, and is not made here.
+ *   A single bone with a `tip` is turned the same way (issue #239): its
+ *   `rotation` is the direction from its origin to its tip and its `length`
+ *   that distance, the segment its weights are already measured along, so a
+ *   `tip` the config states is never accepted and ignored. A tip on its own
+ *   origin has no direction and is refused (`RIG_TIP_DISTINCT`).
+ * - **The face's axis** (issue #239). The five face bones a blink or an
+ *   expression scales or translates, {@link FACE_BONES}, take the eye line's
+ *   angle as their world rotation, so the blink's `scaley` squashes across
+ *   the eye line and not across the page's horizontal on a tilted head. The
+ *   line exists when parts.json holds the parts tagged `eyewhite-r` and
+ *   `eyewhite-l` (the first of each, a cut's piece not counted — the parts
+ *   `propose` stands `eye_r` and `eye_l` on) and config.bones declares both
+ *   eye bones; it runs through the two eye bones' origins, read from the
+ *   image-left one to the image-right one, so the angle is always the
+ *   measured one, inside (−90°, 90°), which tag is which side does not enter
+ *   it, and it is the line rigc's A51 draws. With one eyewhite or none, an
+ *   eye bone missing, or two eye bones in one column, there is no line:
+ *   {@link FaceAxis} says why and the face bones
+ *   keep the page's axes. A face bone with its own `tip` takes the tip. A
+ *   bone under a face bone that nothing else turns keeps its parent's axis,
+ *   so a key on it means the face's axis too; the face bones' controls carry
+ *   the turn as a link's do. Regions on these bones are turned back as every
+ *   region is, so the setup pose is the same picture; a scale key on a face
+ *   bone, and a translate key on a bone under one, mean the face's axes and
+ *   are not refused. A translate key on a face bone itself still moves it
+ *   along its parent's (the head's) axes — Spine's rule, which turning the
+ *   bone does not change. With a line the rig spec also declares
+ *   `invariants.axes` (rig-c 2.40.0): one entry, {@link FACE_AXIS_NAME},
+ *   through `eye_r` and `eye_l`, holding the turned bones and their controls,
+ *   which rigc's `A51_BONES_LIE_ALONG_THEIR_DECLARED_AXIS` checks. Its
+ *   tolerance is measured on the bones as rigc emits them (see where it is
+ *   written), the float floor; with no line no entry is written. A face bone
+ *   with its own `tip` along the line is held too (issue #258), in a second
+ *   entry, {@link FACE_TIPS_AXIS_NAME}: one whose tip lies within the
+ *   whole-pixel rounding bound ({@link tipRoundingBound}) of the line is
+ *   listed, its tolerance measured the same way, and one further off is its
+ *   own axis, named with its gap in `FaceAxis.tipOff` — never silent. The
+ *   roll the face bones stand on has one derivation, `src/headframe.ts`'s
+ *   `eyeLineDegrees`, which `propose`'s head frame reads too (issue #250).
  * - **Meshes** over the parts named in `meshes`: a square lattice (`src/mesh.ts`)
  *   weighted by distance to the mesh's candidate segments (`src/weights.ts`),
  *   written in rigc's by-name `weights` form. The slot's bone is the first
@@ -84,6 +120,8 @@
 import { type AutoSpec, type BoneEntry, type WeightRule, type CharacterConfig, type ConfigConstraint, CONSTRAINT_FOLLOWS, constraintForRig, type ContourSpec, type Point, type RibsSpec, ROOT_BONE, weightsABone } from './config.ts';
 import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toWorld } from './coords.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
+import { eyeLineDegrees } from './headframe.ts';
+import { f32 } from 'rig-c/compile';
 import type { MeshCounts, MeshQualityReport, MeshReductionInput, MotionAmplitude, ReducedMesh, Termination } from 'rig-c/mesh';
 import { type AmplitudeRow, amplitudeRow, partAmplitude, withAmplitude } from './autoamplitude.ts';
 import { type ResidualRow, residualRow, slotEnvelope, withSkinning } from './autoenvelope.ts';
@@ -112,7 +150,8 @@ import { type ContourChainRibs, type ContourReport, contourMesh, type ContourReg
 import { type LocalInfluence, localInfluences } from './localweights.ts';
 import { artCoverage, ART_ALPHA, latticeMesh, ONE_LOOP_PASSES } from './mesh.ts';
 import { BLINK, blinkHoldMisses, blinkSpan, CONTROL_SUFFIX, controlledBones, IDLE_FPS, idleMotion, type MotionSpec, moveKeysToControls } from './motion.ts';
-import { PAINTING_RUN, type PartsFile, readFrom } from './parts.ts';
+import { PAINTING_RUN, type PartsFile, readFrom, tagOf } from './parts.ts';
+import { EYE_GROUP_TAGS } from './propose.ts';
 import { alphaAbove, crop, pad, type Raster } from './raster/index.ts';
 import { pyRound } from './round.ts';
 import { boneHeat, heatInfluences, heatRow, type HeatRow, latticeSilhouette, tracedSilhouette } from './heat.ts';
@@ -151,6 +190,117 @@ function places(v: number): number {
   return placed(v, OFFSET_PLACES);
 }
 
+/**
+ * The face bones that take the face's axis (issue #239): the bones `propose`
+ * writes for the eyes, the brows and the mouth, which the blink and an
+ * expression scale or translate. Read by name, as the blink's groups name
+ * them; a config without one of them has nothing of that name to turn.
+ */
+export const FACE_BONES: readonly string[] = ['eye_r', 'eye_l', 'brow_r', 'brow_l', 'mouth'];
+
+/** The eye line the face bones are turned to, or why there is none (issue #239). */
+export interface FaceAxis {
+  /** The eye line's angle in Spine degrees (counter-clockwise, y up), as written; null with no line. */
+  degrees: number | null;
+  /** The eyewhite parts that make the line exist, `eyewhite-r`'s first; fewer than two when they are what is missing. */
+  parts: string[];
+  /** The face bones turned to the line, in {@link FACE_BONES} order; empty with no line. */
+  turned: string[];
+  /** The face bones a `tip` of their own turns instead, in {@link FACE_BONES} order. */
+  ownTip: string[];
+  /** Why there is no line, or null. */
+  none: string | null;
+  /** The `invariants.axes` entry written for the line (issue #239, rig-c's `A51`), or null with the reason in {@link FaceAxis.noAxis}. */
+  axis: RigAxis | null;
+  /** Why no axes entry was written, or null when one was (or there is no line, which {@link FaceAxis.none} says). */
+  noAxis: string | null;
+  /** The `invariants.axes` entry holding the face bones whose own tip lies along the line within whole-pixel rounding (issue #258), or null when none does. */
+  tipAxis: RigAxis | null;
+  /** For each face bone whose own tip points further off the line than whole-pixel rounding allows, why it is not held (issue #258); in {@link FACE_BONES} order. */
+  tipOff: string[];
+  /** {@link HEAD_UP_BONE} as written (issue #250): its world rotation (the eye line + 90) and its length; null with the reason in {@link FaceAxis.headUpNone}, or with no line. */
+  headUp: { rotation: number; length: number } | null;
+  /** Why {@link HEAD_UP_BONE} was not written, when there is a line; null otherwise. */
+  headUpNone: string | null;
+}
+
+/** One `invariants.axes` entry: rig-c's `RigAxis`, held by its gate rule `A51_BONES_LIE_ALONG_THEIR_DECLARED_AXIS` (2.40.0). */
+export interface RigAxis {
+  name: string;
+  through: [string, string];
+  bones: string[];
+  tolerance: number;
+}
+
+/** The name of the face's `invariants.axes` entry. */
+export const FACE_AXIS_NAME = 'face';
+
+/**
+ * The slotless bone the rig stage adds under `head` (issue #250): at head's origin, pointing along the face's up axis
+ * (the eye line + 90 degrees), as long as the eye midpoint lies from head's origin along it. `head` keeps its own frame,
+ * so no key on it or under it changes meaning; a rule that needs the head's frame (issue #249) reads this bone.
+ */
+export const HEAD_UP_BONE = 'head_up';
+
+/** The name of the `invariants.axes` entry for the face bones whose own tip lies along the eye line (issue #258). */
+export const FACE_TIPS_AXIS_NAME = 'face_tips';
+
+/**
+ * The most a bone's direction can sit off a line through whole-pixel
+ * rounding of its tip alone (issue #258): a tip written in whole pixels is
+ * within half a pixel in each coordinate, sqrt(2)/2 px, of the point on the
+ * line it stands for, so at `length` px from the origin its direction is
+ * within asin((sqrt(2)/2) / length) degrees. Null when the tip is closer than
+ * sqrt(2)/2 px, where rounding alone can point it anywhere.
+ */
+export function tipRoundingBound(length: number): number | null {
+  const s = Math.SQRT1_2 / length;
+  return s >= 1 ? null : (Math.asin(s) * 180) / Math.PI;
+}
+
+/** One unit in the last place a rotation is written to ({@link OFFSET_PLACES}): the axes entry's tolerance stands this far above the gap it measures. */
+const WRITTEN_UNIT = 10 ** -6;
+
+/** Two directions' gap as lines, 0 to 90 degrees — rig-c's `lineGap` (A51), restated here because it is not on an entry this package imports. */
+function lineGap(a: number, b: number): number {
+  const d = (((a - b) % 180) + 180) % 180;
+  return Math.min(d, 180 - d);
+}
+
+/** The bones the face's line runs through: rigc's A51 draws its line through their origins, and the face bones are turned to that same line. */
+export const EYE_BONES: readonly [string, string] = ['eye_r', 'eye_l'];
+
+/**
+ * The eye line (issue #239). It exists when parts.json holds an eye on each
+ * side — the first part tagged `eyewhite-r` and the first tagged `eyewhite-l`
+ * (a cut's piece is neither), the parts `propose` stands `eye_r` and `eye_l`
+ * on — and config.bones declares both eye bones. Its angle is read off the
+ * two eye bones' origins as the config writes them, image-left to
+ * image-right, in Spine's axes through the one y flip: the very line rigc's
+ * A51 draws through those bones, so the face bones stand on what the gate
+ * measures (the eyewhites' unrounded centres would sit up to a rounding off
+ * it — demo's half pixel was 0.47 degrees), and a moved eye bone moves the
+ * line with it. Null with the reason when an eyewhite or an eye bone is
+ * missing, or when the two eye bones share a column, so the line has no
+ * left-to-right direction to read.
+ */
+export function eyeLine(parts: PartsFile, eyeBones: ReadonlyMap<string, Point>): { degrees: number; parts: [string, string] } | { degrees: null; parts: string[]; none: string } {
+  const H = parts.rig_size[1];
+  const found = EYE_GROUP_TAGS.map((tag) => ({ tag, part: parts.parts.find((p) => tagOf(p.from) === tag && p.cut_from === undefined) }));
+  const have = found.flatMap((f) => (f.part === undefined ? [] : [f.part]));
+  if (have.length < 2) {
+    const missing = found.filter((f) => f.part === undefined).map((f) => f.tag);
+    return { degrees: null, parts: have.map((p) => p.name), none: `parts.json holds no part tagged ${missing.join(' or ')} (a cut's piece is not counted), so there is no eye line` };
+  }
+  const names = have.map((p) => p.name);
+  const absent = EYE_BONES.filter((n) => !eyeBones.has(n));
+  if (absent.length > 0) return { degrees: null, parts: names, none: `config.bones declares no single bone ${absent.join(' or ')}, so there is no pair of eye bones for the eye line to run through` };
+  const [a, b] = EYE_BONES.map((n) => eyeBones.get(n) as Point);
+  if (a[0] === b[0]) return { degrees: null, parts: names, none: `${EYE_BONES[0]} ${pt(a)} and ${EYE_BONES[1]} ${pt(b)} share the column x = ${a[0]}, so the eye line has no left-to-right direction to read` };
+  // The one derivation of the roll (issue #250): propose's head frame reads the same function on the same origins.
+  return { degrees: eyeLineDegrees(a, b, H), parts: [names[0], names[1]] };
+}
+
 /**
  * The weights a contour vertex is written with: a vertex no region reaches is
  * rounded as the lattice rounds (each to 5 places, the last `1 − sum(others)`),
@@ -249,7 +399,7 @@ export interface RigSpec {
    * the idle keys a mesh-driving bone. `detached`: written only when a
    * constraint follows a bone ({@link detachedRules}).
    */
-  invariants?: { idleDrivesMeshes?: { why: string }; detached?: DetachedRule[]; deformMayFold?: Array<{ slot: string; why: string }> };
+  invariants?: { idleDrivesMeshes?: { why: string }; detached?: DetachedRule[]; deformMayFold?: Array<{ slot: string; why: string }>; axes?: RigAxis[] };
 }
 
 /** One `invariants.detached` entry: rig-c's `RigDetachedRule`, checked by its gate rule `A25`. */
@@ -541,6 +691,8 @@ export interface RigOutput {
   loopPasses: Record<string, number>;
   /** Per automatic mesh, in parts.json order: what the rig stage's motion gate compares (`src/automotion.ts`). Nothing written. */
   autoMotion: AutoMotionCase[];
+  /** The eye line the face bones were turned to, or why there is none (issue #239). */
+  faceAxis: FaceAxis;
 }
 
 /**
@@ -614,6 +766,8 @@ export function buildRig(
   const chains = new Map<string, string[]>();
   /** Each chain's points and tip, rig px, as declared (issue #188: the ribs are placed along them). */
   const chainLines = new Map<string, Point[]>();
+  /** The single bones that state a `tip` (issue #239: each is turned towards it). */
+  const singleTips = new Set<string>();
   cfg.bones.forEach((e: BoneEntry, i) => {
     if ('chain' in e) {
       const names: string[] = [];
@@ -641,7 +795,17 @@ export function buildRig(
       chainLines.set(e.chain, polyline);
     } else {
       B.set(e.name, { name: e.name, parent: e.parent, x: e.at[0], y: e.at[1] });
-      if (e.tip !== undefined) tips.set(e.name, [e.tip[0], e.tip[1]]);
+      if (e.tip !== undefined) {
+        if (same(e.at, e.tip)) {
+          fail(
+            'RIG_TIP_DISTINCT',
+            `config.bones[${i}] "${e.name}".tip`,
+            `is ${pt(e.tip)}, the bone's own origin; a bone is turned from its origin towards its tip (issue #239), and a tip on the origin has no direction — give a tip other than ${pt(e.at)}, or leave the tip out`,
+          );
+        }
+        tips.set(e.name, [e.tip[0], e.tip[1]]);
+        singleTips.add(e.name);
+      }
     }
   });
 
@@ -781,6 +945,8 @@ export function buildRig(
       fail('RIG_CONTROL_NAME_FREE', `bone "${k}"`, `is keyed by the idle and weighted to by a mesh, so it needs the control bone "${ctl}", and config.bones already declares a bone of that name`);
     }
   }
+  // The face's up-axis bone is the rig stage's (issue #250): a config bone of that name would be shadowed.
+  if (B.has(HEAD_UP_BONE)) fail('RIG_HEAD_UP_NAME_FREE', `bone "${HEAD_UP_BONE}"`, `is the bone the rig stage adds under head to carry the face's up axis (issue #250), and config.bones already declares a bone of that name; rename it`);
   // A two-bone ik over a link and its child link stops being one when the
   // child gets a control: `<child>_ctl` stands between them. rig-c 2.15.0
   // refuses that pair by name (issue #103); the rig stage adds the flag to
@@ -824,6 +990,42 @@ export function buildRig(
       if (controls.includes(l)) aim.set(`${l}${CONTROL_SUFFIX}`, a);
     }
   }
+  // A single bone with a tip points at it the same way, and its control with it (issue #239).
+  for (const n of singleTips) {
+    const b = B.get(n) as Bone;
+    const end = tips.get(n) as Point;
+    const dx = spineX(end[0]) - spineX(b.x);
+    const dy = spineY(end[1]) - spineY(b.y);
+    const a = { rotation: (Math.atan2(dy, dx) * 180) / Math.PI, length: pyRound(Math.sqrt(dx * dx + dy * dy), 3) };
+    aim.set(n, a);
+    if (controls.includes(n)) aim.set(`${n}${CONTROL_SUFFIX}`, a);
+  }
+  // ---- the face's axis (issue #239) --------------------------------------
+  // Each face bone config.bones declares as a single bone with no tip of its own stands on the eye line, and its
+  // control with it; a bone under a face-framed bone that nothing else turns keeps that frame.
+  const eyeAt = new Map<string, Point>();
+  for (const e of cfg.bones) if (!('chain' in e) && (EYE_BONES as readonly string[]).includes(e.name)) eyeAt.set(e.name, [e.at[0], e.at[1]]);
+  const line = eyeLine(parts, eyeAt);
+  const declared = FACE_BONES.filter((n) => cfg.bones.some((e) => !('chain' in e) && e.name === n));
+  const faceAxis: FaceAxis = {
+    degrees: line.degrees,
+    parts: line.parts,
+    turned: line.degrees === null ? [] : declared.filter((n) => !singleTips.has(n)),
+    ownTip: declared.filter((n) => singleTips.has(n)),
+    none: line.degrees === null ? line.none : null,
+    axis: null,
+    noAxis: null,
+    tipAxis: null,
+    tipOff: [],
+    headUp: null,
+    headUpNone: null,
+  };
+  const faceTurn = new Map<string, number>();
+  for (const n of faceAxis.turned) {
+    faceTurn.set(n, line.degrees as number);
+    if (controls.includes(n)) faceTurn.set(`${n}${CONTROL_SUFFIX}`, line.degrees as number);
+  }
+  const faceRoots = new Set(declared.flatMap((n) => (controls.includes(n) ? [n, `${n}${CONTROL_SUFFIX}`] : [n])));
   // Each bone's local rotation turns it from its parent's world rotation to
   // the one it should have: its chain's direction, or 0 for every other bone,
   // so a named bone under a chain link is turned back upright. `turn` is the
@@ -831,6 +1033,8 @@ export function buildRig(
   // tree. Each local offset is the bone's origin carried into its parent's
   // setup frame as written, through rigc's inverse (`src/coords.ts`).
   const turn = new Map<string, number>();
+  /** The bones whose frame is the face's (issue #239): the face bones, their controls, and what hangs under them unturned. */
+  const faceFramed = new Set<string>();
   const bones: RigBone[] = [];
   for (const b of ordered) {
     if (b.parent === null) {
@@ -840,14 +1044,105 @@ export function buildRig(
     }
     const up = turn.get(b.parent) as number;
     const a = aim.get(b.name);
-    const rotation = places(normaliseDegrees((a?.rotation ?? 0) - up));
+    const inherits = a === undefined && !faceRoots.has(b.name) && faceFramed.has(b.parent);
+    if (faceRoots.has(b.name) || inherits) faceFramed.add(b.name);
+    const target = a?.rotation ?? faceTurn.get(b.name) ?? (inherits ? up : 0);
+    const rotation = places(normaliseDegrees(target - up));
     turn.set(b.name, places(up + rotation));
     const frame = computeExactFrameTransforms(bones).get(b.parent) as BoneTransform;
     const [x, y] = toBoneLocal(frame, spineX(b.x), spineY(b.y));
     bones.push({ name: b.name, parent: b.parent, ...(a === undefined ? {} : { length: a.length }), ...(a !== undefined || rotation !== 0 ? { rotation } : {}), x: places(x), y: places(y) });
   }
+  // ---- the head's up axis (issue #250) ----------------------------------
+  // `head` keeps its frame, so every key on it and under it — the idle, the blink's brow drop, an authored
+  // animation's scale or translate — means what it meant. The face's frame is carried by one slotless bone under it,
+  // {@link HEAD_UP_BONE}, at head's origin, turned to the eye line's angle + 90 (the same line, {@link eyeLine}) and
+  // as long as the eye midpoint lies from head's origin along that axis: derived from the three bones the config
+  // writes, so it moves with them. A rule that needs the head's frame reads it here; nothing binds to it or keys it.
+  const headEntry = cfg.bones.find((e) => !('chain' in e) && e.name === 'head');
+  if (line.degrees !== null && headEntry !== undefined && !('chain' in headEntry)) {
+    const up = line.degrees + 90;
+    const [eR, eL] = EYE_BONES.map((n) => eyeAt.get(n) as Point);
+    const mid: Point = [(eR[0] + eL[0]) / 2, (eR[1] + eL[1]) / 2];
+    const h = B.get('head') as Bone;
+    const ux = Math.cos((up * Math.PI) / 180);
+    const uy = Math.sin((up * Math.PI) / 180);
+    const reach = (spineX(mid[0]) - spineX(h.x)) * ux + (spineY(mid[1]) - spineY(h.y)) * uy;
+    if (reach <= 0) {
+      faceAxis.headUpNone = `the eye midpoint ${pt(mid)} lies ${pyRound(-reach, 3)} px below head's origin ${pt([h.x, h.y])} along the face's up axis, so ${HEAD_UP_BONE} would have no length toward the crown; not written`;
+    } else {
+      const parentTurn = turn.get('head') as number;
+      const rotation = places(normaliseDegrees(up - parentTurn));
+      const length = pyRound(reach, 3);
+      bones.push({ name: HEAD_UP_BONE, parent: 'head', length, rotation, x: 0, y: 0 });
+      faceAxis.headUp = { rotation: places(parentTurn + rotation), length };
+    }
+  } else if (line.degrees !== null) faceAxis.headUpNone = 'config.bones declares no single bone "head" for it to hang from';
+
   const world = computeExactFrameTransforms(bones);
 
+  // ---- the face's axes entry (issue #239, rig-c 2.40.0's A51) -------------
+  // The gate draws its line through the eye bones' setup origins, and the face bones were turned to the line through
+  // the same two origins as the config writes them ({@link eyeLine}); what separates the two is only how the numbers
+  // are stored. So the tolerance is measured, not chosen: the largest gap, as lines, between the line through
+  // eye_r -> eye_l and any listed bone's world x axis, in the setup frames of the bones as rigc emits them (each x, y
+  // and rotation through rig-c's own `f32`, the float32 the skeleton stores — 36.869898 is stored 1.6e-6 degrees off,
+  // more than a 6-place unit), rounded up to the places a rotation is written to, plus one unit of that last place —
+  // the float floor of the emitted rig, to the precision this stage writes. A bone turned further off is A51's.
+  // Issue #258: a face bone with its own tip is the author's statement of its axis (#239) and is not turned here, but
+  // a tip written to lie along the eye line is held too, in an entry of its own ({@link FACE_TIPS_AXIS_NAME}), so the
+  // turned bones' entry keeps its float floor. Which tips are meant to lie along the line is read, not chosen: a tip
+  // written in whole pixels sits at most half a pixel off in each coordinate, sqrt(2)/2 px, from the point of the line
+  // it stands for, so its direction can sit up to asin((sqrt(2)/2) / length) degrees off the line through rounding
+  // alone ({@link tipRoundingBound}); a tip within that bone's own bound is held, its entry's tolerance measured as the
+  // turned bones' is, and a tip further off is an axis of its own, said by name in faceAxis.tipOff, never silent.
+  if (line.degrees !== null && (faceAxis.turned.length > 0 || faceAxis.ownTip.length > 0)) {
+    const through: [string, string] = [EYE_BONES[0], EYE_BONES[1]];
+    const emitted = computeExactFrameTransforms(
+      bones.map((bn) => ({ ...bn, x: f32(bn.x), y: f32(bn.y), ...(bn.rotation === undefined ? {} : { rotation: f32(bn.rotation) }) })),
+    );
+    const [a, b] = through.map((n) => emitted.get(n) as BoneTransform);
+    const gateLine = (Math.atan2(b.worldY - a.worldY, b.worldX - a.worldX) * 180) / Math.PI;
+    const gapOf = (n: string): number => {
+      const t = emitted.get(n) as BoneTransform;
+      return lineGap((Math.atan2(t.c, t.a) * 180) / Math.PI, gateLine);
+    };
+    const entry = (name: string, listed: string[]): { axis: RigAxis | null; gap: number } => {
+      const gap = Math.max(...listed.map(gapOf));
+      const tolerance = pyRound(Math.ceil(gap / WRITTEN_UNIT) * WRITTEN_UNIT + WRITTEN_UNIT, OFFSET_PLACES);
+      return { axis: tolerance >= 90 ? null : { name, through, bones: listed, tolerance }, gap };
+    };
+    if (a.worldX === b.worldX && a.worldY === b.worldY) faceAxis.noAxis = `eye_r and eye_l share the world origin (${a.worldX}, ${a.worldY}), so they draw no line`;
+    else {
+      if (faceAxis.turned.length > 0) {
+        const e = entry(FACE_AXIS_NAME, bones.map((bn) => bn.name).filter((n) => faceTurn.has(n)));
+        if (e.axis === null) faceAxis.noAxis = `the face bones lie ${pyRound(e.gap, 6)} degrees off the line through eye_r and eye_l, and rigc takes a tolerance below 90 only`;
+        else faceAxis.axis = e.axis;
+      }
+      const held: string[] = [];
+      for (const n of faceAxis.ownTip) {
+        const length = (aim.get(n) as { length: number }).length;
+        const bound = tipRoundingBound(length);
+        const gap = gapOf(n);
+        if (bound !== null && gap <= bound) {
+          held.push(n);
+          if (controls.includes(n)) held.push(`${n}${CONTROL_SUFFIX}`);
+        } else {
+          faceAxis.tipOff.push(
+            bound === null
+              ? `${n}'s tip is ${length} px from its origin, under the sqrt(2)/2 px a whole-pixel tip can sit off the line, so no direction it states can be read as the line's; its own axis, not held`
+              : `${n}'s tip points ${pyRound(gap, 6)} degrees off the line through eye_r and eye_l, more than the ${pyRound(bound, 6)} degrees a tip ${length} px from its origin can sit off it through whole-pixel rounding; its own axis, not held`,
+          );
+        }
+      }
+      if (held.length > 0) {
+        // In the rig's bone order, as the turned bones' entry lists them.
+        const e = entry(FACE_TIPS_AXIS_NAME, bones.map((bn) => bn.name).filter((n) => held.includes(n)));
+        faceAxis.tipAxis = e.axis;
+      }
+    }
+  }
+
   // ---- keys a turned frame would change ----------------------------------
   // A rotate key turns a bone about its origin whatever its frame, so the
   // idle's chain sways mean what they meant. A translate key moves a bone
@@ -866,7 +1161,8 @@ export function buildRig(
     const translate = k.prop.startsWith('translate');
     const frameBone = translate ? parent : k.bone;
     const deg = turn.get(frameBone) as number;
-    if (deg === 0) continue;
+    // A key in a face-framed bone's frame means the face's axes: that is the point of the turn (issue #239).
+    if (deg === 0 || faceFramed.has(frameBone)) continue;
     const axis = k.prop.slice(-1);
     fail(
       'RIG_KEY_FRAME_UNTURNED',
@@ -1359,7 +1655,10 @@ export function buildRig(
   // issue #126 item 3: an automatic part whose author set motion.deformMayFold — written only then, so no other rig moves.
   const mayFold = autoMotion.filter((c) => c.motion?.deformMayFold === true).map((c) => ({ slot: c.part, why: DEFORM_MAY_FOLD_WHY }));
   if (mayFold.length > 0) rig.invariants = { ...rig.invariants, deformMayFold: mayFold };
-  return { rig, motion, meshReport, images: outImages, controls, meshKeyed, idleKeys, loopPasses, autoMotion };
+  // issue #239: the face's line, written only when the face bones were turned to one, so no other rig moves.
+  const axes = [faceAxis.axis, faceAxis.tipAxis].flatMap((x) => (x === null ? [] : [x]));
+  if (axes.length > 0) rig.invariants = { ...rig.invariants, axes };
+  return { rig, motion, meshReport, images: outImages, controls, meshKeyed, idleKeys, loopPasses, autoMotion, faceAxis };
 }
 
 /**
@@ -1377,7 +1676,11 @@ export function rigJsonText(value: unknown): string {
  * weight's bind `x, y` and each region's `x, y` is carried out of its frame as
  * written (rigc's `toWorld`, `src/coords.ts`) and back in as a difference from
  * the frame's origin, at the reference's 3 places; `length` and `rotation` are
- * dropped. Everything else is copied.
+ * dropped, and so is `invariants.axes` (issue #239): it holds bones to a
+ * line they lie along only when turned, which the flat form undoes, and the
+ * reference declared none; and so is {@link HEAD_UP_BONE} (issue #250), a
+ * slotless bone that carries only a direction, which the reference never
+ * wrote. Everything else is copied.
  *
  * It exists so the reference's outputs stay an oracle: the chain suite and
  * `scripts/rig_oracle.ts` compare `flattenRig(built)` with the reference's
@@ -1403,7 +1706,8 @@ export function flattenRig(rig: RigSpec, sense: 1 | -1 = 1): RigSpec {
     const [wx, wy] = toWorld(m, x, y);
     return [placed(wx - m.worldX, FLAT_PLACES), placed(wy - m.worldY, FLAT_PLACES)];
   };
-  const bones: RigBone[] = rig.bones.map((b) => {
+  // The head's up-axis bone (issue #250) carries only a direction, which the flat form undoes; the reference wrote none.
+  const bones: RigBone[] = rig.bones.filter((b) => b.name !== HEAD_UP_BONE).map((b) => {
     if (b.parent === undefined) return { name: b.name, x: b.x, y: b.y };
     const [x, y] = out(origin(b.parent), b.x, b.y);
     return { name: b.name, parent: b.parent, x, y };
@@ -1436,5 +1740,11 @@ export function flattenRig(rig: RigSpec, sense: 1 | -1 = 1): RigSpec {
     skin[slot] = flat;
   }
   refuseIfAny(problems);
-  return { ...rig, bones, skins: { default: skin } };
+  const flat: RigSpec = { ...rig, bones, skins: { default: skin } };
+  if (rig.invariants?.axes !== undefined) {
+    const { axes: _axes, ...rest } = rig.invariants;
+    if (Object.keys(rest).length > 0) flat.invariants = rest;
+    else delete flat.invariants;
+  }
+  return flat;
 }

package/src/scene.ts

@@ -17,6 +17,7 @@
  *
  * - **Names, totally.** Every bone, slot, attachment (skin entry), constraint
  *   (its name and every bone or slot it names), `invariants.detached` bone,
+ *   `invariants.axes` entry (its name, its `through` and its `bones`; issue #239),
  *   track, group and easing of character `<id>` is renamed `<id>:<name>`
  *   ({@link prefixed}); `root` is the one shared root. A name resolves to
  *   exactly one character, and nothing resolves across characters without its
@@ -382,7 +383,7 @@ const BONE_KEYS = ['name', 'parent', 'length', 'rotation', 'x', 'y'];
 const SLOT_KEYS = ['name', 'bone', 'attachment'];
 const ATTACHMENT_KEYS = ['type', 'image', 'width', 'height', 'uvs', 'triangles', 'hull', 'weights', 'x', 'y', 'rotation'];
 const RIG_KEYS = ['spec', 'name', 'images', 'skeleton', 'bones', 'slots', 'skins', 'constraints', 'invariants'];
-const INVARIANT_KEYS = ['idleDrivesMeshes', 'detached'];
+const INVARIANT_KEYS = ['idleDrivesMeshes', 'detached', 'axes'];
 const MOTION_KEYS = ['spec', 'archetype', 'cut', 'easings', 'groups', 'animations'];
 const IDLE_KEYS = ['duration', 'loop', 'note', 'tracks'];
 const TRACK_KEYS = ['bone', 'group', 'property', 'keys'];
@@ -965,6 +966,10 @@ export function composeScene(
       ownBone(b.id, d.bone, `character "${b.id}" rig.json invariants.detached[${k}].bone`);
       ownBone(b.id, d.notUnder, `character "${b.id}" rig.json invariants.detached[${k}].notUnder`);
     }
+    for (const [k, ax] of (b.rig.invariants?.axes ?? []).entries()) {
+      ax.through.forEach((n, j) => ownBone(b.id, n, `character "${b.id}" rig.json invariants.axes[${k}].through[${j}]`));
+      ax.bones.forEach((n, j) => ownBone(b.id, n, `character "${b.id}" rig.json invariants.axes[${k}].bones[${j}]`));
+    }
   }
   // The root is shared: a character that drives it would move every character.
   for (const b of ready) {
@@ -1030,6 +1035,7 @@ export function composeScene(
   }
   const constraints: Array<Record<string, unknown>> = [];
   const detached: NonNullable<NonNullable<RigSpec['invariants']>['detached']> = [];
+  const axes: NonNullable<NonNullable<RigSpec['invariants']>['axes']> = [];
   scene.characters.forEach((c) => {
     const b = byId.get(c.id) as CharacterBuild;
     const id = c.id;
@@ -1090,6 +1096,8 @@ export function composeScene(
       constraints.push(out);
     }
     for (const d of b.rig.invariants?.detached ?? []) detached.push({ ...d, bone: P(id, d.bone), notUnder: P(id, d.notUnder) });
+    // An axis entry's name is unique within one rig, and two characters each carry a "face": the name is prefixed too.
+    for (const ax of b.rig.invariants?.axes ?? []) axes.push({ name: prefixed(id, ax.name), through: [P(id, ax.through[0]), P(id, ax.through[1])], bones: ax.bones.map((n) => P(id, n)), tolerance: ax.tolerance });
   });
   const slots: RigSpec['slots'] = [];
   if (scene.plate !== null && plate !== null) slots.push({ name: PLATE, bone: PLATE, attachment: PLATE });
@@ -1101,6 +1109,7 @@ export function composeScene(
   const invariants: NonNullable<RigSpec['invariants']> = {};
   if (whys.length === 1) invariants.idleDrivesMeshes = { why: whys[0] };
   if (detached.length > 0) invariants.detached = detached;
+  if (axes.length > 0) invariants.axes = axes;
   if (Object.keys(invariants).length > 0) rig.invariants = invariants;
 
   // ---- the motion ---------------------------------------------------------------
@@ -1246,6 +1255,10 @@ export function unprefixedNames(rig: RigSpec, motion: MotionSpec, ids: readonly
     name('invariants.detached bone', d.bone, false);
     name('invariants.detached notUnder', d.notUnder, false);
   }
+  for (const ax of rig.invariants?.axes ?? []) {
+    name('invariants.axes name', ax.name, false);
+    for (const n of [...ax.through, ...ax.bones]) name(`invariants.axes ${ax.name} bone`, n, false);
+  }
   for (const [k, v] of Object.entries(motion.easings)) name('easing', k, false);
   for (const [g, members] of Object.entries(motion.groups)) {
     name('group', g, false);