animation/.agents/plans/rig-graft-lane-2026-08-04.md

# Rig-graft lane — AccuRig skeleton onto pristine Tripo GLBs (PLAN, not executed)

**Repo home:** this plan and its tools moved from ariki-game into the animation repo
2026-08-06 — the lane authors characters, so `characters/REGISTRY.md` governs it (see
`.agents/wiki/ARCHITECTURE.md` "Which repo does a non-gameplay tool belong to"). Paths
below are animation-repo-relative unless prefixed `ariki-game/`.

**Status 2026-08-04: PLAN ONLY. Jeremy has explicitly held execution — no model
files are to be created or modified until the naming convention is decided.**

## Goal

Rig Ozlem's two unrigged Tripo bodies without the FBX→GLB quality loss the male
lane hit in July (mangled textures, bad hand skinning). The move: FBX is only a
**disposable rig carrier** through AccuRig; the **GLB is the sole source of truth**
for mesh + materials and only ever *gains* bones and weights.

## Source files (curated 2026-08-04)

Byte-identical copies live in both repos: `characters/originals/` here (checksummed in
`characters/REGISTRY.md`) and `ariki-game/assets/models/characters/race-sources/`. Read
from this repo's copies.

| file | verts | tris | height | feet @ Z0 | axis | textures |
|---|---|---|---|---|---|---|
| `female_lena_tripo.glb` | 974,478 | 1,907,931 | 0.979 m | yes (0.0) | upright, rot 0, scale 1 | 3 packed 4K (basecolor/normal/rm) |
| `female_lena_tripo.fbx` | 953,968 | 1,907,931 | 0.979 m | — | upright | 5 external JPEGs (.fbm removed; git-recoverable) |
| `male_base_bald_tripo_v1.glb` | 969,881 | 1,901,449 | 0.980 m | yes (0.0) | upright, rot 0, scale 1 | 3 packed 4K, clean |
| `male_base_bald_tripo_v1.fbx` | 950,729 | 1,901,449 | 0.980 m | — | **lying down (bad axis)** | 6 packed, all mislabeled "Diffuse Texture.NNN", duplicated basecolor |

Census facts that shape the plan:

- **No bones anywhere** — all four files are truly unrigged, so no rig standard is
  imposed by the sources. The 65-bone Quaternius game standard is unaffected.
- **Identical surfaces per pair** (tri counts match exactly); vertex counts differ
  ~2% from format-specific UV-seam splitting → index-exact weight copy is off the
  table, nearest-surface transfer is the mechanism (surfaces coincide, so it is
  near-exact everywhere except close-packed fingers — see step 4).
- The male FBX's axis + texture mangling is the July failure mode reproduced in
  data — never source visual data from FBX.

## Decisions (Jeremy, 2026-08-04)

1. **NO scaling to standard height.** Bodies stay at Tripo's native ~0.98 m.
   (Any scale handling happens later, downstream, not in this lane.)
2. **Axis check + ground the feet** — wanted, and the probe shows both GLBs
   already pass (rot 0 / scale 1 / min-Z exactly 0.0). These become verify-only
   gates, mutating nothing unless a future source fails them.
3. **HOLD before decimation** until the naming convention for derived files is
   agreed. Nothing below the line runs until then.

## The lane (each step gated on the one before)

1. **Verify** (read-only, DONE for the two current GLBs): upright axis, unit
   scale, feet at Z=0, centered X, packed textures present.
2. **Rig bait** *(HELD — naming)*: from the GLB, decimate a disposable copy and
   export FBX for AccuRig. **Confirmed 2026-08-04: AccuRig refuses the raw
   1.9 M-tri FBX outright** (Jeremy tried; July hit the same wall). Use the
   `ariki-game/tools/male_mesh_decimate.py` precedent: region budgets body 24k / head 14k /
   **hands 10k as their own protected region** (global-ratio decimation webs the
   fingers — half of the historic hand-mangling happened here, pre-AccuRig).
   Apply the July male-lane traps: Dummy-export quirk, the 4 cm offset.
   No scale change on the GLB — but if AccuRig misplaces joints on a 0.98 m
   body, scale the DISPOSABLE BAIT up 2× and scale the returned skeleton back
   down in the graft; the GLB never changes size.
