tinqs/animation
5
0
Fork 0
Code Pull Requests Actions Packages Projects Releases Wiki Activity Issues

feat(lena-hands): exp09 graded cross-digit finger weights + honest tear metrics

Browse Source 
The exp05 verdict ("weights alone cannot clear the bar on this mesh") was
measured against a hard partition that was itself causing much of the tearing.
exp01-exp05 gave every vert to exactly ONE digit -- 08_finger_weights.py had an
explicit `elif lo in FING: continue  # other digit: hard wall` -- which
guarantees the fused inter-digit bridges tear by the full finger separation,
because a single edge ring absorbs the whole gap.

Replace that with graded blending (WEB_BLEND_R0): a vert's fraction toward its
nearest other digit ramps 0 -> 0.5 as r = d_own/(d_own+d_other) goes 0.35 -> 0.5,
so both sides of the equidistance valley reach 50/50 and the field is continuous
across the boundary. Applied after the smoother (whose hard wall would erode beta
exactly where it must survive) and evaluated in the neighbour digit's own
arc-length frame. WEB_BLEND_SKIP excludes the thumb: its transform is opposition,
not curl, so its frame does not correspond to a finger's.

Measured against an identical baseline (same input, blend the only variable),
real tears (>=1mm rest length) drop 23-60% with NO regression on flat, the pose
that ships: fist_r 1178 -> 530, grip_r 561 -> 222, fist_l 979 -> 633,
grip_l 420 -> 322; total >5x 2487 -> 1307; p99.9 better on every pose;
flat unchanged at 0/1. fin_bones confirms the mechanism rather than just the
count -- the middle<->ring and pinky<->ring families leave the top classes while
the thumb/palm ones are untouched to the edge (182 -> 182, 148 -> 148).

This does NOT make fist/grip shippable: 222-633 real tears still reads as a
destroyed hand in clay renders, and the residual is now ~53% thumb-pad-fused-to
-palm, which is topology and needs mesh surgery or the v02 rebake. Flat and
relaxed are the shippable poses; fist/grip belong to the morph lane for now.

Also here:
- README: the solver's input is v02/..._exp03.glb, NOT exp01. exp01 is pre-hand
  -fit (converter steps 2b/2c); its finger groups sit on the wrist and overlap
  the real finger by 1.6cm, so a solve from it silently zeroes every _02/_03 bone
  -- rigid stick fingers and a torn flat -- while weight sums stay 1.0 and every
  assert passes. Cost three wasted bakes and one false "the solver regressed".
- Seed assert demanded >=100 seeds while the radius loop caps at
  SEED_AXIS_R_MAX, which left pinky (88 seeds at 16mm) can never satisfy; the two
  constants were mutually unsatisfiable. Now >=60, and it is documented as a
  sanity gate rather than a quality bar.
- Detwist poses tested at last: real but marginal (fist_r 38.7x -> 28.7x,
  grip_r 30.0x -> 17.3x, left hand flat). A knob, not a fix.
- edge_stretch_cmp.py / skin_bone_territory.py / handpose_trim_hand_obj.py:
  judge tears by rest length and absolute posed growth, not raw ratio; audit
  whether a bone owns any verts at all (thumb_01 owns ZERO in exp05); and trim
  an arm-sized skin dump to the hand before rendering.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Jeremy
