企业官网建设流程全解析

Motion2MixamoRig 是一款能把视频或照片里的人物动作，转移到 Adobe Mixamo 3D 角色上的开源工具。它的核心是 GVHMR 人体姿态估计管线：先用 RTMPose 从每一帧提取 2D 关键点，再经过一套"左右一致性稳定化"算法消除左右互换，最后由 GVHMR 提升出米制单位、Y 轴朝上的 3D 骨架，并驱动 Mixamo 角色输出可直接进 Blender / Unity 的 .glb 文件。本文带你完整看懂这条从 2D 到 3D 的动作提取管线。

管线全景：一段视频如何变成 3D 角色动画

整条管线分为四个阶段，每个阶段都有明确的产物文件，方便定位问题：

1. 2D 姿态估计：逐帧检测 COCO-17 人体关键点 → 缓存为preprocess/vitpose.pt
2. 关键点稳定化：校正左右标签互换 → 修正后的 2D 缓存（原文件备份为*_raw）
3. GVHMR 3D 提升：2D 骨架 + 时序上下文 → 24 个 SMPL 关节的世界坐标 3D 骨架 →skeleton_motion.npz
4. 重定向与渲染：3D 骨架驱动 Mixamo rig →mixamo_character.glb+ 预览视频

核心实现分散在 extract.py（GVHMR 调用与 3D 骨架落盘）、stabilize_kp2d.py（稳定化算法）和 pipeline.py（串联全流程）。

第一站：RTMPose 逐帧输出 2D 关键点

m2mr run的提取阶段会调用 extract_motion()，内部以pose2d="rtmpose"模式运行 GVHMR。RTMPose（ViTPose 后端）负责在每一帧上定位 17 个人体关键点（COCO-17：鼻、眼、耳、肩、肘、腕、髋、膝、踝）。

结果会缓存到工作目录的preprocess/vitpose.pt。这个缓存有个关键作用：同一输入重跑时可以直接复用昂贵的 2D 估计，只有 3D 提升会重算——这对调试非常友好。

左右互换：2D 关键点最大的"隐形杀手"

2D 姿态估计器是逐帧独立判断左右的。当人物转身背对镜头时，画面里的"左肩"和"右肩"在图像坐标上会互换位置，RTMPose 很可能把标签也一起换掉。单看任何一帧，标注都"没错"；但连成序列后，骨架会在转身瞬间"跳"一下。

GVHMR 读到这样跳变的 2D 序列，会把一次普通的转身理解成 3D 朝向突变——这就是新手最常遇到的"角色转身时身体乱转"问题的根源。

稳定化算法：追踪解剖学身份，而不是重新猜

关键实现是 stabilize_coco17()。思路非常简洁：每一帧的左右对，跟随上一帧的位置，让解剖学身份（anatomical identity）在时间上连续，而不是每帧重新猜一遍。

具体判断分三步：

• 测量"宽度"：用左肩减右肩的图像 x 坐标（肩部退化时用髋部代替）得到一个带符号的宽度值。宽度取绝对值，因此不受左右互换影响——这是整个算法的巧妙之处。
• 自适应"窄视角"阈值：narrow取整段视频宽度的中位数 ×0.45（夹在 40~80 像素之间）。真转身过程中会经过窄的侧身视角；标签跳变则会在宽度仍很大时直接翻转符号。用"转身后是否有一段持续窄宽度"来区分真转身和标签翻转，还能正确处理转身中途估计器误报 50~60px 宽度的边界帧。
• 执行交换：判定为标签跳变的帧，套用 COCO17_SWAP 重排索引；若只有髋部以下左右不一致，则单独交换髋以下 6 个关键点。

稳定化完成后：

• 若有任何修正，会删除hmr4d_results.pt3D 缓存并重跑一次 GVHMR 提升，保证 3D 结果基于修正后的 2D 数据（见 extract.py 中的缓存处理逻辑）；
• 修正前的原始数据备份为vitpose_raw.pt，事后想对比"估计器 vs 稳定器"永远有据可查；
• 过程完全幂等——已经稳定过的缓存再跑一遍不会有任何改动，并会打印类似stabilized vitpose.pt: corrected 12/480 left/right flips的统计信息。

GVHMR 3D 提升：从像素到米制世界坐标

稳定后的 2D 序列送入 GVHMR（时序模型，static_camera=True假设固定机位）。它输出 SMPL-X 参数，工程上通过 joints_world_from_smplx() 用自带的smplx2smpl稀疏映射和J_regressor转成24 个 SMPL 关节的世界坐标——无需额外加载受限的 SMPL.pkl文件。

最终产物skeleton_motion.npz包含：

两个细节值得注意：

• 单张照片也能跑：GVHMR 是时序模型，单帧"视频"太短不稳定，still_to_hold_video() 会把照片重复约 1 秒（32 帧 @30fps）生成一个"定格"短片，恢复出静态 3D 姿态。
• 60fps 源片不会拖慢：GVHMR 固定报告 30fps，playback_fps() 会用 ffprobe 读到的源片真实时长反算回放帧率，保证动画节奏和原视频一致。

重定向到 Mixamo：从骨架到可交付的 .glb

提取完成后，run_pipeline() 接管：加载 Mixamo rig 做静息姿态标定 → 建立 SMPL 24 关节到 Mixamo 骨骼的映射 → 逐帧生成动画旋转 → 写出mixamo_rotations.npz和带蒙皮的角色文件mixamo_character.glb，并渲染四宫格预览（原视频 / 人体骨架 / Mixamo 骨架 / 最终角色）。

一次运行的目录结构（视频输入为例）：

outputs/20260829_193205_dance/ ├── run.json # 输入、命令、错误指标 ├── skeleton_motion.npz # 3D 人体骨架，可复用 ├── mixamo_rotations.npz # 逐骨骼动画旋转 ├── mixamo_character.glb # 带蒙皮角色（Blender/Unity 直接导入） ├── cache/ # GVHMR 中间产物（vitpose.pt 等） └── videos/ # 预览视频

💡省钱技巧：换角色时不要用--rig重跑全流程，而是用--skeleton复用已提取的骨架，几分钟的提取直接跳过：

m2mr run --skeleton outputs/<上次运行目录>/skeleton_motion.npz --rig assets/mixamo/Vampire.fbx

上手三步与常见坑

快速开始（详见 README.md）：

m2mr doctor # 检查 SMPL-X、Mixamo FBX、输入视频是否就位 m2mr run # 用 assets/video/ 里最新的视频 + 默认 Y Bot 跑全流程

首次运行会自动下载约 5GB 推理权重到weights/（仅一次）；CPU 上 30 秒视频提取约 8–15 分钟。

输入视频的三个硬性要求，不满足会直接拒绝进入提取阶段：

• 画面里有且只有一个人；
• 从头到脚全程在画框内，不能被边缘裁掉；
• 建议使用固定机位拍摄（管线假设static_camera=True）。

排障小抄：

总结

Motion2MixamoRig 的 2D→3D 管线值得借鉴之处，是把"估计器会犯的系统性错误"当工程问题来解：RTMPose 的左右互换不靠换更强的估计器，而靠一段只依赖"宽度符号 + 窄视角连续性"的轻量稳定化（stabilize_kp2d.py），配合幂等、可回溯的缓存策略，让 GVHMR 的 3D 提升始终站在干净数据之上。对新手来说，抓住vitpose.pt（2D）→skeleton_motion.npz（3D）→mixamo_character.glb（交付物）三个文件，就能看懂并调试整条管线。