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 机器人的模型。
这是研究用的代码库,还是现成的应用?这是一个研究代码发布。motionbricks Python 包是代码库和运行时,仓库还附带两个基于它构建的演示应用(Inbetweener 和 Scene Preview)以及两个编辑器,并不是独立的面向普通用户的应用程序。
我该怎么把它跑起来?安装 Git LFS 和 uv,克隆仓库,并在仓库根目录运行安装命令。每个演示和编辑器都有各自的启动命令;每个模型和精度组合的首次运行,会生成并缓存一个 TensorRT 计划。
运行它需要什么硬件?需要 NVIDIA GPU,因为运行时要构建并运行 TensorRT 引擎。演示在 Windows 和 Linux(x86-64)上测试过,所用显卡为 RTX 4090。
要试用演示,我需要下载检查点吗?不需要。演示使用仓库中已经附带的 ONNX 模型;只有当你想导出自己的 ONNX 模型时,才需要从 Hugging Face 下载检查点。
什么是 Smart Primitive?Smart Primitive 用于描述一个动作,比如翻越或坐下,它以放置在物体周围的目标姿态表示。编写完成后,就能直接套用到任何场景中,无需重新训练模型。
同一个模型能同时驱动人类角色和机器人吗?可以。SOMA 人体模型和宇树 Unitree G1 机器人使用同一套运行时和生成代码路径,两者之间只有骨骼绑定的布局不同。
Inbetweener 和 Scene Preview 两个演示实际展示了什么?Inbetweener 让你在片段上放置姿态,并按顺序通过这些姿态生成动作。Scene Preview 则让角色在场景中持续移动,包括行走、翻越和下蹲,并提供六种风格模式,例如 Skipping 和 Zombie。
MotionBricks 为什么在内部使用三个独立模块?根模块预测时长和路径;带掩码令牌的姿态 Transformer 沿该路径补全动作令牌;VQ-VAE 解码器再把这些令牌转换为连续动作,并抵达目标。
作者
NVlabs
大小
26.3 MB
星标
1K
更新
提交Oct 23
时长
6个月
提交 · 90 天