Anim: Slice F — Animation retargeting between skeletons

[fernandotonon]

Parent epic: #517

Goal

Map a clip from one skeleton onto another. Indie devs need this constantly — buy a Mixamo animation on rig A, apply it to character rig B. Currently QtMeshEditor's AnimationMerger only merges clips between compatible skeletons; this slice handles the incompatible case.

Scope

• AnimationRetargeter static helper in src/AnimationRetargeter.{h,cpp} — mirrors AnimationMerger's API style.
• Bone mapping:
  • Auto-mapping via fuzzy name match (hand_L ↔ LeftHand, etc.), Mixamo convention detection, common Unity/Unreal naming.
  • Manual override UI: a two-column "Source bone → Target bone" mapping panel.
  • Save/load named bone mappings as JSON sidecars (mixamo_to_unity.bonemap) for reuse across projects.
• Retargeting algorithm:
  • Compute T-pose alignment between source and target (use the existing PoseLibrary from Slice D as the T-pose source if available; otherwise the bind pose).
  • Per-frame: convert source bone-local TRS to a hierarchy-independent representation (forward-kinematics-based "pose delta") then re-evaluate against the target skeleton.
  • Optional rotation-only retargeting mode for character work (preserve target's bone lengths exactly).
  • Optional position-also retargeting for facial/finger detail.
• GUI: a "Retarget Animation" wizard:
  1. Pick source clip (current or imported).
  2. Pick target entity.
  3. Auto-map → review → manual overrides.
  4. Preview side-by-side.
  5. Apply → new clip on the target entity.
• CLI: qtmesh anim source.fbx --retarget target.fbx --bonemap mixamo_to_unity.bonemap --anim Walk -o target_walking.fbx.
• MCP: retarget_animation.

Acceptance Criteria

• A Mixamo clip on a Mixamo skeleton retargets cleanly onto a Unity HumanIK skeleton with the bundled bonemap and produces a recognisably correct walk.
• Auto-map covers the standard humanoid case without manual edits on test fixtures.
• Manual override UI works for non-standard rigs.
• Bone mappings save/load as JSON.
• Side-by-side preview renders source and target simultaneously.
• The retargeted clip integrates with the existing animation timeline as a normal skeleton clip.
• All operations are undoable.
• Headless-CI-safe tests cover the auto-mapping and at least one retarget round-trip.
• Sentry breadcrumb scene.anim.retarget.* recorded.

Effort

~12 days. Algorithm complexity is real; auto-mapping is the most schedule-fragile part.