@rig-c/pose 0.4.0 → 0.6.0

package/README.md

@@ -48,7 +48,7 @@ and what the run cannot decide for you it lists:
 - `SWITCH` — with `alternates` in the map ([below](#alternate-drawings-alternates)): each span on which a set of alternate drawings shows, its slots, its frames, how far the pose was from the set's key skeleton, and how far each bone with a `drawn` angle was turned from it.
 - `UNCOVERED` — with `alternates` in the map: every fold on a frame where no switch took the folding mesh off screen. This is the list of poses still to paint.
 - `RANGE` — a chain's `range` ([below](#a-joints-range-range)): a bone whose rotate key the pose asks past its range, outside every span of a set depicting its chain, is clamped at the limit; one line per run, with the frames, the seconds and the largest overflow. The demand for an alternate.
-- `ART-RANGE` — inside a set's span: a bone with both a `drawn` angle in the set and a `range`, turned from its drawn angle past that range. Not clamped; the demand for another drawing of that set.
+- `ART-RANGE` — inside a set's span: a bone with a `drawn` angle in the set, turned from it past its limits — the set's `turn` for that bone (held at the limit) or, without one, its chain's `range` (the bone follows the pose). Listed as the pose asked it either way: the demand for another drawing of that set.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
 `--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance` and `switchMin` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, and the demand lists:
@@ -58,7 +58,7 @@ and what the run cannot decide for you it lists:
 - `endOn` — above, under the short hold.
 - `turns: [{ line, joints, frames, seconds, minFraction, reversed }]` — `line` is `hip`, `shoulder` or `eye`.
 - `range: [{ chain, bone, frames, seconds, maxOverflow, key, limits }]` — `key` is the rotate key the pose asked for on the frame of the largest overflow, before the clamp.
-- `artRange: [{ set, chain, bone, frames, seconds, maxOverflow, turn, limits }]` — `turn` is the signed art turn on that frame.
+- `artRange: [{ set, chain, bone, frames, seconds, maxOverflow, turn, limits, clamped }]` — `turn` is the signed art turn the pose asked on that frame; `clamped` says whether the set's `turn` held the bone there.
 
 Runs in `turns`, `range` and `artRange` merge across a gap of one frame, as `endOn` does; `seconds` runs from the first frame's key time to the end of the last frame.
 
@@ -171,6 +171,10 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 
 **TURN.** The cutoff was measured on the three lines across the body before it was fixed ([#6](https://github.com/rig-c/pose/issues/6)): on the 13 s front-facing dance their picture length never drops under 0.81 of its median and none reverses; on a second sequence the hip line falls to 0.17 at frames 465–491 (side-on) and the eye line to 0.22 at 26–58 (head in profile), and 3 frames reverse. 0.5 lies between. A line is reversed when it points more than 90° from the subject's right joint to the left (front-facing, it points at 0°). The lines are read after holds and smoothing, held and smoothed as the map's points are even where the map does not use them; a line whose points are good on no frame is named as not measured.
 
+
+**A stopgap window: `frames`.** A set may state `"frames": [[first, last], …]`: it shows only inside those windows, and on them it is chosen over any set within tolerance that has no window. It is for two sets whose key skeletons the angles cannot tell apart. Measured on HQ's dancer, the hands clasped behind the back and the hands low in front differ by only 2–21°, and the wrist and hand-point scores do not separate them either; the cue that might is #33's depth state. It is recorded in the map as a stopgap, not a selection rule.
+
+**How far a set's art may turn: `turn`.** A drawing reads right only near the angle it was painted at. A set may state, per bone with a `drawn` angle, how far its art may turn from it, `"turn": { "sleeve_r0": [-20, 20] }`. While the set shows, the bone is held within it: its target becomes drawn + clamp(wrap(target − drawn), min, max), each bone on its own world angle, so a forearm under a held upper arm keeps its own target. The landing check measures against the held angle. The overflow the pose asked for is listed as `ART-RANGE`. A `turn` on a bone the set has no `drawn` angle for is refused (`MAP_ALT_TURN`).
 ## Requirements
 
 [Bun](https://bun.sh) ≥ 1.2 on `PATH` — rig-pose, like rig-c, runs its TypeScript sources directly. `rig-c` comes as a dependency. With `@esotericsoftware/spine-core` installed beside it, rig-c's gate runs the spine-core round trip; without it, rig-c's own gate, and the gate's report says which.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/map.ts

@@ -91,6 +91,10 @@ export interface AlternateSet {
   drawn: Record<string, number>;
   /** Bone → a translate, in its parent's axes, held while the set shows. */
   offsets: Record<string, [number, number]>;
+  /** Bone → how far its art may turn from `drawn` while the set shows, [min, max] degrees: the bone is clamped there, and the overflow is ART-RANGE demand. */
+  turn: Record<string, [number, number]>;
+  /** A stopgap: the only frames the set may show on, a list of [first, last] windows; on them it is chosen over any set without windows. Null: any frame. */
+  frames: Array<[number, number]> | null;
 }
 export interface JointMap {
   chains: Chain[];
@@ -224,7 +228,7 @@ export function readMap(text: string, where: string): JointMap {
   return { chains, translate, alternates };
 }
 
-const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] } }';
+const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …] }';
 
 /** `alternates`: each set's shape, its chains against the map's, its key skeleton against those chains' joints, and its bones against those chains' bones. */
 function readAlternates(p: Problems, where: string, raw: unknown, chains: readonly Chain[], translate: Translate | null): AlternateSet[] {
@@ -241,7 +245,7 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
       p.add('MAP_ALT_SHAPE', `${aw} is ${typeName(a)}; a set is ${SET_SHAPE}`);
       return;
     }
-    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets']);
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames']);
     const name = typeof a.name === 'string' && a.name !== '' ? a.name : null;
     if (name === null) p.add('MAP_ALT_NAME', `${aw} "name" is ${typeName(a.name)}; it must be a non-empty string`);
     else if (names.has(name)) p.add('MAP_ALT_NAME', `${aw} "name" "${name}" names two sets`);
@@ -331,7 +335,26 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
         }
       }
     }
