# Motion2MixamoRig
中文 · English · 한국어 · 日本語 · Deutsch · Русский · العربية · Tiếng Việt · Filipino · ไทย · Français · Español · Türkçe · नेपाली
把视频里人物的动作，或一张照片里的姿态，转到 Adobe Mixamo rig 的 3D 角色上。
面向游戏开发者：输入一段**单人**动作视频（或一张人物照片）和一个 Mixamo 角色，输出预览视频，以及可直接丢进 Blender / Unity 的带皮角色文件（`.glb`）。
> Motion2MixamoRig 目前仍处于实验阶段。v0.1.0 是命令行工作流。本仓库另有一个 Blender 4.2+ Extension，在外部 Python 里跑同一条 pipeline。插件的安装和用法见 [`blender_extension/README.md`](../../blender_extension/README.md)。
Agent 请先读 [`AGENTS.md`](../../AGENTS.md)。
https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f
打开本仓库中的 demo.mp4。
另一个 demo：
https://github.com/user-attachments/assets/073f20c8-7283-4209-98e8-f247228bfd56
## 前置条件
需要 Python 3.10+。克隆后建虚拟环境并安装依赖，`m2mr` 命令随之可用：
```bash
git clone https://github.com/MaxLiu22/Motion2MixamoRig.git
cd Motion2MixamoRig
python -m venv .venv && source .venv/bin/activate
# 安装依赖和本项目。chumpy（依赖链里的老包）的构建脚本会 import pip，
# 在 pip 默认的隔离构建环境里必然报 "No module named 'pip'"，
# 所以先关掉隔离（--no-build-isolation）单独装它，再装本项目。
pip install --upgrade pip setuptools wheel \
&& pip install "numpy>=1.26" \
&& pip install --no-build-isolation "chumpy==0.70" \
&& pip install -e .
```
推理权重（GVHMR 等）不在这一步下载，首次 `m2mr run` 时自动拉到 `weights/`（约 5 GB，只下这一次）。
建议再装上 ffmpeg（macOS：`brew install ffmpeg`，Ubuntu：`apt install ffmpeg`）。
没有它也能跑，但输出的视频会**没有声音**，编码格式也没法在浏览器里直接播放。
## 使用前：把这些东西放到 `assets/`
本仓库不附带这些文件，需要你自己准备。SMPL-X 的文件名必须和下表一字不差；FBX、视频和照片叫什么都行。一次运行需要 SMPL-X、一个 Mixamo 角色，以及**视频或照片二选一**。
| 放什么 | 放到哪 | 去哪拿 |
|---|---|---|
| SMPL-X 人体模型 | `assets/body_models/smplx/SMPLX_NEUTRAL.npz` | 注册 [SMPL-X](https://smpl-x.is.tue.mpg.de/) 后下载 |
| Mixamo 角色 FBX | `assets/mixamo/Y_Bot.fbx` | 用 Adobe 账号从 [Mixamo](https://www.mixamo.com) 下载 Y Bot（或其他 Mixamo rig 角色） |
| 动作视频 | `assets/video/.mp4` | **只有一个人**、人清晰可见、**从头到脚全程都在画框内**（可放多个文件，每次跑用最新的那一个） |
| 姿态照片（可选） | `assets/image/.jpg` | **只有一个人**、人清晰可见、**从头到脚都在画框内**。配合 `--image` 使用 |
注意：Mixamo 下载下来的文件叫 `Y Bot.fbx`（中间是**空格**），和上表的 `Y_Bot.fbx`（**下划线**）差一个字符。
改成下划线它就是默认 rig，`m2mr run` 不带 `--rig` 时自动用它；不想改名也行——找不到 `Y_Bot.fbx` 时
会自动用 `assets/mixamo/` 里的第一个 `.fbx`。
`assets/video/` 可以放多个视频文件。不指定 `--video` 或 `--image` 时，会用**最后放进 `assets/video/` 的视频**；这个文件夹是空的，就退回到 `assets/image/` 里最新的一张照片。
每个视频或照片画面里只能有一个人，而且人物必须**从头到脚都在画框内**，不能出画。`m2mr doctor` / `m2mr run` 检测到两个人就直接停，不会进入提取。
## Quick Start
结果都在 `outputs/<运行时间>_<输入名>/`。视频输入写 `videos/`，照片输入写 `images/`。
### 1. 检查资产和环境
缺什么会告诉你去哪下、放到哪。
```bash
m2mr doctor
```
### 2. 第一次跑：先拿到一个能看的结果
不带参数时，用**最后放进 `assets/video/` 的视频** + `assets/mixamo/Y_Bot.fbx`。
```bash
m2mr run
```
这步最慢。第一次跑会先下载约 5 GB 推理权重（只这一次），然后从视频里提取人体动作。
一段约 30 秒的视频，CPU 上提取大约 8–15 分钟；权重下完之后再跑同类长度，大约 3–5 分钟。
后面的重定向和渲染通常一两分钟。用下一节的 `--skeleton` 复用骨架时，提取整段跳过，几十秒就能出结果。
### 3. 同一段动作，换个角色
从 Mixamo 下载别的角色丢进 `assets/mixamo/`。**别直接只改 `--rig` 重跑**——那样最慢的
动作提取会原样再来一遍。用 `--skeleton` 复用上一次运行提取好的骨架，几分钟的事变成几十秒：
```bash
m2mr run --skeleton outputs/<上次的运行目录>/skeleton_motion.npz --rig assets/mixamo/Vampire.fbx
```
### 4. 换视频
`--video` 指定用哪一段，和 `--rig` 可任意组合。
```bash
m2mr run --video assets/video/dance.mp4 --rig assets/mixamo/Vampire.fbx
```
### 5. 用一张照片（静态姿态）
`--image` 从**单人照片**恢复一个静态 3D 姿态，再按和视频相同的路径转到 Mixamo 角色上。预览是 `images/` 里的四张静帧（种类和视频 run 一样），外加左右对比绕转视频 `before_after_360_compare.mp4`。不要和 `--video` 一起用。
```bash
m2mr run --image assets/image/pose.jpg
m2mr run --image assets/image/pose.jpg --rig assets/mixamo/Vampire.fbx
```
`--image` 不带路径时，用 `assets/image/` 里最后放进去的那一张。
## 输出
每次 `m2mr run` 按**命令启动时间**新建一个目录。根目录那四个文件视频和照片都一样，只有预览文件夹会变。
```
outputs/20260829_193205_dance/ # 照片 run 则是 …_pose/
├── run.json # 启动时间、输入、完整命令
├── skeleton_motion.npz # 人体 3D 骨架（可用 --skeleton 复用）
├── mixamo_rotations.npz # Mixamo 骨骼逐帧旋转
├── mixamo_character.glb # 带皮角色，Blender / Unity 可导入
└── videos/ 或 images/ # 预览 — 取决于这次输入是视频还是照片
```
**视频输入**写 `videos/`（比例跟片段一致）：
```
videos/
├── human_skeleton.mp4 # 提取出的人体 3D 骨架
├── mixamo_skeleton.mp4 # Mixamo rig 骨架
├── mixamo_character.mp4 # 带皮 Mixamo 角色
└── compare.mp4 # 四宫格：左上原片 / 右上 Mixamo 骨架
# 左下人体骨架 / 右下角色
```
**照片输入**则写 `images/`（四种图和上面一一对应，外加一条绕转）：
```
images/
├── human_skeleton.png # 提取出的人体 3D 骨架
├── mixamo_skeleton.png # Mixamo rig 骨架
├── mixamo_character.png # 带皮 Mixamo 角色
├── compare.png # 四宫格：左上原图 / 右上 Mixamo 骨架
│ # 左下人体骨架 / 右下角色
└── before_after_360_compare.mp4 # 左：原图
# 右：10° 俯视绕角色转一圈
```
`mixamo_character.glb` 用 Blender 打开：File → Import → glTF 2.0 (.glb/.gltf)。导入后若镜头对不准，选中角色网格，再 View → Frame Selected。头和手上那堆球是骨头的显示形状，不是模型：在 Outliner 里隐藏 **Icosphere** 和骨架（armature），留下带皮网格。时间轴 FPS 和结束帧按 `run.json` 里的 `fps` / `n_frames` 设置，播放才会和原片一样长。视频 run 对照 `videos/mixamo_character.mp4`，照片 run 对照 `images/mixamo_character.png` 或那条绕转视频。
## 许可证
本仓库代码为 Apache-2.0。你自取的资产各有条款，不能随本仓库再分发：
- **SMPL-X**：MPI 门禁，默认非商业科研 / 教育 / 艺术；商用需另谈
- **Mixamo FBX**：可用在成品里，不能把原始 FBX 当资源包发出去
- **GVHMR 等推理权重**：首次 `m2mr run` 自动下载到 `weights/`，遵循各自上游许可
## 联系
若使用中遇到问题、需要协助完成本地部署，或希望洽谈合作，欢迎通过邮箱联系我：
[maxliu2022sz@gmail.com](mailto:maxliu2022sz@gmail.com)