@rig-c/pose 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rig-c
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @rig-c/pose
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Puts motion from a pose onto a rig. The motion is joint positions over time: from a video, a dataset, or points placed by hand. The rig is one [rig-c](https://github.com/rig-c/core) built. A body-18 pose sequence becomes bone keys in rig-c's motion format, and the keys are checked before anything is written.
+
+**0.x is the prototype.** The format, the command and the output can change in any release until 1.0.
+
+Part of the rig-c toolchain: [core](https://github.com/rig-c/core) compiles and gates a rig, [parts](https://github.com/rig-c/parts) builds one from a painting, [play](https://github.com/rig-c/play) plays it, and pose moves it.
+
+<!-- demo -->
+
+## What it does
+
+```sh
+rig-pose retarget --rig out/rig --map map.json --pose dance.pose.json --out motion.json --name dance
+```
+
+For every frame of the pose and every bone the map names, the segment that bone carries (an upper arm: shoulder → elbow) points somewhere in the picture. The bone is turned so its segment points the same way: the picture angle, flipped into rig-c's y-up world, minus the bone's angle at the rig's setup pose (read through rig-c's own poser), less the turn of the mapped bone above it — because a `rotate` key in rig-c adds to the setup rotation and a child turns with its parent. The travel of the pelvis midpoint, scaled by a length measured on both the rig and the pose, moves the hip. The result is one animation in rig-c's motion format (`rigc-motion/1`): a `rotate` track per mapped bone, a `translate` track on the hip, one key per pose frame.
+
+Nothing is written until every check passes:
+
+| Check | Fails with |
+| --- | --- |
+| rig-c's gate is green with the rig as it is, and again with the animation in (`rigc build`) | `RIG_GATE_BASE`, `RIG_GATE`, then rigc's own `FAIL` lines |
+| every mapped bone **lands** on the angle the pose asks for, on every frame — the gated build is posed by rig-c's poser and measured (0.01° / 0.01 units) | `POSE_LANDS`: the bone, the worst error, the frame |
+| elbows and knees bend only the way they can: at every joint inside a chain, the inner angle stays on the side of the rest pose's | `POSE_BEND_ONE_WAY`: the chain, the joint, the frame, the angle |
+| every point the map needs is good on at least one frame | `POSE_POINT_NEVER_GOOD` |
+| the map resolves against the rig: bones exist, chains descend, aims descend | `MAP_*`, naming both sides |
+
+and what the run cannot decide for you it lists:
+
+- `HOLD` — a joint missing, or scored under `--min-score`, holds its last good value; one line per span, with the frames and the reason.
+- `BEND` — with `--bends clamp`, a hinge bent the wrong way is straightened on that frame instead of refusing.
+- `FOLD` — `rigc render --folds` over the new animation: every mesh that folds, and when. A reading, not a gate.
+- `POSTURE` — when the map has a pelvis chain (joints `r_hip`, `l_hip`) and a `translate`: the hip line's tilt range, and the sway — the x-range of mid_hip − mid_shoulder — in rig units and in shoulder widths, the pose's beside the posed rig's. A reading, not a gate.
+
+`--smooth <n>` smooths each joint's positions, after its holds, with a Savitzky–Golay filter: at every frame, the least-squares cubic over the *n* frames around it (clipped at the ends), read at that frame. It is centred, so it moves no motion in time, and a cubic keeps the peaks a moving average flattens. `1` (the default) is none; otherwise *n* is odd and at least 5, since a cubic through 3 points passes through all three.
+
+**Use `--smooth 7` at 24 fps.** It was measured on a 13 s dance on a @rig-c/parts rig, read back from the gated build: the motion's timing did not move (speed cross-correlation lag 0 on the wrists, ankles and hip), the frame-to-frame second difference dropped 2.5× on the wrists, 1.7–2.1× on the ankles and 1.5× on the hip, and the hip's 95th-percentile speed fell to 0.85×. The criterion set beforehand, a 2× drop on every point, was not met on the hip. That criterion was flawed: the hip's second difference is mostly real motion, while the filter cuts white noise 4.6×. A measure that isolates noise is a later card, and the default stays off until it passes.
+
+Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2` bad invocation. `rig-pose --help` has every flag.
+
+## The pose: `rig-pose-sequence/1`
+
+@rig-c/parts' `keypoints.json` (`spine-parts-keypoints/1`) extended to frames — the same vocabulary, one more level:
+
+```json
+{ "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, 410], "score": 0.93 },
+        "r_shoulder": { "state": "observed", "at": [470, 430], "score": 0.91 },
+        "r_wrist":    { "state": "missing" } } } ] } ] }
+```
+
+- `t` is seconds and strictly increases; the animation's keys are at `t − t₀`.
+- Joints are body-18 (`nose neck r_shoulder r_elbow r_wrist l_shoulder l_elbow l_wrist r_hip r_knee r_ankle l_hip l_knee l_ankle r_eye l_eye r_ear l_ear`); `r`/`l` are the **subject's** sides. `state` is `observed`, `occluded` or `missing`, as in the keypoints file. An unlisted joint is missing.
+- Two differences from the keypoints file: the unit is `picture-px`, and `at` may lie outside the picture (a hand leaves the frame; the score says how much to believe it).
+- More than one person: `--person <id>`.
+- `score` is whatever the pose model gives. RTMPose's goes above 1, so `--min-score` is a cut on that model's scale, not a probability.
+
+**From COCO-17** — the layout most pose models and datasets use — `rig-pose convert --coco in.json --out pose.json`, or `retarget --coco`. The input is `{ "format": "coco17-sequence/1", "width", "height", "source", "frames": [{ "t", "keypoints" }] }`, keypoints in COCO's order as 17 `[x, y, score]` or 51 numbers, or `null` for a frame with nobody. The mapping: COCO's `left_*`/`right_*` → body-18's `l_*`/`r_*` (both are the subject's sides), a score of 0 → `missing`, and body-18's `neck`, which COCO lacks, is the shoulders' midpoint scored the lower of the two (OpenPose's definition).
+
+## The map: `rig-pose-map/1`
+
+Which bones carry which joints. You write it for your rig:
+
+```json
+{ "spec": "rig-pose-map/1",
+  "chains": [
+    { "name": "trunk", "bones": ["chest"], "joints": ["mid_hip", "neck"], "aim": ["neck"] },
+    { "name": "arm_r", "bones": ["sleeve_r0", "sleeve_r1"], "joints": ["r_shoulder", "r_elbow", "r_wrist"] },
+    { "name": "leg_l", "bones": ["leg_l0", "leg_l1"], "joints": ["l_hip", "l_knee", "l_ankle"] } ],
+  "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 it lists one joint more than bones; each bone descends from the one before (a control bone between them is fine).
+- `aim`, one entry per bone: `"x"` (default) — the bone's own x axis is the segment; right for a limb link @rig-c/parts turned along its limb. A point — the direction from this bone's origin to that point; right for a trunk bone, whose own axis parts leaves at 0°. `"a>b"` — the direction from point a to point b; right for a head, turned by its eye line: `{ "bones": ["head"], "joints": ["r_eye", "l_eye"], "aim": ["eye_r>eye_l"] }`, or for a pelvis, turned by its hip line: `{ "name": "pelvis", "bones": ["hip"], "joints": ["r_hip", "l_hip"], "aim": ["leg_r0>leg_l0"] }`.
+- A **point** of the rig is a bone's origin (`name`), the end of its x axis (`name:tip`), or the midpoint of two of those (`"a+b"`: `"sleeve_r0+sleeve_l0"` is the shoulders' midpoint). An aim's points must be the bone itself or descend from it.
+- `reach: true`, on a one-bone chain from the translated joint (a trunk from `mid_hip`): the bone is aimed from where its origin is posed — the hip moved and turned — at where the pose puts the segment's end relative to mid_hip, scaled. Without it, a tilted pelvis carries the chest's origin sideways and the trunk, parallel to the pose's, misses the shoulders. Its aim is one point, from the bone's own origin: `{ "name": "trunk", "bones": ["chest"], "joints": ["mid_hip", "mid_shoulder"], "aim": ["sleeve_r0+sleeve_l0"], "reach": true }`. The chain must descend from the translated bone.
+- `bend`: every joint inside a chain is a hinge. `"rest"` (default) takes the side it may bend from the rig's rest pose and refuses a rest that is straight (under 0.5°); `"ccw"`/`"cw"` state it; `"free"` skips the check.
+  ⚠️ **Seen from the front, an elbow's side is not a joint limit.** An elbow flexes toward the camera, and its picture falls on either side of the upper arm depending on how the arm is turned. On a real 13 s front-facing dance (313 frames, RTMPose), the right elbow sat on the "wrong" side of the rig's rest on 165 frames (median 23°), and the left on 200 (median 29°, up to 179° with the hands behind the head). Every one was a real elbow bend. The knees strayed at most 8.8° and 14.7°, which is pose noise around a straight leg. So for front-facing material: arms `"free"`; legs on `"rest"`, with `--bends clamp` straightening the noise.
+- `mid_hip` and `mid_shoulder` are the midpoints of the two hips and the two shoulders.
+- `translate.scale` is one length measured on both: two points on the rig, two points in the pose (its median over the frames where both are good). Pick a long segment that does not foreshorten much.
+
+## 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.
+
+## What 0.2 fixes
+
+A flat painting turned by its bones matches each limb's direction, not its depth. On a real 13 s front-facing dance, retargeted onto a @rig-c/parts rig, five moments were found where it cannot follow. They were found by measuring the pose against the rig and checked against the video:
+
+| | t (s) | what the dancer does | why bone rotation cannot follow |
+| --- | --- | --- | --- |
+| S1 | 0.0–1.1 | hands clasped behind the back | depth order: the forearms go behind the body |
+| S2 | 1.0–2.25 | a hand to the ear, then the forearm toward the camera | foreshortening (the upper arm at 0.27 of its length) and depth order |
+| S3 | 3.7–7.5 | hands behind the head | depth order; both arm meshes fold through the whole span |
+| S4 | 7.7–10.9 | hands crossed in front | which forearm is in front |
+| S5 | 11.1–13.0 | an arm thrust at the camera, then a V sign | foreshortening (0.63) and the shape of the hand; the arm mesh folds |
+
+The answer is a second drawing of the arm for each of those poses, shown in place of the bent mesh while the pose lasts. 0.2 will have rig-pose choose when to show it, key the switch in the motion, and list every fold no drawing covers ([#6](https://github.com/rig-c/pose/issues/6)).
+
+## What 0.1.0 does not do
+
+- **Extract poses from video.** The input is joint positions; how you get them (a pose model, a dataset, a hand) is yours.
+- **Turn the body.** 2D only: a segment pointing at the camera foreshortens, and the rig cannot. The direction is matched; the length is not.
+- **Plant feet** beyond what the pose gives, **hands and fingers** (no bones for them yet, rig-c/parts#171), mobile.
+
+## Licence
+
+MIT, see `LICENSE`.

package/bin/rig-pose.cjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * rig-pose's `bin` entry has one job: hand off to Bun.
+ *
+ * npm's `bin` field has to be something any installed Node can run, but
+ * rig-pose is a Bun program (it runs its TypeScript sources directly, and so
+ * does rig-c underneath it). If `bun` is on PATH, run the real CLI (cli.ts,
+ * next to this file's directory) under it — argv, stdio, the exit code and
+ * signals pass straight through. If it is not, say so once and stop.
+ */
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const cli = path.join(__dirname, '..', 'cli.ts');
+const result = spawnSync('bun', [cli, ...process.argv.slice(2)], { stdio: 'inherit' });
+
+if (result.error) {
+  if (result.error.code === 'ENOENT') {
+    process.stderr.write('rig-pose runs on Bun, which was not found on PATH — install it from https://bun.sh\n');
+  } else {
+    process.stderr.write(`rig-pose: could not launch bun: ${result.error.message}\n`);
+  }
+  process.exit(1);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+} else {
+  process.exit(typeof result.status === 'number' ? result.status : 1);
+}

package/cli.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env bun
+/**
+ * rig-pose — puts motion from a body-18 pose sequence onto a rig rig-c built.
+ *
+ * The command line is the interface for an agent that cannot see the rig: every
+ * refusal names the rule, the object, the value found and the value required,
+ * and the exit code says which kind of outcome it was.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import pkg from './package.json' with { type: 'json' };
+import { convertCoco17, writePoseSequence } from './src/pose.ts';
+import { lineOf, Refusal } from './src/problems.ts';
+import { runRetarget, type RetargetArgs } from './src/run.ts';
+
+const HELP = `rig-pose ${pkg.version} — motion from a pose sequence onto a rig-c rig
+
+Usage:
+  rig-pose retarget --rig <rig> --map <map.json> --pose <pose.json> --out <motion.json> [--name dance] [flags]
+  rig-pose convert --coco <coco17.json> --out <pose.json>
+  rig-pose --version | --help
+
+retarget
+  --rig <path>          the rig spec rigc builds from: a rig.json, or a directory holding one
+                        (with its motion.json beside it — @rig-c/parts writes the pair to <out>/rig/)
+  --map <map.json>      rig-pose-map/1: which bones carry which joints
+  --pose <pose.json>    rig-pose-sequence/1 (body-18 per frame), or COCO-17 with --coco
+  --out <motion.json>   where the motion spec goes: the rig's own animations plus the new one,
+                        ready for \`rigc build --rig <rig> --motion <motion.json>\`
+  --name <name>         the new animation's name (default: dance); refused if the rig has one by that name
+  --coco                read --pose as coco17-sequence/1 and convert it first
+  --person <id>         the person to follow when the sequence holds more than one
+  --base-motion <path>  the rig's motion spec, when it is not motion.json beside rig.json
+  --min-score <s>       a joint scored below s is not good on that frame and holds its last good
+                        value (default: 0.3); a joint with no score is good
+  --smooth <n>          Savitzky–Golay over n frames of joint positions: a centred least-squares cubic,
+                        read at each frame (default: 1, none); n is odd and ≥ 5 — a cubic through 3
+                        points passes through all three, so 3 would change nothing
+  --bends refuse|clamp  a hinge (elbow, knee: any joint inside a chain) bent the wrong way refuses
+                        the run (default), or is straightened on that frame and listed
+  --bend-tolerance <d>  degrees past straight a hinge may bend the wrong way before it counts (default: 0)
+  --profile spine|spine-html  rigc's gate profile (default: spine, rigc's own default)
+  --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here
+  --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
+  --report <file>       write the run's measurements (holds, bends, landings, folds) as JSON
+
+  It writes nothing until rigc's gate is green with the animation in, every mapped bone lands on
+  the angle the pose asks for (posed by rig-c's own poser), and no hinge bends the wrong way.
+  \`rigc render --folds\` is a reading: the run lists every mesh that folds, and still writes.
+
+convert
+  --coco <file>         coco17-sequence/1: { format, width, height, source, frames: [{ t, keypoints }] },
+                        keypoints in COCO's order as 17 [x, y, score] or 51 numbers, or null
+  --out <file>          the rig-pose-sequence/1 it becomes; neck = the shoulders' midpoint
+
+Exit codes: 0 written, 1 refused (every reason printed), 2 bad invocation.
+`;
+
+class Usage extends Error {}
+
+function parseFlags(argv: string[], flags: readonly string[], switches: readonly string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (!a.startsWith('--')) throw new Usage(`unexpected argument "${a}"`);
+    const name = a.slice(2);
+    if (switches.includes(name)) {
+      out.set(name, 'true');
+      continue;
+    }
+    if (!flags.includes(name)) throw new Usage(`unknown flag ${a}; the flags are ${[...flags, ...switches].map((f) => `--${f}`).join(', ')}`);
+    const v = argv[++i];
+    if (v === undefined || v.startsWith('--')) throw new Usage(`${a} needs a value`);
+    if (out.has(name)) throw new Usage(`${a} is given twice`);
+    out.set(name, v);
+  }
+  return out;
+}
+
+function need(f: Map<string, string>, name: string): string {
+  const v = f.get(name);
+  if (v === undefined) throw new Usage(`--${name} is required`);
+  return v;
+}
+
+function num(f: Map<string, string>, name: string, dflt: number, ok: (n: number) => boolean, what: string): number {
+  const v = f.get(name);
+  if (v === undefined) return dflt;
+  const n = Number(v);
+  if (!Number.isFinite(n) || !ok(n)) throw new Usage(`--${name} is "${v}"; it must be ${what}`);
+  return n;
+}
+
+function smoothOf(f: Map<string, string>): number {
+  const n = num(f, 'smooth', 1, (v) => Number.isInteger(v) && v >= 1 && v % 2 === 1, '1 (none) or an odd whole number ≥ 5');
+  if (n === 3) throw new Usage('--smooth is "3"; a cubic fitted through 3 points passes through all three, so a window of 3 changes nothing — it must be 1 (none) or an odd whole number ≥ 5');
+  return n;
+}
+
+function retargetArgs(argv: string[]): RetargetArgs {
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'min-score', 'smooth', 'bends', 'bend-tolerance', 'profile', 'build', 'render', 'report'], ['coco']);
+  const bends = f.get('bends') ?? 'refuse';
+  if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
+  const profile = f.get('profile') ?? 'spine';
+  if (profile !== 'spine' && profile !== 'spine-html') throw new Usage(`--profile is "${profile}"; it must be spine or spine-html`);
+  const name = f.get('name') ?? 'dance';
+  if (!/^[A-Za-z0-9_.-]+$/.test(name)) throw new Usage(`--name is "${name}"; an animation name here is letters, digits, _ . -`);
+  return {
+    rig: need(f, 'rig'),
+    map: need(f, 'map'),
+    pose: need(f, 'pose'),
+    out: need(f, 'out'),
+    name,
+    coco: f.has('coco'),
+    person: f.get('person'),
+    baseMotion: f.get('base-motion'),
+    minScore: num(f, 'min-score', 0.3, (n) => n >= 0, 'a number ≥ 0'),
+    smooth: smoothOf(f),
+    bends,
+    bendTolerance: num(f, 'bend-tolerance', 0, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
+    profile,
+    build: f.get('build'),
+    render: f.get('render'),
+    report: f.get('report'),
+  };
+}
+
+export function main(argv: string[]): number {
+  const [cmd, ...rest] = argv;
+  if (cmd === undefined || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (cmd === '--version' || cmd === '-v') {
+    process.stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+  try {
+    if (rest.includes('--help')) {
+      process.stdout.write(HELP);
+      return 0;
+    }
+    if (cmd === 'retarget') {
+      runRetarget(retargetArgs(rest), (l) => process.stdout.write(`${l}\n`));
+      return 0;
+    }
+    if (cmd === 'convert') {
+      const f = parseFlags(rest, ['coco', 'out'], []);
+      const input = need(f, 'coco');
+      const out = need(f, 'out');
+      const seq = convertCoco17(readFileSync(input, 'utf8'), input);
+      writeFileSync(out, writePoseSequence(seq));
+      process.stdout.write(`rig-pose convert: ${seq.frames.length} frame(s) of COCO-17 → body-18; wrote ${out}\n`);
+      return 0;
+    }
+    process.stderr.write(`rig-pose: unknown command "${cmd}" — the commands are: retarget, convert\n`);
+    return 2;
+  } catch (e) {
+    if (e instanceof Usage) {
+      process.stderr.write(`rig-pose ${cmd}: ${e.message} (rig-pose --help)\n`);
+      return 2;
+    }
+    if (e instanceof Refusal) {
+      for (const p of e.problems) process.stderr.write(`FAIL  ${lineOf(p)}\n`);
+      process.stderr.write(`rig-pose ${cmd}: ${e.problems.length} problem(s) — nothing written\n`);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)));

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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": {
+    "rig-pose": "./bin/rig-pose.cjs"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "license": "MIT",
+  "author": "firejune",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rig-c/pose.git"
+  },
+  "homepage": "https://github.com/rig-c/pose#readme",
+  "bugs": "https://github.com/rig-c/pose/issues",
+  "keywords": [
+    "rigc",
+    "rig-c",
+    "pose",
+    "retarget",
+    "motion-retargeting",
+    "keypoints",
+    "body-18",
+    "coco",
+    "skeletal-animation",
+    "2d",
+    "ai-agents",
+    "cli"
+  ],
+  "files": [
+    "bin/rig-pose.cjs",
+    "cli.ts",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test ./test",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx eslint .",
+    "prepublishOnly": "bun run typecheck && bun run lint && bun run test"
+  },
+  "dependencies": {
+    "rig-c": "^2.47.1"
+  },
+  "devDependencies": {
+    "@esotericsoftware/spine-core": "4.3.13",
+    "@types/bun": "^1.4.2",
+    "eslint": "^10.11.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1"
+  }
+}

package/src/joints.ts

@@ -0,0 +1,70 @@
+/**
+ * The joint vocabulary: body-18, as @rig-c/parts spells it in
+ * `spine-parts-keypoints/1` (its `src/skeleton.ts`), and nothing else.
+ *
+ * `r_` and `l_` are the SUBJECT's sides: for a figure facing the viewer,
+ * `r_shoulder` is on the left of the picture.
+ */
+export const BODY18 = [
+  'nose', 'neck',
+  'r_shoulder', 'r_elbow', 'r_wrist',
+  'l_shoulder', 'l_elbow', 'l_wrist',
+  'r_hip', 'r_knee', 'r_ankle',
+  'l_hip', 'l_knee', 'l_ankle',
+  'r_eye', 'l_eye', 'r_ear', 'l_ear',
+] as const;
+export type Body18 = (typeof BODY18)[number];
+
+/**
+ * Points a map may name that body-18 does not have, each the midpoint of two
+ * body-18 joints. A virtual point is good on a frame only when both of its
+ * joints are, and its score is the lower of the two.
+ */
+export const VIRTUAL: Readonly<Record<string, readonly [Body18, Body18]>> = {
+  mid_hip: ['r_hip', 'l_hip'],
+  mid_shoulder: ['r_shoulder', 'l_shoulder'],
+};
+
+export const POINT_NAMES: readonly string[] = [...BODY18, ...Object.keys(VIRTUAL)];
+
+export function isBody18(name: string): name is Body18 {
+  return (BODY18 as readonly string[]).includes(name);
+}
+
+/**
+ * COCO-17, the keypoint layout of the COCO dataset and of most pose models'
+ * output, in its standard order.
+ */
+export const COCO17 = [
+  'nose', 'left_eye', 'right_eye', 'left_ear', 'right_ear',
+  'left_shoulder', 'right_shoulder', 'left_elbow', 'right_elbow',
+  'left_wrist', 'right_wrist', 'left_hip', 'right_hip',
+  'left_knee', 'right_knee', 'left_ankle', 'right_ankle',
+] as const;
+
+/**
+ * COCO-17 → body-18. Sixteen joints are the same joint under another name
+ * (COCO's `left_` is the subject's left, as body-18's `l_` is); body-18's
+ * `neck`, which COCO does not have, is the midpoint of the two shoulders, as
+ * OpenPose defines it, observed only when both shoulders are and scored the
+ * lower of the two.
+ */
+export const COCO17_TO_BODY18: Readonly<Record<(typeof COCO17)[number], Body18>> = {
+  nose: 'nose',
+  left_eye: 'l_eye',
+  right_eye: 'r_eye',
+  left_ear: 'l_ear',
+  right_ear: 'r_ear',
+  left_shoulder: 'l_shoulder',
+  right_shoulder: 'r_shoulder',
+  left_elbow: 'l_elbow',
+  right_elbow: 'r_elbow',
+  left_wrist: 'l_wrist',
+  right_wrist: 'r_wrist',
+  left_hip: 'l_hip',
+  right_hip: 'r_hip',
+  left_knee: 'l_knee',
+  right_knee: 'r_knee',
+  left_ankle: 'l_ankle',
+  right_ankle: 'r_ankle',
+};