-    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets });
+    const turn: Record<string, [number, number]> = {};
+    if ('turn' in a) {
+      if (!isObject(a.turn)) p.add('MAP_ALT_TURN', `${label} "turn" is ${typeName(a.turn)}; it is { "<bone>": [min, max] }, how far each bone's art may turn from its drawn angle, degrees`);
+      else {
+        for (const [b, v] of Object.entries(a.turn)) {
+          if (!(b in drawn)) p.add('MAP_ALT_TURN', `${label} "turn" names bone "${b}", which has no "drawn" angle in the set; a turn is measured from the drawn angle (the set draws ${Object.keys(drawn).join(', ') || 'none'})`);
+          else if (!Array.isArray(v) || v.length !== 2 || !v.every((x) => typeof x === 'number' && Number.isFinite(x)) || (v[0] as number) > (v[1] as number)) p.add('MAP_ALT_TURN', `${label} "turn" bone "${b}" is ${JSON.stringify(v)}; it must be [min, max], two finite numbers of degrees with min ≤ max`);
+          else turn[b] = [v[0] as number, v[1] as number];
+        }
+      }
+    }
+    let frames: Array<[number, number]> | null = null;
+    if ('frames' in a) {
+      const f = a.frames;
+      const pair = (w: unknown): w is [number, number] => Array.isArray(w) && w.length === 2 && w.every((x) => Number.isInteger(x) && (x as number) >= 0) && (w[0] as number) <= (w[1] as number);
+      if (!Array.isArray(f) || f.length === 0 || !f.every(pair)) {
+        p.add('MAP_ALT_FRAMES', `${label} "frames" is ${JSON.stringify(f)}; it must be a non-empty list of windows [[first, last], …], whole frame numbers ≥ 0 with first ≤ last`);
+      } else frames = (f as Array<[number, number]>).map((w) => [w[0], w[1]]);
+    }
+    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames });
   });
   return out;
 }

package/src/retarget.ts

@@ -67,7 +67,7 @@ import { aimAngle, rigPoint } from './map.ts';
 import type { Joint } from './pose.ts';
 import { Problems } from './problems.ts';
 import type { ArtRange, SlotTrack, Switch, SwitchOptions } from './switch.ts';
