animation/hand-shapes/README.md

# Hand shapes — morph-target hand poses for ariki-game (the "shape" lane)

Where `../hand-poses/` stores poses as **bone rotations** (blocked on a finger-weight
repair that stalled at exp05), this lane bakes poses as **surface deformation** — glTF
morph targets spliced directly into a body GLB. The pose library ships *inside the mesh*.

## Why this exists (the one-paragraph case)

The scan mesh carries ~2.6k inter-digit bridge edges. Weights only choose *which bone
drags a shared vertex* — when adjacent fingers curl apart in a fist, those bridges must
tear, which is exactly the fin-stack failure of exp01–exp05 (torn-edge counts 800–3300
per hand, five iterations, no convergence; the mesh topology is the problem, not the
weights). A morph target IS the final vertex positions: tearing is impossible by
construction, and the web stretch becomes one geometric fix.

## What this mesh actually is (measured 2026-08-18, `LowPoly_40`)

Every one of these was silently breaking the solve. Read before tuning anything.

| Fact | Number | Consequence |
|---|---|---|
| Coincident duplicate verts on chart seams | 356 groups / 732 verts | solved twice, deltas disagreed by up to 2.55cm → seam cracks |
| Hand is built from separate overlapping sheets | 6 components, gaps 1.1–10mm | Dijkstra cannot cross a gap: each bone's field covers only the sheet its seeds landed on |
| Skeleton finger chain overshoots the flesh | mesh ends 14.0cm from the wrist, `_03` joints sit at 19.8cm | `_02`/`_03` carried almost no weight, so `curl_02`/`curl_03` did nothing; the 4mm seed radius found no verts for 10 of 15 bones |
| Detached fragment near the right wrist | 134 verts | took `index_02_r` through a seed leak and flew **31cm** on fist_r |
| Verts owned by any single phalanx | **zero** of 17,480 above 0.85 | 8mm kernels are wider than the gap to the next phalanx; a 3-way blend averages the curl away |

## Pipeline (`tools/handshape_solve.py`, pure numpy on raw GLB bytes)

1. **refit** the finger chain into the flesh (`refit_fingers`) — solver-local scaffolding
   only; the shipped skeleton is never touched, because every clip pins all 65 bone
   positions. A morph is just final vertex positions, so the pose only needs pivots that
   lie inside the flesh they bend.
2. **ROI** = union of spheres about the wrist + refit joints (`build_roi`). NOT a tube
   about bone segments — a tube leaves the ROI riddled with interior chart holes, so its
   "rim" is a fractal inside the hand rather than a wrist band.
3. **weld** coincident verts into single graph nodes (`weld_roi`); deltas scatter back to
   every duplicate, so seams cannot crack by construction.
4. **stitch** separate sheets within 12mm (`stitch_components`) — cross-component pairs
   only, so a stitch can never fake a shortcut inside a sheet.
5. **weights** as a partition of unity along each digit's chain arc (`solve_weights`):
   narrow handover ramps at each joint (1.0 mid-phalanx, 0.5 at the joint), times digit
   ownership from lateral distance *relative to the nearest chain*.
6. **pose** parametric curl/spread/thumb-opposition, LBS with the solver's own weights
   (`pose_globals`, `lbs`); parameters in `DEFAULT_PARAMS`.
7. **relax** by strain-only edge projection (`relax`) plus ROI-border seam constraints.
8. **emit** POSITION *and* NORMAL deltas as morph accessors (`emit_morph_glb`), names in
   `extras.targetNames` as `hand_<pose>_<l|r>`.

`--selftest-bump` splices one synthetic 3cm palm bump with no solve — proves the
import + drive path on a new body. `--no-weld` / `--no-stitch` / `--no-refit` reproduce
the older behaviour for comparison.

### The trap that invalidated every earlier gate

The previous relaxation was **gated Laplacian diffusion of the delta field**. Diffusion
has a null space — constants — and edge stretch is blind to every member of it: a rigid
translation stretches no edge, and neither does a collapse to zero. So the diffusion
always found one of those two exits, and reported perfect bars on the way out. Measured
on this body: the left hand decayed to **0.3cm** of fingertip travel (max 1.93x,
p99.9 1.60x, zero torn edges — a flawless report for a morph that does nothing), and the
right hand converged to a near-constant **6.5cm delta at every arc position from wrist to
fingertip** — the whole hand translated sideways with its shape intact (max 2.43x,
p99.9 1.46x, also "passing"). Strain-only projection has no such exit: a conforming edge
contributes no correction, so the pose survives wherever it does not tear.

Corollary: **edge stretch alone can never gate this lane.** Always read mesh fingertip
travel (`tip_mesh_cm`) and `seam_max_mm` beside it. `tip_bone_cm` is scaffolding — it
read 10cm/finger while the `_03` joints floated 5cm outside the mesh.

## Bake a body

```
"C:/Program Files/Blender Foundation/Blender 5.1/blender.exe" --background \
  --factory-startup --python tools/handshape_solve.py -- \
  --body <body.glb> --poses flat,relaxed,fist,grip --out <out.glb> \
  --workdir characters/work/lena_leafbikini/handmorph/
```

Blender is only the numpy host — no bpy, no scene import (so the
importer-draws-false-shards trap does not apply to the solver). ~1 min for 8 shapes.
Numbers land in `handmorph/handmorph_report.json`, OBJ dumps beside it.

