mixamo-llm-mocap README

The project's README from github.com/squall01337/mixamo-llm-mocap. As one markdown file: README.md.

Mixamo LLM Mocap

Turn any locked-camera video — filmed or AI-generated — into a clean FK animation on any Mixamo character. One performer, or two fighting each other. No mocap suit, no manual keyframing, and every stage scriptable enough that an AI agent can run the whole loop.

license blender gpu agent

showcase

Left: AI-generated source video. Right: the automatic retarget on a Mixamo character in Blender — 10 seconds, nine punches, a slip under and a high side kick, straight through the pipeline.

showcase — two fighters

Two performers, one plate, one pass. The left fighter throws four punches and a roundhouse; the right one blocks, folds over the body shot and ducks under the kick. Both tracks are split out of the same video by screen side, retargeted onto two Mixamo characters with different proportions — Y Bot and Ninja — and placed at the distance the performers actually stood, measured from the footage.

How it works

video plate (locked camera, T-pose bookends)
   │
   ├─ 1. estimate_pose_gvhmr.py    GVHMR (SMPL-X mesh recovery) → 33 landmarks + pelvis height
   ├─ 2. analyze_landmarks.py     numeric beat detection → you write a beat sheet from NUMBERS
   ├─ 3. action_specs/<name>.json  the motion as data: support schedule, rest blends, fists
   ├─ 4. lift_to_mixamo.py         direction-preserving retarget onto YOUR rig's proportions
   ├─ 5. apply_mixamo_fk.py        FK aim + foot planting, inside live Blender (via Blender MCP)
   ├─ 6. qa_clip.py                automated gate: no explosions, no pops, no foot skate
   ├─ 7. compare_reference.py      frame-by-frame vs the video → which windows still differ
   ├─ 8. compare_pair.py           two-character plates: separation, reach, intrusion
   ├─ 9. run_in_blender.py contact real mesh-vs-mesh collision between two characters
   └─ 10. render_preview.py        preview + side-by-side showcase video

With two performers in the plate, stages 1–7 run once per fighter (--person left|right splits the tracks), setup_duo.py builds one scene holding both characters, and compare_pair.py checks what only exists when there are two of them: whether they stand, reach and miss each other the way the performers did.

The estimator provides mesh-quality joints; the lift keeps its segment directions but rebuilds every position from your character's measured bone lengths; the apply plants feet by solving hip height (never IK — Mixamo rigs are FK-only); the spec contributes only what a video cannot know: which foot is the support in each phase (including "none" for airborne beats), when fists close, where the clip locks back to rest.

Why it's different

Quickstart

  1. Install — docs/INSTALL.md walks through every dependency (list below).

  2. Build your rig scene:

    blender --background --python pipeline\setup_rig.py -- --fbx ybot.fbx --out ybot_rest.blend

  3. Run a plate (Blender open on the scene; plate rules in docs/PROMPTING.md):

    tools\GVHMR\.venv\Scripts\python.exe pipeline\estimate_pose_gvhmr.py --video plates\<name>\<name>.mp4 --out plates\<name>\landmarks.json
tools\GVHMR\.venv\Scripts\python.exe pipeline\analyze_landmarks.py --landmarks plates\<name>\landmarks.json
# beat sheet → action_specs\<name>.json  (schema: docs/PIPELINE.md)
tools\GVHMR\.venv\Scripts\python.exe pipeline\lift_to_mixamo.py --spec action_specs\<name>.json
python pipeline\run_in_blender.py all action_specs\<name>.json
tools\GVHMR\.venv\Scripts\python.exe pipeline\qa_clip.py --spec action_specs\<name>.json
tools\GVHMR\.venv\Scripts\python.exe pipeline\compare_reference.py --spec action_specs\<name>.json
tools\GVHMR\.venv\Scripts\python.exe pipeline\render_preview.py action_specs\<name>.json --showcase

    compare_reference.py tells you which frame windows still differ from the video; the last command produces preview.mp4 and the side-by-side showcase.mp4 — the same format as the demo GIF above.

    Two-performer plates add --person left|right to the estimate, one spec per fighter, and a compare_pair.py run — see docs/PIPELINE.md section 9.

  4. Iterate with docs/PIPELINE.md and docs/PITFALLS.md.

What you need to bring (and where to get it)

What Where Notes
A Mixamo character — any model mixamo.com → Characters → download FBX Binary, T-pose Adobe's terms don't allow redistributing them; setup_rig.py builds and validates the scene from your download
Blender 5.1+ blender.org
Blender MCP add-on (official, Blender Lab) blender.org/lab/mcp-server enable Allow Online Access; the apply talks to its socket
GVHMR (the pose estimator — not in this repo) github.com/zju3dv/GVHMR clone into tools/GVHMR; install per docs/INSTALL.md — including a working Windows recipe (docs/requirements_gvhmr_windows.txt + prebuilt pytorch3d wheel)
GVHMR checkpoints (~5 GB) HuggingFace mirror exact curl commands in docs/INSTALL.md
SMPL-X body model smpl-x.is.tue.mpg.de free research registration → download SMPL-X v1.1, place SMPLX_NEUTRAL.npz as shown in docs/INSTALL.md
GPU ~8 GB VRAM developed on an RTX 4080

