@rig-c/pose 0.14.0 → 0.16.0

package/README.md

@@ -25,7 +25,7 @@ The map names **chains**: each limb as bones that descend from one another, pare
 ## Clean first: `rig-pose clean`
 
 ```sh
-rig-pose clean --pose dance.scan.json --out dance.pose.json [--loop] [--legs 5] [--rest 7]
+rig-pose clean --pose dance.scan.json --out dance.pose.json [--loop] [--legs 5] [--rest 7] [--hips-inferred]
 ```
 
 `retarget` reads only a sequence that `clean` wrote ([#67](https://github.com/rig-c/pose/issues/67)). A pose model reads each frame alone, so a hanging wrist moves ±20 px a frame and a cloak-hidden leg jumps 100+ px, and every key carries that shake. `clean` takes it out once, at the sequence, where it can be inspected. A sequence without the record is refused by name (`POSE_NOT_CLEANED`), and the message is the `clean` command to run on that file. There is no flag to skip the step. Windows of 1 (`--legs 1 --rest 1`) are a legitimate run that smooths nothing, and they are recorded as such.
@@ -33,7 +33,7 @@ rig-pose clean --pose dance.scan.json --out dance.pose.json [--loop] [--legs 5]
 The steps, in this order, each printed with its figures:
 
 1. **Spikes.** A joint more than 0.2 trunk lengths from its 5-frame median takes the median. The trunk is neck → mid-hip, the median over the clip. Each replacement is listed by frame and joint (`SPIKE`). Without `--loop`, a clip end cuts the window of the first and last two frames. There the median is a neighbour's value, and a joint moving steadily would read as a spike. Those frames are **not tested**, and the `SPIKES` line and the record name them. Reflecting the window does not help: the median of `[x2, x1, x0, x1, x2]` is still `x1`.
-2. **Occlusion.** A joint whose state is not `observed`, or whose score is under 0.3, takes its 3-frame median (`OCCLUDED`).
+2. **Occlusion.** A joint whose state is not `observed` (or `inferred`), or whose score is under 0.3, takes its 3-frame median (`OCCLUDED`).
 3. **Smoothing.** A quadratic Savitzky–Golay per joint: the legs (both hips, knees and ankles) over `--legs` frames (default 5), every other joint over `--rest` (default 7). A window is 1 (none) or odd and at least 5. 3 is refused because a quadratic through 3 points passes through all three. Without `--loop`, the window is cut at the ends. Where fewer than three frames have a position, the degree drops to fit the ones that do.
 4. **Floor.** Only with `--loop`: the whole figure moves in y by one constant, so that the lowest ankle over the cycle is where it was before smoothing.
 
@@ -50,6 +50,8 @@ The output carries the record, here the dancer's from the table below:
 
 `jitter` is the mean |second difference| of y, in px/f², over every joint and every three consecutive frames that have a position, wrapping with `--loop`. It is measured on the sequence as read and on the cleaned positions. `retarget` prints the record as its `CLEAN` line and copies it into `--report`.
 
+**`--hips-inferred`** ([#63](https://github.com/rig-c/pose/issues/63)) declares that the hips are not seen: under a skirt or a cloak the pose model still places them, but where it puts them is its guess. After the four steps, `r_hip` and `l_hip` are marked `inferred` on every frame where they have a position (`INFERRED`), and the record's params carry `"hipsInferred": { "by": "declared" }` — the person running `clean` said so. Positions and scores are unchanged, so `retarget`'s keys are the same with the flag and without it. What changes is the `POSTURE` line, which does not read a hip tilt off inferred hips (below), and the `CLEAN` line, which ends `hips inferred (declared at clean)`.
+
 **Measured** on HQ's references ([#67](https://github.com/rig-c/pose/issues/67)'s bars):
 
 | Clip | Run | Jitter, px/f² | Against |
@@ -89,11 +91,13 @@ and what the run cannot decide for you it lists:
 - `FLIP` — a segment that turns more than `--flip` degrees in one frame (with `--flip <deg>`; off by default) is spread over the frames around the jump; one line per spread, with the chain, the segment, the jump, the frames and h. Below.
 - `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.
+- `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. A frame on which either hip is `inferred` is left out of the tilt. When that is every frame, as after `clean --hips-inferred`, the line is `hip tilt not read: hips inferred (declared at clean)` and the report's `posture` has `"tilt": null` with `"tiltWhy"`; on some frames only, the tilt is read over the others and the line counts the frames left out (`posture.hipsInferred`). The source is read from the clean record, or is `source not stated` when the joints carry the state and the record does not. The sway reads the hips as before.
 - `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, how far each bone with a `drawn` angle was turned from it, and where each of its boundaries was moved to (`moved`, [below](#alternate-drawings-alternates)).
 - `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 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.
+- `RAISED` — with `--raised-by-head` ([below](#alternate-drawings-alternates)): one line per span of a set that draws an arm raised, per chain. It gives the frames and the median eye distances (the rig's in units, the reference's in px). It gives the wrist's offset from the head centre in eye distances: the median of the reference's, of where the wrist was placed, of the rig's on the pose's angles, and of the rig's as keyed. It gives the worst |rig − reference| before and after, the worst |after − placed|, and the frames whose upper arm the set's `turn` held. `RAISED none` when the flag is given and no such set showed.
+- `REACH` — with `--raised-by-head`: a raised span whose target was out of the arm's reach, too far or too near. It names the frames, which way, and the shortfall in eye distances. The wrist was placed at the reach limit instead. This is not `ART-RANGE`: the rig's proportions were the limit, not the art's range. A too-near frame is placed at the limit like a too-far one, and graded at the placed distance.
 - `LEG-SCALE` — with `--leg-scale` ([below](#the-legs-foreshortening-and-planted-feet)): per leg segment, its straight length, the spread of its picture length over it, and the frames clamped at each limit.
 - `PIVOT` — when the map translates a bone and has both legs: the translated bone's origin against its thigh roots' midpoint at setup, in units and hip widths — the pivot every hip turn swings the legs about.
 - `FEET` — when the map has both legs: the supports and jumps read off the reference ankles (planted or not), and on the posed build, outside the jumps, the lowest ankle's vertical range and each support span's worst vertical range and horizontal drift of the supporting ankle, in leg lengths.
@@ -103,7 +107,7 @@ and what the run cannot decide for you it lists:
 - `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total.
 - `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`, `switchMin`, `switchAt`, `legScale`, `plantFeet` and `stance` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `stance` (`tolerance`, `bounds`, `runs`: `{ state, side, frames, maxHeight, k }`, `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `stance` (`tolerance`, `bounds`, `runs`: `{ state, side, frames, maxHeight, k }`, `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
 
 | field | each entry |
 | --- | --- |
@@ -120,7 +124,8 @@ The demand 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, clamped }]` — `turn` is the signed art turn the pose asked on that frame; `clamped` says whether the set's `turn` held the bone there.
+- `artRange: [{ set, chain, bone, frames, seconds, maxOverflow, turn, limits, clamped, shortfall? }]` — `turn` is the signed art turn the pose asked on that frame; `clamped` says whether the set's `turn` held the bone there. `shortfall` (with `--raised-by-head`) marks a held upper arm whose re-aimed forearm left the wrist short of its placed point: the most, in eye distances, with `turn` and `maxOverflow` the upper arm's on that frame.
+- `raised: [{ set, chain, frames, seconds, eyes: { rig, reference }, reference, placed, before, after, worst: { before, after, placed }, short, upperHeld, reach: { min, max, farthest } }]` — with `--raised-by-head`. `reference`, `placed`, `before` and `after` are the wrist's offset from the head centre on each frame of the span, `[x, y]` in eye distances, x right and y up. `eyes` holds each side's median eye distance over the span. `worst.before` and `worst.after` are the largest |rig − reference| in x and in y; `worst.placed` is the largest |after − placed|. `short` lists the `REACH` runs, each `{ frames, how, shortfall: { max, median } }`, where `how` is `far`, `near` or `missed`. `upperHeld` lists the frames whose upper arm the set's `turn` held. `reach` gives |l0 − l1|, l0 + l1 and the farthest target from the shoulder, in world units.
 
 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.
 
@@ -182,7 +187,7 @@ A rig's motion spec usually has an `idle` — a blink, a breath, hair and hem sw
 
 Every bone still has to land with the carried tracks in. A carried translate above the translated bone moves its origin off the pose's travel, and the run refuses with `POSE_LANDS`, naming the carried tracks above the bone that missed.
 
-On HQ's dancer (`--flip 90 --short 0.35 --bends clamp --carry-idle`) the idle has 26 tracks. Kept out: the four arm rotates, which the dance keys, and `chest_ctl` scalex, `neck` rotate and `head_ctl` rotate, which sit above the mapped chest, head and arms — carried, they missed the chest, the head and the arms by 0.16°–1.37°. Carried: the other 19, the blink (`group "eyes"` scaley) and the breath (`bone "chest_ctl"` translatey) among them. The gate is green, every bone lands (worst 0.00167°), and rig-c's poser shows the blink at every cycle (scaleY 0.12 at 2.37 s, 5.70 s, 9.08 s and 12.41 s, against the idle's at t mod 3.333 s within 8.9e-6) and the breath's chest_ctl offset (5.02 at 0.833, 4.167, 7.5, 10.833 s; 0 at 2.5, 5.833, 9.167, 12.5 s; 1.035 at the cut, 13 s).
+On HQ's dancer (`--flip 90 --short 0.35 --bends clamp --carry-idle`) the idle has 26 tracks. Kept out: the four arm rotates, which the dance keys, and a control bone's scalex above the chest, the neck's rotate and a head control's rotate, which sit above the mapped chest, head and arms — carried, they missed the chest, the head and the arms by 0.16°–1.37°. Carried: the other 19, the blink (an eyes group's scaley) and the breath (the chest control's translatey) among them. The gate is green, every bone lands (worst 0.00167°), and rig-c's poser shows the blink at every cycle (scaleY 0.12 at 2.37 s, 5.70 s, 9.08 s and 12.41 s, against the idle's at t mod 3.333 s within 8.9e-6) and the breath's offset (5.02 at 0.833, 4.167, 7.5, 10.833 s; 0 at 2.5, 5.833, 9.167, 12.5 s; 1.035 at the cut, 13 s).
 
 **`--merge <file>`** merges a timed track fragment into the new animation, at absolute times from its start — blinks read off the video, for example:
 
@@ -222,7 +227,7 @@ Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2
 ```
 
 - `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.
+- 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, or `inferred` ([#63](https://github.com/rig-c/pose/issues/63)): a position the detector supplied but did not see. An `inferred` joint carries `at` (one without it is refused, `POSE_JOINT_AT`), and `retarget` keys it as it keys `observed`. 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.
@@ -273,16 +278,18 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 
 ```json
 "alternates": [
-  { "name": "K1_hands_behind_head",
-    "slots":   { "upperarm_r_under": "K1_upperarm_r", "forearm_r_back": "K1_forearm_r", "topwear": "K1_topwear" },
+  { "name": "raised_arms",
+    "slots":   { "upperarm_r_raised": "raised/upperarm_r", "forearm_r_raised": "raised/forearm_r", "torso": "raised/torso" },
     "hides":   ["upperarm_r", "forearm_r"],
     "chains":  ["arm_r", "arm_l"],
-    "pose":    { "r_shoulder": [450, 640], "r_elbow": [350, 500], "r_wrist": [510, 480],
-                 "l_shoulder": [610, 640], "l_elbow": [720, 500], "l_wrist": [560, 480] },
-    "drawn":   { "sleeve_r0": 117.8, "sleeve_r1": 30.4 },
+    "pose":    { "r_shoulder": [400, 600], "r_elbow": [300, 450], "r_wrist": [450, 400],
+                 "l_shoulder": [600, 600], "l_elbow": [700, 450], "l_wrist": [550, 400] },
+    "drawn":   { "sleeve_r0": 120, "sleeve_r1": 30 },
     "offsets": { "sleeve_r1": [4, -2] } } ]
 ```
 
+(The names, coordinates and angles above are illustrative.)
+
 - `slots`: what each slot of the set shows while it shows; each attachment must be in that slot under some skin of the rig, as rig-c built it. `hides`: the slots that are empty while it shows. A slot's place in the draw order is the rig's own, so a drawing that must sit in front of the torso is an attachment in a slot that is: a switch is attachment keys only, and no draw-order key is written.
 - `chains`: the map's chains whose pose the set depicts; it is selected by them. `pose`: the key skeleton the art was painted from, body-18 (or `mid_hip`/`mid_shoulder`) in picture px, y down, any scale and place — only its directions are read; every joint the listed chains use must be in it.
 - `drawn` (optional): each bone's world angle (Spine degrees) as painted. It changes no key: while a set shows, a bone is keyed to the pose as always, and the art turns with it. What it gives is a figure: the art turn, how far each bone is from the angle its art was painted at (`artTurn`, and `ART-RANGE` past the bone's range).
@@ -305,6 +312,16 @@ Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's
 **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. A window **restricts** a set; it never forces one. Where the set does not show inside its window, the run says why in a `FRAMES` line: the stretch, and whether the pose there was past the tolerance (with the largest distance), or within it but the run was dropped.
 
 **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`).
+
+**A raised arm placed against the head: `--raised-by-head`.** The pose's angles put a hand where it is against the dancer's own shoulder. On a rig whose shoulders sit nearer its head, or whose head is larger, the same angles put a hand raised beside the head on top of it. With `--raised-by-head` (off by default, [#62](https://github.com/rig-c/pose/issues/62)) a set draws an arm **raised** when its `drawn` angle for the chain's first bone (the upper arm) is within 30° of straight up (a world angle of 60°–120°). While that set shows, the arm's wrist goes where the reference's is **against the head**:
+
+- The unit is the **eye distance**: on each side, its median over the span. That is the reference's |r_eye − l_eye|, and on the rig the distance between the two points the head chain's `"a>b"` aim names. The head centre is the eyes' midpoint on each frame. The head chain is the one carrying the eye line (r_eye → l_eye, either way round). The flag is refused without one, or with one not aimed `"a>b"` (`RAISED_HEAD`).
+- The target is rig head centre + (reference wrist − reference head centre) × (rig eye distance ÷ reference eye distance), the picture's y turned up, per frame.
+- **The order of solving.** The arm is solved last of the bones. By then the hip's travel, every reach, the head and every range clamp are final, and the arm moves neither the head nor its own shoulder. On each frame the rig's eye points and the shoulder are posed forward from those targets, as a reach's origin is: each rest offset is turned by the nearest mapped bone above.
+- **Reach.** The arm reaches the annulus about the shoulder from |l0 − l1| to l0 + l1. Here l0 runs from the upper arm's origin to the forearm's, and l1 from there to the wrist (the forearm's tip, or the point it aims at). A target outside it is replaced by the reach limit along the head-relative direction. That is the point inside the annulus, on the ray from the head centre through the target, nearest the target. Where the ray crosses the annulus twice, the nearer stretch wins, and a tie goes to the point nearer the head. A ray that never enters it gives the annulus point nearest the target. Every such frame is listed in `REACH`. A too-near frame is treated as a too-far one: the wrist is placed at the reach limit, and the distance the rule grades it at is the placed one. That is |placed − head centre|, not the reference's, which the arm cannot fold to.
+- **The solve.** Two bones on the rig's own lengths put the wrist on that point, the elbow bending to the side the pose's does. The set's `turn` is part of the solve. When it holds the upper arm, the forearm is re-aimed from the held elbow at the placed wrist rather than held on its own. `ART-RANGE` lists where the re-aimed forearm still cannot reach within `turn`, in two cases. One is a forearm past its own `turn`, held there. The other is a held upper arm whose re-aimed forearm leaves the wrist more than 0.01 eye distances short of its placed point; 0.01 is the float and rounding scale. That case is listed on the upper arm, with the shortfall in eye distances. The solved angles become the targets, which the keys and the landing check follow.
+- Frames outside those spans, and sets that draw no arm raised, are keyed as without the flag, byte for byte. A raised chain must have two bones, each aimed `"x"` or at one point, and the eye points must not turn with it (`RAISED_CHAIN`).
+
 ## Compare: the rig's render against the video
 
 ```sh

package/cli.ts

@@ -34,6 +34,10 @@ clean (required before retarget; rig-c/pose#67)
   --legs <n>            Savitzky–Golay window over the legs — both hips, knees and ankles (default: 5)
   --rest <n>            Savitzky–Golay window over every other joint (default: 7)
                         n is 1 (none), or odd and ≥ 5: a quadratic through 3 points passes through all three
+  --hips-inferred       declare the hips inferred (rig-c/pose#63): r_hip and l_hip are marked "inferred" — a
+                        position the detector supplied but did not see — on every frame where they have one, and
+                        the record says so (hipsInferred: { by: "declared" }). Positions are unchanged, so retarget's
+                        keys are too; its POSTURE line does not read the hip tilt ("hip tilt not read: hips inferred")
 
   In order, each step printed with its figures: (1) spikes — a joint more than 0.2 trunk lengths
   (neck → mid_hip, the median over the clip) from its 5-frame median takes the median, each listed by
@@ -94,6 +98,18 @@ retarget
                         reaches the floor, raised or lowered, k within [0.92, 1.08] (past it, reported, not forced); above
                         it the foot is lifted and keeps the pose's height (STANCE lines; default: off; 0.07 is
                         the card's, rig-c/pose#60)
+  --raised-by-head      while a set whose arm is drawn raised shows (its "drawn" upper arm within 30° of straight
+                        up), that arm's wrist goes where the reference's is against the head, in eye distances:
+                        rig head centre + (reference wrist − reference head centre) × rig eye distance ÷ the
+                        reference's, per frame; each eye distance is its median over the span. The head centre is
+                        the eyes' midpoint; the rig's eyes are the two points the head chain's "a>b" aim names
+                        (refused without one, RAISED_HEAD), posed from the targets of the bones above. A target out
+                        of the arm's reach, too far or too near, goes to the reach limit on the ray from the head
+                        centre toward it and is graded at that placed distance (REACH lines, in eye distances). A
+                        two-bone solve on the rig's own lengths keeps the pose's elbow side; when the set's "turn"
+                        holds the upper arm the forearm is re-aimed at the wrist. ART-RANGE: a forearm still past
+                        its turn, or a held arm leaving the wrist > 0.01 eye distances short of its placed point
+                        (the shortfall listed). RAISED lines (default: off; rig-c/pose#62)
   --idle <name>         the rig's animation read as its idle (default: idle). Every idle track the new
                         animation does not key, on any channel, is listed as IDLE-DROPPED (a blink, a
                         breath); one it keys is IDLE-KEPT-OUT, naming the track that keys it, and so is a
@@ -125,7 +141,7 @@ retarget
   --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, short, endOn, flips, bends, landings, folds,
-                        switches, uncovered, turns, range, artRange,
+                        switches, uncovered, turns, range, artRange, raised,
                         idleDropped, idleKeptOut, merged, reduce) as JSON
 
   It writes nothing until rigc's gate is green with the animation in, every mapped bone lands on
@@ -224,7 +240,7 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 }
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance'], ['coco', 'plant-feet', 'carry-idle']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -250,6 +266,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     legScale: legScaleOf(f),
     plantFeet: f.has('plant-feet'),
     stance: stanceOf(f),
+    raisedByHead: f.has('raised-by-head'),
     bends,
     bendTolerance: num(f, 'bend-tolerance', 0, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
     switchTolerance: num(f, 'switch-tolerance', 25, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
@@ -346,10 +363,10 @@ function runsOf(frames: number[]): string {
 
 /** `rig-pose clean` (#67): read, clean, print each step's figures, write. */
 function runClean(argv: string[], say: (l: string) => void): void {
-  const f = parseFlags(argv, ['pose', 'out', 'legs', 'rest', 'person'], ['loop', 'coco']);
+  const f = parseFlags(argv, ['pose', 'out', 'legs', 'rest', 'person'], ['loop', 'coco', 'hips-inferred']);
   const input = need(f, 'pose');
   const out = need(f, 'out');
-  const params = { loop: f.has('loop'), legs: windowOf(f, 'legs', 5), rest: windowOf(f, 'rest', 7) };
+  const params = { loop: f.has('loop'), legs: windowOf(f, 'legs', 5), rest: windowOf(f, 'rest', 7), hipsInferred: f.has('hips-inferred') };
   const text = readFileSync(input, 'utf8');
   const seq = f.has('coco') ? convertCoco17(text, input) : readPoseSequence(text, input);
   const c = clean(seq, params, f.get('person'), input);
@@ -372,6 +389,7 @@ function runClean(argv: string[], say: (l: string) => void): void {
   }
   const jit = (v: number | null) => (v === null ? 'not measured' : `${fmt(v, 3)}`);
   say(`  JITTER mean |second difference| of y over ${c.triples} joint-frame triple(s): ${jit(c.record.jitter.before)} → ${jit(c.record.jitter.after)} px/f²${c.record.jitter.before !== null && c.record.jitter.after !== null && c.record.jitter.before > 0 ? ` (${fmt(100 * (1 - c.record.jitter.after / c.record.jitter.before), 1)}% lower)` : ''}`);
+  if (c.inferred !== null) say(`  INFERRED r_hip on ${c.inferred.r_hip} frame(s), l_hip on ${c.inferred.l_hip} frame(s) of ${n} marked "inferred" (every frame where it has a position): declared at clean (--hips-inferred); positions and scores unchanged`);
   writeFileSync(out, writePoseSequence(c.seq));
   say(`  CLEAN  ${cleanLine(c.record)}`);
   say(`  wrote ${out}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.14.0",
+  "version": "0.16.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/clean.ts

@@ -37,7 +37,15 @@
  * median of on its own frame, and a value made from its neighbours would be a
  * guess; `retarget` holds it, and says so with a HOLD line. A joint's state and
  * score are the detector's and are written as they were read: this step moves
- * positions only.
+ * positions only — with one stated exception, `hipsInferred` below.
+ *
+ * `hipsInferred` (rig-c/pose#63, `--hips-inferred`): after the four steps, r_hip
+ * and l_hip are marked `inferred` on every frame where they have a position,
+ * and the record says who said so (`{ by: 'declared' }`, the person running
+ * clean). Positions and scores are not touched by it, so retarget's keys are
+ * the same with and without it; what changes is POSTURE, which does not read a
+ * hip tilt off inferred hips. The occlusion step reads `inferred` as it reads
+ * `observed`: a cleaned file cleaned again moves its hips the same way.
  *
  * The smoothing fits the frames of the window where the joint has a position;
  * where fewer than three are there, the polynomial's degree drops to fit the
@@ -75,8 +83,13 @@ export interface CleanParams {
   legs: number;
   /** Savitzky–Golay window over every other joint, frames: 1 (none), or odd and ≥ 5. */
   rest: number;
+  /** Mark r_hip and l_hip `inferred` wherever they have a position (#63): the person running clean declares it. */
+  hipsInferred?: boolean;
 }
 
+/** The joints `--hips-inferred` marks. */
+export const HIPS: readonly Body18[] = ['r_hip', 'l_hip'];
+
 export type Pt = [number, number];
 /** One joint's positions over the frames; null where it has none. */
 export type Series = Array<Pt | null>;
@@ -116,6 +129,8 @@ export interface Cleaned {
   floor: Floor | null;
   /** How many (joint, three-frame) runs the jitter was read over: before, after. */
   triples: number;
+  /** With `hipsInferred`: how many joint-frames were marked `inferred`, per hip. */
+  inferred: { r_hip: number; l_hip: number } | null;
 }
 
 /**
@@ -323,10 +338,10 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
       if (q === null) return;
       const j = track[i]![name]!;
       const low = j.score !== undefined && j.score < OCCLUSION_SCORE;
-      if (j.state === 'observed' && !low) return;
+      if ((j.state === 'observed' || j.state === 'inferred') && !low) return;
       const m = medianAt(xs, i, OCCLUSION_WINDOW, params.loop)!;
       out[i] = m;
-      occluded.push({ joint: name, frame: i, moved: Math.hypot(m[0] - q[0], m[1] - q[1]), why: j.state !== 'observed' ? j.state : `score ${j.score!.toFixed(3)} < ${OCCLUSION_SCORE}` });
+      occluded.push({ joint: name, frame: i, moved: Math.hypot(m[0] - q[0], m[1] - q[1]), why: j.state !== 'observed' && j.state !== 'inferred' ? j.state : `score ${j.score!.toFixed(3)} < ${OCCLUSION_SCORE}` });
     });
     unhidden.set(name, out);
   }
@@ -366,17 +381,23 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
   const after = jitterOf([...smoothed.values()], params.loop);
   const record: CleanRecord = {
     spec: CLEAN_SPEC,
-    params: { loop: params.loop, legs: params.legs, rest: params.rest },
+    params: { loop: params.loop, legs: params.legs, rest: params.rest, ...(params.hipsInferred === true ? { hipsInferred: { by: 'declared' as const } } : {}) },
     spikes: { found: spikes.map((s) => ({ frame: s.frame, joint: s.joint })), untested },
     jitter: { before: before.value, after: after.value },
   };
+  const inferred = params.hipsInferred === true ? { r_hip: 0, l_hip: 0 } : null;
   const frames = seq.frames.map((f, i) => {
     const q = f.people.find((x) => x.id === person);
     if (q === undefined) return { t: f.t, people: [] };
     const joints: Partial<Record<Body18, Joint>> = {};
     for (const [name, j] of Object.entries(q.joints) as Array<[Body18, Joint]>) {
       const moved = smoothed.get(name)?.[i] ?? null;
-      joints[name] = moved === null ? { ...j } : { ...j, at: [moved[0], moved[1]] };
+      const out: Joint = moved === null ? { ...j } : { ...j, at: [moved[0], moved[1]] };
+      if (inferred !== null && (name === 'r_hip' || name === 'l_hip') && out.state !== 'missing' && out.at !== undefined) {
+        out.state = 'inferred';
+        inferred[name]++;
+      }
+      joints[name] = out;
     }
     return { t: f.t, people: [{ id: person, joints: sortedJoints(joints) }] };
   });
@@ -392,6 +413,7 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
     untested,
     floor,
     triples: before.triples,
+    inferred,
   };
 }
 
@@ -409,5 +431,18 @@ export function cleanLine(r: CleanRecord): string {
   const shown = found.slice(0, 8).map((s) => `frame ${s.frame} ${s.joint}`).join(', ');
   const spikes = `${found.length === 0 ? 'no spike' : `${found.length} spike(s) replaced (${shown}${found.length > 8 ? `, … ${found.length - 8} more` : ''})`}, ${untestedText(r.spikes.untested)}`;
   const jit = (v: number | null) => (v === null ? 'not measured' : v.toFixed(2));
-  return `${r.spec}: ${windows}, ${loop ? 'loop' : 'no loop'}; ${spikes}; jitter (mean |second difference| of y) ${jit(r.jitter.before)} → ${jit(r.jitter.after)} px/f²`;
+  const hips = r.params.hipsInferred === undefined ? '' : `; hips inferred (${inferredSource(r)})`;
+  return `${r.spec}: ${windows}, ${loop ? 'loop' : 'no loop'}; ${spikes}; jitter (mean |second difference| of y) ${jit(r.jitter.before)} → ${jit(r.jitter.after)} px/f²${hips}`;
+}
+
+/**
+ * Where a sequence's `inferred` hips come from, as the lines say it: "declared
+ * at clean" when the record says `--hips-inferred` marked them; "source not
+ * stated" when the joints carry the state and the record does not say why
+ * (a file whose states were written by hand or by another tool).
+ */
+export function inferredSource(r: CleanRecord | undefined): string {
+  const h = r?.params.hipsInferred;
+  if (h === undefined) return 'source not stated';
+  return h.by === 'declared' ? 'declared at clean' : h.by;
 }

package/src/pose.ts

@@ -23,7 +23,13 @@ import { isObject, parseJson, Problems, refuseUnknownKeys, typeName } from './pr
 
 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;
+/**
+ * `inferred` (rig-c/pose#63): a position the detector supplied but did not see
+ * — it carries `at` like `observed`, and retarget keys it the same; what it
+ * changes is what a reading may claim from it (POSTURE does not read a hip tilt
+ * off inferred hips).
+ */
+const STATES = ['observed', 'occluded', 'missing', 'inferred'] as const;
 export type JointState = (typeof STATES)[number];
 
 export interface Joint {
@@ -62,9 +68,18 @@ export interface CleanSpike {
   frame: number;
   joint: Body18;
 }
+/**
+ * Who said the hips are `inferred` (#63): `declared` — the person running
+ * `rig-pose clean --hips-inferred` said so. A measured producer would record
+ * itself under another `by`; this reader reads only `declared` today.
+ */
+export interface HipsInferred {
+  by: 'declared';
+}
 export interface CleanRecord {
   spec: typeof CLEAN_SPEC;
-  params: { loop: boolean; legs: number; rest: number };
+  /** `hipsInferred` is present only when clean marked the hips (`--hips-inferred`). */
+  params: { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred };
   /**
    * `found`: every joint the spike step replaced, by frame (index into `frames`)
    * and joint. `untested`: the frames the spike step did not test, because a
@@ -219,10 +234,10 @@ function readCamera(p: Problems, where: string, camera: unknown, frames: number
   return out;
 }
 
-/** `cleaned`: { spec, params: { loop, legs, rest }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }. */
+/** `cleaned`: { spec, params: { loop, legs, rest, hipsInferred? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }. */
 function readCleaned(p: Problems, where: string, c: unknown, frames: number | null): CleanRecord | undefined {
   const cw = `${where} "cleaned"`;
-  const shape = '{ spec, params: { loop, legs, rest }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }';
+  const shape = '{ spec, params: { loop, legs, rest, hipsInferred? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }';
   if (!isObject(c)) {
     p.add('POSE_CLEANED', `${cw} is ${typeName(c)}; it is the record rig-pose clean writes, ${shape}`);
     return undefined;
@@ -234,9 +249,17 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
   const window = (v: unknown) => Number.isInteger(v) && (v === 1 || ((v as number) >= 5 && (v as number) % 2 === 1));
   if ('params' in c) {
     const q = c.params;
-    if (!isObject(q)) p.add('POSE_CLEANED', `${cw} "params" is ${typeName(q)}; it must be { loop, legs, rest }`);
+    if (!isObject(q)) p.add('POSE_CLEANED', `${cw} "params" is ${typeName(q)}; it must be { loop, legs, rest, hipsInferred? }`);
     else {
-      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest']);
+      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest', 'hipsInferred']);
+      if ('hipsInferred' in q) {
+        const h = q.hipsInferred;
+        if (!isObject(h)) p.add('POSE_CLEANED', `${cw} "params" "hipsInferred" is ${typeName(h)}; it must be { by: "declared" }`);
+        else {
+          refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params" "hipsInferred"`, h, ['by']);
+          if (h.by !== 'declared') p.add('POSE_CLEANED', `${cw} "params" "hipsInferred" "by" is ${typeName(h.by)}; this reader reads "declared" (the person running rig-pose clean --hips-inferred said so)`);
+        }
+      }
       if (typeof q.loop !== 'boolean') p.add('POSE_CLEANED', `${cw} "params" "loop" is ${typeName(q.loop)}; it must be true or false`);
       for (const k of ['legs', 'rest'] as const) if (!window(q[k])) p.add('POSE_CLEANED', `${cw} "params" "${k}" is ${typeName(q[k])}; it must be 1 (none) or an odd whole number ≥ 5`);
     }
@@ -277,11 +300,11 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
     }
   }
   if (p.list.length > before) return undefined;
-  const q = c.params as { loop: boolean; legs: number; rest: number };
+  const q = c.params as { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred };
   const j = c.jitter as { before: number | null; after: number | null };
   return {
     spec: CLEAN_SPEC,
-    params: { loop: q.loop, legs: q.legs, rest: q.rest },
+    params: { loop: q.loop, legs: q.legs, rest: q.rest, ...(q.hipsInferred !== undefined ? { hipsInferred: { by: q.hipsInferred.by } } : {}) },
     spikes: {
       found: ((c.spikes as { found: Array<{ frame: number; joint: Body18 }> }).found).map((s) => ({ frame: s.frame, joint: s.joint })),
       untested: [...(c.spikes as { untested: number[] }).untested],
@@ -324,6 +347,8 @@ function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Bo
       }
     } else if (state === 'observed') {
       p.add('POSE_JOINT_AT', `${jw} is "observed" and has no "at"; an observed joint has a position`);
+    } else if (state === 'inferred') {
+      p.add('POSE_JOINT_AT', `${jw} is "inferred" and has no "at"; an inferred joint is a position the detector supplied but did not see, so it has one`);
     }
     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`);
@@ -474,6 +499,6 @@ export function writePoseSequence(seq: PoseSequence): string {
   const camera = seq.camera?.map((c) => ({ s: round(c.s, 6), tx: round(c.tx, 3), ty: round(c.ty, 3), inliers: c.inliers }));
   const c = seq.cleaned;
   const jit = (v: number | null) => (v === null ? null : round(v, 4));
-  const cleaned = c === undefined ? undefined : { spec: c.spec, params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest }, spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] }, jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) } };
+  const cleaned = c === undefined ? undefined : { spec: c.spec, params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: { by: c.params.hipsInferred.by } } : {}) }, spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] }, jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) } };
   return `${JSON.stringify({ spec: seq.spec, space: seq.space, width: seq.width, height: seq.height, source: seq.source, ...(seq.cameraSource !== undefined ? { cameraSource: seq.cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), frames }, null, 2)}\n`;
 }

package/src/retarget.ts

@@ -50,6 +50,14 @@
  * Inside a span nothing is clamped, but a bone with a `drawn` angle is read
  * against it (`artTurn`, and `artRange` where it leaves its range).
  *
+ * With `raisedByHead` (rig-c/pose#62), after the range clamp and before the art
+ * turn is read: inside each span of a set that draws an arm raised, the arm is
+ * solved last, so its wrist lands where the reference's is against the head, in
+ * eye distances (each side's median over the span). The head and the shoulder
+ * are posed from the final targets of the bones above. A target out of reach
+ * goes to the reach limit along the head-relative direction (REACH); the set's
+ * `turn` is part of the solve, and only a forearm it still holds is ART-RANGE.
+ *
  * The lines across the body — hips, shoulders, eyes — are read from the pose
  * after holds, whether the map uses them or not: a line under
  * `TURN_FRACTION` of its median picture length, or reversed (pointing more
@@ -63,16 +71,26 @@ import { screenToSpineDegrees } from 'rig-c/transform';
 import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
 import type { Chain, JointMap, Rest, RigSlots } from './map.ts';
-import { aimAngle, descends, rigPoint } from './map.ts';
+import { aimAngle, aimEnds, descends, partBone, pointParts, rigPoint } from './map.ts';
 import type { Joint } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
-import type { ArtRange, SlotTrack, Switch, SwitchOptions } from './switch.ts';
-import { clampArt, coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
+import type { ArtRange, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { Feet, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
 import { isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, supportsOf, tipOf } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
+/**
+ * --raised-by-head (#62): a held upper arm whose re-aimed forearm leaves the
+ * wrist farther than this from its placed point, in eye distances, "cannot
+ * reach within turn" — ART-RANGE. It sits at the float and rounding scale, so
+ * any real miss counts: the solve itself closes to ~1e-12, and the writer's
+ * 0.001° rounding of two keys moves a wrist by ≤ 2 × 1.75e-5 × (l0 + l1), which
+ * is 0.0004 eye distances on the tests' stick rig (a 130-unit arm, 12-unit eyes).
+ */
+export const HELD_MISS = 0.01;
+
 export interface RetargetOptions extends SwitchOptions {
   /** A joint with a score below this is not good on that frame (a joint with no score is). */
   minScore: number;
@@ -90,6 +108,8 @@ export interface RetargetOptions extends SwitchOptions {
   plantFeet?: boolean;
   /** With plantFeet: a free ankle within this many leg lengths of the floor plants both feet, its leg stretched to reach it (`legs.ts` stanceOf, #60); 'off' (the default) plants one. */
   stance?: number | 'off';
+  /** While a set whose arm is drawn raised shows, its wrist is placed against the rig's head in eye distances (rig-c/pose#62); false (the default) keeps the pose's angles. */
+  raisedByHead?: boolean;
 }
 
 export interface Hold {
@@ -272,6 +292,8 @@ export interface Retarget {
   ankles: { bones: Record<Side, string>; at: Record<Side, Pt[]> } | null;
   /** The translated bone's origin against its thigh roots' midpoint, at setup. */
   pivot: Pivot | null;
+  /** With --raised-by-head: each raised set's span on each raised chain, its wrist placed against the head. */
+  raised: Raised[];
 }
 
 /** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
@@ -368,6 +390,11 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const endOf = (i: number): number => (i + 1 < n ? keyTimes[i + 1]! : n > 1 ? 2 * keyTimes[i]! - keyTimes[i - 1]! : keyTimes[i]!);
   const secondsOf = (run: [number, number]): number => Math.round((endOf(run[1]) - keyTimes[run[0]]!) * 1e6) / 1e6;
 
+  // --raised-by-head (#62) measures against the head in eye distances: the map's head chain must carry the
+  // eye line with an "a>b" aim, whose two ends are the rig's eyes.
+  const head = opts.raisedByHead === true ? headOf(map) : null;
+  if (head !== null && 'problem' in head) p.add('RAISED_HEAD', head.problem);
+
   // Every point the map reads, held where it is not good.
   const needed = new Set<string>();
   for (const c of map.chains) c.joints.forEach((j) => needed.add(j));
@@ -713,29 +740,52 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     for (let a = rest.get(b)!.parent; a !== null; a = rest.get(a)!.parent) d++;
     return d;
   };
+  /** The world turn of `b`'s nearest mapped bone-or-ancestor, degrees, on frame i, by the targets as they stand. */
+  const turnAbove = (b: string, i: number): number => {
+    for (let a: string | null = b; a !== null; a = rest.get(a)!.parent) {
+      const tg = targets.get(a);
+      if (tg !== undefined) return tg[i]! - restOf.get(a)!;
+    }
+    return 0;
+  };
+  /**
+   * Where the poser will put `b`'s origin on frame i: forward from the
+   * translated bone (moved by its travel) or the root (at setup), each rest
+   * offset turned by the nearest mapped bone above — the key formula's own
+   * assumption (unit scale, no shear), which the landing check holds to account.
+   */
+  const posedOrigin = (b: string, i: number): Pt => {
+    const own = rest.get(b)!;
+    if (t !== null && b === t.bone) return [own.worldX + (travel[i]?.[0] ?? 0), own.worldY + (travel[i]?.[1] ?? 0)];
+    if (own.parent === null) return [own.worldX, own.worldY];
+    const parent = own.parent;
+    const po = posedOrigin(parent, i);
+    const r = turnAbove(parent, i) / DEG;
+    const ox = own.worldX - rest.get(parent)!.worldX;
+    const oy = own.worldY - rest.get(parent)!.worldY;
+    return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy, po[1] + Math.sin(r) * ox + Math.cos(r) * oy];
+  };
+  /** A rig point (a bone, `name:tip`, `a+b`) posed on frame i the same way. */
+  const posedPoint = (spec: string, i: number): Pt => {
+    let x = 0;
+    let y = 0;
+    const parts = pointParts(spec);
+    for (const part of parts) {
+      const name = partBone(part);
+      const o = posedOrigin(name, i);
+      const bone = rest.get(name)!;
+      const l = part.endsWith(':tip') ? bone.length : 0;
+      const r = turnAbove(name, i) / DEG;
+      x += o[0] + l * (Math.cos(r) * bone.a - Math.sin(r) * bone.c);
+      y += o[1] + l * (Math.sin(r) * bone.a + Math.cos(r) * bone.c);
+    }
+    return [x / parts.length, y / parts.length];
+  };
   const reaches = map.chains.filter((c) => c.reach).sort((x, y) => depth(x.bones[0]!) - depth(y.bones[0]!));
   let aimReach: ((c: Chain) => void) | null = null;
   if (reaches.length > 0 && t !== null && scale !== null) {
     const s = scale.factor;
     const tb = rest.get(t.bone)!;
-    /** The world turn of `b`'s nearest mapped bone-or-ancestor, degrees, on frame i. */
-    const turnAbove = (b: string, i: number): number => {
-      for (let a: string | null = b; a !== null; a = rest.get(a)!.parent) {
-        const tg = targets.get(a);
-        if (tg !== undefined) return tg[i]! - restOf.get(a)!;
-      }
-      return 0;
-    };
-    /** Where the poser will put `b`'s origin on frame i: forward from the translated bone. */
-    const posedOrigin = (b: string, i: number): Pt => {
-      if (b === t.bone) return [tb.worldX + travel[i]![0], tb.worldY + travel[i]![1]];
-      const parent = rest.get(b)!.parent!;
-      const po = posedOrigin(parent, i);
-      const r = turnAbove(parent, i) / DEG;
-      const ox = rest.get(b)!.worldX - rest.get(parent)!.worldX;
-      const oy = rest.get(b)!.worldY - rest.get(parent)!.worldY;
-      return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy, po[1] + Math.sin(r) * ox + Math.cos(r) * oy];
-    };
     aimReach = (c: Chain): void => {
       const b = c.bones[0]!;
       const anchor = series.get(c.joints[0]!)!;
@@ -793,8 +843,214 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
   }
   p.throwIfAny();
-  const artRange = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
+
+  // --raised-by-head (#62, HQ's ruling): while a set whose arm is drawn raised shows, its wrist goes where
+  // the reference's is against the head, in eye distances (each side's median over the span). Solved last
+  // of the bones: every bone above the arm, the head and the trunk's reach included, has its final target
+  // (range clamp done), so the head and the shoulder are posed from them frame by frame; the arm moves
+  // neither. A target out of reach is placed at the reach limit along the head-relative direction
+  // (`reachLimit`, a REACH line). The set's `turn` is part of the solve: a held upper arm has its forearm
+  // re-aimed at the placed wrist, and only a forearm the turn still holds is ART-RANGE.
+  const raised: Raised[] = [];
+  const raisedArt: Array<{ sw: Switch; entries: ArtRange[] }> = [];
+  const raisedJobs: Array<{ sw: Switch; chain: Chain; wrist: (i: number) => Pt; before: Pt[]; reference: Pt[]; placed: Pt[]; refEye: number; rigEye: number; short: Array<{ i: number; how: 'far' | 'near' | 'missed'; shortfall: number }>; upperHeld: number[]; l0: number; l1: number; farthest: number; eyePoints: [string, string] }> = [];
+  if (head !== null && !('problem' in head)) {
+    const eyesOn = (i: number): { centre: Pt; dist: number } => {
+      const a = posedPoint(head.points[0], i);
+      const b = posedPoint(head.points[1], i);
+      return { centre: [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2], dist: Math.hypot(b[0] - a[0], b[1] - a[1]) };
+    };
+    const headBones = new Set([...head.points.flatMap((x) => pointParts(x).map(partBone))]);
+    const ra = series.get(head.joints[0])!;
+    const rb = series.get(head.joints[1])!;
+    const refCentre = (i: number): Pt => [(ra[i]![0] + rb[i]![0]) / 2, (ra[i]![1] + rb[i]![1]) / 2];
+    for (const s of sw.switches) {
+      const set = map.alternates.find((a) => a.name === s.set)!;
+      const art: ArtRange[] = [];
+      for (const cn of s.chains) {
+        const c = map.chains.find((x) => x.name === cn)!;
+        const drawn = set.drawn[c.bones[0]!];
+        if (drawn === undefined || !isRaised(drawn)) continue;
+        const label = `--raised-by-head: set "${set.name}" draws chain "${c.name}" raised (bone "${c.bones[0]}" at ${drawn}°)`;
+        if (c.bones.length !== 2) {
+          p.add('RAISED_CHAIN', `${label}, and the chain has ${c.bones.length} bone(s); the wrist is placed by a two-bone solve, so it must have two (upper arm, forearm)`);
+          continue;
+        }
+        if (c.reach || c.aim.some((x) => x.includes('>'))) {
+          p.add('RAISED_CHAIN', `${label}, and it aims ${JSON.stringify(c.aim)}${c.reach ? ' with "reach"' : ''}; the solve turns each bone about its own origin toward the next point, so each must aim "x" or at one point`);
+          continue;
+        }
+        const [b0, b1] = c.bones as [string, string];
+        const moved = [...headBones].filter((h) => h === b0 || h === b1 || descends(rest, h, b0));
+        if (moved.length > 0) {
+          p.add('RAISED_CHAIN', `${label}, and the head's eye point ${moved.map((h) => `"${h}"`).join(', ')} turns with it; the wrist cannot be placed against a head the arm moves`);
+          continue;
+        }
+        const wristSpec = c.aim[1] === 'x' ? `${b1}:tip` : c.aim[1]!;
+        if (c.aim[1] === 'x' && !(rest.get(b1)!.length > 1e-9)) {
+          p.add('RAISED_CHAIN', `${label}, and its last bone "${b1}" aims "x" with no length; its wrist (the tip) is its origin, so there is nothing to place`);
+          continue;
+        }
+        const wristOf = (i: number): Pt => posedPoint(wristSpec, i);
+        const refWrist = series.get(c.joints[2]!)!;
+        // The unit, each side's median over the span (HQ's ruling).
+        const span: number[] = [];
+        for (let i = s.frames[0]; i <= s.frames[1]; i++) span.push(i);
+        const refEye = median(span.map((i) => Math.hypot(rb[i]![0] - ra[i]![0], rb[i]![1] - ra[i]![1])));
+        const rigEye = median(span.map((i) => eyesOn(i).dist));
+        if (!(refEye > 1e-9) || !(rigEye > 1e-9)) {
+          p.add('RAISED_EYES', `${label}: over frames ${s.frames[0]}–${s.frames[1]} the median eye distance is ${refEye > 1e-9 ? `${rigEye} units on the rig (points "${head.points[0]}", "${head.points[1]}")` : `${refEye}px in the reference (${head.joints[0]}, ${head.joints[1]})`}; an eye distance of 0 is no unit`);
+          continue;
+        }
+        // The rig's own lengths, and each bone's aim against the vector it carries, at setup.
+        const S0 = rigPoint(rest, b0)!;
+        const E0 = rigPoint(rest, b1)!;
+        const W0 = rigPoint(rest, wristSpec)!;
+        const l0 = Math.hypot(E0[0] - S0[0], E0[1] - S0[1]);
+        const l1 = Math.hypot(W0[0] - E0[0], W0[1] - E0[1]);
+        const d0 = wrap(Math.atan2(E0[1] - S0[1], E0[0] - S0[0]) * DEG - restOf.get(b0)!);
+        const d1 = wrap(Math.atan2(W0[1] - E0[1], W0[0] - E0[0]) * DEG - restOf.get(b1)!);
+        const t0 = targets.get(b0)!;
+        const t1 = targets.get(b1)!;
+        const turn0 = set.turn[b0];
+        const turn1 = set.turn[b1];
+        const job: (typeof raisedJobs)[number] = { sw: s, chain: c, wrist: wristOf, before: [], reference: [], placed: [], refEye, rigEye, short: [], upperHeld: [], l0, l1, farthest: 0, eyePoints: head.points };
+        /** Per frame of the span: the forearm's art turn the re-aim asked, and how far past its turn. */
+        const foreAsked: number[] = [];
+        const foreOver: number[] = [];
+        /** Per frame of the span: the upper arm's art turn the solve asked, how far past its turn, and — where the turn held it — how far the wrist ends from its placed point, eye distances (0 elsewhere). */
+        const upperAsked: number[] = [];
+        const upperOver: number[] = [];
+        const heldMiss: number[] = [];
+        for (const i of span) {
+          const h = eyesOn(i);
+          const rc = refCentre(i);
+          // The reference's wrist from its head centre, in its eye distances, y turned up.
+          const ref: Pt = [(refWrist[i]![0] - rc[0]) / refEye, -(refWrist[i]![1] - rc[1]) / refEye];
+          const w = wristOf(i);
+          job.reference.push(ref);
+          job.before.push([(w[0] - h.centre[0]) / rigEye, (w[1] - h.centre[1]) / rigEye]);
+          const target: Pt = [h.centre[0] + ref[0] * rigEye, h.centre[1] + ref[1] * rigEye];
+          const shoulder = posedOrigin(b0, i);
+          job.farthest = Math.max(job.farthest, Math.hypot(target[0] - shoulder[0], target[1] - shoulder[1]));
+          const place = reachLimit(h.centre, target, shoulder, l0, l1);
+          const P = place.point;
+          job.placed.push([(P[0] - h.centre[0]) / rigEye, (P[1] - h.centre[1]) / rigEye]);
+          if (place.how !== 'in') job.short.push({ i, how: place.how, shortfall: Math.hypot(target[0] - P[0], target[1] - P[1]) / rigEye });
+          // The pose's bend side, read on the vectors the two bones carry.
+          const side: 1 | -1 = wrap(t1[i]! + d1 - (t0[i]! + d0)) >= 0 ? 1 : -1;
+          const sol = twoBone(shoulder, P, l0, l1, side);
+          if (sol.upper === null) {
+            foreAsked.push(wrap(t1[i]! - (set.drawn[b1] ?? 0)));
+            foreOver.push(0);
+            upperAsked.push(0);
+            upperOver.push(0);
+            heldMiss.push(0);
+            continue;
+          }
+          let a0 = wrap(sol.upper - d0);
+          let a1 = wrap(sol.fore - d1);
+          // The set's turn holds the upper arm; the forearm is then re-aimed at the placed wrist from where the held upper arm puts the elbow.
+          let held = false;
+          const tt = turn0 === undefined ? 0 : wrap(a0 - set.drawn[b0]!);
+          upperAsked.push(tt);
+          upperOver.push(turn0 === undefined ? 0 : overflow(tt, turn0));
+          if (turn0 !== undefined) {
+            const cl = Math.min(Math.max(tt, turn0[0]), turn0[1]);
+            if (Math.abs(cl - tt) > RANGE_SLACK) {
+              held = true;
+              a0 = wrap(set.drawn[b0]! + cl);
+              job.upperHeld.push(i);
+              const r = (a0 + d0) / DEG;
+              const E: Pt = [shoulder[0] + l0 * Math.cos(r), shoulder[1] + l0 * Math.sin(r)];
+              a1 = wrap(Math.atan2(P[1] - E[1], P[0] - E[0]) * DEG - d1);
+            }
+          }
+          // A forearm the turn still holds: the re-aim failed within the art's range — ART-RANGE.
+          const asked = turn1 === undefined ? 0 : wrap(a1 - set.drawn[b1]!);
+          const over = turn1 === undefined ? 0 : overflow(asked, turn1);
+          foreAsked.push(asked);
+          foreOver.push(over);
+          if (turn1 !== undefined && over > RANGE_SLACK) a1 = wrap(set.drawn[b1]! + Math.min(Math.max(asked, turn1[0]), turn1[1]));
+          // Where the held arm leaves the wrist: the re-aimed forearm points at the placed point, but from a held
+          // elbow its length need not reach it (rule 3, "cannot reach within turn").
+          const r0 = (a0 + d0) / DEG;
+          const r1 = (a1 + d1) / DEG;
+          const W: Pt = [shoulder[0] + l0 * Math.cos(r0) + l1 * Math.cos(r1), shoulder[1] + l0 * Math.sin(r0) + l1 * Math.sin(r1)];
+          heldMiss.push(held ? Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye : 0);
+          t0[i] = a0;
+          t1[i] = a1;
+        }
+        // A held upper arm whose re-aimed forearm leaves the wrist more than HELD_MISS short of its placed point: ART-RANGE on the upper arm, with the shortfall.
+        if (turn0 !== undefined) {
+          for (const [a, b] of runsOf(heldMiss.map((m) => m > HELD_MISS), RANGE_GAP)) {
+            let worst = a;
+            for (let k = a; k <= b; k++) if (heldMiss[k]! > heldMiss[worst]!) worst = k;
+            const first = s.frames[0] + a;
+            const last = s.frames[0] + b;
+            art.push({ set: set.name, chain: c.name, bone: b0, frames: [first, last], seconds: r6(endOf(last) - keyTimes[first]!), maxOverflow: r3(upperOver[worst]!), turn: r3(upperAsked[worst]!), limits: turn0, clamped: true, shortfall: r3(heldMiss[worst]!) });
+          }
+        }
+        if (turn1 !== undefined) {
+          for (const [a, b] of runsOf(foreOver.map((o) => o > RANGE_SLACK), RANGE_GAP)) {
+            let worst = a;
+            for (let k = a; k <= b; k++) if (foreOver[k]! > foreOver[worst]!) worst = k;
+            const first = s.frames[0] + a;
+            const last = s.frames[0] + b;
+            art.push({ set: set.name, chain: c.name, bone: b1, frames: [first, last], seconds: r6(endOf(last) - keyTimes[first]!), maxOverflow: r3(foreOver[worst]!), turn: r3(foreAsked[worst]!), limits: turn1, clamped: true });
+          }
+        }
+        raisedJobs.push(job);
+      }
+      art.sort((x, y) => x.frames[0] - y.frames[0]);
+      if (art.length > 0) raisedArt.push({ sw: s, entries: art });
+    }
+  }
+  p.throwIfAny();
+  // The art turn of every span; a raised chain's bones were held by the solve, and only its re-aimed forearm is listed (above).
+  const measured = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
+  const solvedBy = (e: ArtRange, s: Switch) => raisedJobs.some((j) => j.sw === s && j.chain.name === e.chain);
+  const artRange: ArtRange[] = [];
+  for (const s of sw.switches) {
+    const own = measured.filter((e) => e.set === s.set && e.frames[0] >= s.frames[0] && e.frames[1] <= s.frames[1]);
+    artRange.push(...own.filter((e) => !solvedBy(e, s)), ...(raisedArt.find((x) => x.sw === s)?.entries ?? []));
+  }
   clampArt(sw.switches, map, targets);
+  // Where each raised wrist lands as keyed: after the solve and the set's `turn`.
+  for (const job of raisedJobs) {
+    const after: Pt[] = [];
+    for (let i = job.sw.frames[0]; i <= job.sw.frames[1]; i++) {
+      const a = posedPoint(job.eyePoints[0], i);
+      const b = posedPoint(job.eyePoints[1], i);
+      const w = job.wrist(i);
+      after.push([(w[0] - (a[0] + b[0]) / 2) / job.rigEye, (w[1] - (a[1] + b[1]) / 2) / job.rigEye]);
+    }
+    const worst = (rig: readonly Pt[]): Pt => [Math.max(...rig.map((v, k) => Math.abs(v[0] - job.reference[k]![0]))), Math.max(...rig.map((v, k) => Math.abs(v[1] - job.reference[k]![1])))].map(r6) as Pt;
+    const round = (vs: readonly Pt[]): Pt[] => vs.map((v) => [r6(v[0]), r6(v[1])]);
+    const short: ReachShort[] = [];
+    for (let k = 0; k < job.short.length;) {
+      let m = k;
+      while (m + 1 < job.short.length && job.short[m + 1]!.i === job.short[m]!.i + 1 && job.short[m + 1]!.how === job.short[k]!.how) m++;
+      const fs = job.short.slice(k, m + 1).map((x) => x.shortfall);
+      short.push({ frames: [job.short[k]!.i, job.short[m]!.i], how: job.short[k]!.how, shortfall: { max: r6(Math.max(...fs)), median: r6(median(fs)) } });
+      k = m + 1;
+    }
+    raised.push({
+      set: job.sw.set,
+      chain: job.chain.name,
+      frames: job.sw.frames,
+      seconds: secondsOf(job.sw.frames),
+      eyes: { rig: r6(job.rigEye), reference: r6(job.refEye) },
+      reference: round(job.reference),
+      placed: round(job.placed),
+      before: round(job.before),
+      after: round(after),
+      worst: { before: worst(job.before), after: worst(after), placed: r6(Math.max(...after.map((v, k) => Math.hypot(v[0] - job.placed[k]![0], v[1] - job.placed[k]![1])))) },
+      short,
+      upperHeld: job.upperHeld,
+      reach: { min: r6(Math.abs(job.l0 - job.l1)), max: r6(job.l0 + job.l1), farthest: r6(job.farthest) },
+    });
+  }
 
   // The legs on their final targets: a bone under a scaled bone is keyed through
   // its parent's posed matrix (legs.ts), and each ankle's world position is read.
@@ -854,10 +1110,34 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs),
+    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised,
   };
 }
 
+/** The head as --raised-by-head reads it: the chain carrying the eye line, its two pose joints and the rig's two eye points. */
+interface Head {
+  chain: string;
+  joints: [string, string];
+  points: [string, string];
+}
+
+/** The map's head chain (the one carrying r_eye → l_eye, either way round) and its "a>b" aim; or why there is none to read. */
+function headOf(map: JointMap): Head | { problem: string } {
+  const lead = '--raised-by-head places a raised arm\'s wrist against the head in eye distances, read on the rig between the two points the head chain\'s "a>b" aim names';
+  for (const c of map.chains) {
+    for (let k = 0; k + 1 < c.joints.length; k++) {
+      const a = c.joints[k]!;
+      const b = c.joints[k + 1]!;
+      if (!((a === 'r_eye' && b === 'l_eye') || (a === 'l_eye' && b === 'r_eye'))) continue;
+      const aim = c.aim[k]!;
+      if (!aim.includes('>')) return { problem: `${lead}; chain "${c.name}" carries ${a} → ${b} on bone "${c.bones[k]}", and aims it ${JSON.stringify(aim)}, not "a>b" between the rig's eye points` };
+      const [pa, pb] = aimEnds(c.bones[k]!, aim);
+      return { chain: c.name, joints: [a, b], points: [pa, pb] };
+    }
+  }
+  return { problem: `${lead}; no chain of the map carries the eye line (joints r_eye → l_eye), so the rig has no eye points to measure` };
+}
+
 type ShortSpan = Omit<Short, 'chain' | 'bone' | 'joints'>;
 
 /**

package/src/run.ts

@@ -8,13 +8,13 @@ import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeF
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { readMap, resolveMap, type JointMap, type Rest } from './map.ts';
-import { cleanLine } from './clean.ts';
+import { cleanLine, inferredSource } from './clean.ts';
 import { convertCoco17, personTrack, readPoseSequence, type CameraFrame } from './pose.ts';
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
-import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
+import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
 import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf } from './legs.ts';
 import { reduceKeys, type ReduceBone, type Reduced } from './reduce.ts';
@@ -108,7 +108,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
-    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
+    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     say(`  CLEAN  ${cleanLine(seq.cleaned!)}`);
     if (a.smoothAlias !== undefined) say(`  SMOOTH --smooth is carried by clean; ignored (given ${a.smoothAlias}; this sequence was cleaned with legs ${seq.cleaned!.params.legs}, rest ${seq.cleaned!.params.rest})`);
@@ -130,6 +130,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
     }
     for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
+    if (a.raisedByHead === true && r.raised.length === 0) say(`  RAISED none — no set drawing an arm within ${RAISED_WITHIN}° of straight up showed; no key moved`);
+    for (const e of r.raised) say(`  RAISED ${raisedLine(e, r.times)}`);
+    for (const e of r.raised) if (e.short.length > 0) say(`  REACH  ${reachLine(e, r.times)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
     for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times)}`);
     if (r.pivot !== null) say(`  PIVOT  bone "${r.pivot.bone}"'s origin is ${r.pivot.distance.toFixed(2)} units (${r.pivot.hipWidths.toFixed(3)} hip widths) from its thigh roots' midpoint (${r.pivot.roots.join(' + ')}): dx ${r.pivot.offset[0].toFixed(2)}, dy ${r.pivot.offset[1].toFixed(2)}, at setup — the pivot every hip turn swings the legs about`);
@@ -225,7 +228,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     p.throwIfAny();
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
-    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore);
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned));
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
@@ -273,7 +276,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         frames: seq.frames.length,
         duration: r.animation.duration,
         cleaned: seq.cleaned,
-        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
+        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -289,6 +292,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         turns: r.turns,
         range: r.range,
         artRange: r.artRange,
+        raised: r.raised,
         legScale: r.legScale.map(({ scale: _scale, ...rest }) => rest),
         pivot: r.pivot,
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, bounds: r.stance.bounds, runs: r.stance.runs, over: r.stance.over },

package/src/switch.ts

@@ -129,6 +129,8 @@ export interface ArtRange {
   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;
+  /** --raised-by-head (#62): on a held upper arm, the most the re-aimed forearm left the wrist short of its placed point, eye distances; `turn` and `maxOverflow` are then the upper arm's on that frame. */
+  shortfall?: number;
 }
 
 export interface Uncovered {
@@ -580,6 +582,9 @@ function moveText(m: Move): string {
 }
 
 export function artRangeLine(e: ArtRange, times: readonly number[]): string {
+  if (e.shortfall !== undefined) {
+    return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" held at its turn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s the re-aimed forearm leaves the wrist up to ${e.shortfall.toFixed(2)} eye distances short of its placed point (the upper arm asked ${sg(e.turn)} from drawn, ${deg(e.maxOverflow)} past) — 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`;
 }
 
@@ -603,3 +608,162 @@ export function clampArt(switches: readonly Switch[], map: JointMap, targets: Ma
     }
   }
 }
+
+/**
+ * A set's arm is raised (rig-c/pose#62) when its `drawn` world angle on the
+ * chain's first bone (the upper arm) is within this many degrees of straight up.
+ */
+export const RAISED_WITHIN = 30;
+
+/** Whether a drawn world angle, Spine degrees, is within `RAISED_WITHIN` of straight up (90°). */
+export const isRaised = (drawn: number): boolean => Math.abs(wrap(drawn - 90)) <= RAISED_WITHIN;
+
+type P2 = [number, number];
+
+/**
+ * A two-bone solve in the world (y up): the directions, degrees, of the vector
+ * from the shoulder to the elbow (`upper`) and from the elbow to the wrist
+ * (`fore`) that put the wrist on `target`, for bones of lengths `l0` and `l1`.
+ * `side` is the elbow's bend: +1 when the forearm turns counter-clockwise from
+ * the upper arm, −1 clockwise. Out of reach (farther than l0 + l1, nearer than
+ * |l0 − l1|, beyond a relative 1e-6) both point straight at the target and
+ * `reached` is false; on the shoulder, where there is no direction, `upper` is
+ * null. `reachLimit` puts a target inside first, so the raised solve always reaches.
+ */
+export function twoBone(shoulder: P2, target: P2, l0: number, l1: number, side: 1 | -1): { upper: number; fore: number; reached: boolean } | { upper: null; reached: false } {
+  const dx = target[0] - shoulder[0];
+  const dy = target[1] - shoulder[1];
+  const d = Math.hypot(dx, dy);
+  if (d < 1e-9) return { upper: null, reached: false };
+  const theta = Math.atan2(dy, dx) * (180 / Math.PI);
+  const eps = 1e-6 * Math.max(1, l0 + l1);
+  if (d > l0 + l1 + eps || d < Math.abs(l0 - l1) - eps) return { upper: theta, fore: theta, reached: false };
+  const cos = Math.min(1, Math.max(-1, (l0 * l0 + d * d - l1 * l1) / (2 * l0 * d)));
+  const upper = theta - side * Math.acos(cos) * (180 / Math.PI);
+  const r = upper * (Math.PI / 180);
+  const ex = shoulder[0] + l0 * Math.cos(r);
+  const ey = shoulder[1] + l0 * Math.sin(r);
+  return { upper: wrap(upper), fore: Math.atan2(target[1] - ey, target[0] - ex) * (180 / Math.PI), reached: true };
+}
+
+/** Where a raised wrist is placed: the target itself, or the reach limit (rig-c/pose#62, HQ's ruling). */
+export interface Placement {
+  point: P2;
+  /** `in`: the target is within reach. `far` / `near`: past l0 + l1, or nearer than |l0 − l1|, and placed on the ray from the head centre. `missed`: that ray never enters the reach; placed at the reach's point nearest the target. */
+  how: 'in' | 'far' | 'near' | 'missed';
+}
+
+/**
+ * The raised wrist's placement. The arm reaches the annulus about the shoulder
+ * between |l0 − l1| and l0 + l1. A target inside it is kept. Otherwise the wrist
+ * goes on the ray from the head centre through the target, at the point of
+ * that ray inside the annulus nearest the target — the reach limit along the
+ * head-relative direction. The ray can cross the annulus twice (out and back
+ * through the inner disc, or through the whole ring): of the reachable stretches
+ * the one nearest the target wins, a tie going to the point nearer the head. A
+ * ray that never enters it (`missed`) gives the annulus point nearest the
+ * target, on the line from the shoulder through it (toward the head centre when
+ * the target is on the shoulder).
+ */
+export function reachLimit(centre: P2, target: P2, shoulder: P2, l0: number, l1: number): Placement {
+  const rMin = Math.abs(l0 - l1);
+  const rMax = l0 + l1;
+  const eps = 1e-9 * Math.max(1, rMax);
+  const dT = Math.hypot(target[0] - shoulder[0], target[1] - shoulder[1]);
+  if (dT >= rMin - eps && dT <= rMax + eps) return { point: target, how: 'in' };
+  const how = dT > rMax ? 'far' : 'near';
+  const vx = target[0] - centre[0];
+  const vy = target[1] - centre[1];
+  const L = Math.hypot(vx, vy);
+  if (L > 1e-9) {
+    const u: P2 = [vx / L, vy / L];
+    // |C + s·u − S|² = s² + 2·s·b + c
+    const b = u[0] * (centre[0] - shoulder[0]) + u[1] * (centre[1] - shoulder[1]);
+    const c = (centre[0] - shoulder[0]) ** 2 + (centre[1] - shoulder[1]) ** 2;
+    const roots = (r: number): [number, number] | null => {
+      const disc = b * b - c + r * r;
+      return disc < 0 ? null : [-b - Math.sqrt(disc), -b + Math.sqrt(disc)];
+    };
+    const outer = roots(rMax);
+    const stretches: Array<[number, number]> = [];
+    if (outer !== null) {
+      const lo = Math.max(0, outer[0]);
+      const hi = outer[1];
+      const inner = rMin > 0 ? roots(rMin) : null;
+      if (hi >= lo) {
+        if (inner === null || inner[1] <= lo || inner[0] >= hi) stretches.push([lo, hi]);
+        else {
+          if (inner[0] > lo) stretches.push([lo, inner[0]]);
+          if (inner[1] < hi) stretches.push([inner[1], hi]);
+        }
+      }
+    }
+    let best: number | null = null;
+    for (const [lo, hi] of stretches) {
+      const s = Math.min(Math.max(L, lo), hi);
+      if (best === null || Math.abs(s - L) < Math.abs(best - L) - 1e-9 || (Math.abs(Math.abs(s - L) - Math.abs(best - L)) <= 1e-9 && s < best)) best = s;
+    }
+    if (best !== null) return { point: [centre[0] + best * u[0], centre[1] + best * u[1]], how };
+  }
+  const from: P2 = dT > 1e-9 ? target : centre;
+  const k = Math.hypot(from[0] - shoulder[0], from[1] - shoulder[1]) || 1;
+  const r = Math.min(Math.max(dT, rMin), rMax);
+  return { point: [shoulder[0] + (r * (from[0] - shoulder[0])) / k, shoulder[1] + (r * (from[1] - shoulder[1])) / k], how: 'missed' };
+}
+
+/** A run of frames whose target was out of reach, one way. */
+export interface ReachShort {
+  frames: [number, number];
+  how: 'far' | 'near' | 'missed';
+  /** |target − placed| in the rig's eye distances: the most, and the median, over the run. */
+  shortfall: { max: number; median: number };
+}
+
+/** One span of a raised set on one chain: its wrist placed against the head (rig-c/pose#62). */
+export interface Raised {
+  set: string;
+  chain: string;
+  frames: [number, number];
+  seconds: number;
+  /** The unit: the eye distance's median over the span, the rig's in world units, the reference's in picture px. */
+  eyes: { rig: number; reference: number };
+  /**
+   * Per frame of the span, the wrist's offset from the head centre in eye
+   * distances (x right, y up): the reference's; where the wrist was placed (the
+   * target, or the reach limit); the rig's on the pose's angles; the rig's as
+   * keyed.
+   */
+  reference: P2[];
+  placed: P2[];
+  before: P2[];
+  after: P2[];
+  /** The largest |rig − reference| over the span, x and y, before and after; and the largest |after − placed|, eye distances. */
+  worst: { before: P2; after: P2; placed: number };
+  /** The runs of frames out of the arm's reach (the REACH line). */
+  short: ReachShort[];
+  /** The frames whose upper arm the set's `turn` held: the forearm re-aimed at the placed wrist. */
+  upperHeld: number[];
+  /** The arm's reach (from |l0 − l1| to l0 + l1, world units from the shoulder) and the farthest target from the shoulder over the span. */
+  reach: { min: number; max: number; farthest: number };
+}
+
+const xy = (v: P2) => `(${v[0].toFixed(2)}, ${v[1].toFixed(2)})`;
+const framesText = (fs: readonly number[]): string => {
+  const flag: boolean[] = [];
+  for (const f of fs) flag[f] = true;
+  return runsOf(Array.from({ length: flag.length }, (_, i) => flag[i] === true), 0).map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
+};
+
+export function raisedLine(e: Raised, times: readonly number[]): string {
+  const med = (vs: readonly P2[]): P2 => [median(vs.map((v) => v[0])), median(vs.map((v) => v[1]))];
+  const held = e.upperHeld.length === 0 ? 'the upper arm within its turn on every frame' : `the upper arm held by the set's turn on ${e.upperHeld.length} frame(s) (${framesText(e.upperHeld)}), the forearm re-aimed`;
+  const out = e.short.length === 0 ? 'every target in reach' : `out of reach on ${e.short.reduce((k, s) => k + s.frames[1] - s.frames[0] + 1, 0)} frame(s) (REACH)`;
+  return `set "${e.set}" chain "${e.chain}" ${spanOf(e.frames, times)}: the wrist placed against the head; eye distance (median) rig ${e.eyes.rig.toFixed(2)} units, reference ${e.eyes.reference.toFixed(2)} px; wrist − head centre in eye distances (x right, y up), median reference ${xy(med(e.reference))}, placed ${xy(med(e.placed))}, before ${xy(med(e.before))}, after ${xy(med(e.after))}; worst |rig − reference| before ${xy(e.worst.before)}, after ${xy(e.worst.after)}; worst |after − placed| ${e.worst.placed.toFixed(2)}; ${held}; ${out}`;
+}
+
+/** The REACH line: a raised span whose target was out of the arm's reach on some frames — the proportions, not the art's range, were the limit. */
+export function reachLine(e: Raised, times: readonly number[]): string {
+  const why = { far: `farther than l0 + l1 = ${e.reach.max.toFixed(1)}`, near: `nearer than |l0 − l1| = ${e.reach.min.toFixed(1)}`, missed: 'and the ray from the head centre never enters the reach; placed at the reach\'s point nearest it' } as const;
+  const runs = e.short.map((s) => `${spanOf(s.frames, times)} ${s.how === 'missed' ? 'out of reach' : why[s.how]}${s.how === 'missed' ? `, ${why.missed}` : ''}: up to ${s.shortfall.max.toFixed(2)} eye distances short (median ${s.shortfall.median.toFixed(2)})`);
+  return `set "${e.set}" chain "${e.chain}": the target out of the arm's reach from the shoulder — ${runs.join('; ')}; the wrist placed at the reach limit along the head-relative direction (the farthest target ${e.reach.farthest.toFixed(1)} units from the shoulder). Not ART-RANGE: the rig's proportions, not the art's range, were the limit`;
+}

package/src/verify.ts

@@ -246,8 +246,19 @@ export interface Posture {
   rigShoulder: string | null;
   /** Reference frames on which the hips (tilt) and the hips and shoulders (sway) are all good. */
   frames: { tilt: number; sway: number; of: number };
-  /** Hip-line tilt, Spine degrees (r_hip → l_hip; the rig: the pelvis chain's aim). */
-  tilt: { reference: Range; rig: Range; ratio: number };
+  /**
+   * Hip-line tilt, Spine degrees (r_hip → l_hip; the rig: the pelvis chain's
+   * aim). Null when every frame with both hips good has an `inferred` hip
+   * (#63): the tilt is not read, and `tiltWhy` says why.
+   */
+  tilt: { reference: Range; rig: Range; ratio: number } | null;
+  /** Present only when `tilt` is null: why it was not read. */
+  tiltWhy?: string;
+  /**
+   * Present only when some frame with both hips good has an `inferred` hip:
+   * how many such frames the tilt left out, and where the state came from.
+   */
+  hipsInferred?: { frames: number; source: string };
   /**
    * Sway: the x-range of mid_hip − mid_shoulder, in rig units (the reference's
    * picture px × the figure scale) and in each body's own shoulder widths.
@@ -282,8 +293,17 @@ const medianOf = (xs: number[]): number => {
  * the joints it needs are good), the rig is the gated build posed by rig-c.
  * Null when the map has no pelvis chain (joints exactly r_hip, l_hip) or no
  * translate.
+ *
+ * Inferred hips (#63): a frame on which either hip is `inferred` is left out of
+ * the tilt — its hip line is a position the detector supplied but did not see,
+ * and a tilt read off it would be the detector's guess reported as the dancer's.
+ * When that is every frame (`clean --hips-inferred` marks them all), the tilt
+ * is null and `tiltWhy` names the reason and its source (`inferredSource`, read
+ * from the clean record). On some frames only, the tilt is read over the rest
+ * and the line counts the frames left out. Sway is read as before, inferred
+ * hips included: it is a different measure, and the card leaves it as it is.
  */
-export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number): Posture | null {
+export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number, inferredSource = 'source not stated'): Posture | null {
   const pelvis = map.chains.find((c) => c.joints.length === 2 && c.joints[0] === 'r_hip' && c.joints[1] === 'l_hip');
   if (pelvis === undefined || map.translate === null || r.origin === null || r.scale === null) return null;
   const s = r.scale.factor;
@@ -294,11 +314,13 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   const refTilt: number[] = [];
   const refSway: number[] = [];
   const refSw: number[] = [];
-  frames.forEach((_, i) => {
+  let inferred = 0;
+  frames.forEach((f, i) => {
     const rh = at(i, 'r_hip');
     const lh = at(i, 'l_hip');
     if (rh === null || lh === null) return;
-    refTilt.push(pictureAngle(rh, lh));
+    if (f.r_hip?.state === 'inferred' || f.l_hip?.state === 'inferred') inferred++;
+    else refTilt.push(pictureAngle(rh, lh));
     const rs = at(i, 'r_shoulder');
     const ls = at(i, 'l_shoulder');
     if (rs === null || ls === null) return;
@@ -307,9 +329,13 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   });
   const bone = pelvis.bones[0]!;
   const aim = pelvis.aim[0]!;
-  const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
-  const tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
-  tilt.ratio = tilt.rig.range / tilt.reference.range;
+  let tilt: Posture['tilt'] = null;
+  const why = `hips inferred (${inferredSource})`;
+  if (inferred === 0 || refTilt.length > 0) {
+    const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
+    tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
+    tilt.ratio = tilt.rig.range / tilt.reference.range;
+  }
 
   // The rig's mid-shoulder: the point a reach aims at, else the midpoint of the arms' first bones.
   const reach = map.chains.find((c) => c.reach);
@@ -340,7 +366,16 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       ratioSw: rig === null || rig.rangeSw === null ? null : rig.rangeSw / reference.rangeSw,
     };
   }
-  return { pelvis: pelvis.name, rigHip: r.origin.bone, rigShoulder, frames: { tilt: refTilt.length, sway: refSway.length, of: frames.length }, tilt, sway };
+  return {
+    pelvis: pelvis.name,
+    rigHip: r.origin.bone,
+    rigShoulder,
+    frames: { tilt: refTilt.length, sway: refSway.length, of: frames.length },
+    tilt,
+    ...(tilt === null ? { tiltWhy: why } : {}),
+    ...(inferred > 0 ? { hipsInferred: { frames: inferred, source: inferredSource } } : {}),
+    sway,
+  };
 }
 
 const f1 = (x: number) => x.toFixed(1);
@@ -350,8 +385,12 @@ const sg = (x: number) => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
 /** The POSTURE lines. */
 export function postureLines(q: Posture): string[] {
   const over = (k: number) => (k === q.frames.of ? '' : ` over ${k} of ${q.frames.of} frames`);
+  const t = q.tilt;
+  const left = q.hipsInferred === undefined ? '' : `; ${q.hipsInferred.frames} frame(s) with an inferred hip not read (${q.hipsInferred.source})`;
   const out = [
-    `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(q.tilt.reference.range)}° (${sg(q.tilt.reference.min)}° … ${sg(q.tilt.reference.max)}°${over(q.frames.tilt)}), rig ${f1(q.tilt.rig.range)}° (${sg(q.tilt.rig.min)}° … ${sg(q.tilt.rig.max)}°) — rig/reference ${f3(q.tilt.ratio)}`,
+    t === null
+      ? `hip tilt not read: ${q.tiltWhy}`
+      : `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(t.reference.range)}° (${sg(t.reference.min)}° … ${sg(t.reference.max)}°${over(q.frames.tilt)}), rig ${f1(t.rig.range)}° (${sg(t.rig.min)}° … ${sg(t.rig.max)}°) — rig/reference ${f3(t.ratio)}${left}`,
   ];
   const w = q.sway;
   if (w === null) out.push('sway: the reference has no frame with both hips and both shoulders good; not measured');