## Gate bars (per shape)

- edge stretch over **all** edges, no rest-length floor: p99.9 <= 1.6x, zero > 5x, zero
  "needles" (>5x *and* >1mm of real growth). The old 1mm floor hid a population of sub-mm
  seam edges that grew to 3–4cm — hairline spikes, sub-pixel in screenshots.
- **mesh** fingertip travel: fist >= 2.5 cm/finger, grip ~2 cm, relaxed 0.5–2 cm
- ROI-border seam: <= ~5mm
- cross-hand independence: 0 cm on the other hand's verts

Current (2026-08-18, `Ariki_Female_QuatSkin_LowPoly_40.glb`, ROI 19,159 → 17,480 nodes):

| shape | max | p99.9 | n>5x | needles | seam | mesh tip cm |
|---|---|---|---|---|---|---|
| flat_l | 1.35 | 1.35 | 0 | 0 | 1.2mm | 0.1 |
| relaxed_l | 1.36 | 1.35 | 0 | 0 | 2.0mm | 1.0 |
| fist_l | 1.63 | 1.38 | 0 | 0 | 1.3mm | 4.6–4.9 |
| grip_l | 1.82 | 1.46 | 0 | 0 | 1.3mm | 3.5–3.7 |
| flat_r | 1.35 | 1.35 | 0 | 0 | 1.5mm | 0.1 |
| relaxed_r | 1.66 | 1.45 | 0 | 0 | 2.6mm | 1.1–1.2 |
| fist_r | 1.77 | 1.54 | 0 | 0 | 3.2mm | 6.0–6.2 |
| grip_r | 2.23 | 1.58 | 0 | 0 | 3.1mm | 4.5–4.7 |

Cross-hand independence is exactly 0.0000 cm on all 8 shapes. `viol_edges_left` in the
report counts edges still above the *soft* 1.35x projection target (~6k on fist/grip after
1500 iterations) — not a bar, but the reason `max` sits near 1.8x rather than 1.35x.

## Verify in-engine (the only honest gate)

```
HANDMORPH_BODY_F=res://scratchpad/lowpoly40_handmorph.glb \
  SCENE=anim_hand_test_bed MOCK_ONLY=1 AGENT_OWNED=1 WAIT=1 bash tools/game.sh spawn
# then: game.sh click 'fist' / 'grip' / 'flat' / 'morph OFF' / 'Cam: Lena hands'
```

Verified 2026-08-18: `[HandMorphLayer] found 4 hand pose(s)`; fist and grip both read as
a real curl on both hands, static and mid-`dance_soul`, at hand-cam range — no fins,
shards, needles or stray geometry. It reads as a **loose fist / cupped hand**, not a
clenched one: her fingers are only ~4–5cm long past the knuckles, so ~6cm of tip travel
is most of the range available.

Two environment notes: this demo body carries the **yellow LowPoly-bake defect** (yellow
with the morph on *and* off — it is the body, not the lane), and 8 dense morph targets on
a 430k-vert mesh **crashed the GPU driver** (`Vulkan device was lost`, TDR) after ~1–2
minutes of bed time. Take screenshots promptly, and treat runtime cost as an open risk.

## Relationship to the bone lane (`../hand-poses/`)

Independent and composable: the bone lane overrides finger-bone rotations (needs
finger-weighted bodies); this lane deforms the surface (works on ANY body carrying the
shapes, including the shipped rigid-mitt bodies). Hotkeys **H** bone lane, **K** shape
lane in the dance bed; button panels in `anim_hand_test_bed`.

## Open items

- **Ship decision.** Nothing shipped carries the shapes, so the layer is a silent no-op
  on the real Lena. Dense float32 POSITION+NORMAL deltas over all 430,551 verts cost
  **~9.9 MB per shape**: 43.8 MB → 122.6 MB for 8 (**+78.8 MB**, not the +41 MB the
  handover estimated). Only 5.5k–9.7k verts per shape are non-zero (2.2%), so glTF
  **sparse accessors** are a ~30x lever (~2.5 MB for all 8) — but the engine's glTF
  module appears to *write* sparse accessors without reading them, so test one shape
  before betting on it. Fallbacks: drop `flat` (max delta 0.33–0.66cm — nearly a no-op)
  and `relaxed`, keeping fist+grip = 4 shapes at ~+39 MB; or LOD1-only; or a hand-region
  remesh. The TDR crash above says runtime cost needs measuring too, not just bytes.
- **Thumb chain refit is unreliable.** Its reach is measured along a wrist→tip axis that
  passes through the palm, so palm/wrist flesh gets claimed by the thumb (a vertex 5cm
  from the wrist came out `thumb_01_r`=0.88 and swung 4.8cm). The right hand still shows
  1.4cm of wrist motion on fist; the left shows none. Needs a thumb-specific axis.
- Projection does not fully converge to 1.35x within 1500 iterations (see above).
- `tools/handshape_verify.py` reports `own-delta = -1` sentinels on this body — a
  mesh/bone space mismatch in the verifier, not in the solve. Superseded in practice by
  the report plus the bed; fix it or retire it.
- Mako male and full-res female via the same one-command solve — untried.
- Pose authoring is editing `DEFAULT_PARAMS` — could become JSON plus a tuning scene.