Docs

Doc What it covers
docs/INSTALL.md Every dependency, step by step, Windows-proven
docs/PIPELINE.md The operational loop + the action_spec schema, field by field
docs/RIG.md Mixamo rig conventions: spaces, units, the rules that must never break
docs/PITFALLS.md Every mistake this pipeline's development paid for, so you don't pay twice
docs/PROMPTING.md Writing gen-video plate prompts that survive retargeting

License

MIT — see LICENSE, including third-party notes (Mixamo, GVHMR, SMPL-X, Blender MCP).

mixamo-llm-mocap (squall01337/mixamo-llm-mocap)

Searching Database…

374 ·GitHub
Mixamo-llm-mocap
Что это?Mixamo LLM Mocap превращает любое видео со статичной камерой — снятое на камеру или сгенерированное ИИ — в чистую FK-анимацию для любого персонажа Mixamo, используя оценщик поз GVHMR, шаг ретаргетинга по спецификации и этап применения через Blender MCP. Он построен так, чтобы ИИ-агент мог запустить весь конвейер от начала до конца.
Это аддон для Blender или набор скриптов командной строки?Это цепочка Python-скриптов командной строки для оценки поз, ретаргетинга и контроля качества, с сокет-подключением к Blender через официальный аддон MCP для финального шага применения — устанавливать как готовый плагин Blender здесь нечего.
Как прогнать полный материал через конвейер?Установите зависимости по docs/INSTALL.md, запустите setuprig.py, чтобы собрать сцену с ригом из самостоятельно скачанного персонажа Mixamo, затем выполняйте этапы конвейера, когда эта сцена открыта в Blender; comparereference.py сверяет ретаргетинг с исходным видео, а финальная команда создаёт preview.mp4 и showcase.mp4, где видео показаны рядом.
Что нужно установить помимо этого репозитория?Blender 5.1+ с официальным аддоном MCP, оценщик поз GVHMR (клонируется отдельно и устанавливается по docs/INSTALL.md), его чекпойнты объёмом около 5 ГБ и модель тела SMPL-X, получаемая через бесплатную регистрацию для исследовательских целей.
Есть ли подводные камни перед началом?Персонажи Mixamo не входят в комплект — условия Adobe запрещают их распространение, поэтому придётся самостоятельно скачать FBX с mixamo.com, а GVHMR вместе с его чекпойнтами нужно получить и настроить отдельно.
Установка работает на Windows или только на Linux/macOS?Windows явно поддерживается — docs/INSTALL.md содержит рабочую инструкцию для GVHMR под Windows с отдельным requirements-файлом и готовым wheel-пакетом pytorch3d.
Нужен ли мощный GPU для оценки поз?Да — оценщику GVHMR нужно примерно 8 ГБ видеопамяти; проект разрабатывался и тестировался на RTX 4080.
Он работает только с одним исполнителем в видео?Нет — при двух исполнителях в кадре setupduo.py и comparepair.py разделяют треки по сторонам экрана, ретаргетят каждого на отдельного персонажа Mixamo и покадрово сверяют с видеозаписью дальность ударов, дистанцию между ними и столкновения конечностей.
Что задаёт новое движение для конвейера?Небольшой JSON-файл «actionspec», который объявляет, какая нога опорная в каждой фазе (включая безопорные моменты), когда сжимаются кулаки и где клип возвращается в позу покоя — код анимации не нужен.
Как он ловит плохие ретаргетинги до того, как те уйдут в дело?Численный контроль качества помечает разлетевшиеся кости, скачки бёдер, скольжение стоп и сломанные позы покоя, а comparereference.py измеряет по исходному видео такие вещи, как высоту рук и расстояние между конечностями, сообщая, в каких именно окнах кадров есть расхождения.
Он работает с любым персонажем Mixamo или только с определёнными?С любым персонажем Mixamo — setuprig.py собирает и обмеряет сцену по самостоятельно скачанному FBX из Mixamo (поза покоя, длины костей, высоты бёдер и земли), и каждый последующий этап читает этот обмеренный профиль.
What are similar projects?Motion2MixamoRig, freemocap, image-to-3dlab, openpose, framefields, InsertAny3D, kimodo, storyboard-ai
Which topics is it in?motion-capture, pose-estimation, blender, video-processing, game-development, 3d, animation, nvidia, computer-vision, cuda, ai-agent, gpu
Creator
squall01337
Size
11.4 MB
Stars
374
Updated
CommitSep 26
Age
2mo
Commits · 90 Days