-import { coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
+import { clampArt, coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -682,6 +682,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
   const artRange = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
+  clampArt(sw.switches, map, targets);
 
   // Keys: the bone's turn less the turn of the nearest mapped bone above it.
   const tracks: Array<MotionTrack | SlotTrack> = [];

package/src/switch.ts

@@ -90,6 +90,8 @@ export interface ArtRange {
   turn: number;
   /** The bone's range, degrees. */
   limits: [number, number];
+  /** Whether the bone was held at the limit (the set's `turn`) or followed the pose (its chain's `range` only). */
+  clamped: boolean;
 }
 
 export interface Uncovered {
@@ -184,13 +186,20 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
   for (const group of competing(map.alternates)) {
     const pick: Array<AlternateSet | null> = [];
     for (let i = 0; i < n; i++) {
+      // A set with a `frames` window shows only inside it, and there it is chosen
+      // over any set without one (a stopgap for what the angles cannot tell apart).
       let best: AlternateSet | null = null;
       let bestD = Infinity;
+      let bestWindowed = false;
       for (const a of group) {
+        if (a.frames !== null && !a.frames.some(([f, l]) => i >= f && i <= l)) continue;
         const d = distances.get(a.name)![i]!;
-        if (d <= opts.switchTolerance && d < bestD) {
+        if (d > opts.switchTolerance) continue;
+        const windowed = a.frames !== null;
+        if ((windowed && !bestWindowed) || (windowed === bestWindowed && d < bestD)) {
           best = a;
           bestD = d;
+          bestWindowed = windowed;
         }
       }
       pick.push(best);
@@ -321,9 +330,11 @@ export const overflow = (v: number, [min, max]: readonly [number, number]): numb
 
 /**
  * The art turn of each switch, in place (`artTurn`), and the art-range demand:
- * inside a span, per bone with both a `drawn` angle in the set and a `range` on
- * its chain, every frame whose signed art turn wrap(target − drawn) falls
- * outside that range, in runs merged across a gap of `gap` frames.
+ * inside a span, per bone with a `drawn` angle in the set and limits — the
+ * set's `turn` for it, else its chain's `range` — every frame whose signed art
+ * turn wrap(target − drawn) falls outside them, in runs merged across a gap of
+ * `gap` frames. Measured on the targets as the pose asks them, before
+ * `clampArt` holds the set's `turn` limits.
  */
 export function measureArt(switches: Switch[], map: JointMap, targets: ReadonlyMap<string, readonly number[]>, endOf: (i: number) => number, times: readonly number[], gap: number): ArtRange[] {
   const out: ArtRange[] = [];
@@ -336,7 +347,7 @@ export function measureArt(switches: Switch[], map: JointMap, targets: ReadonlyM
       const abs = turns.map(Math.abs);
       sw.artTurn[bone] = { max: r3(Math.max(...abs)), median: r3(median(abs)) };
       const chain = map.chains.find((c) => c.bones.includes(bone))!;
-      const limits = chain.range[bone];
+      const limits = set.turn[bone] ?? chain.range[bone];
       if (limits === undefined) continue;
       const flag = turns.map((t) => overflow(t, limits) > RANGE_SLACK);
       for (const [a, b] of runsOf(flag, gap)) {
@@ -344,7 +355,7 @@ export function measureArt(switches: Switch[], map: JointMap, targets: ReadonlyM
         for (let k = a; k <= b; k++) if (overflow(turns[k]!, limits) > overflow(turns[worst]!, limits)) worst = k;
         const first = sw.frames[0] + a;
         const last = sw.frames[0] + b;
-        out.push({ set: sw.set, chain: chain.name, bone, frames: [first, last], seconds: r6(endOf(last) - times[first]!), maxOverflow: r3(overflow(turns[worst]!, limits)), turn: r3(turns[worst]!), limits });
+        out.push({ set: sw.set, chain: chain.name, bone, frames: [first, last], seconds: r6(endOf(last) - times[first]!), maxOverflow: r3(overflow(turns[worst]!, limits)), turn: r3(turns[worst]!), limits, clamped: bone in set.turn });
       }
     }
   }
@@ -426,5 +437,26 @@ export function switchLine(s: Switch, times: readonly number[]): string {
 }
 
 export function artRangeLine(e: ArtRange, times: readonly number[]): string {
-  return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" turned ${sg(e.turn)} from drawn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s, up to ${deg(e.maxOverflow)} past it — demand for another drawing of the set`;
+  return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" turned ${sg(e.turn)} from drawn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s, up to ${deg(e.maxOverflow)} past it; ${e.clamped ? 'held at the limit' : 'the bone follows the pose'} — demand for another drawing of the set`;
+}
+
+/**
+ * Inside each span, a bone with a `turn` in the set is held within it: its
+ * target world angle is drawn + clamp(wrap(target − drawn), min, max). Each
+ * bone is clamped on its own world angle, and keys are differences of world
+ * angles, so a forearm under a clamped upper arm keeps its own target.
+ */
+export function clampArt(switches: readonly Switch[], map: JointMap, targets: Map<string, number[]>): void {
+  for (const sw of switches) {
+    const set = map.alternates.find((a) => a.name === sw.set)!;
+    for (const [bone, limits] of Object.entries(set.turn)) {
+      const drawn = set.drawn[bone]!;
+      const target = targets.get(bone)!;
+      for (let i = sw.frames[0]; i <= sw.frames[1]; i++) {
+        const t = wrap(target[i]! - drawn);
+        const c = Math.min(Math.max(t, limits[0]), limits[1]);
+        if (Math.abs(c - t) > RANGE_SLACK) target[i] = wrap(drawn + c);
+      }
+    }
+  }
 }