# Motion2MixamoRig
中文 · English · 한국어 · 日本語 · Deutsch · Русский · العربية · Tiếng Việt · Filipino · ไทย · Français · Español · Türkçe · नेपाली
Переносит движение человека из видео — или позу с фото — на 3D-персонажа с ригом Adobe Mixamo.
Для разработчиков игр: видео с **одним человеком** (или фото) и персонаж Mixamo; на выходе превью и файл персонажа со скином (`.glb`) для Blender или Unity.
> Motion2MixamoRig пока экспериментален. Версия 0.1.0 — конвейер командной строки. В этом репозитории также есть расширение Blender 4.2+, которое запускает тот же конвейер во внешнем Python. Установка и использование аддона: [`blender_extension/README.md`](../../blender_extension/README.md).
Агентам следует начать с [`AGENTS.md`](../../AGENTS.md).
https://github.com/user-attachments/assets/37c67642-f36c-4815-bcf3-028ed9546a2f
Откройте demo.mp4 в этом репозитории.
Ещё одно демо:
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 (старый пакет в цепочке
# зависимостей) импортирует pip в setup-скрипте; в изолированной сборке 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 ГБ, один раз).
Рекомендуется 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/) и скачать |
| FBX-персонаж Mixamo | `assets/mixamo/Y_Bot.fbx` | С Adobe-аккаунтом скачать Y Bot (или другого персонажа с ригом Mixamo) с [Mixamo](https://www.mixamo.com) |
| Видео с действием | `assets/video/.mp4` | Ролик с **ровно одним** хорошо видимым человеком, **с головы до ног весь ролик в кадре** (можно несколько файлов; каждый запуск берёт последний добавленный) |
| Фото позы (необязательно) | `assets/image/.jpg` | Фото с **ровно одним** хорошо видимым человеком, **с головы до ног в кадре**. Вместе с `--image` |
Замечание: скачанный файл Mixamo называется `Y Bot.fbx` (**пробел**), на один символ отличается от `Y_Bot.fbx` (**подчёркивание**) в таблице.
Переименуйте с подчёркиванием — это станет ригом по умолчанию (`m2mr run` без `--rig`). Можно не переименовывать: если `Y_Bot.fbx` нет, берётся первый `.fbx` в `assets/mixamo/`.
В `assets/video/` можно класть несколько видео. Без `--video` или `--image` запуск берёт файл, **последним положенный в `assets/video/`**; если папка пуста — последнее фото в `assets/image/`.
В каждом ролике или фото должен быть один человек, **с головы до ног в кадре** — ничего не обрезано по краям. `m2mr doctor` / `m2mr run` останавливаются до извлечения, если в кадре двое.
## Быстрый старт
Результаты в `outputs/<время-запуска>_<источник>/`. Видео-запуск пишет в `videos/`; фото-запуск — в `images/`.
### 1. Проверить ассеты и окружение
Чего не хватает — печатается вместе с тем, откуда скачать и куда положить.
```bash
m2mr doctor
```
### 2. Первый запуск: чтобы что-то появилось на экране
Без флагов: **последний файл в `assets/video/`** и `assets/mixamo/Y_Bot.fbx`.
```bash
m2mr run
```
Это медленный шаг. Первый запуск скачивает ~5 ГБ весов инференса (один раз), затем извлекает движение человека из видео.
На CPU клип ~30 секунд извлекается примерно 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/` (те же виды, что у видео) плюс клип орбиты слева/справа `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/ # для фото: …_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
├── mixamo_character.mp4 # персонаж Mixamo со скином
└── compare.mp4 # 2×2: оригинал (верхний левый) / скелет Mixamo (верхний правый)
# скелет человека (нижний левый) / персонаж (нижний правый)
```
**Фото-вход** пишет в `images/` (те же четыре вида плюс орбита):
```
images/
├── human_skeleton.png # восстановленный 3D-скелет человека
├── mixamo_skeleton.png # скелет рига Mixamo
├── mixamo_character.png # персонаж Mixamo со скином
├── compare.png # 2×2: оригинал (верхний левый) / скелет 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`), чтобы длительность совпала с исходником. Видео-запуск сверяйте с `videos/mixamo_character.mp4`, фото-запуск — с `images/mixamo_character.png` или клипом орбиты.
## Лицензия
Код репозитория — Apache-2.0. Скачанные вами ассеты имеют свои условия и не должны распространяться вместе с этим репо:
- **SMPL-X**: доступ через MPI; по умолчанию некоммерческие исследования / образование / искусство; коммерческое использование — отдельный договор
- **Mixamo FBX**: можно в готовом продукте; сырой FBX нельзя раздавать как пак ассетов
- **GVHMR и другие веса инференса**: при первом `m2mr run` автоматически в `weights/`, по лицензии каждого апстрима
## Контакты
Если возникла проблема, нужна помощь с локальной установкой или вы хотите обсудить сотрудничество, напишите на:
[maxliu2022sz@gmail.com](mailto:maxliu2022sz@gmail.com)