motionbricks README

README проекта с github.com/NVlabs/motionbricks. Одним файлом markdown: README.md.

MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives

Project Page Paper Hugging Face Models License MotionBricks animates characters and robots with one model

MotionBricks is a modular latent generative model that animates characters and robots in real time. It fills in the motion between four recent poses and up to four target poses. Three learned modules share the work, as How MotionBricks works explains. Smart Primitives turn target poses into building blocks for navigation and object interaction, so behaviors like vaulting and sitting snap together like bricks, with no retraining.

This repository provides pretrained MotionBricks models, based on the SIGGRAPH 2026 paper, and everything you need to put them to work:

The demos show one way to drive the model. Your application decides where the targets come from. New to MotionBricks? The guided tutorial walks through all four apps as it builds one interaction scene.

News

Setup

The runtime uses TensorRT, which requires an NVIDIA GPU. The demos were tested on Windows and Linux (x86-64) with an NVIDIA GeForce RTX 4090.

Install Git LFS and uv. Then clone this repository and run these commands from its root:

git lfs pull
uv sync

The first launch of each model and precision builds a TensorRT plan. This takes a few minutes. Plans are cached in .trt-cache/, so later launches start quickly. Each app section below gives its command.

How MotionBricks works

Context poses in green, a strobe of generated poses, and a target pose in blue

Each generation fills in the motion between two sets of poses at 30 Hz:

The model decides how long the transition takes. One generation produces 6 to 16 tokens of four poses, or about 0.6 to 1.9 s of motion. Generation length explains the frame counts.

Three learned modules share the work:

Longer motion comes from chaining generations. The runtime plays the generated motion, records what it played, and uses the last four recorded poses as the context of the next generation. Your application decides the targets. That choice is what turns one inbetweening model into keyframe animation, continuous locomotion, or object interactions. The paper covers the method, the training data, and the evaluation.

One runtime for SOMA and G1

Both models generate the same way. Only the pose layout differs. The apps and the runtime work the same for both rigs, so one code path drives a human skeleton and a robot. Engines describes the two layouts.

Repository layout

The motionbricks package is the library. The demos and editors in app are built on it.

Folder Contents
motionbricks The library: engines, motion players, recorder, blend spaces, pivots, and the ONNX models
app The demos, the two editors, and the character runtime they share
assets Sample motion clips, Smart Primitives, and the gym scenes
docs Guides and model cards, with runnable examples in docs/examples
tools/onnx The standalone ONNX exporter

Inbetweener

Start here to see the core idea. Choose poses from clips, place them in the view, and generate motion through them in order.

SOMA Unitree G1
SOMA Inbetweener Unitree G1 Inbetweener

Run it with this command:

uv run python -m app.inbetweener_demo

Inbetweener lists its options and things to try. It also walks through the code.

Scene Preview

Drive a character through a scene with continuous locomotion and interactions. It can walk and run forward, strafe while facing the camera, or strafe while crouching. Six style modes, such as Skipping and Zombie, change how it walks. Scene Preview distills the Unreal Engine demo behind the paper's videos into a small Python runtime. It puts the ideas front and center, so you can carry them into any integration.

SOMA Unitree G1
SOMA Scene Preview Unitree G1 Scene Preview
SOMA walks, runs, and stops with context, target, and blend space poses shown Unitree G1 walks, runs, and stops with context, target, and blend space poses shown
SOMA strafes in four directions, crouches, then stands back up, with context, target, and blend space poses shown Unitree G1 strafes in four directions, crouches, then stands back up, with context, target, and blend space poses shown
SOMA walks in each locomotion style, from Skipping to Combat Unitree G1 walks in each locomotion style, from Skipping to Combat

Run it with the SOMA or the Unitree G1 gym:

uv run python -m app.scene_preview --scene assets/scenes/soma_gym.scene.json
uv run python -m app.scene_preview --scene assets/scenes/g1_gym.scene.json

Scene Preview lists its options and controls. It also explains the runtime behind it: the character, the state machine, locomotion, and interactions.

Editors

A Smart Primitive describes an action as target poses placed around an object. Author one in the Smart Primitive Editor. Place it in a scene for Scene Preview with the Scene Editor.

Smart Primitive Editor Scene Editor
Smart Primitive Editor with a jump primitive Scene Editor with the SOMA gym

Run them with these commands:

uv run python -m app.smart_primitive_editor
uv run python -m app.scene_editor

Start with the guided tutorial to learn these tools. It builds an interaction step by step with both editors. Smart Primitive Editor and Scene Editor describe each editor and its documents.

These editors show one way to build dynamic sequences and interactions. Your application can follow the same approach or a different one. For example, these editors sample a handful of target poses from clips. A motion generation model, such as Kimodo or ARDY, could generate those poses instead.

Checkpoints

MotionBricks checkpoints are available for the SOMA body model and the Unitree G1 robot. Their weights use the SafeTensors format.

Note: the apps use the ONNX models bundled in motionbricks/assets/onnx, so you do not need to download a checkpoint to run them. Download one to export your own ONNX models or to build another runtime. This repository includes the ONNX exporter.

Model Skeleton Training Data FPS Hugging Face License
MotionBricks-SOMA-RP-v1 SOMA Bones RigPlay 1 (RP1) 30 Link NVIDIA Open Model Agreement
MotionBricks-G1-RP-v1 Unitree G1 Bones RigPlay 1 (RP1), retargeted 30 Link NVIDIA Open Model Agreement

