mocapgod/docs/C_RETARGET.md

Lane C — retarget + cleanup (retarget.py)

DONE (machinery) 2026-07-17 (session 6). retarget.py takes a SKEL-24 motion.bvh (from pose_engine.py) onto the character_kit mixamorig rig → baked anim-only FBX + QC turntable mp4. Verified on the gymnasts demo: recognizable human motion (not soup), and the FBX merges onto female_game.glb and drives it. Final quality sign-off awaits John's own walk/DJ footage.

Run (headless Blender only)

/Applications/Blender.app/Contents/MacOS/Blender --background --python retarget.py -- \
    --bvh out/<name>/motion.bvh [--rig <glb>] [--name <n>] [--travel] [--foot-fix] [--no-qc]

Defaults: rig = character_kit/female/female_game.glb, out = clips_out/, root in-place. Outputs: clips_out/<name>.fbx (anim-only, Mixamo "Without Skin") + clips_out/<name>_qc.mp4. Proven chain A→C: pose_engine.py <clip> → out/<name>/motion.bvh → retarget.py --bvh ….

How it works

• Import mixamorig rig (glb) + SKEL BVH (axis_forward=-Z, axis_up=Y; both land Z-up in Blender).
• Per spec/skel_to_mixamorig.json (20 bones; 4 null twist/heel), add world-space Copy Rotation (target mixamorig ← SKEL bone), then nla.bake(visual_keying, clear_constraints) → a clean mixamorig action. find_bone tolerates the mixamorig: colon vs mixamorig_ underscore trap.
• Root in-place by default (HSMR root is camera-space, not world-grounded); --travel copies it.
• Export anim-only FBX (object_types={ARMATURE}, bake_anim). QC = Workbench turntable, PNG frames stitched to mp4 by system ffmpeg, camera auto-framed from the world bbox.

Blender 5.0 gotchas hit + resolved (carry into Lane D)

• Baklava actions: Action.fcurves is gone → action_fcurves() walks layers/strips/channelbags.
• Merge needs slot binding (load-bearing): assigning an action is NOT enough — you must set animation_data.action_slot = act.slots[0] or nothing drives. Verified: with the slot bound, gymnasts.fbx drives female_game.glb (RightHand +121u), exports a playable 7.3 MB GLB. character_kit/scripts/merge_anims.py FIXED 2026-07-17 — binds strip.action_slot on each NLA strip (hasattr-guarded for 4.x); verified Lifting_Object drives female_game.glb (LeftHand delta 6.7u frame 1→138).
• No FFMPEG image format in Blender 5.0 → render PNG frames + system ffmpeg stitch.
• Mixamo scale: female_game.glb imports at armature-scale 0.01 but ≈156 units tall, centred z≈77. QC auto-frames from the bbox; keep retarget rotation-only — never scale the rig (scaling a skinned ancestor tears the mesh when it animates; the merge_anims.py units warning).

Deferred (honest — not gold-plated)

• Foot-contact fix is a stub (--foot-fix logs planted frames only, no IK → feet may slide). Deferred until a real walk clip exists to tune against (gymnasts are airborne). # ponytail in code.
• --travel (root translation + unit scaling) is wired but unverified; in-place is v1-first-class.
• Arms/hands quality: gymnasts looked clean (no catastrophic roll). If DJ hand work twists on John's footage, upgrade the single map_and_bake to a rest-delta transfer (Rt=Rs·Rs_rest⁻¹·Rt_rest) — noted in code; nothing else changes.