# MotionBricks — README Reference
> A product manual from a studio that ships: a plain left-set title, four quiet tags, a filmstrip of hooded characters and robots, then prose that explains itself in short sentences.
**Theme:** both
Read from `README.md` on the default branch `main` of github.com/NVlabs/motionbricks (last commit touching the file 54fc563, 2026-10-23; captured 2026-10-28). Evidence is the raw Markdown, the HTML that GitHub's API returns for it, a 1440×900 first-screen capture and a 2700px tall capture of the light theme, with the README column 920px wide (856px content width). Badge colors and widths come from the SVGs that shields.io returns for the four badge URLs; image sizes and the GIF's context and target colors come from the files in `docs/media/` fetched through Git LFS. GitHub sets the type (its system stack, Segoe UI in the Windows captures), the 16px body size and the heading rules; nothing in the README overrides them.
## Overview
The README reads like documentation rather than a paper poster. The first line is an ordinary left-aligned `#` heading holding the full paper title on two lines, with GitHub's grey rule under it. A single centred `` holds both the four flat badges and the teaser, a 1600×668 filmstrip: four rendered stills of a hooded character with ghosted white target poses across the top, and ten small frames of a Unitree G1 robot across the bottom, all inside a thin dark frame. Then the page is prose: two paragraphs, a four-bullet "what you get" list with bold leads, and a short note pointing to a guided tutorial. The body has fifteen plain `##` sections with no emoji. One full-width GIF explains the method, two-column HTML tables pair SOMA and G1 GIFs for each demo, and two pipe tables carry the repository layout and the checkpoints. There are no author names, affiliations or venue line in the header.
## Header Block
Rendered positions are y values in the 1440×900 capture (the README box starts at y≈24 with its "README.md" file bar; content starts at y≈90).
1. **Title** (y≈116–156, two lines): `# MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives`. GitHub h1, 2em (32px), weight 600, left-aligned, with a 1px grey rule under the second line at y≈184.
2. **Badge row** (y≈200–220): the first four lines of one `
`, each `
`, `--` in shields.io's default `flat` style: 20px tall, 3px corner radius, a faint vertical gloss, Verdana 11px, label on the default #555555 grey and white (#ffffff) text with a #010101 text shadow. None has a logo.
| Label | Message | Color (hex) | Style | Links to |
|---|---|---|---|---|
| Project | Page | #007ec6 (`blue`, label #555555) | flat (default) | nvlabs.github.io/motionbricks/ |
| arXiv | 2604.24833 | #b31b1b (label #555555) | flat (default), `.svg` suffix | arxiv.org/abs/2604.24833 |
| Hugging Face | Models | #d8b800 (`yellow` as shields.io now draws it, label #555555, white text) | flat (default) | `#checkpoints` (in-page anchor) |
| License | Apache 2.0 | #76b900 (label #555555) | flat (default), `.svg` suffix | LICENSE |
Badge widths from the SVGs: 86, 116, 134 and 124px. The named `yellow` renders today as #d8b800 with white text in the served SVG, not the older #dfb317. The Hugging Face badge does not leave the page; it jumps to the Checkpoints table, which then links to Hugging Face. The license message color #76b900 is NVIDIA's brand green.
Other colored marks come from the imagery, not from badges: in `core_idea.gif` the context poses are bright green (median sampled value about #22cd5e) and the target pose is light blue (about #38a5e0), with white generated poses between them on a dark charcoal stage (about #202020). The prose refers to these as "green above" and "blue above".
## Section Outline
| Level | Text | What it holds |
|---|---|---|
| h1 | MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives | title; badges, teaser, intro, offer list and tutorial note follow without a heading |
| h2 | News | one undated bullet |
| h2 | Setup | hardware sentence, install sentence with links, a two-line `sh` block, a note on the TensorRT cache |
| h2 | How MotionBricks works | the `core_idea.gif` at 100%, two bullet lists with bold terms (context, target; root module, pose module, decoder) and prose on chaining; one h3 "One runtime for SOMA and G1" |
| h2 | Repository layout | one sentence, a two-column Folder / Contents table with five linked folders |
| h2 | Inbetweener | one sentence, a 2×1 HTML table of GIFs headed SOMA / Unitree G1, a one-line `sh` block, a link to its doc |
| h2 | Scene Preview | one paragraph, a 2×4 HTML table of GIFs, a two-line `sh` block, a link to its doc |
| h2 | Editors | one paragraph, a 2×1 HTML table of PNG screenshots, a two-line `sh` block, two paragraphs |
| h2 | Checkpoints | one paragraph, a `> Note:` blockquote, a six-column model table with two bold model names, a link to two model cards |
| h2 | Export ONNX models | one paragraph, an `sh` block with `#` comment labels, two paragraphs of options |
| h2 | Documentation | bold link to the guided tutorial, then three bold group labels (Apps, Integration, Models) each over bullets of the form `**[Doc](...):** description` |
| h2 | Related humanoid work at NVIDIA | eight bullets, `[Name](url): lower-case description` |
| h2 | Citation | one sentence and a `bibtex` block with aligned `=` |
| h2 | License | one sentence and four bullets with bold labels (Code, Documentation and media, Models, Sample motions), then three paragraphs |
| h2 | Acknowledgments | six bullets, `[Project](url) for ` |
| h2 | Contact | two sentences |
Absent from the source: author list, affiliations, venue line in the header, table of contents, results table, star-history chart, emoji anywhere, dated news entries, captions under images.
Present but unusual: badges and teaser share one ``, so the teaser's centring comes from the badge paragraph; the title is left-aligned while the badges are centred; the Hugging Face badge links to an in-page anchor; demo media are laid out in HTML `
` grids with column headers rather than stacked images; the bundled-models note is a plain `> Note:` blockquote, not a GitHub alert; the Contact section says the project is not accepting contributions.
## Components
**Centred media paragraph.** One `` with badge links on the first four lines and a `width="100%"` image on the fifth; the image wraps below the badges because it cannot share their line.
**Badge row.** Four flat badges, label #555555, messages #007ec6, #b31b1b, #d8b800 and #76b900, each with a descriptive `alt` ("Project Page", "Paper", "Hugging Face Models", "License").
**Bold-lead bullets.** Bullets that open with a bold noun phrase or term and continue in plain text: in the intro ("**Pretrained models** for the..."), in How it works ("The **context** is..."), in License ("**Code:** Apache 2.0"). Sentences are short and declarative throughout.
**Media comparison grid.** HTML `
` with a header row of `` labels (SOMA, Unitree G1, or the two editor names) and rows of ` ` endings for acknowledgements. No badges or logos below the header.
## Imagery
| Image | Type | Source size | Markdown | Rendered at 920px | Placement |
|---|---|---|---|---|---|
| teaser.jpg | JPEG filmstrip in a thin dark frame | 1600×668 | `` | 856×357 | header, under the badges, no caption |
| core_idea.gif | animated GIF, 38 frames, dark stage | 1280×480 | `
` | 856×321 | first element of How MotionBricks works |
| inbetweener_soma.gif, inbetweener_g1.gif | animated GIFs (the SOMA one has 84 frames) | 1280×560 (SOMA) | `
` switching; the flat badges also work on both. The media live in Git LFS (the repo stores pointer files), which GitHub serves transparently.
## Adapting to Other Content
- **A library.** This README already works as one: keep the left-aligned `#` name, the four-badge row (Docs, PyPI, License and one destination), an intro paragraph and a bold-lead "what you get" list, then Setup, a How it works figure and a folder table.
- **A dataset.** Replace the checkpoint table with a split table in the same alignment pattern (name left, counts centred), and use the two-column `` grid to pair samples from two sources at about 400px each.
- **A paper repo that needs authors.** Keep the plain h1, add one left-aligned author line under it, and leave the badges and teaser in the centred ``; the venue stays in running text.
- **A repo without a teaser.** Close the centred `
` after the badges and let the How it works GIF (856px) carry the explanation, moved up to follow the intro.
- **A tool with several apps.** Give each app its own `##` with one sentence of purpose, a media grid, "Run it with this command:" and a one-line `sh` block, then a link to its doc.
## Do's and Don'ts
| Do | Don't |
|---|---|
| Keep the title a plain left-aligned `#` and let the prose carry the venue | Stack author, affiliation and venue blocks over a documentation README |
| Put a full-sentence `alt` on every image | Leave GIFs without alternative text |
| Pair related demos in a `
` with `` labels | Stack eight GIFs one above another |
| End each app section with one short command and a doc link | Inline the full option list in the README |
| Map each top-level folder to its purpose in a two-column table | Paste a full repository tree |
| Write bold-lead bullets with short declarative sentences | Pad sections with emoji or decorative dividers |
| Point a badge at an in-page anchor when the table there holds the links | Duplicate external links in both the badge row and the table |
## Agent Prompt Guide
1. "Write a README opening in GitHub Markdown: a left-aligned `# Name: Full Paper Title`, then one `` holding four flat shields.io badges (label #555555; messages Project Page #007ec6, arXiv #b31b1b, Hugging Face Models #d8b800 linking to `#checkpoints`, License Apache 2.0 #76b900) and, on the next line of the same paragraph, a `width="100%"` teaser with a one-sentence `alt`. Follow with two plain paragraphs and four bullets that start with a bold noun phrase."
2. "Write plain `##` sections in this order: News, Setup, How it works (a full-width GIF, then bullets with bold terms), Repository layout (two-column Folder / Contents table with `| --- |`), one section per app, Checkpoints, Export, Documentation, Related work, Citation, License, Acknowledgments, Contact. Use the `sh` tag for every command block and no emoji."
3. "For each app section, write one sentence of purpose, an HTML `
` whose header row names the two variants and whose cells hold `
ProjectName is a ... It ... See [How it works](#how-projectname-works).
This repository provides ... based on the [Venue paper](https://arxiv.org/abs/XXXX.XXXXX):
- **Pretrained models** for ...
- **A runtime**, built on ...
- **Demos**: an [App](#app) that ...
## News
- One sentence.
## Setup
```sh
uv sync
```
## How ProjectName works
- The **context** is ...
- The **target** is ...
## Repository layout
| Folder | Contents |
| --- | --- |
| [pkg](pkg) | The library: ... |
| [app](app) | The demos ... |
## App
One sentence of purpose.
Variant A
Variant B
Run it with this command:
```sh
uv run python -m app.demo
```
## Checkpoints
> Note: one caveat.
| Model | Skeleton | Training Data | FPS | Hugging Face | License |
|:-------|:-------------|:------:|:------:|:-------------:|:-------------:|
| **Model-A-v1** | [Rig](https://example.org/) | [Data](https://example.org/) | 30 | [Link](https://huggingface.co/org/name) | [License](https://example.org/) |
## Documentation
**Apps**
- **[App](docs/app.md):** What it covers.
## Citation
If you use this code in your research, please cite:
```bibtex
@article{key,
title = {...},
}
```
## License
- **Code:** [Apache 2.0](LICENSE).
## Acknowledgments
## Contact
````
## Provenance
- Repo: https://github.com/NVlabs/motionbricks (`README.md`, branch `main`, last README commit 54fc563 on 2026-10-23).
- Paper: "MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives", SIGGRAPH 2026 (ACM Transactions on Graphics 45(4)), DOI 10.1145/3811334, arXiv 2604.24833; first author Tingwu Wang. Project page https://nvlabs.github.io/motionbricks/.
- Selection: documentation-first restraint, with plain prose, a filmstrip teaser, a How it works figure explained in short bullets, and a repository-layout table that maps folders to purpose, with almost no decoration.
- Evidence: raw Markdown and GitHub-rendered HTML (saved 2026-10-28), 1440×900 and 2700px captures at a 920px README column, shields.io SVGs for the four badge URLs, `teaser.jpg`, `core_idea.gif`, `inbetweener_soma.gif` and the two editor PNGs fetched through Git LFS for pixel sizes and sampled colors.
- Written 2026-10-28.
`. Each badge is 20px tall and the row spans about 472px. Details in Badges.
3. **Teaser** (y≈233 to about 590): the fifth line of the same `
`. At `width="100%"` it is too wide to share the line, so it wraps under the badges and renders at 856×357. No link and no caption; the `alt` text is a full sentence.
4. **Intro** (y≈618 onward): two left-aligned paragraphs. The first defines the model and links to the "How MotionBricks works" anchor; the second links the "SIGGRAPH 2026 paper" in running text, which is the only place the venue appears above the fold.
5. **Offer list** (below the fold): four bullets, each opening with a bold noun phrase ("**Pretrained models**", "**A Python runtime**", "**Two demos**", "**Two editors**") followed by plain text with in-page anchor links.
6. **Closing note**: one paragraph that ends "New to MotionBricks? The [guided tutorial](docs/guided_tutorial.md) walks through all four apps". The `## News` heading follows.
## Badges
All four use the static path form `https://img.shields.io/badge/