Retarget human motion from video to an Adobe Mixamo-rigged 3D character.
Python
Blender Extension (maintainer notes)
User install and usage: docs/user-guide.md.
Building from source and the Advanced (own venv) setup:
blender_extension/README.md.
This page is the smoke-test checklist and the out-of-scope list.
Manual smoke-test checklist
macOS (Apple Silicon): one-click runtime
Run this on a clean user state: move ~/Motion2MixamoRig aside first
(mv ~/Motion2MixamoRig ~/Motion2MixamoRig.bak) and restore it afterwards.
python scripts/package_blender_extension.py --platform macos-arm64- Install the zip in Blender 4.2+ and enable the add-on; the version in Get Extensions matches the zip name.
- Confirm the Motion2MixamoRig tab in the 3D Viewport N-panel.
- Click ⚙ after the title: Setup hides and shows again.
- Install Runtime (one click): the bar advances and ends with "Runtime installed"; External Python and Project Directory (under Advanced) are filled in.
- Choose SMPL-X Model… → "SMPL-X model: found".
- Check Environment → Ready.
- The first-run notice shows above Generate Motion.
- Generate a short single-person video on CPU: the download box shows size, speed, and time left, then disappears; the job finishes and the GLB is auto-imported.
- Generate again: no download box, no first-run notice.
- Reinstall the zip, click Update Runtime: it finishes without re-downloading the weights.
- Switch UI Language to a few languages, including ไทย, नेपाली, and العربية, and check that the text renders.
- Detect Hands is off. Turning it on shows the twice-as-long note, finger smoothing, and Choose MANO Hand Model….
- After import, a Floor Markers mesh sits on the floor. The checkbox under Progress / Result hides it and shows it again.
macOS (Apple Silicon): own venv
- Create
.venv, install Motion2MixamoRig, place SMPL-X. - Install the zip and enable the add-on.
- Under Advanced, set External Python to
.venv/bin/pythonand Project Directory to the repo. - Quit Blender, reopen a different
.blend, and confirm the two paths remain. - Check Environment → Ready (or a clear Error).
- Pick a single-person still, a Mixamo FBX, Device MPS (or CPU).
- Generate with preview off. The UI must stay usable (orbit the viewport).
- Confirm stage/progress/log update, then auto-import of the GLB.
- Timeline start is 0; end is
n_frames− 1 fromrun.json; FPS matches. - Open Output Folder and View Full Log work.
- Diagnostics box: red cells match
diagnostics.json; clicking a cell, Previous and Next move the playhead; during playback the triangle stays under the current cell. Open HTML Report builds the report on the first click (Blender opened from the Dock, so the source video is embedded via Homebrewffmpeg) and opens it at once on the second. The report's 3D view shows fixed 0.5 m floor crosses. The amber lane above the intersection tracks takes a dragged range or In / Out. The Notes list on the right shows those notes, and Download notes saves them with the intersection list. - Start a second job and click Cancel. Only that job should stop.
- Disable and re-enable the add-on without a crash.
Windows 10/11 (not tested yet)
Build with --platform windows-x64. Known blocker for the one-click runtime:
cython-bbox (pulled in by gvhmr[preproc], unused at runtime) has no
Windows wheel and needs a C compiler.
- One-click runtime: Install Runtime works, including paths with spaces
(
C:\Users\Jane Doe\...). - Own venv: External Python is
.venv\Scripts\python.exe. - Check Environment.
- Run a short single-person video on CPU first; the one-click runtime has a CPU-only PyTorch, so try CUDA only with your own venv.
- Blender must not freeze during Generate.
- Confirm auto-import, FPS, and frame range.
- Open Output Folder uses Explorer; View Full Log opens the log.
- Cancel a running job; no other
python.exeprocesses should be killed. - Uninstall the add-on and confirm
~/Motion2MixamoRig(or the project'sweights/andoutputs/) is still there.
Future work
Not done yet:
- Automatic SMPL-X download (its license requires each user to register)
- Bundling weights inside the extension
- CUDA PyTorch in the one-click runtime on Windows
- A mirror option for slow downloads
- Cloud inference
- Multi-person video
- Writing
mixamo_rotations.npzonto the current Armature - Foot lock, root-motion editor, curve cleanup, NLA tools
- Publishing to the Blender Extensions Platform