@rig-c/pose 0.42.0 → 0.43.0

package/README.md

@@ -104,7 +104,7 @@ A retarget of the cleaned `dance-a` fixture finds the same jumps (`FEET`) as the
 ## The pelvis track: `rig-pose pelvis`
 
 ```sh
-rig-pose pelvis --pose dance.scan.json --frames frames/ --out dance.pelvis.json [--mode silhouette|waistband] [--person <id>]
+rig-pose pelvis --pose dance.scan.json --frames frames/ --out dance.pelvis.json [--mode silhouette|waistband|below-cover] [--person <id>]
 rig-pose pelvis --pose dance.scan.json --pelvis-keys pelvis.keys.json --out dance.pelvis.json
 ```
 
@@ -114,12 +114,13 @@ A pose detector keeps little of a drawn pelvis tilt ([#288](https://github.com/r
 
 - **`silhouette`** (the default): the straightest edge of the drawn figure across the hip span, near the hips' height. An edge pixel is a figure pixel (a channel more than 64 from the background colour, the median of the frame's border) beside a background pixel, so a drawn outline and a filled shape both have one. Every straight line within ±40° of level and one hip width of the hips is scored by the edge pixels within 1 px of it; the best is read when its pixels cover at least 60 % of the span's columns, and fitted by least squares (one 3-MAD rejection pass) within 2.5 px rms. It reads a drawn pelvis line, or the edge of a drawn hip.
 - **`waistband`**: the top edge of a garment covering the hips (a skirt, shorts). The garment's colour is the median at the hips' midpoint, and must not be the background's. In each column of the span, the first row from 1.5 hip widths above the hips where three pixels in a row carry it (within 40 per channel) is the top edge, and the line is fitted through those tops on the same terms. The colour must **hold** on its patch: at least 75 % of the patch's pixels carry its median ([#293](https://github.com/rig-c/pose/issues/293)). A dithered or paletted garment (a 216-colour GIF, whose channels alternate between palette steps pixel by pixel) does not, so its pixels are read through the mean of a 5×5 window, which does. Hips on the band's top edge give a patch that is half garment and half ground, so the patch is also tried one and two patch radii (0.3 hip widths) below the hips, and the scan then runs down to that patch. The first patch that holds and is not the background gives the colour, trying each height as is and then through the window mean. If none holds, the midpoint's median is read as before. The `PELVIS` line counts the frames read through the window mean and those whose colour was found below the hips.
+- **`below-cover`** ([#342](https://github.com/rig-c/pose/issues/342)): for a garment whose top is hidden under another — a sweater's hem lying over a skirt's waistband hangs level whatever the pelvis does, so the band-top reader reads the cover. It reads what the cover cannot hide, every colour through the 5×5 window mean, a pixel being garment when it is nearer the garment's colour than each leg's (sampled 0.7 of the way hip → knee) and the ground's: the **hem** (in each column of the span, the last garment row before three that are not; a line fitted through them), the **thigh roots** (along each hip → knee, where the garment stops for 3 px; the line from the right root to the left), and the waistband's band top only when the ground lies above it. The tilt is the mean of the cues; fewer than two, or two more than 8° apart, decline the frame by name (`too few cues below the cover`, `cues disagree`). A `CUES` line per frame prints every cue and the hip keypoints' line and sign beside the fit's; the hips are reported, not fitted (a detector's hips keep a fraction of a drawn tilt), and a `HIPS-SIGN` line names a frame where their sign is opposite the fit's. On the synthetic walk with shorts turned with the drawn pelvis under a level sweater (`sweater`), every frame reads within 1.5° of the drawn tilt; the `waistband` reader reads the sweater's level hem there. **Known limit:** a thigh drawn in front of the garment (raised toward the camera) is read as the hem — its outline over the cloth looks like the hem's edge, and the hem and that thigh's root agree on it — so those frames must be declined by hand (set their `pelvisTilt` to null, or leave them out of `--pelvis-keys`). Reading them is [#349](https://github.com/rig-c/pose/issues/349).
 
 Both pass over the forearms: pixels within 0.15 hip widths of a segment elbow → wrist (1.5 times that of a wrist, the hand) are not read, and a waistband top right under a forearm is not taken. A frame neither reader can read is **declined**: its `pelvisTilt` is `null` — marked, not guessed — and a `DECLINED` line names the frames and the reason (the pelvis blank, no garment, no straight edge across 60 % of the span, the hips side-on or missing). The `PELVIS` line counts the frames read and declined and gives the swing read.
 
 `--pelvis-keys` is the hand override where neither reader applies: `rig-pose-pelvis-keys/1`, `{ "spec": "rig-pose-pelvis-keys/1", "keys": [ { "frame", "deg" } ], "note"? }`. Frames are the sequence's and strictly increase, `deg` is in `pelvisTilt`'s sense; the tilt is linear between keys, the short way round, and held before the first and after the last. A frame may be fractional ([#294](https://github.com/rig-c/pose/issues/294)): a scan interpolated from drawn keys puts them between its frames — k × 4.75 for 8 keys over 38 frames — and a key rounded onto the grid moves up to half a frame and bends the tilt between. On that synthetic case (24 fps, a known tilt sampled at the keys' times), the tilt written on every frame is the keys' linear interpolation within 0.0005° (the writer's rounding), where the same keys rounded to whole frames miss it by up to 1.19° (`test/pelvis.test.ts`). A key outside the sequence's span, `[0, frames − 1]`, is refused by name. Fractional frames stay `/1`: they are a wider value of the same key, and a reader before #294 refuses them by name (`"frame" is number 4.75; it must be a frame index in [0, N]`) rather than misreading them. Anything malformed is refused by name (`PELVIS_KEYS`), and the source is `"keys"`. `--person` picks the person when there is more than one, and only that person is written.
 
-**The track** is `pelvisTilt` on every frame and `pelvisSource` (`"silhouette"`, `"waistband"` or `"keys"`) on the sequence, written as `rig-pose-sequence/1.1` ([below](#the-pose-rig-pose-sequence1)). `pelvisTilt` is Spine degrees — counter-clockwise, y up — of the direction from the figure's right hip to its left, the angle `retarget` reads off `r_hip → l_hip`: about 0 for a figure facing the camera, about ±180 facing away.
+**The track** is `pelvisTilt` on every frame and `pelvisSource` (`"silhouette"`, `"waistband"`, `"below-cover"` or `"keys"`) on the sequence, written as `rig-pose-sequence/1.1` ([below](#the-pose-rig-pose-sequence1)). `pelvisTilt` is Spine degrees — counter-clockwise, y up — of the direction from the figure's right hip to its left, the angle `retarget` reads off `r_hip → l_hip`: about 0 for a figure facing the camera, about ±180 facing away.
 
 **`clean`** smooths `pelvisTilt` as its own track, not re-read from the hips: the quadratic Savitzky–Golay over the legs' window (`--legs`, the hips' window), circular with `--loop`, on the frames that carry a reading — a `null` stays `null`. It prints a `PELVIS` line with the largest change, and records `"pelvis": { "window" }` in the record's `params` (the `CLEAN` line ends `pelvisTilt smoothed as its own track over N frames`). A sequence with a track whose record lacks it — the track added after `clean` — is refused by name (`POSE_PELVIS`).
 
@@ -168,15 +169,15 @@ With `--draw-order depth` (off by default; without it nothing changes) `retarget
 
 - **The pair.** The legs: a leg is the map's chains naming its knee or ankle, their bones and the bones under them no other chain maps. Its slots are the slots on those bones. A slot of an alternate set (`alternates`) on none of them goes with the leg the set depicts, so a set keeps its own switch and takes the order of the leg it replaces. The legs are keyed when their slots overlap in the draw order, filling one unbroken run of the setup order. A slot of anything else drawn between them would be re-layered by the swap, and the setup order is not changed here. The pair is then not keyed, and the line names that slot. The arms across the trunk are a later card.
 - **The rule.** On each frame the leg whose depth is the lower is drawn behind: its slots first in the pair's run, in their setup order, then the other's. The depths must differ by at least a tie, the depth a flat chain can hold there. Inside the tie, or where a leg is not ordered, the order before holds. Before the first decided frame it is the setup order, or on a looped sequence the order the clip ends in. A key is written where the order changes.
-- **The joint the gait names** ([#336](https://github.com/rig-c/pose/issues/336), the owner's two statements). On a sequence cleaned with `--depth walk` a leg's depth is its ankle's (the hip at 0, plus the thigh's, plus the shin's), the tie √(1 − 0.95²) × (thigh + shin) of the rest lengths (46.83 px on the fixtures): in a walk the lifted foot is behind the supporting leg. With `--depth run` it is its knee's (the thigh's), the tie √(1 − 0.95²) × thigh (24.97 px): in a run the lifted leg is in front, its knee protruding. The limb mean (`layers`, above) says neither: a lifted leg's thigh forward and shin back cancel in it, and a walk whose thighs stay inside the band leaves it at most half a shin (35 px on the fixtures), under its tie of √(1 − 0.95²) × (thigh + shin ÷ 2) (35.89 px). A measured depth names no gait and keeps the limb mean and its tie ([#304](https://github.com/rig-c/pose/issues/304)).
+- **The joint the gait names** ([#336](https://github.com/rig-c/pose/issues/336), the owner's two statements). On a sequence cleaned with `--depth walk` a leg's depth is its ankle's (the hip at 0, plus the thigh's, plus the shin's), the tie √(1 − 0.95²) × (thigh + shin) of the rest lengths (46.83 px on the fixtures): in a walk the lifted foot is behind the supporting leg. With `--depth run` it is its knee's (the thigh's), the tie √(1 − 0.95²) × thigh (24.96 px): in a run the lifted leg is in front, its knee protruding. The limb mean (`layers`, above) says neither: a lifted leg's thigh forward and shin back cancel in it, and a walk whose thighs stay inside the band leaves it at most half a shin (35 px on the fixtures), under its tie of √(1 − 0.95²) × (thigh + shin ÷ 2) (35.89 px). A measured depth names no gait and keeps the limb mean and its tie ([#304](https://github.com/rig-c/pose/issues/304)).
 - **No depth.** On a sequence without depth the flag is refused (`DRAWORDER_NO_DEPTH`): the order would come from nowhere, and a motion written without it would read as ordered.
 - **A walk cleaned before #336** ([#336](https://github.com/rig-c/pose/issues/336)). A derived depth whose foreshortened shin leans the way the trunk faces carries the sign table before #336, where a walk's lifted foot read forward; the ankle would draw that foot in front. The flag refuses it by name (`DEPTH_RECLEAN`), listing the frames, until it is cleaned again with this version. The table since leans the shin back in both gaits, so a record it wrote never matches. A run's signs did not change, so a run cleaned by an earlier release is read as it is, and so is a walk with no foreshortened shin (its signs read the same under both tables). Measured depth is not checked. The file format does not change.
 
 On #281's fixtures, retargeted onto a limb-cut rig whose legs overlap (the left leg drawn first; `test/draworder.test.ts`):
 
 - **The walk** (by the ankle): each of the 36 frames with one leg lifted draws that leg behind; the order changes on frames 3, 15, 27 and 39, where a lifted foot first goes back past the tie, and holds through the double support between. The generator orders the true ankles on 16 of the 48 frames, and the keyed order agrees on all 16.
-- **The run** (by the knee): the order changes on frames 2, 12, … 52. Of the 42 frames with one leg lifted, the 30 whose lifted knee protrudes (its thigh leaning forward past the band) draw that leg in front. The other 12 (frames 0–1, 10–11, …) are the early swing: the lifted thigh is still inside the band, the generator's knees are within the tie, and the order holds — the landing leg in front, as the generator's ankles have it. The generator orders the true knees on 42 of the 60 frames, and the keyed order agrees on all 42. On frame 12, on a rig that draws the right leg first, none of the 8,763 pixels the lifted right leg draws shows the standing leg, against 2,192 in the setup order.
-- **Read otherwise**: by the limb mean or by the ankle, the run draws the lifted leg behind on all 30 frames whose knee protrudes; by the limb mean or by the knee, the walk keys nothing (the setup order) and draws the lifted right leg in front on its 18 frames. Knees planted 10 px apart, inside the knee tie, hold the order before; without the tie they swap it.
+- **The run** (by the knee): the order changes on frames 0, 10, … 50, where the other foot lands. The generator's swing thigh flexes forward from toe-off ([#343](https://github.com/rig-c/pose/issues/343)), so on each of the 42 frames with one leg lifted the lifted knee is in front of the supporting one, its thigh leaning forward past the band, and that leg is drawn in front. The generator orders the true knees on 42 of the 60 frames, and the keyed order agrees on all 42. On frame 12, on a rig that draws the right leg first, none of the 8,771 pixels the lifted right leg draws shows the standing leg, against 2,205 in the setup order.
+- **Read otherwise**: by the limb mean or by the ankle, the run draws the lifted leg behind on 21 of its 42 lifted frames; by the limb mean or by the knee, the walk keys nothing (the setup order) and draws the lifted right leg in front on its 18 frames. Knees planted 10 px apart, inside the knee tie, hold the order before; without the tie they swap it.
 
 ## What it does
 
@@ -228,7 +229,7 @@ and what the run cannot decide for you it lists:
 - `REACH` — with `--raised-by-head`, or a `"by-hip"` set: a placed 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 (hip widths for `"by-hip"`). 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 in px and as a share of `FEET`'s leg length, the spread of its picture length over it, the limits in px, the frames clamped at each limit, where its leg was free on clamped frames how far the clamps on that leg left the free ankle above or below the picture's (in the rig's leg at setup, thigh origin → ankle, and in `FEET`'s px; `legScale[].free` in the report, [#237](https://github.com/rig-c/pose/issues/237)), and (with `--plant-feet`) one `past the floor (support)` line per supporting run that asked under the floor ([#133](https://github.com/rig-c/pose/issues/133), `legScale[].support` in the report).
 - `DEPTH` — when the sequence carries depth ([above](#derived-depth-clean---depth)): where it came from, on how many frames the limbs were ordered front to back, and which limb was in front alone how often — `DEPTH  layers from the sequence's derived depth (clean --depth run): the limbs ordered front to back on N of N frame(s); in front alone: r_arm a, l_arm b, r_leg c, l_leg d; tied in front on k (the report's layers)`.
-- `DRAWORDER` — with `--draw-order depth` ([above](#draw-order-from-depth---draw-order-depth)): the keys and the spans they key, per leg drawn behind, cut to 260 characters — `DRAWORDER from depth by the knee (run; tie 24.97 px), 6 key(s) over 3 span(s) (leg_r behind leg_l 2–11, 22–31, 42–51)`, naming the joint and its tie for a keyed pair ([#336](https://github.com/rig-c/pose/issues/336)) — and a line per pair not keyed, saying why.
+- `DRAWORDER` — with `--draw-order depth` ([above](#draw-order-from-depth---draw-order-depth)): the keys and the spans they key, per leg drawn behind, cut to 260 characters — `DRAWORDER from depth by the knee (run; tie 24.96 px), 6 key(s) over 3 span(s) (leg_r behind leg_l 0–9, 20–29, 40–49)`, naming the joint and its tie for a keyed pair ([#336](https://github.com/rig-c/pose/issues/336)) — and a line per pair not keyed, saying why.
 - `PELVIS` — when the map has a pelvis chain (one bone, joints `r_hip → l_hip`) or the sequence a pelvis track ([above](#the-pelvis-track-rig-pose-pelvis)): where the pelvis bone's rotation came from and its swing — `PELVIS: from <source>, swing N°`, or `PELVIS: from hip line (no track)` — with the frames keyed from the hip line on a track that declined them.
 - `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: one `segment` line per mapped leg segment with its picture length ÷ straight length (min · median · max), the scale `--leg-scale` would ask before its clamp, printed with or without the flag so the minimum can be read before choosing the range ([#237](https://github.com/rig-c/pose/issues/237)); 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.
@@ -427,7 +428,7 @@ Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2
 - 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>`.
-- **The pelvis track** ([#288](https://github.com/rig-c/pose/issues/288)) is the minor `rig-pose-sequence/1.1`: a `pelvisTilt` on every frame (beside `t` and `people`; Spine degrees in (−180, 180] of the direction r_hip → l_hip, or `null` where the reading declined the frame) and `pelvisSource` on the sequence (`"silhouette"`, `"waistband"` or `"keys"`), written by `rig-pose pelvis` ([above](#the-pelvis-track-rig-pose-pelvis)). A sequence carrying them holds one person; a track on some frames only, a source without a track, or a track without a source is refused by name (`POSE_PELVIS`). The writer writes the minor the content needs — `/1.1` with a track, `/1` without — so a sequence without one stays readable by a reader of `/1`; a `/1` file carrying a 1.1 key is refused naming the minor (`POSE_SPEC`). The spec string is what the file records of the version that wrote it: a file of a newer minor than this reader's is read, and each key it does not know is refused with the minor the file says it was written as (`… the file says it was written as "rig-pose-sequence/1.3", a newer minor than this reader's "rig-pose-sequence/1.2" — read it with a rig-pose that reads that minor`). A reader of `/1` (rig-pose 0.37 and before) refuses a `/1.1` file by its spec (`POSE_SPEC`, naming `"rig-pose-sequence/1.1"`) and its keys (`POSE_KEYS`).
+- **The pelvis track** ([#288](https://github.com/rig-c/pose/issues/288)) is the minor `rig-pose-sequence/1.1`: a `pelvisTilt` on every frame (beside `t` and `people`; Spine degrees in (−180, 180] of the direction r_hip → l_hip, or `null` where the reading declined the frame) and `pelvisSource` on the sequence (`"silhouette"`, `"waistband"`, `"below-cover"` or `"keys"`), written by `rig-pose pelvis` ([above](#the-pelvis-track-rig-pose-pelvis)). A sequence carrying them holds one person; a track on some frames only, a source without a track, or a track without a source is refused by name (`POSE_PELVIS`). The writer writes the minor the content needs — `/1.1` with a track, `/1` without — so a sequence without one stays readable by a reader of `/1`; a `/1` file carrying a 1.1 key is refused naming the minor (`POSE_SPEC`). The spec string is what the file records of the version that wrote it: a file of a newer minor than this reader's is read, and each key it does not know is refused with the minor the file says it was written as (`… the file says it was written as "rig-pose-sequence/1.3", a newer minor than this reader's "rig-pose-sequence/1.2" — read it with a rig-pose that reads that minor`). A reader of `/1` (rig-pose 0.37 and before) refuses a `/1.1` file by its spec (`POSE_SPEC`, naming `"rig-pose-sequence/1.1"`) and its keys (`POSE_KEYS`).
 - **Depth** ([#281](https://github.com/rig-c/pose/issues/281)) is the minor `rig-pose-sequence/1.2`: a `depth` on every frame (beside `t` and `people`), `{ "<segment>": { "ratio", "sign", "source" } }` — the segments `r_upper_arm`, `r_forearm`, `r_thigh`, `r_shin`, `l_upper_arm`, `l_forearm`, `l_thigh`, `l_shin`, each present where its two joints are placed on the frame (`{}` where none is); `ratio` a number ≥ 0, `sign` −1, 0 or 1, `source` `"derived"` (`clean --depth`, [above](#derived-depth-clean---depth)) or `"measured"` (a 3D detector). A minor includes the keys of the minors before it, so a sequence with depth and a pelvis track is `/1.2`, and one with the track alone stays `/1.1`. A sequence with depth holds one person; depth on some frames only, a malformed entry, an unknown segment, derived and measured depth together, and derived depth without the `cleaned` record's `"depth": { "gait" }` (or that record without derived depth on every frame) are refused by name (`POSE_DEPTH`); a `/1` or `/1.1` file carrying `depth` is refused naming the minor (`POSE_SPEC`).
 - `travel` (optional, [#92](https://github.com/rig-c/pose/issues/92)) is the clip's frame of reference. Its one value is `"in-place"`: a gait filmed without the figure travelling, such as a treadmill or reel walk, or a loop. `clean --loop` writes it, and it may be written by hand on any sequence. Any other value is refused by name (`POSE_TRAVEL`). Without it the figure's travel in the picture is its travel. It is a property of the sequence, not of a flag ([#242](https://github.com/rig-c/pose/issues/242)): with or without `--plant-feet`, retarget reads the supports in place, skips the camera-zoom normalisations (a loop has no zoom, and their rolling windows do not wrap) and reads the head nod without its detrend window or clamp. Only the following foot and the loop closure need `--plant-feet` ([below](#the-legs-foreshortening-and-planted-feet)).
 - `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.

package/cli.ts

@@ -22,7 +22,7 @@ import { runRetarget, type RetargetArgs } from './src/run.ts';
 const HELP = `rig-pose ${pkg.version} — motion from a pose sequence onto a rig-c rig
 
 Usage:
-  rig-pose pelvis --pose <pose.json> --out <pose.pelvis.json> (--frames <dir> [--mode silhouette|waistband] | --pelvis-keys <keys.json>) [--person <id>]
+  rig-pose pelvis --pose <pose.json> --out <pose.pelvis.json> (--frames <dir> [--mode silhouette|waistband|below-cover] | --pelvis-keys <keys.json>) [--person <id>]
   rig-pose clean --pose <pose.json> --out <pose.clean.json> [--loop] [--legs 5] [--rest 7] [--hold off] [--depth walk|run] [--coco] [--person <id>]
   rig-pose retarget --rig <rig> --map <map.json> --sequence <pose.json> --out <motion.json> [--animation dance] [flags]
   rig-pose convert --coco <coco17.json> --out <pose.json>
@@ -38,11 +38,15 @@ pelvis (before clean; rig-c/pose#288)
                         r_hip → l_hip, about 0 facing the camera — or null on a frame the reading declined
   --frames <dir>        the picture: one PNG per sequence frame, in file-name order, the sequence's size (no video;
                         extract the frames first). The hip keypoints place the reading; their angle is not read
-  --mode silhouette|waistband
+  --mode silhouette|waistband|below-cover
                         silhouette (default): the straightest edge of the drawn figure across the hip span (between
                         the two hip keypoints), within 40° of level and one hip width of the hips' height — a drawn
                         pelvis line or the edge of a drawn hip. waistband: the top edge of a garment covering the hips
                         (skirt, shorts) — the colour at the hips' midpoint, its first row in each column of the span.
+                        below-cover: for a garment whose top is hidden under another (a sweater's hem over a skirt)
+                        — the bottomwear's lower hem across the span, where each thigh leaves it, and the band's top
+                        only where nothing covers it; the mean of those cues, declined when they differ by more
+                        than 8° (a CUES line per frame; the hip keypoints are printed there, not fitted).
                         Forearms (elbow → wrist) and hands are masked. A frame either cannot read (the pelvis blank,
                         no garment, no straight edge over 60% of the span) is declined, named on a DECLINED line,
                         and written null: marked, not guessed

package/package.json

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

@@ -59,7 +59,7 @@ type Pt = [number, number];
 type RGB = [number, number, number];
 
 /** The two readers. */
-export const PELVIS_MODES = ['silhouette', 'waistband'] as const;
+export const PELVIS_MODES = ['silhouette', 'waistband', 'below-cover'] as const;
 export type PelvisMode = (typeof PELVIS_MODES)[number];
 export const PELVIS_KEYS_SPEC = 'rig-pose-pelvis-keys/1';
 
@@ -85,13 +85,41 @@ export const MIN_SPAN = 6;
 export const CLIMB_SPREAD = 2;
 /** The band's top is climbed against at most this many garment colours (rig-c/pose#318): a paletted garment's own, or a painted one's fullest cells. */
 export const MAX_CLOTH = 16;
+/** rig-c/pose#342: the below-cover cues read the same line when their tilts lie within this many degrees (max − min). */
+export const CUE_SPREAD = 8;
+/** ... a leg's colour is sampled this far along its thigh, hip → knee. */
+export const LEG_AT = 0.7;
+/** ... the hem and a thigh root are where the garment stops for this many px (rows, or along the thigh) in a row. */
+export const LEAVE = 3;
 
 /**
  * One frame's reading: the tilt (Spine degrees, r_hip → l_hip), or why it was declined. A waistband
  * read through the window mean says so (`mean`), and one whose colour was found below the hips says
  * how far (`below`, px); one whose band top lay above the colour's edge in some columns says how many (`raised`, #318).
  */
-export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number; raised?: number } | { kind: string; why: string };
+export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number; raised?: number; cues?: CueTilts } | { kind: string; why: string };
+
+/**
+ * rig-c/pose#342: the below-cover cues of one frame, Spine degrees r_hip → l_hip; null where the cue was not read. `band` is
+ * "covered" when something other than the ground lies over the band's top. `hips` is the keypoints' line: reported, not fitted.
+ */
+export interface CueTilts {
+  hem: number | null;
+  roots: number | null;
+  band: number | 'covered' | null;
+  hips: number;
+}
+
+/** rig-c/pose#342: a below-cover reading's figures and points (the picture's), and why each cue not read was not. */
+export interface CueDetail {
+  tilts: CueTilts;
+  why: { hem?: string; roots?: string; band?: string };
+  garment: RGB;
+  legs: { r: RGB | null; l: RGB | null };
+  hem: { pts: Pt[]; fit: { m: number; q: number; rms: number } | null };
+  roots: { r: Pt | null; l: Pt | null; paths: Array<[Pt, Pt]> };
+  band: { m: number; q: number } | null;
+}
 
 /** The frame as RGB over white, its background colour, and which pixels are masked (forearms, hands). */
 interface Frame {
@@ -194,7 +222,38 @@ export function readPelvis(plate: Plate, joints: Partial<Record<Body18, Joint>>,
   const f = frameOf(plate, arms, Math.max(3, ARM_RADIUS * span));
   if (x0 < 0 || x1 >= f.w || c[1] < 0 || c[1] >= f.h) return { kind: 'hips outside the frame', why: `the hips (${c[0].toFixed(1)}, ${c[1].toFixed(1)}) lie outside the ${f.w}×${f.h} frame` };
   const cols = x1 - x0 + 1;
-  return mode === 'silhouette' ? silhouette(f, c, span, x0, x1, cols, rHip, lHip) : waistband(f, c, span, x0, x1, cols, rHip, lHip);
+  if (mode === 'silhouette') return silhouette(f, c, span, x0, x1, cols, rHip, lHip);
+  if (mode === 'waistband') return waistband(f, c, span, x0, x1, cols, rHip, lHip);
+  return belowCover(f, c, span, x0, x1, cols, rHip, lHip, pt).reading;
+}
+
+/**
+ * rig-c/pose#342: the below-cover reading of one frame with every cue's figures and points, for a picture of it. Null when
+ * the frame is declined before any cue is read (no hips, side-on, outside the frame); the reading is `readPelvis`'s.
+ */
+export function readBelowCover(plate: Plate, joints: Partial<Record<Body18, Joint>>): { reading: Reading; detail: CueDetail | null } {
+  const reading = readPelvis(plate, joints, 'below-cover');
+  const pt = (n: Body18): Pt | null => {
+    const j = joints[n];
+    return j === undefined || j.state === 'missing' || j.at === undefined ? null : [j.at[0], j.at[1]];
+  };
+  const rHip = pt('r_hip');
+  const lHip = pt('l_hip');
+  if (rHip === null || lHip === null) return { reading, detail: null };
+  const span = Math.hypot(lHip[0] - rHip[0], lHip[1] - rHip[1]);
+  const x0 = Math.round(Math.min(rHip[0], lHip[0]));
+  const x1 = Math.round(Math.max(rHip[0], lHip[0]));
+  if (span < MIN_SPAN || x1 - x0 + 1 < MIN_SPAN) return { reading, detail: null };
+  const c: Pt = [(rHip[0] + lHip[0]) / 2, (rHip[1] + lHip[1]) / 2];
+  const arms: Array<[Pt, Pt]> = [];
+  for (const [e, w] of [['r_elbow', 'r_wrist'], ['l_elbow', 'l_wrist']] as const) {
+    const a = pt(e);
+    const b = pt(w);
+    if (a !== null && b !== null) arms.push([a, b]);
+  }
+  const f = frameOf(plate, arms, Math.max(3, ARM_RADIUS * span));
+  if (x0 < 0 || x1 >= f.w || c[1] < 0 || c[1] >= f.h) return { reading, detail: null };
+  return { reading, detail: belowCover(f, c, span, x0, x1, x1 - x0 + 1, rHip, lHip, pt).detail };
 }
 
 function silhouette(f: Frame, c: Pt, span: number, x0: number, x1: number, cols: number, rHip: Pt, lHip: Pt): Reading {
@@ -272,7 +331,8 @@ function meanOf(f: Frame): (x: number, y: number) => RGB | null {
   };
 }
 
-function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols: number, rHip: Pt, lHip: Pt): Reading {
+/** `out.fit`, when given, receives the edge read (rig-c/pose#342 looks at what lies above it). */
+function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols: number, rHip: Pt, lHip: Pt, out?: { fit?: { m: number; q: number } }): Reading {
   // The garment's colour: the median over the unmasked pixels of a patch at the hips' midpoint (or below it), as they are or through the window mean.
   const r = Math.max(2, 0.3 * span);
   const raw = (x: number, y: number): RGB | null => f.rgb(x, y);
@@ -341,6 +401,7 @@ function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
   if (Math.abs(Math.atan(fit.m)) * (180 / Math.PI) > 45) return { kind: 'waistband too steep', why: `the garment's top edge runs ${(Math.atan(fit.m) * (180 / Math.PI)).toFixed(1)}° from level; a waistband is within 45°` };
   const off = notTheBand(f, fit, tops, top, colourAt);
   if (off !== null) return off;
+  if (out !== undefined) out.fit = { m: fit.m, q: fit.q };
   return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms, ...(isMean ? { mean: true as const } : {}), ...(below > 0 ? { below } : {}), ...(raised > 0 ? { raised } : {}) };
 }
 
@@ -532,6 +593,193 @@ function notTheBand(f: Frame, fit: { m: number; q: number }, tops: Pt[], top: nu
   };
 }
 
+/**
+ * rig-c/pose#342: the pelvis read below a cover. A garment hanging over the waistband (a sweater's hem) hides the band's top
+ * and hangs level whatever the pelvis does, so the band-top reader reads the cover. What the cover cannot hide is read:
+ *
+ * - `hem`: the bottomwear's lower hem across the hip span — in each column, from the hips' row down, the last garment row
+ *   before `LEAVE` rows that are not garment; a line fitted through them (≥ `MIN_COVER` of the columns);
+ * - `roots`: where each thigh leaves the garment — along hip → knee (keypoints), the last garment point before `LEAVE` px
+ *   that are not; the line from the right root to the left;
+ * - `band`: the waistband reader's band top, used only when the ground lies above it (nothing covers it);
+ * - `hips`: the keypoints' line, reported but not fitted — a detector's hips keep a fraction of a drawn tilt (#288).
+ *
+ * Every colour is the window mean (`DITHER_RADIUS`); a pixel is garment when it is nearest the garment's colour among the
+ * garment's, each leg's (sampled `LEG_AT` along its thigh) and the ground's, so both shades of a cloth and the ink on it
+ * are garment and skin or ground under the hem are not. The tilt is the mean of the cues fitted (hem, roots, an
+ * uncovered band); fewer than two, or two that differ by more than `CUE_SPREAD`, decline the frame by name.
+ */
+function belowCover(f: Frame, c: Pt, span: number, x0: number, x1: number, cols: number, rHip: Pt, lHip: Pt, pt: (n: Body18) => Pt | null): { reading: Reading; detail: CueDetail | null } {
+  const r = Math.max(2, 0.3 * span);
+  const mean = meanOf(f);
+  const disc = (at: Pt): RGB | null => {
+    const ps: RGB[] = [];
+    for (let y = Math.floor(at[1] - r); y <= Math.ceil(at[1] + r); y++) {
+      for (let x = Math.floor(at[0] - r); x <= Math.ceil(at[0] + r); x++) {
+        if (x < 0 || y < 0 || x >= f.w || y >= f.h || Math.hypot(x - at[0], y - at[1]) > r || f.masked(x, y)) continue;
+        const p = mean(x, y);
+        if (p !== null) ps.push(p);
+      }
+    }
+    return ps.length === 0 ? null : ([0, 1, 2].map((k) => median(ps.map((p) => p[k]!))) as RGB);
+  };
+  const holds = (at: Pt, g: RGB) => {
+    let n = 0;
+    let k = 0;
+    for (let y = Math.floor(at[1] - r); y <= Math.ceil(at[1] + r); y++) {
+      for (let x = Math.floor(at[0] - r); x <= Math.ceil(at[0] + r); x++) {
+        if (x < 0 || y < 0 || x >= f.w || y >= f.h || Math.hypot(x - at[0], y - at[1]) > r || f.masked(x, y)) continue;
+        const p = mean(x, y);
+        if (p === null) continue;
+        n++;
+        if (diff(p, g) <= GARMENT_DIFF) k++;
+      }
+    }
+    return n > 0 && k >= HOLD * n;
+  };
+  const mid = disc(c);
+  if (mid === null) return { reading: { kind: 'hips behind a forearm', why: 'the hips\' midpoint is covered by a forearm; no garment colour to read' }, detail: null };
+  let g: RGB = mid;
+  for (const drop of [0, r, 2 * r]) {
+    const at: Pt = [c[0], c[1] + drop];
+    const p = drop === 0 ? mid : disc(at);
+    if (p !== null && diff(p, f.bg) > FIGURE_DIFF && holds(at, p)) {
+      g = p;
+      break;
+    }
+  }
+  if (diff(g, f.bg) <= FIGURE_DIFF) return { reading: { kind: 'no garment over the hips', why: `the colour at the hips' midpoint (${g.map((v) => v.toFixed(0)).join(', ')}) is the background's (${f.bg.map((v) => v.toFixed(0)).join(', ')})` }, detail: null };
+  const knee = { r: pt('r_knee'), l: pt('l_knee') };
+  const hip = { r: rHip, l: lHip };
+  const legs = { r: null as RGB | null, l: null as RGB | null };
+  for (const s of ['r', 'l'] as const) {
+    const k = knee[s];
+    if (k === null) continue;
+    const L = disc([hip[s][0] + LEG_AT * (k[0] - hip[s][0]), hip[s][1] + LEG_AT * (k[1] - hip[s][1])]);
+    if (L !== null && diff(L, g) > GARMENT_DIFF) legs[s] = L;
+  }
+  const others = [f.bg, ...(legs.r !== null ? [legs.r] : []), ...(legs.l !== null ? [legs.l] : [])];
+  if (others.length === 1) return { reading: { kind: 'no leg below the garment', why: `neither thigh carries a colour of its own ${LEG_AT} of the way to its knee (${knee.r === null || knee.l === null ? 'a knee has no position' : 'both within ' + GARMENT_DIFF + ' of the garment\'s'}); nothing below the garment to tell its hem by` }, detail: null };
+  // Garment: nearest the garment's colour among it, the legs' and the ground's (a tie is garment). Null where every pixel of the window is masked.
+  const isGarment = (x: number, y: number): boolean | null => {
+    if (x < 0 || y < 0 || x >= f.w || y >= f.h || f.masked(x, y)) return null;
+    const p = mean(x, y);
+    if (p === null) return null;
+    return diff(p, g) <= Math.min(...others.map((o) => diff(p, o)));
+  };
+  const why: CueDetail['why'] = {};
+  // The hem.
+  const hemPts: Pt[] = [];
+  const yEnd = Math.min(f.h - 1, Math.floor(c[1] + 2.5 * span));
+  for (let x = x0; x <= x1; x++) {
+    let inside = false;
+    let last = -1;
+    let out = 0;
+    for (let y = Math.max(0, Math.round(c[1])); y <= yEnd; y++) {
+      const gm = isGarment(x, y);
+      if (gm === null) {
+        if (inside) break;
+        continue;
+      }
+      if (gm) {
+        inside = true;
+        last = y;
+        out = 0;
+      } else if (inside && ++out >= LEAVE) {
+        hemPts.push([x, last]);
+        break;
+      }
+    }
+  }
+  const hemFit = hemPts.length >= MIN_COVER * cols ? fitLine(hemPts) : null;
+  let hem: number | null = null;
+  if (hemFit === null) why.hem = hemPts.length < MIN_COVER * cols ? `the hem is found in ${hemPts.length} of the ${cols} columns between the hips (< ${100 * MIN_COVER}%)` : 'the hem rows do not fit a line';
+  else hem = tiltOf(hemFit.m, rHip, lHip);
+  // The thigh roots.
+  const root = { r: null as Pt | null, l: null as Pt | null };
+  const rootWhy: string[] = [];
+  const paths: Array<[Pt, Pt]> = [];
+  for (const s of ['r', 'l'] as const) {
+    const k = knee[s];
+    if (k === null) {
+      rootWhy.push(`${s}_knee has no position`);
+      continue;
+    }
+    const h = hip[s];
+    paths.push([h, k]);
+    const len = Math.hypot(k[0] - h[0], k[1] - h[1]);
+    const n = Math.ceil(len / 0.5);
+    let inside = false;
+    let last: Pt | null = null;
+    let out = 0;
+    let hidden = false;
+    for (let i = 0; i <= n; i++) {
+      const p: Pt = [h[0] + (i / n) * (k[0] - h[0]), h[1] + (i / n) * (k[1] - h[1])];
+      const gm = isGarment(Math.round(p[0]), Math.round(p[1]));
+      if (gm === null) {
+        if (inside) {
+          hidden = true;
+          break;
+        }
+        continue;
+      }
+      if (gm) {
+        inside = true;
+        last = p;
+        out = 0;
+      } else if (inside && ++out * (len / n) >= LEAVE) {
+        root[s] = last;
+        break;
+      }
+    }
+    if (root[s] === null) rootWhy.push(hidden ? `the ${s} thigh's root is behind a forearm` : inside ? `the ${s} thigh does not leave the garment before its knee` : `the ${s} thigh's path carries no garment`);
+  }
+  let roots: number | null = null;
+  if (root.r !== null && root.l !== null) {
+    if (Math.abs(root.l[0] - root.r[0]) < MIN_SPAN) rootWhy.push(`the roots are ${Math.abs(root.l[0] - root.r[0]).toFixed(1)} px apart across (< ${MIN_SPAN})`);
+    else roots = pictureAngle(root.r, root.l);
+  }
+  if (roots === null) why.roots = rootWhy.join('; ');
+  // The band's top, when nothing covers it.
+  const edge: { fit?: { m: number; q: number } } = {};
+  const wb = waistband(f, c, span, x0, x1, cols, rHip, lHip, edge);
+  let band: number | 'covered' | null = null;
+  if (!('tilt' in wb) || edge.fit === undefined) why.band = 'kind' in wb ? `${wb.kind}` : 'no edge';
+  else {
+    const above: RGB[] = [];
+    for (let x = x0; x <= x1; x++) {
+      const y = Math.round(edge.fit.m * x + edge.fit.q) - 3 * (DITHER_RADIUS + 1);
+      if (y < 0 || y >= f.h || f.masked(x, y)) continue;
+      const p = mean(x, y);
+      if (p !== null) above.push(p);
+    }
+    const a = above.length === 0 ? null : ([0, 1, 2].map((k) => median(above.map((p) => p[k]!))) as RGB);
+    if (a !== null && diff(a, f.bg) <= FIGURE_DIFF) band = wb.tilt;
+    else {
+      band = 'covered';
+      why.band = a === null ? 'nothing seen above the band\'s top' : `the band's top is covered (${a.map((v) => v.toFixed(0)).join(', ')} lies ${3 * (DITHER_RADIUS + 1)} px above it, not the ground)`;
+    }
+  }
+  const hips = pictureAngle(rHip, lHip);
+  const tilts: CueTilts = { hem, roots, band, hips };
+  const detail: CueDetail = { tilts, why, garment: g, legs, hem: { pts: hemPts, fit: hemFit === null ? null : { m: hemFit.m, q: hemFit.q, rms: hemFit.rms } }, roots: { ...root, paths }, band: typeof band === 'number' ? edge.fit! : null };
+  const fitted: Array<[string, number]> = [];
+  if (hem !== null) fitted.push(['hem', hem]);
+  if (roots !== null) fitted.push(['roots', roots]);
+  if (typeof band === 'number') fitted.push(['band', band]);
+  const fmt = (v: number) => `${v >= 0 ? '+' : ''}${v.toFixed(1)}°`;
+  if (fitted.length < 2) {
+    const missing = (['hem', 'roots', 'band'] as const).filter((k) => why[k] !== undefined).map((k) => `${k}: ${why[k]}`);
+    return { reading: { kind: 'too few cues below the cover', why: `${fitted.length} of the cues read (${fitted.map(([n, v]) => `${n} ${fmt(v)}`).join(', ') || 'none'}); ${missing.join('; ')}` }, detail };
+  }
+  const base = fitted[0]![1];
+  const about = fitted.map(([, v]) => base + wrap(v - base));
+  const spread = Math.max(...about) - Math.min(...about);
+  if (spread > CUE_SPREAD) return { reading: { kind: 'cues disagree', why: `${fitted.map(([n, v]) => `${n} ${fmt(v)}`).join(', ')}: ${spread.toFixed(1)}° apart (> ${CUE_SPREAD}°); they do not read one line (hips ${fmt(hips)}, not fitted)` }, detail };
+  const tilt = wrap(about.reduce((s, v) => s + v, 0) / about.length);
+  return { reading: { tilt, cover: hemPts.length / cols, rms: hemFit?.rms ?? 0, mean: true, cues: tilts }, detail };
+}
+
 /**
  * `rig-pose-pelvis-keys/1`: `{ spec, keys: [{ frame, deg }], note? }` — frames of the
  * sequence, strictly increasing, within its span [0, frames − 1]; `deg` the tilt in
@@ -686,6 +934,17 @@ export function runPelvis(a: PelvisArgs, say: (l: string) => void): void {
   const tilt = readings.map((r) => ('tilt' in r ? r.tilt : null));
   const read = tilt.filter((v): v is number => v !== null);
   say(`rig-pose pelvis: ${n} frame(s) of person "${person}" from ${a.pose}, read by ${a.mode} off ${dir} (${files.length} PNG)`);
+  if (a.mode === 'below-cover') {
+    // rig-c/pose#342: every frame's cues, read or not, so a decline or a reading can be checked cue by cue.
+    const fmt = (v: number | 'covered' | null) => (v === null ? 'not read' : v === 'covered' ? 'covered' : `${v >= 0 ? '+' : ''}${v.toFixed(2)}°`);
+    readings.forEach((r, i) => {
+      if (!('tilt' in r) || r.cues === undefined) return;
+      // The hips stay out of the vote; their sign is printed beside the fit, and an opposite sign is warned.
+      const sign = (v: number) => (Math.abs(v) < 0.5 ? '0' : v > 0 ? '+' : '−');
+      say(`  CUES frame ${i}: hem ${fmt(r.cues.hem)}, roots ${fmt(r.cues.roots)}, band ${fmt(r.cues.band)}, hips ${fmt(r.cues.hips)} (not fitted) → ${fmt(r.tilt)}; hips sign ${sign(r.cues.hips)}, fit sign ${sign(r.tilt)}`);
+      if (sign(r.cues.hips) !== '0' && sign(r.tilt) !== '0' && sign(r.cues.hips) !== sign(r.tilt)) say(`  HIPS-SIGN frame ${i}: the hip keypoints tilt ${fmt(r.cues.hips)}, opposite the fit's ${fmt(r.tilt)} (the hips are not fitted)`);
+    });
+  }
   for (const d of declinedRuns(readings)) say(`  DECLINED frame${d.from === d.to ? ` ${d.from}` : `s ${d.from}–${d.to}`} (${d.to - d.from + 1}): ${d.kind} — ${d.same ? d.why : `frame ${d.from}: ${d.why}; the figures differ frame to frame`}`);
   if (read.length > 0) {
     const covers = readings.flatMap((r) => ('tilt' in r ? [r.cover] : []));

package/src/pose.ts

@@ -80,9 +80,10 @@ export type DepthGait = (typeof DEPTH_GAITS)[number];
 /**
  * Where a sequence's `pelvisTilt` came from (rig-c/pose#288): `silhouette` — the
  * straight edge of the drawn figure across the hips; `waistband` — the top edge
- * of a garment covering them; `keys` — a hand file (`--pelvis-keys`).
+ * of a garment covering them; `below-cover` — the cues under a garment hanging
+ * over the waistband (rig-c/pose#342); `keys` — a hand file (`--pelvis-keys`).
  */
-export const PELVIS_SOURCES = ['silhouette', 'waistband', 'keys'] as const;
+export const PELVIS_SOURCES = ['silhouette', 'waistband', 'below-cover', 'keys'] as const;
 export type PelvisSource = (typeof PELVIS_SOURCES)[number];
 export const POSE_SPACE = { units: 'picture-px', origin: 'top-left', y: 'down' } as const;
 /**

package/src/retarget.ts

@@ -76,7 +76,7 @@ import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
 import type { Chain, JointMap, Rest, RigSets, RigSlots } from './map.ts';
 import { aimAngle, aimEnds, bodyYawSets, descends, faceYawSets, knownSetsOf, partBone, pointParts, rigPoint } from './map.ts';
-import type { Joint, Travel } from './pose.ts';
+import type { DepthGait, Joint, Travel } from './pose.ts';
 import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SetRuns, SlotTrack, Switch, SwitchOptions } from './switch.ts';
@@ -188,6 +188,35 @@ export interface RetargetOptions extends SwitchOptions {
    * frame they cover they decide the support. Absent, nothing changes.
    */
   contactKeys?: ContactKeys;
+  /**
+   * rig-c/pose#344: the gait the sequence was cleaned as (its `cleaned.params.depth.gait`, `clean --depth`). An
+   * in-place walk anchors the upper body (`TorsoAnchor`): the pelvis sways under it. Absent, or a run, nothing changes.
+   */
+  gait?: DepthGait;
+}
+
+/**
+ * rig-c/pose#344: in an in-place walk the upper body is the anchor and the pelvis sways under it. The pelvis bone
+ * carries the torso (its child), so its turn and its travel would swing the chest around it; the first spine bone
+ * (`bone`: the pelvis bone's child on the way to the trunk chain's bone) is keyed with the counter: a rotate of minus
+ * the pelvis's turn (none when it is the trunk bone itself, whose aim is already in the world), and a translate that
+ * puts its origin back where the pelvis's turn moved it from, up and down, and sideways where it carries `point`
+ * (the trunk chain's aim bone: the top of the trunk) on the drawn neck's own sideways path: about the world x `x`
+ * (the setup x plus the pelvis's mean travel), the picture's `joint` x less its mean, times `factor` — the pelvis's
+ * sideways sway in the rig against the drawing's (`joints[0]`, mid_hip), each its standard deviation over the frames,
+ * so the neck sways against the pelvis as the drawing's does; the figure's scale where the drawing's pelvis does not
+ * sway. The pelvis's own keys are as read; `neck` is the carried path's peak-to-peak and `sway` the first spine bone's
+ * sideways counter's, world units.
+ */
+export interface TorsoAnchor {
+  gait: DepthGait;
+  bone: string;
+  point: string;
+  joint: string;
+  x: number;
+  factor: number;
+  neck: number;
+  sway: number;
 }
 
 /**
@@ -208,6 +237,8 @@ export interface PelvisReading {
   hipLine: number;
   /** The frames keyed from the hip line on a sequence that carries a track: the frames its reading declined. */
   declined: Array<[number, number]>;
+  /** rig-c/pose#344: the torso held over the swaying pelvis, in an in-place walk only. */
+  anchor?: TorsoAnchor;
 }
 
 export interface Hold {
@@ -904,6 +935,32 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
+  // rig-c/pose#344: an in-place walk holds the upper body over the swaying pelvis, on the first spine bone.
+  const anchorOf = ((): { bone: string; trunk: string; point: string; pelvis: string; joints: [string, string] } | null => {
+    if (opts.gait !== 'walk' || opts.travel !== TRAVEL_IN_PLACE || pelvisChain === null) return null;
+    const pelvisBone = pelvisChain.bones[0]!;
+    const trunk = map.chains.find((c) => !c.reach && c.joints[0] === 'mid_hip' && descends(rest, c.bones[0]!, pelvisBone));
+    if (trunk === undefined) return null;
+    const tb = trunk.bones[0]!;
+    let first = tb;
+    while (rest.get(first)!.parent !== pelvisBone) first = rest.get(first)!.parent!;
+    // The aim's upper end (aimEnds: `neck` and `chest>neck` alike end at the neck), a rig point on the trunk bone or below it.
+    const aim = trunk.aim[0]!;
+    const top = aim === 'x' ? null : aimEnds(tb, aim)[1];
+    const onTrunk = top !== null && pointParts(top).every((part) => {
+      const b = partBone(part);
+      return rest.has(b) && (b === tb || descends(rest, b, tb));
+    });
+    const point = onTrunk ? top! : tb;
+    return { bone: first, trunk: tb, point, pelvis: pelvisBone, joints: [trunk.joints[0]!, trunk.joints[1]!] };
+  })();
+  if (anchorOf !== null && anchorOf.bone !== anchorOf.trunk && !targets.has(anchorOf.bone)) {
+    // Not in a chain: its world turn is held at setup, so the bones below it are keyed against none.
+    const a0 = restAngle(rest, anchorOf.bone, 'x');
+    restOf.set(anchorOf.bone, a0);
+    targets.set(anchorOf.bone, Array.from({ length: n }, () => a0));
+  }
+
   // The short hold, on every segment the pose aims directly (not a reach): its
   // picture length against its own median, on the points the angle was read from.
   // A horizontal line across the body (`isAcross`: pelvis, shoulders, head line)
@@ -1509,7 +1566,43 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     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 + nod[0], po[1] + Math.sin(r) * ox + Math.cos(r) * oy + nod[1]];
+    const at: Pt = [po[0] + Math.cos(r) * ox - Math.sin(r) * oy + nod[0], po[1] + Math.sin(r) * ox + Math.cos(r) * oy + nod[1]];
+    if (anchorOf === null || b !== anchorOf.bone || anchorRaw) return at;
+    const s = anchorShift(i, at, po, oy);
+    return [at[0] + s[0], at[1] + s[1]];
+  };
+  /**
+   * rig-c/pose#344: the world shift that holds the first spine bone over the pelvis: up and down, its origin where
+   * the pelvis's travel alone puts it (the pelvis's turn taken out); sideways, the trunk's top point on `anchorPath`:
+   * the drawn neck's sideways path about its mean, scaled by the pelvis's rig ÷ drawn sideways sway (`TorsoAnchor`).
+   */
+  let anchorRaw = false;
+  let anchorX: number | null = null;
+  let anchorFactor = 1;
+  let anchorPath: number[] | null = null;
+  const anchorShift = (i: number, at: Pt, po: Pt, oy: number): Pt => {
+    const a = anchorOf!;
+    if (anchorPath === null) {
+      anchorRaw = true;
+      const hipX = Array.from({ length: n }, (_, k) => posedOrigin(a.pelvis, k)[0] - rest.get(a.pelvis)!.worldX);
+      anchorRaw = false;
+      const mean = (xs: readonly number[]) => xs.reduce((s, x) => s + x, 0) / xs.length;
+      const sd = (xs: readonly number[]) => {
+        const m = mean(xs);
+        return Math.sqrt(xs.reduce((s, x) => s + (x - m) ** 2, 0) / xs.length);
+      };
+      const drawnHip = series.get(a.joints[0])!.map((p) => p[0]);
+      const drawnNeck = series.get(a.joints[1])!.map((p) => p[0]);
+      const sdHip = sd(drawnHip);
+      anchorFactor = sdHip > 1e-6 ? sd(hipX) / sdHip : (scale?.factor ?? 1);
+      anchorX = rigPoint(rest, a.point)![0] + mean(hipX);
+      const m = mean(drawnNeck);
+      anchorPath = drawnNeck.map((x) => anchorX! + (x - m) * anchorFactor);
+    }
+    anchorRaw = true;
+    const top = posedPoint(a.point, i);
+    anchorRaw = false;
+    return [anchorPath[i]! - top[0], po[1] + oy - at[1]];
   };
   /** A rig point (a bone, `name:tip`, `a+b`) posed on frame i the same way. */
   const posedPoint = (spec: string, i: number): Pt => {
@@ -2999,6 +3092,42 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
     }
   }
+  // rig-c/pose#344: the first spine bone's counter — its rotate when it is not the trunk bone, and its translate.
+  let anchor: TorsoAnchor | null = null;
+  if (anchorOf !== null) {
+    const a = anchorOf;
+    if (a.bone !== a.trunk) {
+      const above = mappedAbove(a.bone);
+      let prev = 0;
+      const keys: MotionKey[] = [];
+      for (let i = 0; i < n; i++) {
+        const raw = turn(a.bone, i) - (above === null ? 0 : turn(above, i));
+        prev = i === 0 ? wrap(raw) : prev + wrap(raw - prev);
+        keys.push({ t: keyTimes[i]!, v: [r3(prev)] });
+      }
+      tracks.push({ bone: a.bone, property: 'rotate', keys });
+    }
+    const pr = rest.get(a.pelvis)!;
+    const det = pr.a * pr.d - pr.b * pr.c;
+    const keys: MotionKey[] = [];
+    const xs: number[] = [];
+    for (let i = 0; i < n; i++) {
+      const held = posedOrigin(a.bone, i);
+      anchorRaw = true;
+      const free = posedOrigin(a.bone, i);
+      anchorRaw = false;
+      const wx = held[0] - free[0];
+      const wy = held[1] - free[1];
+      xs.push(wx);
+      // Into the pelvis's turned frame, then through its setup matrix: the translate is in the parent's local axes.
+      const r = -turnAbove(a.pelvis, i) / DEG;
+      const ux = Math.cos(r) * wx - Math.sin(r) * wy;
+      const uy = Math.sin(r) * wx + Math.cos(r) * wy;
+      keys.push({ t: keyTimes[i]!, v: [r3((pr.d * ux - pr.b * uy) / det), r3((-pr.c * ux + pr.a * uy) / det)] });
+    }
+    tracks.push({ bone: a.bone, property: 'translate', keys });
+    anchor = { gait: 'walk', bone: a.bone, point: a.point, joint: a.joints[1], x: r3(anchorX!), factor: r6(anchorFactor), neck: r3(Math.max(...anchorPath!) - Math.min(...anchorPath!)), sway: r3(Math.max(...xs) - Math.min(...xs)) };
+  }
   let face: FaceReading | null = null;
   if (map.face !== undefined) {
     const rEar = series.get('r_ear') ?? (() => {
@@ -3136,6 +3265,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
 
   const pivot = pivotOf(rest, t?.bone ?? null, legs);
   const pelvis = pelvisReadingOf(pelvisChain, opts.pelvis, track, fromTrack, tracks);
+  if (pelvis !== null && anchor !== null) pelvis.anchor = anchor;
   const scaleFit = t === null || scale === null || origin === null ? null : scaleFitOf({
     joints: t.scale.pose, joint: t.joint, bone: t.bone, lengths: scaleLengths, factor: scale.factor,
     series, good, legLength: feet?.legLength ?? null, legStraight, rigLeg,
@@ -3187,10 +3317,16 @@ export function pelvisLine(r: PelvisReading, frames: number): string {
   const where = r.bone === null ? '' : `bone "${r.bone}", chain "${r.chain}"`;
   if (r.bone === null) return `PELVIS: not keyed — the sequence carries a ${r.trackSource} track (${frames - r.declined.reduce((s, [a, b]) => s + b - a + 1, 0)} of ${frames} frames read) and the map has no pelvis chain (one bone, joints r_hip → l_hip); no bone turns with the pelvis`;
   const swing = r.swing === null ? '' : `, swing ${r.swing.toFixed(2)}°`;
-  if (r.trackSource === null) return `PELVIS: from hip line (no track)${swing} (${where}; every frame from r_hip → l_hip)`;
-  if (r.track === 0) return `PELVIS: from hip line (the ${r.trackSource} track read none of the ${frames} frames)${swing} (${where}; every frame from r_hip → l_hip)`;
+  if (r.trackSource === null) return `PELVIS: from hip line (no track)${swing} (${where}; every frame from r_hip → l_hip)${anchorClause(r.anchor)}`;
+  if (r.track === 0) return `PELVIS: from hip line (the ${r.trackSource} track read none of the ${frames} frames)${swing} (${where}; every frame from r_hip → l_hip)${anchorClause(r.anchor)}`;
   const rest = r.hipLine === 0 ? `all ${frames} frames from the track` : `${r.track} of ${frames} frames from the track, the hip line on the ${r.hipLine} it declined (frames ${spans(r.declined)})`;
-  return `PELVIS: from ${r.source}${swing} (${where}; ${rest})`;
+  return `PELVIS: from ${r.source}${swing} (${where}; ${rest})${anchorClause(r.anchor)}`;
+}
+
+/** rig-c/pose#344: the PELVIS line's clause for the torso held over the pelvis. */
+function anchorClause(a: TorsoAnchor | undefined): string {
+  if (a === undefined) return '';
+  return `; torso anchored (in-place ${a.gait}): bone "${a.bone}" keyed with the pelvis's counter, "${a.point}" carried on the drawn ${a.joint}'s sideways path about x ${a.x.toFixed(2)} (× ${a.factor.toFixed(4)}, the pelvis's rig ÷ drawn sway; ${a.neck.toFixed(2)} peak to peak, the counter ${a.sway.toFixed(2)}), the pelvis swaying under it`;
 }
 
 /** A reach bone's origin within this many world units of the anchor's, with nothing above it moved, is aimed along the pair: no REACH line. */

package/src/run.ts

@@ -168,7 +168,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const slots = slotsOf(doc0);
     resolveMap(map, rest, a.map, slots, input.sets);
 
-    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}), ...(seq.pelvisSource !== undefined ? { pelvis: { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } } : {}), ...(contactKeys !== null ? { contactKeys } : {}) }, slots, input.sets);
+    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}), ...(seq.pelvisSource !== undefined ? { pelvis: { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } } : {}), ...(contactKeys !== null ? { contactKeys } : {}), ...(seq.cleaned!.params.depth !== undefined ? { gait: seq.cleaned!.params.depth.gait } : {}) }, slots, input.sets);
     if (fragment.length > 0 && ((r.face?.sets?.length ?? 0) > 0 || (r.body?.sets?.length ?? 0) > 0)) {
       const known = knownSetsOf(map, input.sets);
       for (const s of [...(r.face?.sets ?? []), ...(r.body?.sets ?? [])]) {