@rig-c/pose 0.0.0-stage → 0.1.1

package/src/map.ts

@@ -0,0 +1,325 @@
+/**
+ * The joint map: `rig-pose-map/1` — which bones of the rig carry which joints.
+ *
+ *   { "spec": "rig-pose-map/1",
+ *     "chains": [
+ *       { "name": "arm_r", "bones": ["sleeve_r0", "sleeve_r1"], "joints": ["r_shoulder", "r_elbow", "r_wrist"] },
+ *       { "name": "trunk", "bones": ["chest"], "joints": ["mid_hip", "neck"], "aim": ["neck"] } ],
+ *     "translate": { "bone": "hip", "joint": "mid_hip",
+ *                    "scale": { "pose": ["mid_hip", "neck"], "rig": ["hip", "neck"] } } }
+ *
+ * A chain's bone k carries the segment from joint k to joint k+1, so a chain
+ * has one joint more than it has bones; each bone after the first must descend
+ * from the one before it. Each joint strictly inside a chain is a hinge, and
+ * `bend` says which way it may bend (see `checkBends`).
+ *
+ * `aim` says which direction of the rig's bone the segment is, one entry per
+ * bone: `"x"` (the default) is the bone's own x axis — right for a chain link
+ * @rig-c/parts turned along its limb; a bone name is the direction from this
+ * bone's origin to that descendant's origin — right for a trunk bone, whose
+ * own axis @rig-c/parts leaves at world 0°; and `"a>b"` is the direction from
+ * point a to point b, each the bone itself or a descendant (`name:tip` is the
+ * end of a bone's x axis) — right for a head, whose eye line
+ * (`"eye_r>eye_l"` against the joints `r_eye`, `l_eye`) turns with it.
+ *
+ * Wherever the map names a point of the rig — an aim's end, a scale's end — it
+ * may also be `"a+b"`, the midpoint of two points (each a bone or `name:tip`):
+ * `"sleeve_r0+sleeve_l0"` is the rig's mid-shoulder.
+ *
+ * `reach: true` on a one-bone chain whose first joint is the translated joint
+ * (a trunk from mid_hip) aims the bone not along the pose's segment but from
+ * where its origin is posed — the hip moved and turned — at the point where the
+ * pose puts the segment's end, relative to the translated joint and scaled: so a
+ * tilted pelvis does not carry the chest off the shoulders' line. Its aim is one
+ * point (a bone, `name:tip` or `a+b`), measured from the bone's own origin.
+ *
+ * `translate` moves one bone by the travel of one point, scaled by the ratio of
+ * a length measured on the rig (between two points: a bone's origin, `name:tip`
+ * the end of a bone's x axis, or `a+b`) to the same length measured in the pose
+ * (its median over the frames where both points are good).
+ */
+import type { RawBone } from 'rig-c/core';
+import { POINT_NAMES } from './joints.ts';
+import { isObject, parseJson, Problems, refuseUnknownKeys, typeName } from './problems.ts';
+
+export const MAP_SPEC = 'rig-pose-map/1';
+export const BENDS = ['rest', 'ccw', 'cw', 'free'] as const;
+export type Bend = (typeof BENDS)[number];
+
+export interface Chain {
+  name: string;
+  bones: string[];
+  joints: string[];
+  aim: string[];
+  bend: Bend;
+  /** Aim from the bone's posed origin at the pose's end point, anchored at the translated bone. */
+  reach: boolean;
+}
+export interface Translate {
+  bone: string;
+  joint: string;
+  scale: { pose: [string, string]; rig: [string, string] };
+}
+export interface JointMap {
+  chains: Chain[];
+  translate: Translate | null;
+}
+
+/** The rig as the map is resolved against it: each bone's setup pose, by rig-c's poser. */
+export interface RestBone extends RawBone {
+  /** The bone's `length` in the compiled model (0 when it has none). */
+  length: number;
+}
+export type Rest = ReadonlyMap<string, RestBone>;
+
+export function readMap(text: string, where: string): JointMap {
+  const doc = parseJson(text, where, 'MAP_JSON');
+  const p = new Problems();
+  if (!isObject(doc)) {
+    p.add('MAP_SHAPE', `${where} is ${typeName(doc)}; a ${MAP_SPEC} document is an object`);
+    p.throwIfAny();
+    throw new Error('unreachable');
+  }
+  refuseUnknownKeys(p, 'MAP_KEYS', where, doc, ['spec', 'note', 'chains', 'translate']);
+  if (doc.spec !== MAP_SPEC) p.add('MAP_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${MAP_SPEC}"`);
+  const chains: Chain[] = [];
+  if (!Array.isArray(doc.chains) || doc.chains.length === 0) {
+    p.add('MAP_CHAINS', `${where} "chains" is ${typeName(doc.chains)}; it must be a non-empty array of chains`);
+  } else {
+    const names = new Set<string>();
+    doc.chains.forEach((c: unknown, i: number) => {
+      const cw = `${where} chains[${i}]`;
+      if (!isObject(c)) {
+        p.add('MAP_CHAIN_SHAPE', `${cw} is ${typeName(c)}; a chain is { name, bones, joints, aim?, bend?, reach? }`);
+        return;
+      }
+      refuseUnknownKeys(p, 'MAP_KEYS', cw, c, ['name', 'bones', 'joints', 'aim', 'bend', 'reach']);
+      const name = typeof c.name === 'string' && c.name !== '' ? c.name : null;
+      if (name === null) p.add('MAP_CHAIN_NAME', `${cw} "name" is ${typeName(c.name)}; it must be a non-empty string`);
+      else if (names.has(name)) p.add('MAP_CHAIN_NAME', `${cw} "name" "${name}" names two chains`);
+      if (name !== null) names.add(name);
+      const label = name === null ? cw : `chain "${name}"`;
+      const bones = strings(c.bones);
+      const joints = strings(c.joints);
+      if (bones === null || bones.length === 0) p.add('MAP_CHAIN_BONES', `${label} "bones" is ${typeName(c.bones)}; it must be a non-empty array of bone names`);
+      if (joints === null || joints.length < 2) p.add('MAP_CHAIN_JOINTS', `${label} "joints" is ${typeName(c.joints)}; it must be an array of at least two joint names`);
+      if (bones !== null && joints !== null && bones.length > 0 && joints.length !== bones.length + 1) {
+        p.add('MAP_CHAIN_JOINTS', `${label} has ${bones.length} bone(s) and ${joints.length} joint(s); bone k carries the segment from joint k to joint k+1, so it needs ${bones.length + 1}`);
+      }
+      for (const j of joints ?? []) {
+        if (!POINT_NAMES.includes(j)) p.add('MAP_JOINT_NAME', `${label} names joint "${j}", which is not a point this package reads; they are ${POINT_NAMES.join(', ')}`);
+      }
+      let aim = bones === null ? [] : bones.map(() => 'x');
+      if ('aim' in c) {
+        const a = strings(c.aim);
+        if (a === null || bones === null || a.length !== bones.length) p.add('MAP_CHAIN_AIM', `${label} "aim" is ${typeName(c.aim)}; it must be one entry per bone ("x", a descendant point, or "a>b")`);
+        else {
+          aim = a;
+          for (const x of a) if (x !== 'x') for (const end of x.split('>')) pointProblem(p, label, end);
+        }
+      }
+      let bend: Bend = 'rest';
+      if ('bend' in c) {
+        if (typeof c.bend !== 'string' || !(BENDS as readonly string[]).includes(c.bend)) p.add('MAP_CHAIN_BEND', `${label} "bend" is ${typeName(c.bend)}; it must be one of ${BENDS.join(', ')}`);
+        else bend = c.bend as Bend;
+      }
+      let reach = false;
+      if ('reach' in c) {
+        if (typeof c.reach !== 'boolean') p.add('MAP_REACH', `${label} "reach" is ${typeName(c.reach)}; it must be true or false`);
+        else reach = c.reach;
+      }
+      chains.push({ name: name ?? cw, bones: bones ?? [], joints: joints ?? [], aim, bend, reach });
+    });
+  }
+  let translate: Translate | null = null;
+  if ('translate' in doc) {
+    const t = doc.translate;
+    const tw = `${where} "translate"`;
+    if (!isObject(t)) {
+      p.add('MAP_TRANSLATE', `${tw} is ${typeName(t)}; it is { bone, joint, scale: { pose: [a, b], rig: [a, b] } }`);
+    } else {
+      refuseUnknownKeys(p, 'MAP_KEYS', tw, t, ['bone', 'joint', 'scale']);
+      if (typeof t.bone !== 'string' || t.bone === '') p.add('MAP_TRANSLATE', `${tw} "bone" is ${typeName(t.bone)}; it must name a bone`);
+      if (typeof t.joint !== 'string' || !POINT_NAMES.includes(t.joint)) p.add('MAP_JOINT_NAME', `${tw} "joint" is ${typeName(t.joint)}; it must be one of ${POINT_NAMES.join(', ')}`);
+      const s = t.scale;
+      const pose = isObject(s) ? strings(s.pose) : null;
+      const rig = isObject(s) ? strings(s.rig) : null;
+      if (isObject(s)) refuseUnknownKeys(p, 'MAP_KEYS', `${tw} "scale"`, s, ['pose', 'rig']);
+      if (pose === null || pose.length !== 2 || rig === null || rig.length !== 2) {
+        p.add('MAP_TRANSLATE_SCALE', `${tw} "scale" is ${JSON.stringify(s)}; it must be { pose: [joint, joint], rig: [bone, bone] }, the same length measured in each`);
+      } else {
+        for (const j of pose) if (!POINT_NAMES.includes(j)) p.add('MAP_JOINT_NAME', `${tw} "scale.pose" names "${j}"; the points are ${POINT_NAMES.join(', ')}`);
+        for (const r of rig) pointProblem(p, `${tw} "scale.rig"`, r);
+        if (typeof t.bone === 'string' && typeof t.joint === 'string') translate = { bone: t.bone, joint: t.joint, scale: { pose: [pose[0]!, pose[1]!], rig: [rig[0]!, rig[1]!] } };
+      }
+    }
+  }
+  for (const c of chains) {
+    if (!c.reach) continue;
+    const label = `chain "${c.name}"`;
+    if (c.bones.length !== 1) p.add('MAP_REACH', `${label} has "reach" and ${c.bones.length} bones; a reach turns one bone from its posed origin, so the chain must have exactly one`);
+    const aim = c.aim[0];
+    if (aim !== undefined && (aim === 'x' || aim.includes('>'))) {
+      p.add('MAP_REACH', `${label} has "reach" and aims ${JSON.stringify(aim)}; a reach aims from the bone's own origin at one point, so "aim" must name it (a bone, name:tip or a+b)`);
+    }
+    if (!('translate' in doc)) p.add('MAP_REACH', `${label} has "reach" and the map has no "translate"; a reach is anchored at the translated bone's posed origin`);
+    else if (translate !== null && c.joints[0] !== translate.joint) {
+      p.add('MAP_REACH', `${label} has "reach" and starts at joint "${c.joints[0]}"; the reach is measured from the translated joint, so its first joint must be "${translate.joint}"`);
+    }
+  }
+  p.throwIfAny();
+  return { chains, translate };
+}
+
+/** A rig point as the map spells it: `name`, `name:tip`, or `a+b`, the midpoint of two such. */
+function pointProblem(p: Problems, label: string, spec: string): void {
+  const parts = spec.split('+');
+  if (parts.length > 2 || parts.some((x) => x === '' || x === ':tip')) {
+    p.add('MAP_POINT', `${label} names the point ${JSON.stringify(spec)}; a point is a bone name, name:tip (the end of its x axis), or a+b (the midpoint of two of those)`);
+  }
+}
+
+/** The points a point spec averages: one (`name`, `name:tip`) or two (`a+b`). */
+export function pointParts(spec: string): string[] {
+  return spec.split('+');
+}
+
+/** The bone a point part is read off (`name:tip` → `name`). */
+export function partBone(part: string): string {
+  return part.endsWith(':tip') ? part.slice(0, -4) : part;
+}
+
+function strings(v: unknown): string[] | null {
+  return Array.isArray(v) && v.every((s) => typeof s === 'string') ? (v as string[]) : null;
+}
+
+/** Whether `bone` descends from `ancestor` (strictly). */
+export function descends(rest: Rest, bone: string, ancestor: string): boolean {
+  for (let b = rest.get(bone)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) if (b === ancestor) return true;
+  return false;
+}
+
+/** The two points a non-`x` aim runs between: `"a>b"`, or the bone's origin to a descendant point. */
+export function aimEnds(bone: string, aim: string): [string, string] {
+  const i = aim.indexOf('>');
+  return i < 0 ? [bone, aim] : [aim.slice(0, i), aim.slice(i + 1)];
+}
+
+/** What an aim reads off a bone: its world x axis column and origin. */
+export interface AimBone {
+  a: number;
+  c: number;
+  worldX: number;
+  worldY: number;
+}
+
+/**
+ * A mapped bone's aim, Spine world degrees, on any pose of the rig: the setup
+ * pose (the rest angle) or a posed frame (where it landed). `lengths` are the
+ * model's bone lengths, for `name:tip`.
+ */
+export function aimAngle(bones: ReadonlyMap<string, AimBone>, lengths: ReadonlyMap<string, number>, bone: string, aim: string): number {
+  const DEG = 180 / Math.PI;
+  if (aim === 'x') {
+    const b = bones.get(bone)!;
+    return Math.atan2(b.c, b.a) * DEG;
+  }
+  const [f, t] = aimEnds(bone, aim).map((e) => pointAt(bones, lengths, e)!) as [[number, number], [number, number]];
+  return Math.atan2(t[1] - f[1], t[0] - f[0]) * DEG;
+}
+
+/**
+ * A rig point on any pose of the rig: a bone's origin, `name:tip` (the end of
+ * its x axis), or `a+b` (their midpoint); null when a bone is not there.
+ */
+export function pointAt(bones: ReadonlyMap<string, AimBone>, lengths: ReadonlyMap<string, number>, spec: string): [number, number] | null {
+  let x = 0;
+  let y = 0;
+  const parts = pointParts(spec);
+  for (const part of parts) {
+    const name = partBone(part);
+    const b = bones.get(name);
+    if (b === undefined) return null;
+    const l = part.endsWith(':tip') ? lengths.get(name) ?? 0 : 0;
+    x += b.worldX + b.a * l;
+    y += b.worldY + b.c * l;
+  }
+  return [x / parts.length, y / parts.length];
+}
+
+/** A rig point at the setup pose: a bone's origin, `name:tip`, or `a+b`. */
+export function rigPoint(rest: Rest, spec: string): [number, number] | null {
+  return pointAt(rest, new Map([...rest].map(([n, b]) => [n, b.length])), spec);
+}
+
+/** Check every name the map gives against the rig; every miss is named. */
+export function resolveMap(map: JointMap, rest: Rest, where: string): void {
+  const p = new Problems();
+  const all = [...rest.keys()];
+  const listed = all.length <= 40 ? all.join(', ') : `${all.slice(0, 40).join(', ')} … (${all.length} in all)`;
+  const owner = new Map<string, string>();
+  for (const c of map.chains) {
+    c.bones.forEach((b, k) => {
+      if (!rest.has(b)) {
+        p.add('MAP_BONE_EXISTS', `chain "${c.name}" — bone "${b}" is not in the rig; its bones are ${listed}`);
+        return;
+      }
+      const prev = owner.get(b);
+      if (prev !== undefined) p.add('MAP_BONE_ONCE', `bone "${b}" is in chain "${prev}" and in chain "${c.name}"; a bone carries one segment`);
+      owner.set(b, c.name);
+      if (k > 0 && rest.has(c.bones[k - 1]!) && !descends(rest, b, c.bones[k - 1]!)) {
+        p.add('MAP_CHAIN_ORDER', `chain "${c.name}" — bone "${b}" does not descend from "${c.bones[k - 1]}"; its parent is "${rest.get(b)!.parent}"`);
+      }
+      const aim = c.aim[k]!;
+      if (aim === 'x') {
+        const o = rest.get(b)!;
+        if (Math.hypot(o.a, o.c) < 1e-9) p.add('MAP_AIM_LENGTH', `chain "${c.name}" — bone "${b}" has a collapsed x axis at setup (scale 0); aim it at a descendant`);
+        return;
+      }
+      const [from, to] = aimEnds(b, aim);
+      const verb = aim.includes('>') ? 'aims through' : 'aims at';
+      let ok = true;
+      for (const end of [from, to]) {
+        for (const part of pointParts(end)) {
+          const name = partBone(part);
+          const which = part === end ? `"${end}"` : `"${part}" (of "${end}")`;
+          if (!rest.has(name)) {
+            p.add('MAP_AIM_EXISTS', `chain "${c.name}" — bone "${b}" ${verb} ${which}, which is not in the rig`);
+            ok = false;
+          } else if (name !== b && !descends(rest, name, b)) {
+            p.add('MAP_AIM_DESCENDS', `chain "${c.name}" — bone "${b}" ${verb} "${name}", which does not descend from it; turning "${b}" would not turn that direction`);
+            ok = false;
+          }
+        }
+      }
+      if (ok) {
+        const pf = rigPoint(rest, from)!;
+        const pt = rigPoint(rest, to)!;
+        if (Math.hypot(pt[0] - pf[0], pt[1] - pf[1]) < 1e-6) p.add('MAP_AIM_LENGTH', `chain "${c.name}" — bone "${b}" aims from "${from}" to "${to}", which are at the same point; the direction is undefined`);
+      }
+    });
+  }
+  const t = map.translate;
+  if (t !== null) {
+    if (!rest.has(t.bone)) p.add('MAP_BONE_EXISTS', `"translate" — bone "${t.bone}" is not in the rig; its bones are ${listed}`);
+    else {
+      for (const b of owner.keys()) {
+        if (descends(rest, t.bone, b)) p.add('MAP_TRANSLATE_PARENT', `"translate" — bone "${t.bone}" descends from "${b}", which chain "${owner.get(b)}" turns; a translated bone's parent frame must not move`);
+      }
+    }
+    for (const r of t.scale.rig) {
+      for (const part of pointParts(r)) if (!rest.has(partBone(part))) p.add('MAP_BONE_EXISTS', `"translate" "scale.rig" — "${r}"${part === r ? '' : ` reads "${partBone(part)}", which`} is not a bone in the rig (a point is a bone name, name:tip, or a+b)`);
+    }
+    const [r0, r1] = t.scale.rig.map((r) => rigPoint(rest, r));
+    if (r0 && r1 && Math.hypot(r1[0] - r0[0], r1[1] - r0[1]) < 1e-6) p.add('MAP_TRANSLATE_SCALE', `"translate" "scale.rig" — "${t.scale.rig[0]}" and "${t.scale.rig[1]}" are at the same point; the length is 0`);
+  }
+  for (const c of map.chains) {
+    const b = c.bones[0];
+    if (!c.reach || t === null || b === undefined || !rest.has(b) || !rest.has(t.bone)) continue;
+    if (b !== t.bone && !descends(rest, b, t.bone)) {
+      p.add('MAP_REACH', `chain "${c.name}" — bone "${b}" reaches from its posed origin, but it does not descend from the translated bone "${t.bone}"; its origin would not travel with the anchor`);
+    }
+  }
+  if (p.any) p.list.unshift({ code: 'MAP_RESOLVES', text: `${where} does not resolve against the rig` });
+  p.throwIfAny();
+}

package/src/pose.ts

@@ -0,0 +1,303 @@
+/**
+ * The pose sequence: `rig-pose-sequence/1`.
+ *
+ * It is @rig-c/parts' `spine-parts-keypoints/1` (one picture's joints) extended
+ * to frames, with the same vocabulary — `space`, `width`/`height`, `source`,
+ * `people[].id`, `people[].joints.<body-18 name>.{state, at, score}` — and one
+ * new level, `frames[]`, each carrying its time `t` in seconds:
+ *
+ *   { "spec": "rig-pose-sequence/1",
+ *     "space": { "units": "picture-px", "origin": "top-left", "y": "down" },
+ *     "width": 1080, "height": 1920,
+ *     "source": "what produced the file",
+ *     "frames": [ { "t": 0, "people": [ { "id": "a", "joints": {
+ *         "neck": { "state": "observed", "at": [540, 400], "score": 0.93 } } } ] } ] }
+ *
+ * Differences from the keypoints file, each a consequence of what a sequence
+ * is: the unit is `picture-px` (a video frame is not a painting), and `at` may
+ * lie outside the picture (a dancer's hand leaves the frame; a pose model
+ * places it anyway, and its score says how much to believe it).
+ */
+import { BODY18, COCO17, COCO17_TO_BODY18, isBody18, type Body18 } from './joints.ts';
+import { isObject, parseJson, Problems, refuseUnknownKeys, typeName } from './problems.ts';
+
+export const POSE_SPEC = 'rig-pose-sequence/1';
+export const POSE_SPACE = { units: 'picture-px', origin: 'top-left', y: 'down' } as const;
+const STATES = ['observed', 'occluded', 'missing'] as const;
+export type JointState = (typeof STATES)[number];
+
+export interface Joint {
+  state: JointState;
+  at?: [number, number];
+  score?: number;
+}
+export interface Person {
+  id: string;
+  joints: Partial<Record<Body18, Joint>>;
+}
+export interface PoseFrame {
+  t: number;
+  people: Person[];
+}
+export interface PoseSequence {
+  spec: typeof POSE_SPEC;
+  space: typeof POSE_SPACE;
+  width: number;
+  height: number;
+  source: string;
+  frames: PoseFrame[];
+}
+
+const TOP_KEYS = ['spec', 'space', 'width', 'height', 'source', 'frames'];
+
+/** Read and check a pose sequence; every problem is collected and thrown once. */
+export function readPoseSequence(text: string, where: string): PoseSequence {
+  const doc = parseJson(text, where, 'POSE_JSON');
+  const p = new Problems();
+  if (!isObject(doc)) {
+    p.add('POSE_SHAPE', `${where} is ${typeName(doc)}; a ${POSE_SPEC} document is an object`);
+    p.throwIfAny();
+    throw new Error('unreachable');
+  }
+  refuseUnknownKeys(p, 'POSE_KEYS', where, doc, TOP_KEYS);
+  for (const k of TOP_KEYS) if (!(k in doc)) p.add('POSE_KEYS', `${where} has no "${k}"; a ${POSE_SPEC} document carries ${TOP_KEYS.join(', ')}`);
+  if ('spec' in doc && doc.spec !== POSE_SPEC) p.add('POSE_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${POSE_SPEC}"`);
+  if ('space' in doc && JSON.stringify(doc.space) !== JSON.stringify(POSE_SPACE)) {
+    p.add('POSE_SPACE', `${where} "space" is ${JSON.stringify(doc.space)}; it must be exactly ${JSON.stringify(POSE_SPACE)}`);
+  }
+  for (const k of ['width', 'height'] as const) {
+    if (k in doc && !(Number.isInteger(doc[k]) && (doc[k] as number) > 0)) p.add('POSE_SIZE', `${where} "${k}" is ${typeName(doc[k])}; it must be a positive integer (picture pixels)`);
+  }
+  if ('source' in doc && (typeof doc.source !== 'string' || doc.source.trim() === '')) p.add('POSE_SOURCE', `${where} "source" is ${typeName(doc.source)}; it must say what produced the file`);
+  const frames: PoseFrame[] = [];
+  if ('frames' in doc) {
+    if (!Array.isArray(doc.frames) || doc.frames.length === 0) {
+      p.add('POSE_FRAMES', `${where} "frames" is ${typeName(doc.frames)}; it must be a non-empty array`);
+    } else {
+      let lastT = -Infinity;
+      doc.frames.forEach((f: unknown, i: number) => {
+        const fw = `${where} frames[${i}]`;
+        if (!isObject(f)) {
+          p.add('POSE_FRAME_SHAPE', `${fw} is ${typeName(f)}; a frame is { t, people }`);
+          return;
+        }
+        refuseUnknownKeys(p, 'POSE_KEYS', fw, f, ['t', 'people']);
+        const t = f.t;
+        if (typeof t !== 'number' || !Number.isFinite(t) || t < 0) {
+          p.add('POSE_TIME', `${fw} "t" is ${typeName(t)}; it must be a finite number of seconds ≥ 0`);
+        } else if (t <= lastT) {
+          p.add('POSE_TIME', `${fw} "t" is ${t}s, not after frame ${i - 1}'s ${lastT}s; times must strictly increase`);
+        }
+        if (typeof t === 'number' && Number.isFinite(t)) lastT = Math.max(lastT, t);
+        const people: Person[] = [];
+        if (!Array.isArray(f.people)) {
+          p.add('POSE_PEOPLE', `${fw} "people" is ${typeName(f.people)}; it must be an array (empty when nobody was found)`);
+        } else {
+          const ids = new Set<string>();
+          f.people.forEach((person: unknown, j: number) => {
+            const pw = `${fw} people[${j}]`;
+            if (!isObject(person)) {
+              p.add('POSE_PERSON_SHAPE', `${pw} is ${typeName(person)}; a person is { id, joints }`);
+              return;
+            }
+            refuseUnknownKeys(p, 'POSE_KEYS', pw, person, ['id', 'joints']);
+            if (typeof person.id !== 'string' || person.id === '') {
+              p.add('POSE_PERSON_ID', `${pw} "id" is ${typeName(person.id)}; it must be a non-empty string`);
+              return;
+            }
+            if (ids.has(person.id)) p.add('POSE_PERSON_ID', `${pw} "id" "${person.id}" appears twice in frame ${i}`);
+            ids.add(person.id);
+            people.push({ id: person.id, joints: readJoints(p, pw, person.joints) });
+          });
+        }
+        frames.push({ t: typeof t === 'number' ? t : NaN, people });
+      });
+    }
+  }
+  p.throwIfAny();
+  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: doc.source as string, frames };
+}
+
+function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Body18, Joint>> {
+  const out: Partial<Record<Body18, Joint>> = {};
+  if (!isObject(joints)) {
+    p.add('POSE_JOINTS', `${pw} "joints" is ${typeName(joints)}; it must be an object keyed by body-18 joint names`);
+    return out;
+  }
+  for (const [name, j] of Object.entries(joints)) {
+    const jw = `${pw} joint "${name}"`;
+    if (!isBody18(name)) {
+      p.add('POSE_JOINT_NAME', `${pw} names joint "${name}", which body-18 does not have; the joints are ${BODY18.join(', ')}`);
+      continue;
+    }
+    if (!isObject(j)) {
+      p.add('POSE_JOINT_SHAPE', `${jw} is ${typeName(j)}; a joint is { state, at?, score? }`);
+      continue;
+    }
+    refuseUnknownKeys(p, 'POSE_KEYS', jw, j, ['state', 'at', 'score']);
+    const state = j.state;
+    if (typeof state !== 'string' || !(STATES as readonly string[]).includes(state)) {
+      p.add('POSE_JOINT_STATE', `${jw} "state" is ${typeName(state)}; it must be one of ${STATES.join(', ')}`);
+      continue;
+    }
+    const joint: Joint = { state: state as JointState };
+    if ('at' in j) {
+      const at = j.at;
+      if (state === 'missing') {
+        p.add('POSE_JOINT_AT', `${jw} is "missing" and carries "at"; a missing joint has no position`);
+      } else if (!Array.isArray(at) || at.length !== 2 || !at.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+        p.add('POSE_JOINT_AT', `${jw} "at" is ${typeName(at)}; it must be [x, y] in picture pixels`);
+      } else {
+        joint.at = [at[0] as number, at[1] as number];
+      }
+    } else if (state === 'observed') {
+      p.add('POSE_JOINT_AT', `${jw} is "observed" and has no "at"; an observed joint has a position`);
+    }
+    if ('score' in j) {
+      if (typeof j.score !== 'number' || !Number.isFinite(j.score)) p.add('POSE_JOINT_SCORE', `${jw} "score" is ${typeName(j.score)}; it must be a finite number`);
+      else joint.score = j.score;
+    }
+    out[name] = joint;
+  }
+  return out;
+}
+
+/**
+ * The one person the retarget follows: `wanted` when given, else the only id
+ * the sequence contains. Frames where that person is absent carry no joints.
+ */
+export function personTrack(seq: PoseSequence, wanted: string | undefined, where: string): Array<Partial<Record<Body18, Joint>>> {
+  const ids = [...new Set(seq.frames.flatMap((f) => f.people.map((q) => q.id)))].sort();
+  const p = new Problems();
+  let id = wanted;
+  if (id === undefined) {
+    if (ids.length === 1) id = ids[0];
+    else if (ids.length === 0) p.add('POSE_PERSON', `${where} has no person on any of its ${seq.frames.length} frames`);
+    else p.add('POSE_PERSON', `${where} holds ${ids.length} people (${ids.join(', ')}); name the one to follow with --person`);
+  } else if (!ids.includes(id)) {
+    p.add('POSE_PERSON', `--person "${id}" is not in ${where}; its people are ${ids.join(', ') || '(none)'}`);
+  }
+  p.throwIfAny();
+  return seq.frames.map((f) => f.people.find((q) => q.id === id)?.joints ?? {});
+}
+
+// --- COCO-17 -------------------------------------------------------------
+
+export const COCO_SPEC = 'coco17-sequence/1';
+
+/**
+ * Convert a COCO-17 sequence to a pose sequence. The input is the common shape
+ * of a pose model's per-frame output:
+ *
+ *   { "format": "coco17-sequence/1", "width": W, "height": H, "source": "…",
+ *     "frames": [ { "t": 0, "keypoints": [[x, y, score] × 17] | [x, y, s × 17 flat] | null } ] }
+ *
+ * in COCO's standard joint order (`COCO17`). A keypoint whose score is 0 is
+ * missing (COCO's `v = 0`); every other keypoint is observed with its score —
+ * the retarget, not the conversion, decides what score is good enough. `neck`
+ * is the shoulders' midpoint (`COCO17_TO_BODY18`). A `null` frame is a frame
+ * with nobody in it. The one person is written with id "a".
+ */
+export function convertCoco17(text: string, where: string): PoseSequence {
+  const doc = parseJson(text, where, 'COCO_JSON');
+  const p = new Problems();
+  if (!isObject(doc)) {
+    p.add('COCO_SHAPE', `${where} is ${typeName(doc)}; a ${COCO_SPEC} document is an object`);
+    p.throwIfAny();
+    throw new Error('unreachable');
+  }
+  refuseUnknownKeys(p, 'COCO_KEYS', where, doc, ['format', 'width', 'height', 'source', 'frames', 'joints', 'fps', 'model']);
+  if (doc.format !== COCO_SPEC) p.add('COCO_SPEC', `${where} "format" is ${typeName(doc.format)}; this reader reads "${COCO_SPEC}"`);
+  if ('joints' in doc && JSON.stringify(doc.joints) !== JSON.stringify(COCO17)) {
+    p.add('COCO_ORDER', `${where} "joints" is ${JSON.stringify(doc.joints)}; this reader reads COCO's standard order ${JSON.stringify(COCO17)}`);
+  }
+  for (const k of ['width', 'height'] as const) {
+    if (!(Number.isInteger(doc[k]) && (doc[k] as number) > 0)) p.add('COCO_SIZE', `${where} "${k}" is ${typeName(doc[k])}; it must be a positive integer (picture pixels)`);
+  }
+  const source = typeof doc.source === 'string' ? doc.source : isObject(doc.source) ? JSON.stringify(doc.source) : '';
+  if (source === '') p.add('COCO_SOURCE', `${where} "source" is ${typeName(doc.source)}; it must say what produced the file`);
+  const frames: PoseFrame[] = [];
+  if (!Array.isArray(doc.frames) || doc.frames.length === 0) {
+    p.add('COCO_FRAMES', `${where} "frames" is ${typeName(doc.frames)}; it must be a non-empty array`);
+  } else {
+    doc.frames.forEach((f: unknown, i: number) => {
+      const fw = `${where} frames[${i}]`;
+      if (!isObject(f)) {
+        p.add('COCO_FRAME_SHAPE', `${fw} is ${typeName(f)}; a frame is { t, keypoints }`);
+        return;
+      }
+      if (typeof f.t !== 'number' || !Number.isFinite(f.t)) {
+        p.add('COCO_TIME', `${fw} "t" is ${typeName(f.t)}; it must be seconds`);
+        return;
+      }
+      if (f.keypoints === null) {
+        frames.push({ t: f.t, people: [] });
+        return;
+      }
+      const triples = cocoTriples(f.keypoints);
+      if (triples === null) {
+        p.add('COCO_KEYPOINTS', `${fw} "keypoints" is ${typeName(f.keypoints)}; it must be 17 [x, y, score] triples, 51 numbers, or null`);
+        return;
+      }
+      const joints: Partial<Record<Body18, Joint>> = {};
+      COCO17.forEach((name, k) => {
+        const [x, y, s] = triples[k] as [number, number, number];
+        joints[COCO17_TO_BODY18[name]] = s === 0 ? { state: 'missing' } : { state: 'observed', at: [x, y], score: s };
+      });
+      const ls = joints.l_shoulder;
+      const rs = joints.r_shoulder;
+      if (ls?.at !== undefined && rs?.at !== undefined) {
+        joints.neck = {
+          state: 'observed',
+          at: [(ls.at[0] + rs.at[0]) / 2, (ls.at[1] + rs.at[1]) / 2],
+          score: Math.min(ls.score ?? 1, rs.score ?? 1),
+        };
+      } else {
+        joints.neck = { state: 'missing' };
+      }
+      frames.push({ t: f.t, people: [{ id: 'a', joints: sortedJoints(joints) }] });
+    });
+  }
+  p.throwIfAny();
+  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: `converted from COCO-17 (${COCO_SPEC}): ${source}`, frames };
+}
+
+function cocoTriples(k: unknown): Array<[number, number, number]> | null {
+  if (!Array.isArray(k)) return null;
+  const nums = (a: unknown[]): a is number[] => a.every((v) => typeof v === 'number' && Number.isFinite(v));
+  if (k.length === 51 && nums(k)) return Array.from({ length: 17 }, (_, i) => [k[3 * i], k[3 * i + 1], k[3 * i + 2]] as [number, number, number]);
+  if (k.length === 17 && k.every((t) => Array.isArray(t) && t.length === 3 && nums(t))) return k as Array<[number, number, number]>;
+  return null;
+}
+
+/** Joints in body-18 order, so a written file's key order is fixed. */
+export function sortedJoints(j: Partial<Record<Body18, Joint>>): Partial<Record<Body18, Joint>> {
+  const out: Partial<Record<Body18, Joint>> = {};
+  for (const n of BODY18) {
+    const v = j[n];
+    if (v !== undefined) out[n] = v;
+  }
+  return out;
+}
+
+/** A pose sequence as JSON text, in a fixed key order. */
+export function writePoseSequence(seq: PoseSequence): string {
+  const round = (v: number, d: number) => Number(v.toFixed(d));
+  const frames = seq.frames.map((f) => ({
+    t: f.t,
+    people: f.people.map((q) => ({
+      id: q.id,
+      joints: Object.fromEntries(
+        Object.entries(sortedJoints(q.joints)).map(([n, j]) => [
+          n,
+          {
+            state: j.state,
+            ...(j.at !== undefined ? { at: [round(j.at[0], 2), round(j.at[1], 2)] } : {}),
+            ...(j.score !== undefined ? { score: round(j.score, 4) } : {}),
+          },
+        ]),
+      ),
+    })),
+  }));
+  return `${JSON.stringify({ spec: seq.spec, space: seq.space, width: seq.width, height: seq.height, source: seq.source, frames }, null, 2)}\n`;
+}