2026-08-18 11:33:15 -07:00
parent 3f335ee2d7
commit cf336f3b5b
28 changed files with 3285 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
hand-poses/README.md
+61 -14
View File
@@ -8,25 +8,55 @@ byte-identical — the runtime `HandPoseLayer` reads the game copy).
`{"bones": {"<bone_name>": [x, y, z, w], ...}}` — glTF node-local quaternions on the
**canonical Quaternius skeleton**, which is exactly Godot bone-pose space for these
bodies. Apply directly:
```csharp
skeleton.SetBonePoseRotation(skeleton.FindBone(name), new Quaternion(x, y, z, w));
```
bodies.
40 bones per pose, including `*_04_leaf_*` tip bones. Some bodies lack the leaf
bones — **skip bones `FindBone` returns -1 for**, never error. On non-canonical rigs
(Mako) poses must be applied rest-relative; the runtime layer simply excludes those
bodies instead.
bones — **skip bones `FindBone` returns -1 for**, never error.
**Apply REST-RELATIVE, not directly** (runtime does this as of 2026-08-18):
```csharp
// delta = canonicalRest^-1 * pose; target = thisBodysRest * delta
var target = boneRest * (canonRest.Inverse() * pose);
skeleton.SetBonePoseRotation(idx, target);
```
`canonical_rest.json` (regenerate with `tools/make_canonical_rest.py`) holds the canonical
finger rests this correction needs. On a rig whose finger rest matches canonical the
correction is algebraically a no-op, so nothing changes for the Quaternius/QuatSkin
bodies. On one that deviates it is the only correct form — Mako's `*_01` knuckles sit
**11.5°** off canonical, and writing poses straight in wrenched them away from his own
rest and tore the palm/wrist boundary.
## Poses
| File | Source (Kevin packs) | Runtime status |
|---|---|---|
| `pose_flat.json` | harvested flat hand | **SHIPPED to layer 2026-08-17** — verified in the dance bed on exp01 |
| `pose_relaxed.json` | `HandWave01` f0 | staged |
| `pose_fist.json` | `AttackPunch01_R/L` f7, merged | blocked on Lena finger-weight repair (fist/grip shred on exp01–exp04) |
| `pose_grip.json` | `CombatIdle1H01` f0, both hands | blocked, same repair |
| `pose_flat.json` | **= canonical REST** (see below) | **SHIPPED** — verified in-engine on Mako 2026-08-18 |
| `pose_relaxed.json` | `HandWave01` f0 (~10° off rest) | staged |
| `pose_fist.json` | `AttackPunch01_R/L` f7, merged (~61° off rest) | blocked on finger-weight repair (shreds on exp01–exp05 and on Mako) |
| `pose_grip.json` | `CombatIdle1H01` f0, both hands (~44° off rest) | blocked, same repair |
### `pose_flat` is the REST pose — and that is why it is useful
Measured 2026-08-18: `pose_flat.json` matches `kevin_female_combat.glb`'s finger rests to
**0.04°** — it is the canonical rest pose, not a separately harvested "flat hand". Do not
expect it to straighten a hand that is already at rest.
It is still the load-bearing pose, because **the shipped clips do not hold fingers at
rest** — they pin them in a permanent curl (frozen tracks, spread 0.0°). `UAL1 Idle_Loop`
holds the fingers **53.9° off rest on average, up to 86.8°** (`thumb_03_r`) — near a
clench. So the FLAT layer's real job is to undo that baked-in curl.
On Mako that curl is what shreds his hands. It does not fling verts (max displacement only
23.3 cm, i.e. legitimate fingertip travel) — it **tears**: 2,258 edges stretched >5×, max
198×, which rips his fused hand open into sheets. Turning FLAT on removes the bulk of it.
Evidence (in-engine, the only honest judge here):
`characters/work/mako/handfix/review/ingame_handcam_flat_{OFF,ON}.png` and the
`ingame_mako_{left,right}_hand_flat_ON_zoom.png` crops. **Residual:** at close range his
RIGHT hand still shows a torn patch with FLAT on — his right hand owns far less finger
geometry than his left (4,283 verts vs 10,532; `middle_02_r` owns just 157), so it is not
fully fixed. FLAT only holds the FINGER bones at rest; `hand_l/r` still follow the clip.
## Verification (before shipping a pose)
@@ -34,5 +64,22 @@ bodies instead.
- `tools/skin_displacement_check.py posed.glb original.glb` — Godot-exact LBS travel;
cm-scale = sane, m-scale = broken. **Blind to fin tearing** — pair it with the
edge-stretch check (`tools/edge_stretch.py`).
- `tools/handpose_skin_to_obj.py` + `tools/handpose_render_objs.py` — the only honest
visual check. Never judge by importing a baked-pose GLB into Blender (false shards).
- `tools/handpose_skin_to_obj.py` + `tools/handpose_render_objs.py` — clay render. Never
judge by importing a baked-pose GLB into Blender (false shards). Pass an ABSOLUTE outdir
(a relative one silently writes nothing), name inputs `<pose>_hand_<l|r>.obj` (the glob
requires it), and crop to the hand with `tools/obj_crop.py` or the arm dominates the frame.
- `tools/skin_lever_audit.py body.glb` — finds bindings whose joint is implausibly far away
in rest, and verts bound across the midline to the opposite hand. **Invisible at rest**,
so nothing else catches them: this is what found Mako's 444 cross-hand verts.
- `tools/skin_crosshand_repair.py in.glb out.glb` — repairs those by inpainting from the
mesh's own healthy neighbours (`--diagnose` to preview).
- `tools/hand_bone_ownership.py body.glb [l|r]` — which finger bones actually own geometry.
Run it before trusting a pose on a new body: Mako is a **two-finger rig**, so only his
thumb and middle chains own verts and index/ring/pinky own nothing.
- `tools/rest_deviation.py canonical.glb other.glb` — per-bone finger rest deviation, i.e.
whether a body needs the rest-relative correction.
**Ratio alone is not the tearing gate.** `edge_stretch.py` reports huge ratios on this
mesh's sub-millimetre sliver edges (unwelded duplicates) — judge the **absolute posed
length**. On Mako, flat's worst stretched edge reaches ~1–2.4 cm (benign, sub-pixel in
engine) while fist/grip reach 10–15 cm (real, visible needles).
hand-poses/canonical_rest.json
+246
View File
@@ -0,0 +1,246 @@
{
"_comment": "Canonical Quaternius finger-bone REST rotations, read from kevin_female_combat.glb. The runtime applies a pose rest-relative: delta = canonical_rest^-1 * pose, target = body_rest * delta. This makes poses correct on rigs whose finger rest differs from canonical (Mako's *_01 knuckles sit 11.5 deg off). Generated by tools/make_canonical_rest.py.",
"source": "kevin_female_combat.glb",
"bones": {
"index_04_leaf_l": [
-4e-08,
0.99982297,
0.0,
0.01881603
],
"index_03_l": [
1.99e-06,
-7.07e-06,
-0.00018567,
1
],
"index_02_l": [
4.8e-07,
4.949e-05,
-0.00053302,
0.99999988
],
"index_01_l": [
0.00850501,
0.70681149,
-0.0185241,
0.7071082
],
"middle_04_leaf_l": [
-0.0,
0.99982554,
0.0,
0.0186798
],
"middle_03_l": [
-3.6e-07,
-5.432e-05,
-0.00141977,
0.99999905
],
"middle_02_l": [
5.9e-07,
7.837e-05,
0.00205278,
0.99999791
],
"middle_01_l": [
0.00506735,
0.70676285,
-0.02195816,
0.70709157
],
"pinky_04_leaf_l": [
0.0,
0.99982917,
-1e-08,
0.01848373
],
"pinky_03_l": [
3.26e-06,
-0.00013735,
0.00046609,
0.99999988
],
"pinky_02_l": [
4.4e-07,
9.531e-05,
-0.0015675,
0.99999881
],
"pinky_01_l": [
0.00260105,
0.70668215,
-0.0244147,
0.70710504
],
"ring_04_leaf_l": [
-0.0,
0.99981856,
4e-08,
0.01904976
],
"ring_03_l": [
3.61e-06,
-0.00025298,
-0.00338758,
0.99999422
],
"ring_02_l": [
-4.8e-06,
0.00021854,
0.00239975,
0.99999708
],
"ring_01_l": [
0.01532381,
0.70691711,
-0.01171326,
0.70703346
],
"thumb_04_leaf_l": [
-1e-08,
0.38270876,
1e-08,
0.92386907
],
"thumb_03_l": [
-1.3e-07,
-2.972e-05,
1.65e-06,
1
],
"thumb_02_l": [
7.4e-07,
4.63e-06,
-3.99e-06,
1
],
"thumb_01_l": [
-0.24446329,
-0.94356763,
-0.21606149,
0.05688012
],
"index_04_leaf_r": [
0.0,
-0.99982297,
-0.0,
0.01881603
],
"index_03_r": [
1.98e-06,
7.07e-06,
0.00018565,
1
],
"index_02_r": [
4.1e-07,
-4.94e-05,
0.00053306,
0.99999988
],
"index_01_r": [
0.00850504,
-0.70681167,
0.01852416,
0.70710802
],
"middle_04_leaf_r": [
-6e-08,
-0.99982554,
-0.0,
0.01867968
],
"middle_03_r": [
-4.3e-07,
5.437e-05,
0.00141985,
0.99999899
],
"middle_02_r": [
5.9e-07,
-7.843e-05,
-0.00205283,
0.99999791
],
"middle_01_r": [
0.00506735,
-0.70676279,
0.02195819,
0.70709163
],
"pinky_04_leaf_r": [
-0.0,
-0.99982917,
0.0,
0.01848373
],
"pinky_03_r": [
3.21e-06,
0.00013741,
-0.000466,
0.99999988
],
"pinky_02_r": [
4.2e-07,
-9.54e-05,
0.00156743,
0.99999875
],
"pinky_01_r": [
0.0026011,
-0.70668221,
0.02441467,
0.70710492
],
"ring_04_leaf_r": [
0.0,
-0.99981856,
-0.0,
0.01904976
],
"ring_03_r": [
3.69e-06,
0.00025282,
0.00338756,
0.99999422
],
"ring_02_r": [
-4.9e-06,
-0.0002185,
-0.00239973,
0.99999714
],
"ring_01_r": [
0.01532385,
-0.70691711,
0.01171329,
0.7070334
],
"thumb_04_leaf_r": [
-5e-08,
-0.38270876,
2e-08,
0.92386901
],
"thumb_03_r": [
-2e-07,
2.964e-05,
-2.08e-06,
1
],
"thumb_02_r": [
6.8e-07,
-4.78e-06,
3.18e-06,
1
],
"thumb_01_r": [
-0.24446253,
0.94356787,
0.21606137,
0.0568799
]
}
}
hand-poses/pose_fist_detwist.json
+244
View File
@@ -0,0 +1,244 @@
{
"bones": {
"index_01_r": [
0.351009,
-0.560774,
0.497857,
0.56077
],
"index_02_r": [
0.695232,
1e-06,
0.211656,
0.686916
],
"index_03_r": [
0.700051,
-1e-06,
0.205494,
0.683886
],
"index_04_leaf_r": [
2.422049449890551e-09,
-0.9998229742050171,
-1.465072729800454e-09,
0.01881602592766285
],
"middle_01_r": [
0.368445,
-0.522544,
0.543295,
0.544083
],
"middle_02_r": [
0.625715,
-0.000948,
0.176605,
0.759796
],
"middle_03_r": [
0.636196,
0.000719,
0.144964,
0.757786
],
"middle_04_leaf_r": [
-7.969595827717058e-08,
-0.9998255372047424,
-1.2168405838508534e-08,
0.018679669126868248
],
"pinky_01_r": [
0.45704,
-0.469857,
0.56239,
0.50405
],
"pinky_02_r": [
0.797564,
0.000666,
0.130697,
0.588905
],
"pinky_03_r": [
0.800258,
-0.000488,
0.105028,
0.590386
],
"pinky_04_leaf_r": [
-1.2306506924630867e-08,
-0.9998291730880737,
2.6629458638183223e-09,
0.018483733758330345
],
"ring_01_r": [
0.439332,
-0.489788,
0.556349,
0.507514
],
"ring_02_r": [
0.716635,
-7e-06,
0.101299,
0.690053
],
"ring_03_r": [
0.725824,
0.000775,
0.019064,
0.687615
],
"ring_04_leaf_r": [
-1.1020341972312053e-08,
-0.9998185634613037,
-4.304683276501464e-09,
0.0190497525036335
],
"thumb_01_r": [
0.3767375349998474,
-0.924089252948761,
-0.06302371621131897,
0.01248654630035162
],
"thumb_02_r": [
0.41932806372642517,
0.04982568323612213,
0.0259289238601923,
0.9060955047607422
],
"thumb_03_r": [
0.41881823539733887,
0.04550888016819954,
0.03892602026462555,
0.9060932397842407
],
"thumb_04_leaf_r": [
-4.8268116614735845e-08,
-0.38270869851112366,
2.2432569579677875e-08,
0.9238690137863159
],
"index_01_l": [
0.39218,
0.555922,
-0.477598,
0.555918
],
"index_02_l": [
0.724569,
-0.0,
-0.139418,
0.674954
],
"index_03_l": [
0.727499,
-0.0,
-0.131666,
0.673357
],
"index_04_leaf_l": [
-3.7380786466201243e-08,
0.9998229742050171,
1.2021164064179857e-09,
0.018816031515598297
],
"middle_01_l": [
0.415844,
0.518752,
-0.515325,
0.54075
],
"middle_02_l": [
0.64627,
0.000979,
-0.123229,
0.753093
],
"middle_03_l": [
0.652853,
-0.000737,
-0.090181,
0.752097
],
"middle_04_leaf_l": [
-9.942080492209016e-10,
0.9998255372047424,
4.936169251124056e-09,
0.018679805099964142
],
"pinky_01_l": [
0.510799,
0.470059,
-0.513511,
0.504415
],
"pinky_02_l": [
0.811413,
-0.000677,
-0.021826,
0.584065
],
"pinky_03_l": [
0.811635,
0.000494,
0.003368,
0.584156
],
"pinky_04_leaf_l": [
-2.0175272563704993e-09,
0.9998291730880737,
-1.9009007701242808e-08,
0.018483726307749748
],
"ring_01_l": [
0.491088,
0.489266,
-0.512127,
0.507126
],
"ring_02_l": [
0.726699,
8e-06,
-0.026298,
0.686453
],
"ring_03_l": [
0.724342,
-0.000773,
0.056651,
0.687109
],
"ring_04_leaf_l": [
1.3828260758685929e-10,
0.9998185634613037,
3.419970084905799e-08,
0.019049758091568947
],
"thumb_01_l": [
0.37334099411964417,
0.924976646900177,
0.06633511930704117,
0.02518703043460846
],
"thumb_02_l": [
0.42000612616539,
-0.049613188952207565,
-0.011237763799726963,
0.9060944318771362
],
"thumb_03_l": [
0.4200849235057831,
-0.044214341789484024,
-0.023830465972423553,
0.9060937762260437
],
"thumb_04_leaf_l": [
-1.3077848803888514e-09,
0.38270875811576843,
4.056841529376243e-09,
0.9238690137863159
]
}
}
hand-poses/pose_grip_detwist.json
+244
View File
@@ -0,0 +1,244 @@
{
"bones": {
"index_01_l": [
0.372089,
0.575212,
-0.44701,
0.575207
],
"index_02_l": [
0.536175,
-0.0,
-0.075882,
0.840689
],
"index_03_l": [
0.537411,
-0.0,
-0.074724,
0.840004
],
"index_04_leaf_l": [
-4.2130491095804246e-08,
0.9998229742050171,
6.104919680893772e-09,
0.018816012889146805
],
"middle_01_l": [
0.362081,
0.571521,
-0.440008,
0.590469
],
"middle_02_l": [
0.530509,
0.000803,
-0.091032,
0.842777
],
"middle_03_l": [
0.535123,
-0.000604,
-0.066811,
0.842128
],
"middle_04_leaf_l": [
1.4026132255651191e-08,
0.9998255372047424,
-1.303601337987459e-09,
0.01867981255054474
],
"pinky_01_l": [
0.379526,
0.578646,
-0.394442,
0.604603
],
"pinky_02_l": [
0.534097,
-0.000446,
-0.015743,
0.845276
],
"pinky_03_l": [
0.534231,
0.000325,
0.006553,
0.845313
],
"pinky_04_leaf_l": [
1.7368666505035435e-08,
0.9998291730880737,
-2.2143675337815694e-08,
0.01848371885716915
],
"ring_01_l": [
0.382671,
0.580734,
-0.403254,
0.594725
],
"ring_02_l": [
0.553724,
6e-06,
-0.018994,
0.832484
],
"ring_03_l": [
0.552551,
-0.00059,
0.03354,
0.832804
],
"ring_04_leaf_l": [
-5.756760401709471e-09,
0.9998185634613037,
2.5820394711217887e-08,
0.01904975064098835
],
"thumb_01_l": [
0.36847078800201416,
0.8819453120231628,
0.2921511232852936,
0.03239520639181137
],
"thumb_02_l": [
0.24808266758918762,
-0.029302185401320457,
-0.0066396272741258144,
0.968272864818573
],
"thumb_03_l": [
0.24812805652618408,
-0.026128530502319336,
-0.014074699021875858,
0.9682725071907043
],
"thumb_04_leaf_l": [
-4.946755449708462e-09,
0.38270875811576843,
1.279980677004744e-09,
0.9238690137863159
],
"index_01_r": [
0.33652,
-0.579358,
0.464165,
0.579353
],
"index_02_r": [
0.522149,
1e-06,
0.108755,
0.845891
],
"index_03_r": [
0.524414,
-1e-06,
0.108105,
0.844573
],
"index_04_leaf_r": [
4.50209008961977e-10,
-0.9998229742050171,
-7.24976256805121e-09,
0.0188160240650177
],
"middle_01_r": [
0.329666,
-0.574074,
0.458768,
0.592699
],
"middle_02_r": [
0.517316,
-0.000784,
0.123773,
0.846796
],
"middle_03_r": [
0.524415,
0.000592,
0.1003,
0.845534
],
"middle_04_leaf_r": [
-4.130962949489003e-08,
-0.9998255372047424,
-1.7077526059949832e-09,
0.018679669126868248
],
"pinky_01_r": [
0.354361,
-0.578543,
0.417584,
0.604433
],
"pinky_02_r": [
0.529705,
0.000442,
0.049638,
0.846728
],
"pinky_03_r": [
0.530597,
-0.000323,
0.027208,
0.847188
],
"pinky_04_leaf_r": [
2.6093180949260386e-09,
-0.9998291730880737,
3.3186802195217524e-09,
0.018483715131878853
],
"ring_01_r": [
0.355867,
-0.581001,
0.426447,
0.594928
],
"ring_02_r": [
0.54862,
-5e-06,
0.055744,
0.834212
],
"ring_03_r": [
0.553196,
0.000591,
0.003472,
0.833044
],
"ring_04_leaf_r": [
-2.2238539898467025e-08,
-0.9998185634613037,
-6.419670128821053e-09,
0.019049761816859245
],
"thumb_01_r": [
0.37758150696754456,
-0.8796287178993225,
-0.288614422082901,
0.019680041819810867
],
"thumb_02_r": [
0.24768105149269104,
0.029427889734506607,
0.015316151082515717,
0.9682735204696655
],
"thumb_03_r": [
0.2473800927400589,
0.02689296193420887,
0.02299121953547001,
0.96827232837677
],
"thumb_04_leaf_r": [
-4.4832216161694305e-08,
-0.38270875811576843,
2.3225833700735166e-08,
0.9238690137863159
]
}
}