3. **AccuRig** (manual, Jeremy/Ozlem): rig the bait FBX. Export rigged FBX.
4. **Graft** (headless Blender): import rigged bait FBX + pristine GLB; snap rest
   poses; transfer skeleton + skin weights decimated→full-res by nearest-surface
   with tight max-distance. Export GLB: original mesh + original packed
   textures + new rig. FBX artifacts are discarded.
   **Hands are no longer part of this step — see "Hands" below.**
5. **QC**: pose sweep incl. finger curls; then (if/when destined for game) the
   existing AccuRig→Quaternius conversion (`ariki-game/tools/make_male_ib_quatskin_accurig.py`
   lineage) picks it up.

## Hands: transplanted, not solved (RESOLVED 2026-08-07)

The hands come off the bait entirely and are transplanted from a body that already
ships working ones — `tools/graft_hands.py`, wrist-aligned. Three measurements
decided this:

- **There is nothing to solve.** The nude lane never touched the hands: hand-region
  displacement from the Tripo original is mean **0.010 mm**, p50 exactly 0.000, only
  0.06% beyond 1 mm (the 12.6% vertex churn there is micron jitter from the v03
  despeckle pass). A donor's hand weights fit this mesh as-is.
- **A mitten rig would cost real animation.** Fingers move *relative to each other*
  by up to **89°** over a clip (fertility 89.4°, taming 77.6°, nd_01 46.7°,
  canoedismount 26.4°); only `war_dance_01` and `hakadance1_static` hold them still.
  So four of six dances would visibly flatten. Rejected.
- **The bone list is not negotiable anyway.** 40 of the 65 joints are hands, every
  clip carries tracks for all 40, and `tools/verify_body_variant.py` gates on "65
  joints in identical order". A mitten could only ever have been a *skinning* choice.

`graft_hands.py` edits the glTF node graph directly rather than round-tripping the
armature through Blender, because Blender re-derives bone rest orientation from
edit-bone head/tail — the exact failure `ariki-game/tools/rig_pose_gate.py` exists to
catch. Validated: two self-tests (identity, and a 0.55× + 7° similarity) place every
hand joint to **5e-16 u** and recover 100% of donor weights; output passes
`verify_body_variant.py`; and `rig_pose_gate.py` reports **max error 0.000° over 260
(bone, clip, sample) comparisons** under the two most finger-heavy dances.

Two self-inflicted bugs the similarity test caught, worth not re-introducing: the
wrist scale gets applied **twice** if you compose the target's wrist matrix without
stripping its own scale first (the forearm ratio was measured in that same scaled
space), and the weight transfer must convert donor-local → world → target-local, not
compare raw POSITION arrays across two files.

**Still open on hands:** if AccuRig returns no wrist joint at all once the hands are
cut from the bait, `graft_hands.py` aborts — the `--wrist-from-forearm` fallback is
specified but not implemented, because what AccuRig actually returns is unknown until
step 3 runs.

## Naming + step 2 status (RESOLVED 2026-08-04, later same day)

Jeremy raised the hands budget and released the bait step. Built with
`tools/rigbait_decimate.py` (parameterized successor to male_mesh_decimate.py —
no scale/recenter, bbox-relative region cuts, budgets body 24k / head 14k /
**hands 40k**):

- `characters/rig-work/lena_tripo_rigbait.fbx` — 77,999 tris, QA'd
- `characters/rig-work/mako_tripo_rigbait.fbx` — 78,000 tris, QA'd
- `characters/rig-work/` is exempt from the naming grammar (REGISTRY.md rule 11) —
  disposable carriers, no registry rows. In the game repo it had needed a `.gdignore`
  to stop Godot importing it, which was the tell that it lived in the wrong repo.
- QA renders alongside (`*_qa_front.png`, `*_qa_hand.png`) — fingers fully
  distinct at 40k, no webbing.
- Baits are geometry-only (~3.5 MB; the GLB's packed textures don't survive FBX
  embed) — AccuRig shows a grey model, which is fine for rigging. It does mean
  the July "Dummy001 export" check can't use textures: **verify AccuRig's output
  by mesh name + ~78k tri count instead.**

**AccuRig exports must be saved as** (same folder):
- `characters/rig-work/lena_tripo_accurig.fbx`
- `characters/rig-work/mako_tripo_accurig.fbx`

## Open before execution

- Step 3 (AccuRig) — manual, waiting on Jeremy/Ozlem.
- Step 4 graft script — build once a rigged FBX exists to test against.
- Whether to restore the female FBX's `.fbm` texture folder from git (only needed
  if the FBX is ever used for more than rigging; the lane says it shouldn't be).