The SOMA model card and the Unitree G1 model card describe each model, its inputs and outputs, and its limitations.

Export ONNX models

The ONNX models in this repository were exported from these checkpoints with the standalone exporter in tools/onnx. To export them yourself, install the Hugging Face CLI, then download the checkpoint folders and run the command for your model from the repository root:

hf download nvidia/MotionBricks --local-dir checkpoints/MotionBricks

# SOMA
uv run --locked --project tools/onnx motionbricks-onnx --model soma --checkpoints checkpoints/MotionBricks/soma

# Unitree G1
uv run --locked --project tools/onnx motionbricks-onnx --model unitree_g1 --checkpoints checkpoints/MotionBricks/g1

To download one model, add --include "soma/*" or --include "g1/*". Keep the downloaded folder structure intact.

The exporter has its own environment, and uv installs it the first time you run the command. FP32 is the default. Add --precision fp16 for mixed FP16. The exporter guide lists every option, and ONNX inference explains the tensor interfaces and batching.

Documentation

New to MotionBricks? Start with the guided tutorial. It explains the core concepts, then builds an interaction scene with all four apps.

Apps

Integration

Models

MotionBricks is part of a larger effort to enable humanoid motion for animation, robotics, and physical AI. Check out these related works:

Citation

If you use this code in your research, please cite:

@article{wang2026motionbricks,
  title   = {MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives},
  author  = {Wang, Tingwu and Dionne, Olivier and De Ruyter, Michael and Minor, David and Rempe, Davis and Zhao, Kaifeng and Petrovich, Mathis and Yuan, Ye and Li, Chenran and Luo, Zhengyi and Robison, Brian and Blackwell, Xavier and Antoniazzi, Bernardo and Peng, Xue Bin and Zhu, Yuke and Yuen, Simon},
  journal = {ACM Transactions on Graphics (TOG)},
  year    = {2026},
  volume  = {45},
  number  = {4},
  doi     = {10.1145/3811334}
}

License

Code, documentation, models, and sample motions have different licenses:

Licenses for dependencies and bundled robot assets are in licenses. Exporter dependency licenses are in tools/onnx/licenses.

This project downloads and installs additional components under their own license terms. Review those terms before use.

The TensorRT OSS notice applies to TensorRT OSS components, not the separately installed tensorrt-cu12, tensorrt-cu12-bindings, and tensorrt-cu12-libs runtime packages. Those packages are governed by the NVIDIA TensorRT Software License Agreement distributed with the packages.

Acknowledgments

This project builds upon excellent open source projects:

Contact

This project is currently not accepting contributions.

For questions or issues, please open an issue on this repository or reach out directly to the authors.

motionbricks (NVlabs/motionbricks)

Ищем в базе…

Что это такое?MotionBricks — это модульная латентная генеративная модель, которая анимирует персонажей и роботов в реальном времени, достраивая движение между недавними позами и целевыми позами. В комплекте есть предобученные модели для тела человека (SOMA) и робота Unitree G1.
Это исследовательская библиотека или готовое приложение?Это релиз исследовательского кода. Пакет Python motionbricks является библиотекой и средой выполнения. В репозитории также есть два демо-приложения (Inbetweener, Scene Preview) и два редактора на его основе, но это не самостоятельное приложение для конечных пользователей.
Как это запустить?Установите Git LFS и uv, клонируйте репозиторий и выполните команды установки из его корня. У каждого демо и редактора есть своя команда запуска, а при первом запуске для каждой модели и точности собирается кэшированный план TensorRT.
Какое железо нужно, чтобы это запустить?Нужна видеокарта NVIDIA, так как среда выполнения собирает и запускает движки TensorRT. Демо тестировались на Windows и Linux (x86-64) с RTX 4090.
Нужно ли скачивать чекпоинты, чтобы попробовать демо?Нет, демо используют модели ONNX, которые уже включены в репозиторий. Скачивать чекпоинт с Hugging Face нужно только в том случае, если вы хотите экспортировать собственные модели ONNX.
Что такое Smart Primitive?Smart Primitive описывает действие, например перемахивание через препятствие или сидение, в виде целевых поз, расположенных вокруг объекта. После создания он встраивается в любую сцену без переобучения модели.
Может ли одна и та же модель управлять и персонажем-человеком, и роботом?Да. И модель тела человека SOMA, и робот Unitree G1 используют одну и ту же среду выполнения и один и тот же путь генерации. Различается только раскладка поз у каждого скелета.
Что именно показывают демо Inbetweener и Scene Preview?Inbetweener позволяет расставлять позы на клипах и генерировать движение между ними по порядку. Scene Preview проводит персонажа через сцену с непрерывным передвижением, перемахиванием через препятствия, пригибанием и шестью стилями движения, например Skipping и Zombie.
Зачем MotionBricks внутри использует три отдельных модуля?Корневой модуль предсказывает длительность и траекторию. Трансформер поз на маскированных токенах заполняет токены движения вдоль этой траектории. Декодер VQ-VAE превращает токены в непрерывное движение, которое доходит до целевых поз.
Какие есть похожие проекты?HairDeck, UniMate, SuperMimic-Reproduced, kimodo, pointdit, vggt, TRELLIS.2, SolarWM
Автор
NVlabs
Размер
26.3 MB
Звёзды
1K
Обновлён
КоммитOct 23
Возраст
6 мес
Коммиты · 90 дней