91 lines
4.5 KiB
Markdown
91 lines
4.5 KiB
Markdown
|
# Architecture — animation pipeline
|
||
|
|
|
||
|
|
Entry point to architecture law for this repo. Per-system detail lives in
|
||
|
|
`.agents/wiki/architecture/`.
|
||
|
|
|
||
|
|
## The one-sentence shape
|
||
|
|
|
||
|
|
PC-side motion capture (iClone 8 + Video Mocap) → this repo (Mac↔PC bridge,
|
||
|
|
Blender-headless retargeting, loop QC) → `ariki-game` (Quaternius-rig GLB
|
||
|
|
consumption via ClipCatalog).
|
||
|
|
|
||
|
|
## Machines and where things live
|
||
|
|
|
||
|
|
| Machine | Owns |
|
||
|
|
|---|---|
|
||
|
|
| PC (Windows) | iClone 8 + Video Mocap plugin — authors motion, exports FBX |
|
||
|
|
| Mac (and PC) | Blender 5.1.2, this repo's retarget tools, `ariki-game` checkout |
|
||
|
|
|
||
|
|
Files move machine-to-machine only through `exchange/` in this repo, synced
|
||
|
|
with `tinqs push`/`tinqs pull` (Git LFS for `.fbx/.glb/.mp4/.task` — see
|
||
|
|
`.gitattributes`). Raw `git pull` hangs on LFS in tinqs.com repos.
|
||
|
|
|
||
|
|
## Pipeline stages
|
||
|
|
|
||
|
|
1. **Capture (PC)** — iClone export, Blender preset, Range=All, Preserve Bone
|
||
|
|
Names ON → `exchange/incoming-fbx/`.
|
||
|
|
2. **Retarget (either machine)** — Blender-headless, source-specific retargeter
|
||
|
|
in `tools/`, all bake onto the shared Quaternius rig and export a
|
||
|
|
mesh-stripped GLB with one NLA track per clip:
|
||
|
|
- `cc_retarget.py` — Reallusion CC/iClone `CC_Base_*` FBX (60fps; rejects
|
||
|
|
2-frame `_TempMotion` exports as a guard against motion-less takes)
|
||
|
|
- `mixamo_retarget.py` — Mixamo FBX (prefix auto-detect)
|
||
|
|
- `kevin_retarget.py` — Kevin Iglesias Unity FBX (`B-*` rig; hardcoded
|
||
|
|
target path, non-portable)
|
||
|
|
- `mocap_retarget.py` — MediaPipe pose JSON → GLB (rotation solving, no
|
||
|
|
source armature)
|
||
|
|
→ `exchange/converted-glb/`.
|
||
|
|
3. **Loop QC** — `tools/loop_qc.py` (pre-commit gate: pose/velocity/root-drift
|
||
|
|
continuity across the seam, exit 0 = smooth). Fixers when it fails:
|
||
|
|
`tools/loop_fix.py` (de-drift/trim/seam-blend → `exchange/looped-glb/`) and
|
||
|
|
`tools/pingpong_bake.py` (palindrome bake, seam-perfect but motion reverses
|
||
|
|
at the turn → `exchange/pingpong-glb/`, clip suffix `PP`). Every adopted
|
||
|
|
dance ships as a base clip + `_pp` pair.
|
||
|
|
4. **Ship** — commit + `tinqs push` the GLBs in this repo, then copy into
|
||
|
|
`ariki-game/assets/quaternius/dancegen/` (auto-discovered by ClipCatalog as
|
||
|
|
`<pack>/<ClipName>` — also watches `kevin/`, `mixamo/`), write one dance JSON
|
||
|
|
per clip in `ariki-game/assets/dances/`, `game.sh import`, verify clip names
|
||
|
|
match GLB `animations[].name` exactly, commit in ariki-game (push only when
|
||
|
|
Jeremy asks).
|
||
|
|
5. **Post-ingest QC (game side, out of this repo)** — `ariki-game/tools/anim_qc.py`
|
||
|
|
re-checks world-space seam continuity + renders a seam-cross video for eye
|
||
|
|
review. Two QC tools by design: this repo's gate is pre-commit/local-space,
|
||
|
|
the game's is post-ingest/world-space.
|
||
|
|
|
||
|
|
## Naming law
|
||
|
|
|
||
|
|
Full detail: `.agents/wiki/dances/REGISTRY.md` (source of truth — do not
|
||
|
|
duplicate its content elsewhere). Summary: new takes get a provisional `nd_##`
|
||
|
|
id (never a content-derived name); a take is renamed to its ceremony code
|
||
|
|
(snake_case of the sim's `DanceType` enum + index) only once Jeremy assigns it
|
||
|
|
to a specific ceremony, via `tools/rename_clip.py`. Rejected/superseded takes
|
||
|
|
are archived (`archive/`), never deleted; numbers are never reused.
|
||
|
|
|
||
|
|
## Canonical target rig
|
||
|
|
|
||
|
|
All retargeters bake onto ariki-game's
|
||
|
|
`assets/quaternius/base-characters/.../Godot - UE/Superhero_Male_FullBody.gltf`.
|
||
|
|
Run from this repo, `--target` must be passed explicitly (the tool's default
|
||
|
|
path is ariki-relative and won't resolve here). The rig/pack standard itself
|
||
|
|
(65-bone Quaternius UE-named skeleton, hero body `Ariki_Female_QuatSkin.glb`) is
|
||
|
|
governed by `ariki-game/.humans/animation-bone-sources.html` and
|
||
|
|
`ariki-game/.agents/wiki/quaternius-ual-packs.md` — this repo's iClone/mocap
|
||
|
|
lane is explicitly a separate clip source (not UAL1/UAL2/Kevin/Mixamo), landing
|
||
|
|
in `dancegen/` only.
|
||
|
|
|
||
|
|
## Tool provenance / mirroring
|
||
|
|
|
||
|
|
`tools/cc_retarget.py`, `mixamo_retarget.py`, `kevin_retarget.py`,
|
||
|
|
`mocap_retarget.py` are **mirrors of `ariki-game/tools/`** — the game copies are
|
||
|
|
authoritative; re-copy from ariki-game when they change (they have silently
|
||
|
|
diverged before). `.claude/skills/` here mirror a subset of `ariki-game/.claude/skills/`
|
||
|
|
plus `~/.claude/skills/pose-estimation` — see `README.md` Provenance section.
|
||
|
|
|
||
|
|
## See also
|
||
|
|
|
||
|
|
- `.agents/wiki/architecture/` — per-system detail (currently: this file covers
|
||
|
|
the whole pipeline; split out if a subsystem grows its own doc).
|
||
|
|
- `.agents/wiki/dances/REGISTRY.md` — naming/registry source of truth.
|
||
|
|
- `.agents/wiki/iclone-bridge.md` — PC-lane routing stub.
|
||
|
|
- `.agents/wiki/devops-reports/` — point-in-time audits and convergence reports.
|