Skip to content

Official implementation of MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives (SIGGRAPH 2026)

Python

v0.2.0 commit

Olivier Dionne54fc563aeaaf
diff --git a/.python-version b/.python-version
new file mode 100644
index 0000000..e4fba21
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.12
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..3551c88
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,39 @@
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "[Tool] Smart Primitive Editor",
+ "type": "debugpy",
+ "request": "launch",
+ "module": "app.smart_primitive_editor",
+ "console": "integratedTerminal"
+ },
+ {
+ "name": "[Tool] Scene Editor",
+ "type": "debugpy",
+ "request": "launch",
+ "module": "app.scene_editor",
+ "console": "integratedTerminal"
+ },
+ {
+ "name": "[Demo] Inbetweener",
+ "type": "debugpy",
+ "request": "launch",
+ "module": "app.inbetweener_demo",
+ "console": "integratedTerminal",
+ "args": [
+ "--model-precision", "fp32"
+ ]
+ },
+ {
+ "name": "[Demo] Scene Preview",
+ "type": "debugpy",
+ "request": "launch",
+ "module": "app.scene_preview",
+ "console": "integratedTerminal",
+ "args": [
+ "--model-precision", "fp32"
+ ]
+ }
+ ]
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..981d2d8
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.2.0] - 2026-10-23
+
+- MotionBricks moves to its own repository. It started as a Unitree G1 preview in
+ [GR00T Whole-Body Control](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/main/motionbricks).
+- A new pretrained model, retrained on the SOMA human skeleton.
+- The paper's Smart Primitive setup, rebuilt in plain Python with Newton, Warp, and TensorRT.
+- New [Inbetweener](README.md#inbetweener) and [Scene Preview](README.md#scene-preview) demos for generating continuous motion and interacting with scenes.
diff --git a/LICENSE b/LICENSE
index 3c43404..f6083b8 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,5 @@
Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+This code is dual-licensed with documentation/skills/assets under the CC-BY-4.0 AND source code under Apache-2.0 license terms.
Apache License
Version 2.0, January 2004
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f67df14
--- /dev/null
+++ b/README.md
@@ -0,0 +1,273 @@
+# MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives
+
+<p align="center">
+ <a href="https://nvlabs.github.io/motionbricks/"><img src="https://img.shields.io/badge/Project-Page-blue" alt="Project Page"></a>
+ <a href="https://arxiv.org/abs/2604.24833"><img src="https://img.shields.io/badge/arXiv-2604.24833-b31b1b.svg" alt="Paper"></a>
+ <a href="#checkpoints"><img src="https://img.shields.io/badge/Hugging%20Face-Models-yellow" alt="Hugging Face Models"></a>
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-76B900.svg" alt="License"></a>
+ <img src="docs/media/teaser.jpg" alt="MotionBricks animates characters and robots with one model" width="100%">
+</p>
+
+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](#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](https://arxiv.org/abs/2604.24833), and everything you need to put them to work:
+
+- **Pretrained models** for the [SOMA body model](https://github.com/NVlabs/SOMA-X) and the Unitree G1 robot. They ship as ONNX files, with the pretrained [checkpoints](#checkpoints) on Hugging Face.
+- **A Python runtime**, built on [Warp](https://github.com/NVIDIA/warp), [Newton](https://github.com/newton-physics/newton), and [TensorRT](https://github.com/NVIDIA/TensorRT), that chains generations into continuous motion.
+- **Two demos**: an [Inbetweener](#inbetweener) that generates motion between poses you place, and a [Scene Preview](#scene-preview) where a character walks, runs, vaults, ducks, and sits its way through a scene.
+- **Two editors** to author your own [Smart Primitives](#editors) and [scenes](#editors).
+
+The demos show one way to drive the model. Your application decides where the targets come from. New to MotionBricks? The [guided tutorial](docs/guided_tutorial.md) walks through all four apps as it builds one interaction scene.
+
+## News
+
+- MotionBricks has its own repository and a pretrained model for SOMA humans. The first release was a Unitree G1 preview in [GR00T Whole-Body Control](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/main/motionbricks).
+
+## 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](https://git-lfs.com/) and [uv](https://docs.astral.sh/uv/getting-started/installation/). Then clone this repository and run these commands from its root:
+
+```sh
+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
+
+<p align="center">
+ <img src="docs/media/core_idea.gif" alt="Context poses in green, a strobe of generated poses, and a target pose in blue" width="100%">
+</p>
+
+Each generation fills in the motion between two sets of poses at 30 Hz:
+
+- The **context** is the four most recent poses of the character (green above).
+- The **target** is one to four poses that the motion should reach (blue above). One pose sets where the character ends up and stops. More poses also set how it moves at that point.
+
+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](docs/runtime_api.md#generation-length) explains the frame counts.
+
+Three learned modules share the work:
+
+- The **root module** predicts the duration and the path of the root.
+- The **pose module** is a masked token transformer. It predicts the motion tokens along that path.
+- The **decoder** turns the tokens into continuous motion that reaches the targets. It uses a VQ-VAE with several codebook heads.
+
+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](https://arxiv.org/abs/2604.24833) 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](docs/runtime_api.md#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](motionbricks) | The library: engines, motion players, recorder, blend spaces, pivots, and the ONNX models |
+| [app](app) | The demos, the two editors, and the character runtime they share |
+| [assets](assets) | Sample motion clips, Smart Primitives, and the gym scenes |
+| [docs](docs) | Guides and model cards, with runnable examples in [docs/examples](docs/examples) |
+| [tools/onnx](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.
+
+<table>
+ <tr>
+ <th>SOMA</th>
+ <th>Unitree G1</th>
+ </tr>
+ <tr>
+ <td><img src="docs/media/inbetweener_soma.gif" alt="SOMA Inbetweener" width="100%"></td>
+ <td><img src="docs/media/inbetweener_g1.gif" alt="Unitree G1 Inbetweener" width="100%"></td>
+ </tr>
+</table>
+
+Run it with this command:
+
+```sh
+uv run python -m app.inbetweener_demo
+```
+
+[Inbetweener](docs/inbetweener.md) 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](https://nvlabs.github.io/motionbricks/) into a small Python runtime. It puts the ideas front and center, so you can carry them into any integration.
+
+<table>
+ <tr>
+ <th>SOMA</th>
+ <th>Unitree G1</th>
+ </tr>
+ <tr>
+ <td><img src="docs/media/scene_preview_soma.gif" alt="SOMA Scene Preview" width="100%"></td>
+ <td><img src="docs/media/scene_preview_g1.gif" alt="Unitree G1 Scene Preview" width="100%"></td>
+ </tr>
+ <tr>
+ <td><img src="docs/media/locomotion_targets_soma.gif" alt="SOMA walks, runs, and stops with context, target, and blend space poses shown" width="100%"></td>
+ <td><img src="docs/media/locomotion_targets_g1.gif" alt="Unitree G1 walks, runs, and stops with context, target, and blend space poses shown" width="100%"></td>
+ </tr>
+ <tr>
+ <td><img src="docs/media/locomotion_directional_soma.gif" alt="SOMA strafes in four directions, crouches, then stands back up, with context, target, and blend space poses shown" width="100%"></td>
+ <td><img src="docs/media/locomotion_directional_g1.gif" alt="Unitree G1 strafes in four directions, crouches, then stands back up, with context, target, and blend space poses shown" width="100%"></td>
+ </tr>
+ <tr>
+ <td><img src="docs/media/locomotion_styles_soma.gif" alt="SOMA walks in each locomotion style, from Skipping to Combat" width="100%"></td>
+ <td><img src="docs/media/locomotion_styles_g1.gif" alt="Unitree G1 walks in each locomotion style, from Skipping to Combat" width="100%"></td>
+ </tr>
+</table>
+
+Run it with the SOMA or the Unitree G1 gym:
+
+```sh
+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](docs/scene_preview.md) 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.
+
+<table>
+ <tr>
+ <th>Smart Primitive Editor</th>
+ <th>Scene Editor</th>
+ </tr>
+ <tr>
+ <td><img src="docs/media/smart_primitive_editor.png" alt="Smart Primitive Editor with a jump primitive" width="100%"></td>
+ <td><img src="docs/media/scene_editor.png" alt="Scene Editor with the SOMA gym" width="100%"></td>
+ </tr>
+</table>
+
+Run them with these commands:
+
+```sh
+uv run python -m app.smart_primitive_editor
+uv run python -m app.scene_editor
+```
+
+Start with the [guided tutorial](docs/guided_tutorial.md#part-2-build-a-smart-primitive) to learn these tools. It builds an interaction step by step with both editors. [Smart Primitive Editor](docs/smart_primitive_editor.md) and [Scene Editor](docs/scene_editor.md) 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](https://github.com/nv-tlabs/kimodo) or [ARDY](https://github.com/nv-tlabs/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](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](#export-onnx-models).
+
+| Model | Skeleton | Training Data | FPS | Hugging Face | License |
+|:-------|:-------------|:------:|:------:|:-------------:|:-------------:|
+| **MotionBricks-SOMA-RP-v1** | [SOMA](https://github.com/NVlabs/SOMA-X) | [Bones RigPlay 1 (RP1)](https://bones.studio/datasets#rp01) | 30 | [Link](https://huggingface.co/nvidia/MotionBricks/tree/main/soma) | [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/) |
+| **MotionBricks-G1-RP-v1** | [Unitree G1](https://github.com/unitreerobotics/unitree_ros/tree/master/robots/g1_description) | [Bones RigPlay 1 (RP1)](https://bones.studio/datasets#rp01), [retargeted](https://github.com/NVIDIA/soma-retargeter) | 30 | [Link](https://huggingface.co/nvidia/MotionBricks/tree/main/g1) | [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/) |
+
+The [SOMA model card](docs/soma_model.md) and the [Unitree G1 model card](docs/unitree_g1_model.md) 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](tools/onnx/README.md). To export them yourself, install the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/en/guides/cli), then download the checkpoint folders and run the command for your model from the repository root:
+
+```sh
+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](tools/onnx/README.md) lists every option, and [ONNX inference](docs/onnx_inference.md) explains the tensor interfaces and batching.
+
+## Documentation
+
+New to MotionBricks? Start with the **[guided tutorial](docs/guided_tutorial.md)**. It explains the core concepts, then builds an interaction scene with all four apps.
+
+**Apps**
+
+- **[Inbetweener](docs/inbetweener.md):** Shows how to run the Inbetweener, then walks through its code, from sampling and placing poses to chained playback.
+- **[Scene Preview](docs/scene_preview.md):** Lists the options and controls, then describes the example runtime, from the character and the state machine to locomotion and interactions.
+- **[Smart Primitive Editor](docs/smart_primitive_editor.md):** Describes what a Smart Primitive holds and how to author one: the node hierarchy, target poses, interaction boxes, pivots, and sequences.
+- **[Scene Editor](docs/scene_editor.md):** Shows how to build a scene, and describes the `.scene.json` document that Scene Preview opens.
+
+**Integration**
+
+- **[Runtime API](docs/runtime_api.md):** Start here to integrate MotionBricks in your application. Describes the engines, pose layouts, clips, and chaining generations. It includes two runnable scripts that generate motion without a viewer.
+- **[ONNX inference](docs/onnx_inference.md):** Describes the tensor shapes, batching, and other inference libraries, for use without the bundled engines.
+
+**Models**
+
+- **[ONNX exporter](tools/onnx/README.md):** Describes how to export the bundled ONNX models from the checkpoints on Hugging Face.
+- **[SOMA model card](docs/soma_model.md):** Describes the SOMA model, its inputs and outputs, its training data, and its limitations.
+- **[Unitree G1 model card](docs/unitree_g1_model.md):** Describes the Unitree G1 model, its inputs and outputs, its training data, and its limitations.
+
+## Related humanoid work at NVIDIA
+
+MotionBricks is part of a larger effort to enable humanoid motion for animation, robotics, and physical AI. Check out these related works:
+
+- [Kimodo](https://github.com/nv-tlabs/kimodo): human motion generation model specializing in controllable offline motion authoring.
+- [ARDY](https://github.com/nv-tlabs/ardy): builds on Kimodo to enable controllable motion generation in real time for interactive applications.
+- [SOMA Body Model](https://github.com/NVlabs/SOMA-X): a unified parametric human body model.
+- [BONES-SEED Dataset](https://huggingface.co/datasets/bones-studio/seed): a large motion capture dataset of humans and humanoids in SOMA and G1 format.
+- [ProtoMotions](https://github.com/NVlabs/ProtoMotions): simulation and learning framework for training physically simulated humans and humanoids.
+- [SOMA Retargeter](https://github.com/NVIDIA/soma-retargeter): retargets SOMA motion to humanoid robots such as the Unitree G1.
+- [GEM](https://github.com/NVlabs/GEM-X): human motion reconstruction from video.
+- [GEAR SONIC](https://github.com/NVlabs/GR00T-WholeBodyControl): humanoid behavior foundation model for physical robots.
+
+## Citation
+
+If you use this code in your research, please cite:
+
+```bibtex
+@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:
+
+- **Code:** [Apache 2.0](LICENSE), including code examples and snippets in the documentation.
+- **Documentation and media:** NVIDIA-authored documentation text and media (images, screenshots, and videos, including the files in `docs/media/`) use [Creative Commons Attribution 4.0 International (CC-BY-4.0)](https://creativecommons.org/licenses/by/4.0/).
+- **Models:** [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). This covers the SOMA and G1 checkpoints on Hugging Face and the [ONNX models](motionbricks/assets/onnx/LICENSE.md). It permits commercial use and redistribution of modified models, subject to the agreement's terms. Licensed by NVIDIA Corporation under the NVIDIA Open Model Agreement.
+- **Sample motions:** [NVIDIA Sample Data Evaluation License](assets/motions/LICENSE.txt). The covered human BVH and retargeted G1 CSV clips are for evaluating and testing NVIDIA technologies. The [sample-data notice](assets/motions/README.md) lists the covered files and credits Bones. These sample terms are separate from the model terms.
+
+Licenses for dependencies and bundled robot assets are in [licenses](licenses). Exporter dependency licenses are in [tools/onnx/licenses](tools/onnx/licenses/).
+
+This project downloads and installs additional components under their own license terms. Review those terms before use.
+
+The [TensorRT OSS notice](licenses/tensorrt-LICENSE.txt) 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:
+
+- [Newton](https://github.com/newton-physics/newton) for the viewer and scene
+- [NVIDIA Warp](https://github.com/NVIDIA/warp) for GPU kernels
+- [NVIDIA TensorRT](https://github.com/NVIDIA/TensorRT) for inference
+- [Dear ImGui](https://github.com/ocornut/imgui) through [imgui_bundle](https://github.com/pthom/imgui_bundle) for the user interface
+- [OpenUSD](https://github.com/PixarAnimationStudios/OpenUSD) for the SOMA character
+- [Unitree Robotics](https://github.com/unitreerobotics/unitree_ros/tree/master/robots/g1_description) for the Unitree G1 robot model and meshes
+
+## 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.
diff --git a/app/authoring/common.py b/app/authoring/common.py
new file mode 100644
index 0000000..c10c358
--- /dev/null
+++ b/app/authoring/common.py
@@ -0,0 +1,1129 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Viewer controls and UI helpers shared by the editors and the Inbetweener."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import math
+from pathlib import Path
+
+import newton
+import numpy as np
+from pyglet.math import Vec3
+import warp as wp
+
+from motionbricks.model.contract import (
+ MODEL_MAX_TOKEN_COUNT,
+ MODEL_MIN_TOKEN_COUNT,
+ MODEL_POSES_PER_TOKEN,
+ ModelRig,
+)
+
+from ..runtime.common.clip_registry import ClipRegistry
+from ..runtime.common.io.document_io import DocumentError, DocumentType
+from ..runtime.common.rig import RIG_LABELS
+from ..utils.file_dialog import choose_file
+from ..utils.tooltips import show_delayed_tooltip
+
+
+
+EDITOR_FRAME_RATE = 60.0
+WINDOW_MARGIN = 10.0
+RIGHT_DOCK_RATIO = 0.30
+PROPERTIES_WINDOW_WIDTH = 440.0
+PROPERTIES_WINDOW_HEIGHT = 420.0
+NAME_TEXT_COLOR = (0.60, 0.80, 1.0, 1.0)
+POSES_TO_USE_TOOLTIP = (
+ "How many of the target's four poses inform the model. One pose makes the motion stop at "
+ "the target. More poses add velocity, acceleration, and momentum."
+)
+
+_MENU_BAR_ALPHA = 0.8
+_PANEL_ALPHA = 0.9
+_PROPERTIES_DOCK_RATIO = 0.52
+_FULL_ROTATION = 360.0
+_HALF_ROTATION = 0.5 * _FULL_ROTATION
+_DISPLAY_ZERO_EPSILON = 5.0e-4
+_TRANSFORM_AXES = (newton.Axis.X, newton.Axis.Y, newton.Axis.Z)
+_TRANSFORM_AXIS_NAMES = ("X", "Y", "Z")
+_LOCKED_AXIS_COLOR = (1.0, 0.3, 0.3, 1.0)
+_HIDDEN_NAME_ALPHA = 0.45
+
+
+class FileAction(Enum):
+ """File menu commands that an editor can request."""
+
+ NEW = "new"
+ OPEN = "open"
+ SAVE = "save"
+ SAVE_AS = "save_as"
+ EXIT = "exit"
+
+
+@dataclass
+class InlineRename:
+ """Rename state for one item, drawn as a text field in place of its name."""
+
+ item_id: int | None = None
+ text: str = ""
+ focus: bool = False
+
+ def begin(self, item_id: int, name: str) -> None:
+ """Start renaming an item, with its current name in the field."""
+ self.item_id, self.text, self.focus = item_id, name, True
+
+ def draw(self, ui) -> str | None:
+ """Draw the rename field, and return the new name once it is confirmed.
+
+ Enter or leaving the field confirms it. Escape cancels it.
+ """
+ ui.set_next_item_width(-1.0)
+ if self.focus:
+ ui.set_keyboard_focus_here()
+ self.focus = False
+ submitted, self.text = ui.input_text(
+ f"##rename_{self.item_id}", self.text,
+ ui.InputTextFlags_.enter_returns_true | ui.InputTextFlags_.auto_select_all,
+ )
+ if ui.is_key_pressed(ui.Key.escape, False):
+ self.item_id = None
+ elif submitted or ui.is_item_deactivated():
+ self.item_id = None
+ return self.text.strip() or None
+ return None
+
+
+def draw_label(ui, label: str, *, tooltip: str | None = None, column: float = 0.0, width: float = -1.0) -> None:
+ """Draw a label, then place and size the next widget on the same row.
+
+ Args:
+ ui: The ImGui module.
+ label: Text before the widget. A colon follows it.
+ tooltip: Text shown when the pointer rests on the label.
+ column: Where the widget starts, in pixels from the window's left edge. Zero places
+ the widget right after the label.
+ width: Widget width in pixels. -1 fills the rest of the row.
+ """
+ ui.align_text_to_frame_padding()
+ ui.text_unformatted(f"{label}:")
+ if tooltip:
+ show_delayed_tooltip(ui, tooltip)
+ ui.same_line(column)
+ ui.set_next_item_width(width)
+
+
+def draw_add_remove_buttons(ui, can_remove: bool) -> tuple[bool, bool]:
+ """Draw the + and - buttons of a panel, and return whether each one was clicked."""
+ add = ui.button("+")
+ ui.same_line()
+ ui.begin_disabled(not can_remove)
+ remove = ui.button("-")
+ ui.end_disabled()
+ return add, remove
+
+
+def draw_tree_row(
+ ui,
+ name: str,
+ item_id: int,
+ rename: InlineRename,
+ reveal_ids: set[int],
+ *,
+ selected: bool,
+ leaf: bool = False,
+ renamable: bool = True,
+ hidden: bool = False,
+) -> tuple[bool, bool, str | None]:
+ """Draw one row of an outliner tree.
+
+ A click selects the row. A double click selects it and starts renaming it. When the
+ row is open, the caller draws its children and then calls ui.tree_pop().
+
+ Args:
+ ui: The ImGui module.
+ name: Name shown in the row.
+ item_id: ID of the row's item.
+ rename: Rename state shared by the tree's rows.
+ reveal_ids: IDs of rows to open so a new selection shows. The selected row scrolls
+ into view and clears the set.
+ selected: Highlight the row.
+ leaf: Draw the row without an arrow.
+ renamable: Let a double click rename the item.
+ hidden: Dim the name of an item that the view hides.
+
+ Returns:
+ Whether the row is open, whether the user selected it, and the new name once a
+ rename is confirmed.
+ """
+ renaming = item_id == rename.item_id
+ flags = ui.TreeNodeFlags_.open_on_arrow | ui.TreeNodeFlags_.default_open
+ if not renaming:
+ flags |= ui.TreeNodeFlags_.span_avail_width
+ if leaf:
+ flags |= ui.TreeNodeFlags_.leaf
+ if selected:
+ flags |= ui.TreeNodeFlags_.selected
+ reveal = item_id in reveal_ids
+ if reveal and not selected:
+ ui.set_next_item_open(True)
+ text_color = (*NAME_TEXT_COLOR[:3], _HIDDEN_NAME_ALPHA) if hidden else NAME_TEXT_COLOR
+ ui.push_style_color(ui.Col_.text, ui.ImVec4(*text_color))
+ row_open = ui.tree_node_ex("###TreeRow" if renaming else f"{name}###TreeRow", flags=flags)
+ ui.pop_style_color()
+ if reveal and selected:
+ ui.set_scroll_here_y()
+ reveal_ids.clear()
+
+ if renaming:
+ ui.same_line()
+ return row_open, False, rename.draw(ui)
+ toggled = ui.is_item_toggled_open()
+ if renamable and ui.is_item_hovered() and ui.is_mouse_double_clicked(0) and not toggled:
+ rename.begin(item_id, name)
+ return row_open, True, None
+ return row_open, ui.is_item_clicked() and not toggled, None
+
+
+def drag_source(ui, payload_type: str, item_id: int, text: str) -> bool:
+ """Let the last widget be dragged with item_id as its payload.
+
+ Returns:
+ True while the widget is dragged. text follows the pointer during the drag.
+ """
+ if not ui.begin_drag_drop_source():
+ return False
+ ui.set_drag_drop_payload_py_id(payload_type, item_id)
+ ui.text(text)
+ ui.end_drag_drop_source()
+ return True
+
+
+def accept_drop(ui, payload_type: str) -> int | None:
+ """Return the item ID dropped on the last widget in this frame, or None."""
+ if not ui.begin_drag_drop_target():
+ return None
+ payload = ui.accept_drag_drop_payload_py_id(payload_type)
+ ui.end_drag_drop_target()
+ return None if payload is None else payload.data_id
+
+
+def draw_int_slider_property(
+ ui, label: str, value: int, minimum: int, maximum: int, item_id: int,
+ *, tooltip: str | None = None,
+) -> int:
+ """Draw a labeled integer slider that fills the available width."""
+ draw_label(ui, label, tooltip=tooltip)
+ _, value = ui.slider_int(f"##{label}{item_id}", value, minimum, maximum, flags=ui.SliderFlags_.always_clamp)
+ return value
+
+
+def draw_token_range_property(ui, min_tokens: int, max_tokens: int, item_id: int) -> tuple[int, int]:
+ """Draw the Tokens to Generate range and its raw frames, then return the range."""
+ draw_label(ui, "Tokens to Generate")
+ _, min_tokens, max_tokens = ui.drag_int_range2(
+ f"##tokens{item_id}", min_tokens, max_tokens, 1.0, MODEL_MIN_TOKEN_COUNT, MODEL_MAX_TOKEN_COUNT,
+ "Min: %d", "Max: %d", flags=ui.SliderFlags_.always_clamp,
+ )
+ min_frames = min_tokens * MODEL_POSES_PER_TOKEN
+ max_frames = max_tokens * MODEL_POSES_PER_TOKEN
+ frame_range = str(min_frames) if min_frames == max_frames else f"{min_frames} to {max_frames}"
+ ui.text_unformatted(f"Raw frames: {frame_range}")
+ return min_tokens, max_tokens
+
+
+def draw_box_dimensions(
+ ui, dimensions: tuple[float, float, float], minimum: float, dpi_scale: float,
+) -> tuple[bool, tuple[float, float, float]]:
+ """Draw Width, Depth, and Height fields in meters.
+
+ Returns:
+ Whether a value changed, and the width, depth, and height. Edited values are at
+ least minimum. A value that is not finite becomes minimum.
+ """
+ values = list(dimensions)
+ changed = False
+ for index, label in enumerate(("Width", "Depth", "Height")):
+ draw_label(ui, label, column=80.0 * dpi_scale, width=100.0 * dpi_scale)
+ value_changed, values[index] = ui.input_float(f"##{label}", values[index])
+ changed |= value_changed
+ if changed:
+ values = [max(value, minimum) if math.isfinite(value) else minimum for value in values]
+ return changed, tuple(values)
+
+
+def clean_display_value(value: float) -> float:
+ """Return 0 for a value too small to show."""
+
+ return 0.0 if abs(value) < _DISPLAY_ZERO_EPSILON else value
+
+
+def stable_rotation_degrees(rotation: wp.quat, reference: list[float] | None) -> list[float]:
+ """Keep displayed rotation angles close to their previous values to avoid jumps."""
+
+ rpy = wp.quat_to_rpy(rotation)
+ primary = [float(wp.degrees(rpy[index])) for index in range(3)]
+ if reference is None:
+ return [clean_display_value(value) for value in primary]
+
+ primary = [
+ _nearest_angle(primary[index], reference[index])
+ for index in range(3)
+ ]
+ alternate = [
+ _nearest_angle(primary[0] + _HALF_ROTATION, reference[0]),
+ _nearest_angle(_HALF_ROTATION - primary[1], reference[1]),
+ _nearest_angle(primary[2] + _HALF_ROTATION, reference[2]),
+ ]
+ primary_distance = sum(
+ (primary[index] - reference[index]) ** 2 for index in range(3)
+ )
+ alternate_distance = sum(
+ (alternate[index] - reference[index]) ** 2 for index in range(3)
+ )
+ if alternate_distance < primary_distance:
+ primary = alternate
+ return [clean_display_value(value) for value in primary]
+
+
+def transforms_equal(lhs: wp.transform, rhs: wp.transform) -> bool:
+ """Compare two transforms, ignoring tiny differences and treating q and -q as the same rotation."""
+
+ position_equal = all(abs(a - b) <= 1e-6 for a, b in zip(lhs.p, rhs.p))
+ rotation_equal = (
+ all(abs(a - b) <= 1e-6 for a, b in zip(lhs.q, rhs.q))
+ or all(abs(a + b) <= 1e-6 for a, b in zip(lhs.q, rhs.q))
+ )
+ return position_equal and rotation_equal
+
+
+def ellipsize_text(ui, text: str, max_width: float) -> str:
+ """Shorten text with ... to fit max_width (in pixels)."""
+
+ if max_width <= 0.0:
+ return ""
+ if ui.calc_text_size(text).x <= max_width:
+ return text
+
+ ellipsis = "..."
+ if ui.calc_text_size(ellipsis).x > max_width:
+ return ""
+ lower = 0
+ upper = len(text)
+ while lower < upper:
+ middle = (lower + upper + 1) // 2
+ if ui.calc_text_size(text[:middle] + ellipsis).x <= max_width:
+ lower = middle
+ else:
+ upper = middle - 1
+ return text[:lower] + ellipsis
+
+
+def draw_character_selector(ui, rig: ModelRig, locked_reason: str | None = None) -> ModelRig:
+ """Show the Character combo and return the chosen rig.
+
+ When locked_reason is given, the combo is disabled and its tooltip
+ shows the reason.
+ """
+ rigs = list(RIG_LABELS)
+ draw_label(ui, "Character")
+ ui.begin_disabled(locked_reason is not None)
+ _, index = ui.combo("##Character", rigs.index(rig), list(RIG_LABELS.values()))
+ ui.end_disabled()
+ if locked_reason is not None and ui.is_item_hovered(ui.HoveredFlags_.allow_when_disabled):
+ ui.set_tooltip(locked_reason)
+ return rigs[index]
+
+
+def draw_clip_selector(
+ ui, name: str, path: Path | None, item_id: int, *, label: str = "Clip",
+) -> bool:
+ """Show a file name after the label, with its path in a tooltip. Return True when the load button is clicked."""
+ style = ui.get_style()
+ button_width = ui.calc_text_size("...").x + 2 * style.frame_padding.x
+ ui.align_text_to_frame_padding()
+ ui.text_unformatted(f"{label}:")
+ ui.same_line()
+ name_width = ui.get_content_region_avail().x - button_width - style.item_spacing.x
+ ui.text_unformatted(ellipsize_text(ui, name, name_width))
+ if path is not None:
+ show_delayed_tooltip(ui, str(path))
+ ui.same_line()
+ return ui.button(f"...##LoadClip{item_id}", ui.ImVec2(button_width, 0))
+
+
+def choose_clip(clip_registry: ClipRegistry, current_path: Path | None = None) -> str:
+ """Show the Open dialog for the clips of the registry's rig, BVH for SOMA and CSV for G1.
+
+ Returns:
+ The chosen path, or an empty string when the dialog is canceled.
+ """
+ suffix = clip_registry.suffix
+ kind = suffix[1:].upper()
+ return choose_file(f"Open {kind} Clip", f"{kind} clips", suffix, current_path)
+
+
+def draw_transform_editor(
+ ui, transform: wp.transform, euler_degrees: list[float] | None, scale: float,
+ translation_locks: list[bool], rotation_locks: list[bool],
+) -> tuple[bool, wp.transform, list[float]]:
+ """Edit position and rotation, with reset menus and axis locks.
+
+ Args:
+ ui: The ImGui module.
+ transform: Transform shown in the fields.
+ euler_degrees: Angles from the previous call, in degrees, or None. They keep the
+ shown angles from jumping.
+ scale: DPI scale for the field layout.
+ translation_locks: Lock flag for each axis. The lock menus edit it in place.
+ rotation_locks: Lock flag for each axis. The lock menus edit it in place.
+
+ Returns:
+ Whether a value changed, the edited transform, and the angles to pass back on the
+ next call.
+ """
+ position = [clean_display_value(float(value)) for value in transform.p]
+ rotation = stable_rotation_degrees(transform.q, euler_degrees)
+ moved = draw_transform_row(ui, "Translation", position, scale, translation_locks)
+ rotated = draw_transform_row(ui, "Rotation", rotation, scale, rotation_locks)
+ position = [
+ value if moved and not translation_locks[axis] else transform.p[axis]
+ for axis, value in enumerate(position)
+ ]
+ quaternion = wp.quat_rpy(*(wp.radians(value) for value in rotation)) if rotated else transform.q
+ return moved or rotated, wp.transform(wp.vec3(*position), quaternion), rotation
+
+
+def apply_transform_locks(
+ current: wp.transform, edited: wp.transform, euler_degrees: list[float] | None,
+ translation_locks: list[bool], rotation_locks: list[bool],
+) -> tuple[wp.transform, list[float]]:
+ """Keep locked axes unchanged when applying a gizmo edit."""
+ position = wp.vec3(*(
+ current.p[axis] if translation_locks[axis] else edited.p[axis]
+ for axis in range(3)
+ ))
+ current_euler = stable_rotation_degrees(current.q, euler_degrees)
+ edited_euler = stable_rotation_degrees(edited.q, current_euler)
+ rotation = [
+ current_euler[axis] if rotation_locks[axis] else edited_euler[axis]
+ for axis in range(3)
+ ]
+ if all(rotation_locks):
+ quaternion = current.q
+ elif any(rotation_locks):
+ quaternion = wp.quat_rpy(*(wp.radians(value) for value in rotation))
+ else:
+ quaternion = edited.q
+ return wp.transform(position, quaternion), rotation
+
+
+def draw_transform_row(
+ ui,
+ label: str,
+ values: list[float],
+ dpi_scale: float,
+ locks: list[bool],
+) -> bool:
+ """Draw X, Y, and Z fields with a reset menu and axis locks."""
+
+ ui.begin_group()
+ changed = _draw_transform_reset(ui, label, values, locks)
+ ui.same_line(110.0 * dpi_scale)
+ for index, axis_name in enumerate(_TRANSFORM_AXIS_NAMES):
+ if index:
+ ui.same_line()
+ changed |= _draw_transform_axis(
+ ui,
+ label,
+ axis_name,
+ index,
+ values,
+ locks,
+ dpi_scale,
+ )
+ ui.end_group()
+ return changed
+
+
+def draw_clip_scrubber(
+ ui,
+ animation,
+ sample_time: float,
+ show_frames: bool,
+ dpi_scale: float,
+) -> tuple[bool, float, bool]:
+ """Edit the sample time and return (changed, time_in_seconds, show_frames).
+
+ Frame numbers use the clip's sample rate. Switching to Frames snaps to the
+ nearest frame, and switching to Seconds keeps the same time. The controls
+ stay visible but disabled until a clip is loaded.
+ """
+ original_time = sample_time
+ num_frames = animation.num_frames if animation is not None else 0
+ sample_rate = animation.sample_rate if animation is not None else 1.0
+ last_frame = max(0, num_frames - 1)
+ duration = last_frame / sample_rate
+ frame = min(max(round(sample_time * sample_rate), 0), last_frame)
+
+ ui.begin_disabled(animation is None)
+ if ui.button("Frames" if show_frames else "Seconds", ui.ImVec2(65.0 * dpi_scale, 0.0)):
+ show_frames = not show_frames
+ if show_frames:
+ sample_time = frame / sample_rate
+ ui.same_line()
+ ui.set_next_item_width(250.0 * dpi_scale)
+ if show_frames:
+ changed, frame = ui.slider_int("##SamplePosition", frame, 0, last_frame, flags=ui.SliderFlags_.always_clamp)
+ if changed:
+ sample_time = frame / sample_rate
+ ui.same_line()
+ ui.text(str(num_frames))
+ else:
+ changed, sample_time = ui.slider_float(
+ "##SamplePosition", sample_time, 0.0, duration, "%.2f", flags=ui.SliderFlags_.always_clamp,
+ )
+ ui.same_line()
+ ui.text(f"{duration:.2f} s")
+ ui.end_disabled()
+ return changed or sample_time != original_time, sample_time, show_frames
+
+
+def log_transform_gizmo(
+ viewer,
+ name: str,
+ transform: wp.transform,
+ *,
+ translation_locks: list[bool],
+ rotation_locks: list[bool],
+ axes_rotation: wp.quat | None = None,
+) -> None:
+ """Draw handles for the unlocked axes.
+
+ axes_rotation sets their orientation. Omit it to use the world axes.
+ """
+
+ viewer.log_gizmo(
+ name,
+ transform,
+ translate=tuple(
+ axis
+ for axis, locked in zip(_TRANSFORM_AXES, translation_locks)
+ if not locked
+ ),
+ rotate=tuple(
+ axis
+ for axis, locked in zip(_TRANSFORM_AXES, rotation_locks)
+ if not locked
+ ),
+ )
+ if axes_rotation is not None:
+ viewer._gizmo_log[name]["axes_rotation"] = wp.quat(axes_rotation)
+
+
+def _read_gizmo_transform(matrix) -> wp.transform:
+ """Read an ImGuizmo matrix as a Warp transform."""
+ rows = np.asarray(matrix.values, dtype=np.float32).reshape(4, 4, order="F")
+ return wp.transform_from_matrix(wp.mat44(*rows.flatten()))
+
+
+def _gizmo_matrix_values(transform: wp.transform) -> list[float]:
+ """Return matrix values in ImGuizmo's column order."""
+ matrix = np.asarray(wp.transform_to_matrix(transform), dtype=np.float32).reshape(4, 4)
+ return matrix.flatten(order="F").tolist()
+
+
+class _TransformGizmo:
+ """Draw handles in the chosen axes and keep movement within the unlocked axes."""
+
+ def __init__(self, giz, gizmo_log) -> None:
+ self._giz = giz
+ self._gizmo_log = gizmo_log or {}
+
+ def __getattr__(self, name):
+ return getattr(self._giz, name)
+
+ def push_id(self, name) -> None:
+ entry = self._gizmo_log.get(name, {})
+ self._translation_axes = entry.get("translate", _TRANSFORM_AXES)
+ self._axes_rotation = entry.get("axes_rotation", wp.quat_identity())
+ self._translation_drawn = False
+ self._giz.push_id(name)
+
+ def manipulate(self, view, projection, operation, mode, matrix, *args):
+ giz = self._giz
+ translating = bool(operation & giz.OPERATION.translate)
+ if translating:
+ if self._translation_drawn:
+ return False
+ self._translation_drawn = True
+ giz.set_axis_mask(
+ *(axis not in self._translation_axes for axis in _TRANSFORM_AXES)
+ )
+ if len(self._translation_axes) == 2:
+ # Keep the square handle between the two unlocked axes.
+ operation = giz.OPERATION.translate
+ else:
+ giz.set_axis_mask(False, False, False)
+
+ # The handles have their own orientation at the item's position.
+ current = _read_gizmo_transform(matrix)
+ axes_rotation = self._axes_rotation
+ handle_matrix = giz.Matrix16(_gizmo_matrix_values(wp.transform(current.p, axes_rotation)))
+ if not giz.manipulate(view, projection, operation, giz.MODE.local, handle_matrix, *args):
+ return False
+
+ edited = _read_gizmo_transform(handle_matrix)
+ offset = wp.quat_rotate_inv(axes_rotation, edited.p - current.p)
+ if translating:
+ # The center handle can also move along locked axes. Remove that movement.
+ offset = wp.vec3(*(
+ offset[index] if axis in self._translation_axes else 0.0
+ for index, axis in enumerate(_TRANSFORM_AXES)
+ ))
+ rotation_delta = wp.mul(edited.q, wp.quat_inverse(axes_rotation))
+ rotation = wp.normalize(wp.mul(rotation_delta, current.q))
+ position = current.p + wp.quat_rotate(axes_rotation, offset)
+ matrix.values[:] = _gizmo_matrix_values(wp.transform(position, rotation))
+ return True
+
+
+class NewtonViewerUIBridge:
+ """Manage Newton's viewer panels, gizmos with axis locks, and clicks in the view."""
+
+ def __init__(self, viewer: newton.viewer.ViewerGL) -> None:
+ """Start with the viewer's options and stats panels hidden.
+
+ Set on_scene_click to receive the world ray of each click in the view.
+ """
+ self.viewer = viewer
+ self.show_options = False
+ self.show_stats = False
+ self.dockspace_id: int | None = None
+ self._viewer_gui = None
+ self._options_callback = None
+ self._stats_callback = None
+ self._gizmos_callback = None
+ self.on_scene_click = None
+ self._scene_click_pending = False
+
+ def install(self, ui) -> None:
+ """Enable docking, and route the viewer's options, stats, and gizmo panels here."""
+ ui.get_io().config_flags |= ui.ConfigFlags_.docking_enable
+ viewer_gui = self.viewer.gui
+ self._viewer_gui = viewer_gui
+ self._options_callback = viewer_gui._render_left_panel
+ self._stats_callback = viewer_gui._render_stats_overlay
+ self._gizmos_callback = viewer_gui._render_gizmos
+ viewer_gui._render_left_panel = self._render_options
+ viewer_gui._render_stats_overlay = self._render_stats
+ viewer_gui._render_gizmos = self._render_gizmos
+
+ def _render_options(self) -> None:
+ if self.show_options:
+ self._options_callback()
+
+ def _render_stats(self) -> None:
+ if self.show_stats:
+ self._stats_callback()
+
+ def _render_gizmos(self) -> None:
+ viewer_ui = self._viewer_gui.ui
+ ui = viewer_ui.imgui
+ draw_list = ui.get_background_draw_list(ui.get_main_viewport())
+ viewer_ui.giz.set_drawlist(draw_list)
+
+ clip_rect_pushed = False
+ if self.dockspace_id is not None:
+ central_node = ui.internal.dock_builder_get_central_node(
+ self.dockspace_id
+ )
+ if central_node is not None:
+ clip_min = central_node.pos
+ clip_max = ui.ImVec2(
+ central_node.pos.x + central_node.size.x,
+ central_node.pos.y + central_node.size.y,
+ )
+ draw_list.push_clip_rect(clip_min, clip_max, True)
+ clip_rect_pushed = True
+ giz = viewer_ui.giz
+ try:
+ viewer_ui.giz = _TransformGizmo(
+ giz, self.viewer._gizmo_log
+ )
+ self._gizmos_callback()
+ finally:
+ viewer_ui.giz = giz
+ giz.set_axis_mask(False, False, False)
+ if clip_rect_pushed:
+ draw_list.pop_clip_rect()
+ self._handle_scene_click(ui, giz)
+
+ def _handle_scene_click(self, ui, giz) -> None:
+ if self.on_scene_click is None:
+ return
+ io = ui.get_io()
+ blocked = io.want_capture_mouse or giz.is_over() or giz.is_using_any()
+ if ui.is_mouse_clicked(0):
+ self._scene_click_pending = not blocked
+ if blocked or ui.is_mouse_dragging(0):
+ self._scene_click_pending = False
+ if ui.is_mouse_released(0):
+ clicked = self._scene_click_pending
+ self._scene_click_pending = False
+ if clicked and io.display_size.x > 0 and io.display_size.y > 0:
+ # Convert mouse coordinates to camera pixels, with Y measured from the bottom.
+ mouse = ui.get_mouse_pos()
+ viewport = ui.get_main_viewport()
+ camera = self.viewer.camera
+ x = (mouse.x - viewport.pos.x) * camera.width / io.display_size.x
+ y = (1.0 - (mouse.y - viewport.pos.y) / io.display_size.y) * camera.height
+ origin, direction = camera.get_world_ray(x, y)
+ self.on_scene_click(wp.vec3(*origin), wp.vec3(*direction))
+
+
+class EditorViewer:
+ """Shared frame loop, menus, panels, and file handling for the editors."""
+
+ # Each editor sets its window title, its outliner window's title, and the kind of
+ # document it edits.
+ _EDITOR_TITLE: str
+ _OUTLINER_WINDOW_TITLE: str
+ _DOCUMENT_TYPE: DocumentType
+
+ def __init__(self, viewer: newton.viewer.ViewerGL) -> None:
+ """Set up the editor on a graphical viewer.
+
+ A null viewer raises TypeError.
+ """
+ if isinstance(viewer, newton.viewer.ViewerNull):
+ raise TypeError("This editor requires a graphical viewer.")
+
+ self.viewer = viewer
+ self._viewer_time = 0.0
+ self._viewer_ui = NewtonViewerUIBridge(viewer)
+ self._dock_layout_pending = True
+ # An error message to show in the editor.
+ self._status: str | None = None
+ self._exit_requested = False
+ self._document_path: Path | None = None
+
+ viewer_gui = viewer.gui
+ if viewer_gui is not None:
+ self._viewer_ui.install(viewer_gui.ui.imgui)
+
+ builder = newton.ModelBuilder()
+ builder.add_ground_plane()
+ self.model = builder.finalize()
+ self.state = self.model.state()
+ viewer.set_model(self.model)
+ viewer.set_world_offsets([0, 0, 0])
+ viewer.vsync = True
+ viewer.register_ui_callback(self.gui, position="free")
+ self._update_window_title()
+
+ def _capture_camera_state(self) -> dict:
+ camera = self.viewer.camera
+ return {
+ "pos": [float(camera.pos[index]) for index in range(3)],
+ "pivot": [float(camera.pivot[index]) for index in range(3)],
+ "pitch": float(camera.pitch),
+ "yaw": float(camera.yaw),
+ "fov": float(camera.fov),
+ "near": float(camera.near),
+ "far": float(camera.far),
+ }
+
+ def _apply_camera_state(self, camera_state: dict | None) -> None:
+ if camera_state is None:
+ return
+
+ camera = self.viewer.camera
+ camera.pos = Vec3(*camera_state["pos"])
+ camera.pivot = Vec3(*camera_state["pivot"])
+ camera.pitch = camera_state["pitch"]
+ camera.yaw = camera_state["yaw"]
+ camera.fov = camera_state["fov"]
+ camera.near = camera_state["near"]
+ camera.far = camera_state["far"]
+
+ def render(self) -> None:
+ """Draw one editor frame, then apply the selection gizmo's changes."""
+ self.viewer.begin_frame(self._viewer_time)
+ self._draw_editor_scene()
+ self._draw_selection_gizmo()
+ self.viewer.log_state(self.state)
+ self.viewer.end_frame()
+ self._apply_selection_gizmo()
+ self._viewer_time += 1.0 / EDITOR_FRAME_RATE
+
+ def run(self, max_frames: int | None = None) -> None:
+ """Draw frames until the window closes, Exit is chosen, or max_frames is reached."""
+ frame = 0
+ while not self._exit_requested and self.viewer.is_running() and (
+ max_frames is None or frame < max_frames
+ ):
+ self.render()
+ frame += 1
+ self.viewer.close()
+
+ def gui(self, ui) -> None:
+ """Draw the menu bar, the dock space, and the editor windows."""
+ dpi_scale = max(1.0, float(ui.get_style().font_scale_dpi))
+ self._draw_main_menu_bar(ui)
+ self._draw_dockspace(ui)
+ self._draw_outliner_window(ui, dpi_scale)
+ self._draw_additional_windows(ui, dpi_scale)
+ self._draw_properties_window(ui, dpi_scale)
+ self._draw_exit_confirmation(ui)
+
+ def _draw_additional_windows(self, ui, dpi_scale: float) -> None:
+ """Draw any extra panels provided by this editor."""
+
+ def _draw_main_menu_bar(self, ui) -> None:
+ file_action = None
+ style = ui.get_style()
+ menu_bar_color = style.color_(ui.Col_.menu_bar_bg)
+ ui.push_style_color(
+ ui.Col_.menu_bar_bg,
+ ui.ImVec4(
+ menu_bar_color.x,
+ menu_bar_color.y,
+ menu_bar_color.z,
+ _MENU_BAR_ALPHA,
+ ),
+ )
+ try:
+ if ui.begin_main_menu_bar():
+ file_action = self._draw_file_menu(ui)
+ self._draw_tools_menu(ui)
+ ui.end_main_menu_bar()
+ finally:
+ ui.pop_style_color()
+
+ # Handle the choice after the menu bar ends, so the menu closes before a file dialog opens.
+ if file_action is FileAction.EXIT:
+ ui.open_popup("Exit")
+ else:
+ self._handle_file_action(file_action)
+
+ def _draw_exit_confirmation(self, ui) -> None:
+ ui.set_next_window_pos(
+ ui.get_main_viewport().get_center(), ui.Cond_.appearing,
+ pivot=ui.ImVec2(0.5, 0.5),
+ )
+ if not ui.begin_popup_modal("Exit", flags=ui.WindowFlags_.always_auto_resize)[0]:
+ return
+
+ ui.text_unformatted("Save the current document before exiting?")
+ if ui.button("Save"):
+ if self._handle_file_action(FileAction.SAVE):
+ self._exit_requested = True
+ ui.close_current_popup()
+ ui.same_line()
+ if ui.button("Don't Save"):
+ self._exit_requested = True
+ ui.close_current_popup()
+ ui.same_line()
+ if ui.button("Cancel"):
+ ui.close_current_popup()
+ self._draw_status(ui)
+ ui.end_popup()
+
+ def _draw_tools_menu(self, ui) -> None:
+ if not ui.begin_menu("Tools"):
+ return
+ viewer_ui = self._viewer_ui
+ _, viewer_ui.show_options = ui.menu_item("Viewer Options", "", viewer_ui.show_options)
+ _, viewer_ui.show_stats = ui.menu_item("Viewer Stats", "", viewer_ui.show_stats)
+ ui.end_menu()
+
+ def _draw_dockspace(self, ui) -> None:
+ dockspace_flags = (
+ ui.DockNodeFlags_.passthru_central_node
+ | ui.DockNodeFlags_.no_docking_over_central_node
+ )
+ dockspace_id = ui.dock_space_over_viewport(
+ 0,
+ ui.get_main_viewport(),
+ dockspace_flags,
+ )
+ self._viewer_ui.dockspace_id = dockspace_id
+ if not self._dock_layout_pending:
+ return
+
+ dock_builder = ui.internal
+ root_node = dock_builder.dock_builder_get_node(dockspace_id)
+ if root_node is None:
+ return
+ if root_node.is_split_node() or not root_node.is_empty():
+ self._dock_layout_pending = False
+ return
+
+ self._build_initial_dock_layout(ui, dockspace_id)
+ self._dock_layout_pending = False
+
+ def _build_initial_dock_layout(self, ui, dockspace_id: int) -> None:
+ """Set up the tree panel and the Properties panel when no layout has been saved."""
+
+ dock_builder = ui.internal
+ _, right_dock_id, _ = dock_builder.dock_builder_split_node_py(
+ dockspace_id,
+ ui.Dir.right,
+ RIGHT_DOCK_RATIO,
+ )
+ _, properties_dock_id, outliner_dock_id = (
+ dock_builder.dock_builder_split_node_py(
+ right_dock_id,
+ ui.Dir.down,
+ _PROPERTIES_DOCK_RATIO,
+ )
+ )
+ dock_builder.dock_builder_dock_window(
+ self._OUTLINER_WINDOW_TITLE,
+ outliner_dock_id,
+ )
+ dock_builder.dock_builder_dock_window(
+ "Properties",
+ properties_dock_id,
+ )
+ dock_builder.dock_builder_finish(dockspace_id)
+
+ @staticmethod
+ def _set_initial_panel_geometry(
+ ui,
+ dpi_scale: float,
+ width: float,
+ height: float,
+ top_offset: float,
+ ) -> None:
+ """Place a panel before ImGui has a saved layout for it."""
+
+ viewport = ui.get_main_viewport()
+ margin = WINDOW_MARGIN * dpi_scale
+ ui.set_next_window_pos(
+ ui.ImVec2(
+ viewport.work_pos.x + viewport.work_size.x - margin,
+ viewport.work_pos.y + top_offset * dpi_scale,
+ ),
+ ui.Cond_.first_use_ever,
+ pivot=ui.ImVec2(1.0, 0.0),
+ )
+ ui.set_next_window_size(
+ ui.ImVec2(width * dpi_scale, height * dpi_scale),
+ ui.Cond_.first_use_ever,
+ )
+ ui.set_next_window_bg_alpha(_PANEL_ALPHA)
+
+ def _draw_status(self, ui) -> None:
+ if self._status is None:
+ return
+
+ ui.push_style_color(
+ ui.Col_.text,
+ ui.ImVec4(1.0, 0.35, 0.35, 1.0),
+ )
+ ui.text_wrapped(self._status)
+ ui.pop_style_color()
+
+ def _draw_editor_scene(self) -> None:
+ raise NotImplementedError
+
+ def _draw_selection_gizmo(self) -> None:
+ raise NotImplementedError
+
+ def _apply_selection_gizmo(self) -> None:
+ raise NotImplementedError
+
+ def _draw_file_menu(self, ui) -> FileAction | None:
+ """Draw the File menu and return the chosen action."""
+ if not ui.begin_menu("File"):
+ return None
+
+ new_requested, _ = ui.menu_item("New", "", False)
+ ui.separator()
+ open_requested, _ = ui.menu_item("Open...", "", False)
+ save_requested, _ = ui.menu_item("Save", "", False)
+ save_as_requested, _ = ui.menu_item("Save As...", "", False)
+ ui.separator()
+ exit_requested, _ = ui.menu_item("Exit", "", False)
+ ui.end_menu()
+
+ if new_requested:
+ return FileAction.NEW
+ if open_requested:
+ return FileAction.OPEN
+ if save_requested:
+ return FileAction.SAVE
+ if save_as_requested:
+ return FileAction.SAVE_AS
+ if exit_requested:
+ return FileAction.EXIT
+ return None
+
+ def _handle_file_action(self, file_action: FileAction | None) -> bool | None:
+ """Handle a File menu choice. Save and Save As return whether the save succeeded."""
+ if file_action is FileAction.NEW:
+ self._new_document()
+ elif file_action is FileAction.OPEN:
+ self._open()
+ elif file_action is FileAction.SAVE:
+ return self._save()
+ elif file_action is FileAction.SAVE_AS:
+ return self._save_as()
+ return None
+
+ def _open(self) -> None:
+ kind = self._DOCUMENT_TYPE.kind
+ path = choose_file(f"Open {kind}", f"{kind} documents", self._DOCUMENT_TYPE.suffix, self._document_path)
+ if path:
+ self._open_document(path)
+
+ def _save(self) -> bool:
+ if self._document_path is None:
+ return self._save_as()
+ return self._save_to(self._document_path)
+
+ def _save_as(self) -> bool:
+ kind = self._DOCUMENT_TYPE.kind
+ path = choose_file(
+ f"Save {kind}", f"{kind} documents", self._DOCUMENT_TYPE.suffix, self._document_path, save=True,
+ )
+ if not path:
+ return False
+ return self._save_to(path)
+
+ def _save_to(self, path: str | Path) -> bool:
+ try:
+ document_path = self._save_document(path)
+ except DocumentError as exc:
+ self._status = f"Save failed: {exc}"
+ return False
+ self._set_document_path(document_path)
+ return True
+
+ def _set_document_path(self, document_path: Path | None) -> None:
+ """Make document_path the current file and show its name in the window title."""
+ self._document_path = document_path
+ self._status = None
+ self._update_window_title()
+
+ def _update_window_title(self) -> None:
+ title = self._EDITOR_TITLE
+ if self._document_path is not None:
+ title = f"{title} - {self._DOCUMENT_TYPE.name_from_path(self._document_path)}"
+ self.viewer.renderer.set_title(title)
+
+ def _new_document(self) -> None:
+ raise NotImplementedError
+
+ def _open_document(self, path: str | Path) -> None:
+ """Open the document at path, or show why it failed in the status line."""
+ raise NotImplementedError
+
+ def _save_document(self, path: str | Path) -> Path:
+ """Save the document to path and return the saved file, or raise DocumentError."""
+ raise NotImplementedError
+
+ def _draw_outliner_window(self, ui, dpi_scale: float) -> None:
+ raise NotImplementedError
+
+ def _draw_properties_window(self, ui, dpi_scale: float) -> None:
+ raise NotImplementedError
+
+
+def _nearest_angle(angle: float, reference: float) -> float:
+ delta = (angle - reference + _HALF_ROTATION) % _FULL_ROTATION
+ return reference + delta - _HALF_ROTATION
+
+
+def _draw_transform_reset(ui, label: str, values: list[float], locks: list[bool]) -> bool:
+ ui.align_text_to_frame_padding()
+ label_text = f"{label}:"
+ ui.selectable(
+ f"{label_text}##{label}ResetLabel",
+ False,
+ ui.SelectableFlags_.none,
+ ui.ImVec2(ui.calc_text_size(label_text).x, 0.0),
+ )
+ changed = False
+ if ui.begin_popup_context_item(f"##{label}Reset"):
+ reset, _ = ui.menu_item("Reset", "", False)
+ if reset:
+ for axis in range(3):
+ if not locks[axis]:
+ changed |= values[axis] != 0.0
+ values[axis] = 0.0
+ ui.end_popup()
+ return changed
+
+
+def _draw_transform_axis(
+ ui,
+ label: str,
+ axis_name: str,
+ index: int,
+ values: list[float],
+ locks: list[bool],
+ dpi_scale: float,
+) -> bool:
+ ui.begin_group()
+ ui.align_text_to_frame_padding()
+ if locks[index]:
+ ui.push_style_color(
+ ui.Col_.text,
+ ui.ImVec4(*_LOCKED_AXIS_COLOR),
+ )
+ ui.selectable(
+ f"{axis_name}##{label}{axis_name}LockLabel",
+ False,
+ ui.SelectableFlags_.none,
+ ui.ImVec2(ui.calc_text_size(axis_name).x, 0.0),
+ )
+ if locks[index]:
+ ui.pop_style_color()
+ if ui.begin_popup_context_item(f"##{label}{axis_name}Lock"):
+ action = "Unlock" if locks[index] else "Lock"
+ toggle_lock, _ = ui.menu_item(
+ f"{action} {axis_name}",
+ "",
+ False,
+ )
+ if toggle_lock:
+ locks[index] = not locks[index]
+ ui.end_popup()
+ ui.same_line()
+ ui.begin_disabled(locks[index])
+ ui.set_next_item_width(60.0 * dpi_scale)
+ changed, values[index] = ui.input_float(
+ f"##{label}{axis_name}",
+ values[index],
+ )
+ ui.end_disabled()
+ ui.end_group()
+ return changed
+
+
+__all__ = [
+ "NAME_TEXT_COLOR",
+ "POSES_TO_USE_TOOLTIP",
+ "PROPERTIES_WINDOW_HEIGHT",
+ "PROPERTIES_WINDOW_WIDTH",
+ "RIGHT_DOCK_RATIO",
+ "WINDOW_MARGIN",
+ "EditorViewer",
+ "FileAction",
+ "InlineRename",
+ "NewtonViewerUIBridge",
+ "apply_transform_locks",
+ "draw_character_selector",
+ "draw_clip_scrubber",
+ "draw_clip_selector",
+ "draw_int_slider_property",
+ "draw_token_range_property",
+ "draw_transform_editor",
+ "log_transform_gizmo",
+ "transforms_equal",
+]
diff --git a/app/inbetweener_demo.py b/app/inbetweener_demo.py
new file mode 100644
index 0000000..399ae74
--- /dev/null
+++ b/app/inbetweener_demo.py
@@ -0,0 +1,722 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""A simple example of generating motion between poses with MotionBricks.
+
+Choose poses from clips, place them in the view, and arrange them in the list.
+Press Generate to move from Start through the targets in that order.
+Each transition builds on the motion that came before it.
+
+The engine creates the context token, target token, and output buffer once.
+Every transition reuses them:
+
+ context.update_from_poses(recent_poses)
+ target.update_from_poses(target_poses)
+ engine.generate_animation(context=context, target=target, output=output)
+ output.sample(time, current_pose)
+
+See reset(), generate_next_segment(), and step() for how this demo does it.
+
+Choose SOMA or the Unitree G1 robot in the Character selector. SOMA uses BVH
+clips and G1 uses CSV clips. Both models use the same calls. Only their pose
+layouts differ.
+
+This demo uses clips to create target poses, but your app can create them in
+other ways.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import time
+
+import newton
+import numpy as np
+from pyglet.math import Vec3
+import warp as wp
+
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.model.config import DEFAULT_TOKEN_COUNTS, MotionBricksInferenceConfig
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE, ModelRig
+from motionbricks.renderers.foot_contact_renderer import FootContactRenderer
+from motionbricks.renderers.picking import raycast_line
+from motionbricks.renderers.vector_arrow_renderer import VectorArrowRenderer
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+from motionbricks.runtime.target_pose import MAX_TRANSITION_EARLY_BY_FRAMES
+
+from .authoring.common import (
+ InlineRename,
+ NewtonViewerUIBridge,
+ POSES_TO_USE_TOOLTIP,
+ accept_drop,
+ apply_transform_locks,
+ choose_clip,
+ drag_source,
+ draw_add_remove_buttons,
+ draw_character_selector,
+ draw_clip_scrubber,
+ draw_clip_selector,
+ draw_int_slider_property,
+ draw_token_range_property,
+ draw_transform_editor,
+ log_transform_gizmo,
+ transforms_equal,
+)
+from .runtime.common.rig import (
+ ASSETS_ROOT,
+ CHARACTER_COLORS,
+ create_foot_contact_renderer,
+ create_mesh_renderer,
+ create_skeleton_renderer,
+ load_rig_assets,
+)
+from .utils.cli import add_model_precision_argument, configure_logging, create_gl_parser
+from .utils.model_loading import create_engine, require_tensorrt
+from .utils.tooltips import show_delayed_tooltip
+
+
+_MOTION_ROOT = ASSETS_ROOT / "motions"
+_DEFAULT_CLIPS = {
+ ModelRig.SOMA: _MOTION_ROOT / "soma/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.bvh",
+ ModelRig.UNITREE_G1: _MOTION_ROOT / "unitree_g1/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.csv",
+}
+_START_COLOR = (0.2, 0.9, 0.4)
+_TARGET_COLOR = (0.25, 0.65, 1.0)
+_SELECTED_COLOR = (1.0, 0.5, 0.15)
+_ORDER_COLOR = (1.0, 0.8, 0.25)
+_GROUND_MARKER_HEIGHT = 0.05
+_PLAYBACK_MESH_ID = -1
+_POSE_PAYLOAD = "INBETWEENER_POSE"
+_RING_SEGMENTS = 48
+_RING_RADIUS = 0.3
+_MAX_FRAME_SECONDS = 0.1
+
+
+@dataclass(eq=False)
+class PoseEntry:
+ """Start or a target, sampled from a clip and placed in the view. Start comes first in the list."""
+
+ id: int
+ name: str
+ path: Path
+ clip: AnimationBuffer | DOFAnimationBuffer
+ sample_time: float
+ placement: wp.transform
+ min_tokens: int = DEFAULT_TOKEN_COUNTS[0]
+ max_tokens: int = DEFAULT_TOKEN_COUNTS[-1]
+ color: tuple[float, float, float] = _TARGET_COLOR
+ euler_degrees: list[float] | None = None
+ translation_locks: list[bool] = field(default_factory=lambda: [False, False, True])
+ rotation_locks: list[bool] = field(default_factory=lambda: [True, True, False])
+ show_frames: bool = False
+ num_poses_to_use: int = MODEL_POSES_PER_TOKEN
+ transition_early_by_frames: int = 0
+ show_mesh: bool = True
+ show_skeletons: bool = False
+ show_velocity: bool = False
+
+ # refresh_poses() samples these from the clip, sample time, and placement.
+ sampled_poses: wp.array = field(init=False, repr=False)
+ preview_pose: wp.array = field(init=False, repr=False)
+ root_position: np.ndarray = field(init=False, repr=False)
+ velocity: np.ndarray = field(init=False, repr=False)
+
+
+def sample_pose_window(
+ entry: PoseEntry,
+ model_to_runtime: wp.transform,
+ poses: wp.array,
+ *,
+ anchor: int,
+) -> None:
+ """Sample four poses at 30 Hz into the poses array.
+
+ anchor is the pose that sits at the entry's sample time: 3 for Start, whose
+ samples end there, or 0 for a target, whose samples begin there. The anchor's
+ root moves to the entry's placement and keeps its height. The other samples move
+ with it, so the motion between them stays the same. Only the root needs
+ coordinate conversion. SOMA child joints stay relative to their parents, and G1
+ joint angles do not change.
+ """
+ entry.clip.sample(entry.sample_time, poses[anchor], root_offset=model_to_runtime)
+ # Both pose layouts start with the root position, in world space.
+ root = poses[anchor].numpy().reshape(-1)
+ ground_offset = wp.transform(wp.vec3(-float(root[0]), -float(root[1]), 0.0), wp.quat_identity())
+ root_offset = wp.mul(entry.placement, wp.mul(ground_offset, model_to_runtime))
+ for frame in range(MODEL_POSES_PER_TOKEN):
+ sample_time = entry.sample_time + (frame - anchor) / MODEL_SAMPLE_RATE
+ entry.clip.sample(sample_time, poses[frame], root_offset=root_offset)
+
+
+class InbetweenerDemo:
+ """Place Start and targets, then play the motion generated through them."""
+
+ def __init__(self, viewer, rig: ModelRig, *, fp16: bool = False):
+ """Open the Inbetweener on a viewer with Start and one target.
+
+ fp16 selects the mixed FP16 models.
+ """
+ self.viewer = viewer
+ self.fp16 = fp16
+ self.engine = None
+ self._pending_clip: PoseEntry | None = None
+ self._pending_rig: ModelRig | None = None
+ self._rename = InlineRename()
+ self.error: str | None = None
+ self.show_foot_contacts = False
+ self.foot_contact_threshold = FootContactRenderer.DEFAULT_THRESHOLD
+ self._setup_viewer()
+ self.use_rig(rig)
+
+ def use_rig(self, rig: ModelRig) -> None:
+ """Switch to a rig and start over with Start, one target, and the default view.
+
+ The previous rig's engine closes before the new one loads, so only one engine
+ holds GPU memory.
+ """
+ if self.engine is not None:
+ # Finish the previous rig's work, remove its drawings, and release its engine.
+ self.engine.synchronize()
+ self.mesh_renderer.clear(self.viewer)
+ self.skeleton_renderer.clear(self.viewer)
+ self.velocity_renderer.clear(self.viewer)
+ self.foot_contact_renderer.clear(self.viewer)
+ self.engine.close()
+ self.engine = None
+ self.rig, self.engine = rig, create_engine(self.viewer, rig, self.fp16)
+ with wp.ScopedStream(self.engine.stream):
+ self._prepare_rig(rig)
+ camera = self.viewer.camera
+ camera.pos = Vec3(-7.0, -4.0, 3.5)
+ camera.look_at(np.array([0.0, -1.0, 1.0], dtype=np.float32))
+
+ def _prepare_rig(self, rig: ModelRig) -> None:
+ """Create the rig's buffers and renderers, then place Start and one target."""
+ engine = self.engine
+ assets = load_rig_assets(rig)
+ self.clip_registry = assets.clip_registry
+ self.model_to_runtime = assets.model_to_runtime
+
+ # Reuse the same context token, target token, and output buffer across all generations.
+ if rig is ModelRig.SOMA:
+ # A SOMA pose has one local transform per skeleton joint.
+ skeleton = assets.model.skeleton
+ self.context = engine.create_input(skeleton)
+ self.target = engine.create_input(skeleton)
+ self.output = engine.create_output(skeleton)
+ else:
+ # A G1 pose has the root position and XYZW rotation, then 29 joint angles.
+ self.context = engine.create_input()
+ self.target = engine.create_input()
+ self.output = engine.create_output()
+ self.mesh_renderer = create_mesh_renderer(rig, assets.model)
+ self.skeleton_renderer = create_skeleton_renderer(rig, assets.model, max_instances=MODEL_POSES_PER_TOKEN)
+ self.playback_color = CHARACTER_COLORS[rig]
+ self.foot_contact_renderer = create_foot_contact_renderer(rig, "generated_foot_contacts", assets.model)
+ self.foot_contacts = wp.empty(FOOT_CONTACT_COUNT, dtype=wp.float32, device=engine.device)
+ self.current_pose = wp.empty_like(assets.reference_pose)
+
+ path = _DEFAULT_CLIPS[rig]
+ clip = self.clip_registry.load(path).animation
+ duration = (clip.num_frames - 1) / clip.sample_rate
+ self.pose_entries = [
+ PoseEntry(
+ 0, "Start", path, clip, sample_time=min(1.0, duration),
+ placement=wp.transform_identity(), color=_START_COLOR,
+ ),
+ PoseEntry(
+ 1, "Target 1", path, clip, sample_time=min(7.0, duration),
+ placement=wp.transform(wp.vec3(0.0, -2.0, 0.0), wp.quat_identity()),
+ ),
+ ]
+ self.selected_index = 1
+ self._next_id = 2
+ self.refresh_poses()
+ self._last_frame_time = time.perf_counter()
+
+ def reset(self) -> None:
+ """Go back to Start and restore its four context poses."""
+ self.playing = False
+ self.has_segment = False
+ self.next_target_index = 1
+ self.playback_time = 0.0
+ self.segment_end_frame = 0
+ start = self.pose_entries[0]
+ self.context.update_from_poses(start.sampled_poses, stream=self.engine.stream)
+ wp.copy(self.current_pose, start.preview_pose, stream=self.engine.stream)
+
+ def play(self) -> None:
+ """Restart from Start and play through the targets. It needs at least one target."""
+ self.reset()
+ if len(self.pose_entries) > 1:
+ self.playing = True
+
+ def generate_next_segment(self) -> None:
+ """Generate from the current context toward the next placed target."""
+ entry = self.pose_entries[self.next_target_index]
+ self.target.update_from_poses(entry.sampled_poses[:entry.num_poses_to_use], stream=self.engine.stream)
+ self.engine.generate_animation(
+ context=self.context, target=self.target, output=self.output,
+ config=MotionBricksInferenceConfig(
+ allowed_token_counts=tuple(range(entry.min_tokens, entry.max_tokens + 1)),
+ ),
+ )
+
+ # Transition Early By skips frames at the end of the motion. At least four frames
+ # still play, because the next context is the last four played frames.
+ self.segment_end_frame = max(
+ MODEL_POSES_PER_TOKEN - 1, self.output.num_frames - 1 - entry.transition_early_by_frames,
+ )
+ self.playback_time = 0.0
+ self.has_segment = True
+ self.output.sample(0.0, self.current_pose, stream=self.engine.stream)
+ # Don't count generation time as playback time.
+ self._last_frame_time = time.perf_counter()
+
+ def step(self, delta_time: float) -> None:
+ """Advance playback by delta_time (in seconds).
+
+ A call with no segment ready generates one instead. At the transition point, the last
+ four played poses become the next context.
+ """
+ if not self.playing:
+ return
+ if not self.has_segment:
+ self.generate_next_segment()
+ return
+
+ end_time = self.segment_end_frame / MODEL_SAMPLE_RATE
+ self.playback_time = min(self.playback_time + delta_time, end_time)
+ self.output.sample(self.playback_time, self.current_pose, stream=self.engine.stream)
+ if self.playback_time < end_time:
+ return
+
+ played_frames = self.segment_end_frame + 1
+ recent_poses = self.output.poses[played_frames - MODEL_POSES_PER_TOKEN:played_frames]
+ self.context.update_from_poses(recent_poses, stream=self.engine.stream)
+ self.next_target_index += 1
+ self.has_segment = False
+ self.playing = self.next_target_index < len(self.pose_entries)
+
+ def refresh_poses(self) -> None:
+ """Resample Start and every target, update their previews, and return to Start."""
+ for index, entry in enumerate(self.pose_entries):
+ # Start shows its last context pose, and a target shows its first pose.
+ anchor = MODEL_POSES_PER_TOKEN - 1 if index == 0 else 0
+ entry.sampled_poses = wp.empty_like(self.context.poses)
+ sample_pose_window(entry, self.model_to_runtime, entry.sampled_poses, anchor=anchor)
+ entry.preview_pose = entry.sampled_poses[anchor]
+ # Both pose layouts start with the root position.
+ roots = entry.sampled_poses.numpy().reshape(MODEL_POSES_PER_TOKEN, -1)[:, :3]
+ entry.root_position = roots[anchor]
+ # Use motion leading into Start, or motion leaving a target, for its velocity.
+ pair = roots[-2:] if index == 0 else roots[:2]
+ entry.velocity = (pair[1] - pair[0]) * MODEL_SAMPLE_RATE
+ if entry.num_poses_to_use == 1:
+ entry.velocity[:] = 0.0
+ self._refresh_order_markers()
+ self.reset()
+
+ def add_target(self) -> None:
+ """Add a target after the last one.
+
+ It copies the clip and sample time of the selection.
+ """
+ source = self.pose_entries[self.selected_index]
+ previous = self.pose_entries[-1].placement
+ placement = wp.transform(previous.p + wp.vec3(0.0, -1.5, 0.0), previous.q)
+ self.pose_entries.append(PoseEntry(
+ self._next_id, f"Target {self._next_id}", source.path, source.clip,
+ source.sample_time, placement,
+ ))
+ self._next_id += 1
+ self.selected_index = len(self.pose_entries) - 1
+ self.refresh_poses()
+
+ def remove_target(self) -> None:
+ """Remove the selected target. Start cannot be removed."""
+ if self.selected_index == 0:
+ return
+ self.pose_entries.pop(self.selected_index)
+ self.mesh_renderer.clear(self.viewer)
+ self.skeleton_renderer.clear(self.viewer)
+ self.velocity_renderer.clear(self.viewer)
+ self._rename.item_id = None
+ self.selected_index = min(self.selected_index, len(self.pose_entries) - 1)
+ self.refresh_poses()
+
+ def move_target(self, source: int, destination: int) -> None:
+ """Move the target at index source to index destination. Start always stays first."""
+ if not 1 <= source < len(self.pose_entries) or not 1 <= destination < len(self.pose_entries):
+ return
+ if source == destination:
+ return
+ entry = self.pose_entries.pop(source)
+ self.pose_entries.insert(destination, entry)
+ self.selected_index = destination
+ self.refresh_poses()
+
+ def _choose_pending_clip(self) -> None:
+ entry = self._pending_clip
+ if entry is None:
+ return
+ self._pending_clip = None
+ try:
+ chosen = choose_clip(self.clip_registry, entry.path)
+ if chosen:
+ path = Path(chosen).resolve()
+ clip = self.clip_registry.load(path).animation
+ entry.path, entry.clip = path, clip
+ entry.sample_time = min(
+ (MODEL_POSES_PER_TOKEN - 1) / MODEL_SAMPLE_RATE,
+ (clip.num_frames - 1) / clip.sample_rate,
+ )
+ self.refresh_poses()
+ except Exception as exc:
+ self.playing = False
+ self.error = f"Open failed: {exc}"
+ finally:
+ self._last_frame_time = time.perf_counter()
+
+ def _switch_pending_rig(self) -> None:
+ rig, self._pending_rig = self._pending_rig, None
+ if rig is None:
+ return
+ try:
+ self.use_rig(rig)
+ except Exception as exc:
+ self.error = f"Character load failed: {exc}"
+
+ def _draw_pose_list(self, ui) -> None:
+ move = None
+ ui.begin_child("pose_list", ui.ImVec2(0, 160), child_flags=ui.ChildFlags_.borders)
+ for index, entry in enumerate(self.pose_entries):
+ if self._rename.item_id == entry.id:
+ if name := self._rename.draw(ui):
+ entry.name = name
+ continue
+ label = f"{entry.name}###pose_{entry.id}"
+ clicked, _ = ui.selectable(label, self.selected_index == index)
+ row_min, row_max = ui.get_item_rect_min(), ui.get_item_rect_max()
+ if clicked:
+ self.selected_index = index
+ if ui.is_item_hovered() and ui.is_mouse_double_clicked(0):
+ self.selected_index = index
+ self._rename.begin(entry.id, entry.name)
+ if index == 0:
+ continue
+ drag_source(ui, _POSE_PAYLOAD, entry.id, entry.name)
+ dropped_id = accept_drop(ui, _POSE_PAYLOAD)
+ if dropped_id is not None:
+ source = next(i for i, pose_entry in enumerate(self.pose_entries) if pose_entry.id == dropped_id)
+ insertion = index + int(ui.get_mouse_pos().y > (row_min.y + row_max.y) / 2)
+ move = source, insertion - int(source < insertion)
+ ui.end_child()
+ if move is not None:
+ self.move_target(*move)
+
+ def _draw_properties(self, ui, scale: float) -> None:
+ entry = self.pose_entries[self.selected_index]
+ ui.text_colored(ui.ImVec4(*entry.color, 1.0), entry.name)
+
+ if ui.collapsing_header("Transform", flags=ui.TreeNodeFlags_.default_open):
+ changed, transform, entry.euler_degrees = draw_transform_editor(
+ ui, entry.placement, entry.euler_degrees, scale,
+ entry.translation_locks, entry.rotation_locks,
+ )
+ if changed:
+ entry.placement = transform
+ self.refresh_poses()
+
+ if ui.collapsing_header("Target Pose", flags=ui.TreeNodeFlags_.default_open):
+ if draw_clip_selector(ui, entry.path.name, entry.path, entry.id):
+ self._pending_clip = entry
+ changed, sample_time, entry.show_frames = draw_clip_scrubber(
+ ui, entry.clip, entry.sample_time, entry.show_frames, scale,
+ )
+ if changed:
+ entry.sample_time = sample_time
+ self.refresh_poses()
+ ui.text_unformatted(f"Speed: {np.linalg.norm(entry.velocity):.3f} m/s")
+ ui.separator()
+ # Start supplies the model's four required context poses.
+ ui.begin_disabled(self.selected_index == 0)
+ num_poses = draw_int_slider_property(
+ ui, "Poses to Use", entry.num_poses_to_use, 1, MODEL_POSES_PER_TOKEN, entry.id,
+ tooltip=POSES_TO_USE_TOOLTIP,
+ )
+ early_frames = draw_int_slider_property(
+ ui, "Transition Early By (frames)", entry.transition_early_by_frames,
+ 0, MAX_TRANSITION_EARLY_BY_FRAMES, entry.id,
+ tooltip="Move on to the next target this many frames before the generated motion ends. "
+ "At least four frames still play.",
+ )
+ min_tokens, max_tokens = draw_token_range_property(ui, entry.min_tokens, entry.max_tokens, entry.id)
+ ui.end_disabled()
+ if (num_poses, early_frames, min_tokens, max_tokens) != (
+ entry.num_poses_to_use, entry.transition_early_by_frames, entry.min_tokens, entry.max_tokens,
+ ):
+ entry.num_poses_to_use, entry.transition_early_by_frames = num_poses, early_frames
+ entry.min_tokens, entry.max_tokens = min_tokens, max_tokens
+ self.refresh_poses()
+
+ if ui.collapsing_header("Visibility", flags=ui.TreeNodeFlags_.default_open):
+ changed, color = ui.color_edit3("Color", entry.color, ui.ColorEditFlags_.no_inputs)
+ if changed:
+ entry.color = tuple(color)
+ _, entry.show_mesh = ui.checkbox("Show Mesh", entry.show_mesh)
+ _, entry.show_skeletons = ui.checkbox("Show Skeleton(s)", entry.show_skeletons)
+ _, entry.show_velocity = ui.checkbox("Show Velocity", entry.show_velocity)
+
+ def gui(self, ui) -> None:
+ """Draw the Inbetweener window."""
+ viewport = ui.get_main_viewport()
+ scale = ui.get_font_size() / 13.0
+ ui.set_next_window_pos(
+ ui.ImVec2(viewport.pos.x + viewport.size.x - 12, viewport.pos.y + 12),
+ ui.Cond_.first_use_ever, pivot=ui.ImVec2(1, 0),
+ )
+ ui.set_next_window_size(
+ ui.ImVec2(440 * scale, min(740 * scale, viewport.size.y - 24)),
+ ui.Cond_.first_use_ever,
+ )
+ # Double-clicking the title bar collapses the window, as in the Newton viewer.
+ expanded, _ = ui.begin("Inbetweener")
+ if expanded:
+ footer_height = ui.get_frame_height_with_spacing() + ui.get_style().item_spacing.y
+ ui.begin_child("pose_settings", ui.ImVec2(0, -footer_height))
+ rig = draw_character_selector(ui, self.rig)
+ if rig is not self.rig:
+ self._pending_rig = rig
+ if ui.collapsing_header("Target Poses", flags=ui.TreeNodeFlags_.default_open):
+ self._draw_pose_list(ui)
+ add, remove = draw_add_remove_buttons(ui, self.selected_index != 0)
+ if add:
+ self.add_target()
+ if remove:
+ self.remove_target()
+ if ui.collapsing_header("Properties", flags=ui.TreeNodeFlags_.default_open):
+ ui.push_id(self.pose_entries[self.selected_index].id)
+ self._draw_properties(ui, scale)
+ ui.pop_id()
+
+ ui.end_child()
+ ui.separator()
+ ui.begin_disabled(len(self.pose_entries) < 2)
+ if ui.button("Generate"):
+ self.play()
+ ui.end_disabled()
+ ui.same_line()
+ _, self.show_foot_contacts = ui.checkbox("Show Foot Contacts", self.show_foot_contacts)
+ show_delayed_tooltip(ui, "Show outlines for foot contacts above the threshold on the right.")
+ ui.same_line()
+ ui.set_next_item_width(80 * scale)
+ ui.begin_disabled(not self.show_foot_contacts)
+ _, self.foot_contact_threshold = ui.slider_float(
+ "##FootContactThreshold", self.foot_contact_threshold, 0.0, 1.0, "%.2f",
+ flags=ui.SliderFlags_.always_clamp,
+ )
+ ui.end_disabled()
+ if self.error is not None:
+ ui.open_popup("Error")
+ if ui.begin_popup_modal("Error", flags=ui.WindowFlags_.always_auto_resize)[0]:
+ ui.text_unformatted(self.error or "")
+ if ui.button("OK"):
+ self.error = None
+ ui.close_current_popup()
+ ui.end_popup()
+ ui.end()
+
+ def _select_pose(self, origin: wp.vec3, direction: wp.vec3) -> None:
+ """Select the nearest pose whose mesh or ground ring is under the cursor."""
+ nearest = self.viewer.camera.far
+ ring_starts = self.ring_starts.numpy().reshape(len(self.pose_entries), -1, 3)
+ ring_ends = self.ring_ends.numpy().reshape(len(self.pose_entries), -1, 3)
+ for index, entry in enumerate(self.pose_entries):
+ distance = nearest
+ if entry.show_mesh:
+ distance = self.mesh_renderer.raycast_pose(
+ entry.preview_pose, wp.transform_identity(), origin, direction, distance,
+ )
+ for start, end in zip(ring_starts[index], ring_ends[index]):
+ distance = raycast_line(wp.vec3(*start), wp.vec3(*end), origin, direction, distance)
+ if distance < nearest:
+ nearest = distance
+ self.selected_index = index
+
+ def _setup_viewer(self) -> None:
+ viewer = self.viewer
+ self.skeleton_colors = wp.empty(MODEL_POSES_PER_TOKEN, dtype=wp.vec3)
+ self.velocity_renderer = VectorArrowRenderer("target_pose_velocity", wp.vec3(1.0, 0.0, 0.0))
+ builder = newton.ModelBuilder()
+ builder.add_ground_plane()
+ ground_model = builder.finalize()
+ self.state = ground_model.state()
+ viewer.set_model(ground_model)
+ viewer.renderer.set_title("MotionBricks - Inbetweener")
+ self._viewer_ui = NewtonViewerUIBridge(viewer)
+ if viewer.ui is not None:
+ self._viewer_ui.install(viewer.ui.imgui)
+ self._viewer_ui.on_scene_click = self._select_pose
+ viewer.register_ui_callback(self.gui, position="free")
+
+ def _refresh_order_markers(self) -> None:
+ """Build ground circles and connections in the same order as the pose list."""
+ centers = np.array([entry.root_position for entry in self.pose_entries])
+ centers[:, 2] = _GROUND_MARKER_HEIGHT
+ angles = np.linspace(0, 2 * np.pi, _RING_SEGMENTS + 1)
+ circle = _RING_RADIUS * np.column_stack((np.cos(angles), np.sin(angles), np.zeros(_RING_SEGMENTS + 1)))
+ rings = centers[:, None, :] + circle[None, :, :]
+ self.ring_starts = wp.array(rings[:, :-1].reshape(-1, 3), dtype=wp.vec3)
+ self.ring_ends = wp.array(rings[:, 1:].reshape(-1, 3), dtype=wp.vec3)
+ self.ring_colors = wp.empty(len(self.pose_entries) * _RING_SEGMENTS, dtype=wp.vec3)
+ self.order_starts = wp.array(centers[:-1], dtype=wp.vec3)
+ self.order_ends = wp.array(centers[1:], dtype=wp.vec3)
+ self.order_colors = wp.array([_ORDER_COLOR] * (len(self.pose_entries) - 1), dtype=wp.vec3)
+
+ def _draw_target_previews(self) -> None:
+ for entry in self.pose_entries:
+ if entry.show_mesh:
+ self.mesh_renderer.draw_pose(
+ self.viewer, entry.preview_pose, wp.transform_identity(),
+ wp.vec3(*entry.color), entry.id,
+ )
+ else:
+ self.mesh_renderer.hide(self.viewer, entry.id)
+ if entry.show_skeletons:
+ self.skeleton_colors.fill_(wp.vec3(*entry.color))
+ self.skeleton_renderer.draw_batch(
+ self.viewer, entry.sampled_poses, entry.num_poses_to_use, wp.transform_identity(),
+ self.skeleton_colors, entry.id,
+ )
+ else:
+ self.skeleton_renderer.hide(self.viewer, entry.id)
+ if entry.show_velocity and np.linalg.norm(entry.velocity) > 1e-6:
+ self.velocity_renderer.draw(
+ self.viewer, entry.id, wp.transform_identity(),
+ wp.vec3(*entry.root_position), wp.vec3(*entry.velocity),
+ )
+ else:
+ self.velocity_renderer.hide(self.viewer, entry.id)
+
+ def _draw_generated_pose(self) -> None:
+ # Hide the playback mesh only when a visible target preview already shows its pose.
+ # Time is also zero at each new segment, so it does not always mean playback is at Start.
+ target_index = self.next_target_index
+ if not self.has_segment:
+ target_index -= 1
+ endpoint_visible = self.pose_entries[target_index].show_mesh
+ at_endpoint = self.playback_time >= self.output.duration
+ previous_entry = self.pose_entries[self.next_target_index - 1]
+ at_visible_start = (
+ self.playback_time == 0.0
+ and previous_entry.show_mesh and previous_entry.transition_early_by_frames == 0
+ )
+ has_playback = self.has_segment or self.next_target_index > 1
+ if has_playback and not at_visible_start and not (at_endpoint and endpoint_visible):
+ self.mesh_renderer.draw_pose(
+ self.viewer, self.current_pose, wp.transform_identity(),
+ self.playback_color, _PLAYBACK_MESH_ID,
+ )
+ else:
+ self.mesh_renderer.hide(self.viewer, _PLAYBACK_MESH_ID)
+
+ def _draw_foot_contacts(self) -> None:
+ """Show foot contacts for generated motion, including its final pose."""
+ if (
+ not self.show_foot_contacts or self.output.num_frames == 0
+ or not (self.has_segment or self.next_target_index > 1)
+ ):
+ self.foot_contact_renderer.hide(self.viewer)
+ return
+ self.output.sample_foot_contacts(self.playback_time, self.foot_contacts, stream=self.engine.stream)
+ # The renderer places the outlines itself, because the playback mesh can be hidden at a target.
+ self.foot_contact_renderer.threshold = self.foot_contact_threshold
+ self.foot_contact_renderer.draw_pose(self.viewer, self.current_pose, self.foot_contacts)
+
+ def render(self) -> None:
+ """Draw one frame, then apply any gizmo edit to the selection."""
+ entry = self.pose_entries[self.selected_index]
+ gizmo = wp.transform(entry.placement)
+ before = wp.transform(gizmo)
+ colors = [
+ _SELECTED_COLOR if index == self.selected_index else pose_entry.color
+ for index, pose_entry in enumerate(self.pose_entries)
+ ]
+ self.ring_colors.assign(np.repeat(colors, _RING_SEGMENTS, axis=0))
+ self.viewer.begin_frame(self.playback_time)
+ self._draw_target_previews()
+ self._draw_generated_pose()
+ self._draw_foot_contacts()
+ self.viewer.log_lines("pose_rings", self.ring_starts, self.ring_ends, self.ring_colors)
+ if len(self.pose_entries) > 1:
+ self.viewer.log_arrows("pose_order", self.order_starts, self.order_ends, self.order_colors)
+ else:
+ self.viewer.log_arrows("pose_order", None, None, None)
+ log_transform_gizmo(
+ self.viewer, "pose_placement", gizmo,
+ translation_locks=entry.translation_locks, rotation_locks=entry.rotation_locks,
+ )
+ self.viewer.log_state(self.state)
+ self.viewer.end_frame()
+ # The UI runs in end_frame(), so selection or placement may have changed.
+ if self.pose_entries[self.selected_index] is entry and not transforms_equal(gizmo, before):
+ entry.placement, entry.euler_degrees = apply_transform_locks(
+ entry.placement, gizmo, entry.euler_degrees,
+ entry.translation_locks, entry.rotation_locks,
+ )
+ self.refresh_poses()
+
+ def run(self, max_frames: int | None = None) -> None:
+ """Play and draw frames until the window closes or max_frames is reached."""
+ frame = 0
+ try:
+ while self.viewer.is_running() and (max_frames is None or frame < max_frames):
+ # A switch can build an engine, so it runs before choosing this frame's stream.
+ self._switch_pending_rig()
+ with wp.ScopedStream(self.engine.stream):
+ self._choose_pending_clip()
+ now = time.perf_counter()
+ delta_time = min(max(now - self._last_frame_time, 0.0), _MAX_FRAME_SECONDS)
+ self._last_frame_time = now
+ try:
+ self.step(delta_time)
+ except Exception as exc:
+ self.playing = False
+ self.error = f"Generation failed: {exc}"
+ self.render()
+ frame += 1
+ finally:
+ if self.engine is not None:
+ self.engine.close()
+ self.viewer.close()
+
+
+def main() -> None:
+ """Parse the command line and open the Inbetweener."""
+ import newton.examples
+
+ parser = create_gl_parser()
+ parser.add_argument(
+ "--model",
+ type=ModelRig,
+ choices=list(ModelRig),
+ default=ModelRig.SOMA,
+ help="Character to start with.",
+ )
+ add_model_precision_argument(parser)
+ viewer, args = newton.examples.init(parser)
+ configure_logging(args)
+ try:
+ require_tensorrt()
+ demo = InbetweenerDemo(viewer, args.model, fp16=args.model_precision == "fp16")
+ demo.run(args.num_frames if args.test else None)
+ finally:
+ if viewer.is_running():
+ viewer.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/app/runtime/common/__init__.py b/app/runtime/common/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/app/runtime/common/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/app/runtime/common/character.py b/app/runtime/common/character.py
new file mode 100644
index 0000000..292c537
--- /dev/null
+++ b/app/runtime/common/character.py
@@ -0,0 +1,417 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Play generated motion and clips for a character, and keep recent poses for the next generation."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+import math
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE
+from motionbricks.runtime.smart_primitive import InteractionBox
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+from motionbricks.utils.pose_utils import sample_root_position
+
+from .interaction import InteractionProbe
+from .motion import (
+ CLIP_FACING_YAW,
+ AnimationClip,
+ LocomotionCommand,
+ LocomotionMode,
+ MovementControl,
+ PlaybackSource,
+ character_start_position_and_facing,
+ load_locomotion_mode,
+ ground_direction,
+ make_animation_clip,
+)
+from .state_machine import StateMachine
+
+if TYPE_CHECKING:
+ from motionbricks.runtime.target_pose import TargetPoseIKCorrector
+
+ from .io.smart_primitive_document import SmartPrimitiveAssetPool
+ from .target_pose_blender import BaseTargetPoseBlender
+
+
+_CLIP_TRANSITION_INFERENCE_PARAMS = TargetPoseInferenceParams(
+ transition_early_by_frames=0,
+ num_poses_to_use=MODEL_POSES_PER_TOKEN,
+)
+
+# Target pose IK fades in from this fraction of a generated segment until its transition point.
+_TARGET_POSE_IK_BLEND_START_FRACTION = 0.5
+
+
+def _root_transform(pose: wp.array) -> wp.transform:
+ """Read the root of a pose of local joint transforms or joint coordinates."""
+ # Both layouts start with the root: position (XYZ), then rotation (XYZW).
+ values = pose.numpy().reshape(-1)
+ return wp.transform(*values[:7])
+
+
+class BaseCharacter(ABC):
+ """Animate a character with generated motion and clips through its own state machine.
+
+ Each rig subclass supplies its motion player and target pose blender. It also sets
+ root_forward_axis. Its constructor passes its presets as defaults. A rig with target
+ pose IK also supplies an IK corrector.
+ """
+
+ root_forward_axis: wp.vec3
+ target_pose_blender: BaseTargetPoseBlender
+
+ def __init__(
+ self,
+ engine,
+ *,
+ asset_pool: SmartPrimitiveAssetPool,
+ initial_transform: wp.transform,
+ modes: tuple[LocomotionMode, ...],
+ initial_mode: str,
+ idle_paths: tuple[str | Path, ...],
+ crouch_idle_paths: tuple[str | Path, ...],
+ interaction_probe: InteractionProbe,
+ target_pose_ik_corrector: TargetPoseIKCorrector | None = None,
+ current_pose: wp.array | None = None,
+ ) -> None:
+ """Start the character in an idle clip at initial_transform.
+
+ Args:
+ engine: Engine that generates the character's motion.
+ asset_pool: Clips and Smart Primitive assets of the rig.
+ initial_transform: Where the character starts, from the scene's CharacterStart.
+ modes: Locomotion modes, standing and crouching.
+ initial_mode: Name of the mode the character starts in.
+ idle_paths: Standing idle clips.
+ crouch_idle_paths: Crouching idle clips.
+ interaction_probe: Size and reach of the probe box.
+ target_pose_ik_corrector: Target pose IK for pinned hands and feet. None
+ applies no IK.
+ current_pose: Pose buffer the character plays into, such as one robot's
+ view of a Newton joint_q. None creates a copy of the reference pose.
+ """
+ self.engine = engine
+ self.asset_pool = asset_pool
+ self.clip_registry = asset_pool.clip_registry
+ self.model_to_runtime = asset_pool.model_to_runtime
+ self.interaction_probe = interaction_probe
+
+ self._current_clip: AnimationClip | None = None
+ self._playback_source = PlaybackSource.GENERATED
+ self._clip_playback_time = 0.0
+ self._clip_loop = False
+
+ initial_position, initial_facing = character_start_position_and_facing(
+ initial_transform
+ )
+ self.movement = MovementControl(initial_facing)
+ self.character_ground_position = initial_position
+ self.actual_velocity = np.zeros(3, dtype=np.float32)
+
+ # The pose we display and record, including any IK adjustments.
+ self.current_pose = wp.clone(asset_pool.reference_pose) if current_pose is None else current_pose
+ # These stay at 0 while a clip plays.
+ self.current_foot_contacts = wp.zeros(FOOT_CONTACT_COUNT, dtype=wp.float32, device=engine.device)
+ self.player = self._create_player()
+ self._target_pose_ik_corrector = target_pose_ik_corrector
+ self._clip_target_poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, *self.current_pose.shape),
+ dtype=self.current_pose.dtype,
+ device=engine.device,
+ )
+ self.probe_box = wp.empty(
+ 1,
+ dtype=InteractionBox,
+ device=engine.device,
+ )
+ self.state_machine = StateMachine(
+ tuple(load_locomotion_mode(mode, asset_pool) for mode in modes),
+ initial_mode,
+ standing_idle_clips=tuple(self.load_clip(path, loop=True) for path in idle_paths),
+ crouching_idle_clips=tuple(self.load_clip(path, loop=True) for path in crouch_idle_paths),
+ pose=self.current_pose,
+ )
+ self.state_machine.start(self)
+ self._update_probe_box()
+
+ def load_clip(self, path: Path, *, loop: bool) -> AnimationClip:
+ """Load a clip from the registry. A looping clip gets its own copy with its ends joined."""
+ animation = self.clip_registry.load_looping(path) if loop else self.clip_registry.load(path).animation
+ return make_animation_clip(animation, self.model_to_runtime)
+
+ @abstractmethod
+ def _create_player(self):
+ """Return this rig's motion player, which samples generated motion into current_pose."""
+
+ @property
+ def current_clip(self) -> AnimationClip | None:
+ """Latest clip that played or that a clip transition leads into."""
+ return self._current_clip
+
+ @property
+ def probe_segment(self) -> tuple[np.ndarray, np.ndarray]:
+ """The near and far ends of the character's probe box on the ground."""
+ return self.interaction_probe.segment(
+ self.character_ground_position,
+ self.movement.desired_velocity_direction,
+ float(np.linalg.norm(self.movement.desired_velocity[:2])),
+ )
+
+ def clear_ik_pins(self) -> None:
+ """Stop applying the current target's hand and foot pins."""
+
+ if self._target_pose_ik_corrector is not None:
+ self._target_pose_ik_corrector.clear_pins()
+
+ def clip_transition_ends_within(self, delta_time: float) -> bool:
+ """Return whether a clip transition reaches its transition point within delta_time (in seconds)."""
+ return (
+ self._playback_source is PlaybackSource.CLIP_TRANSITION
+ and self.time_to_transition() <= delta_time
+ )
+
+ def clip_ends_within(self, delta_time: float) -> bool:
+ """Return whether the current clip ends within delta_time. Looping clips never end."""
+ return (
+ self._playback_source is PlaybackSource.CLIP
+ and not self._clip_loop
+ and self._clip_playback_time + delta_time >= self._current_clip.duration
+ )
+
+ def time_to_transition(self) -> float:
+ """Return the seconds left until the transition point. Clip playback returns 0."""
+
+ if self._playback_source is PlaybackSource.CLIP:
+ return 0.0
+ return self.player.time_to_transition
+
+ def step(self, delta_time: float, command: LocomotionCommand) -> None:
+ """Advance the state machine and playback by delta_time (in seconds).
+
+ The pose that is shown is then recorded for the next generation.
+ """
+ self.state_machine.update(self, delta_time, command)
+ previous_ground_position = self.character_ground_position.copy()
+ self._sample_playback(delta_time)
+ self._update_character_velocity(previous_ground_position, delta_time)
+ self.player.record_pose(delta_time, self.current_pose)
+ self._update_probe_box()
+
+ def _update_probe_box(self) -> None:
+ self.interaction_probe.write_box(
+ self.probe_segment,
+ self.state_machine.probe_box_height_scale,
+ self.probe_box,
+ self.engine.stream,
+ )
+
+ def _sample_playback(self, delta_time: float) -> None:
+ """Advance playback by the full frame time and sample the resulting pose."""
+ if self._playback_source is PlaybackSource.CLIP:
+ clip = self._current_clip
+ self._clip_playback_time += delta_time
+ if self._clip_loop:
+ self._clip_playback_time %= clip.duration
+ clip.animation.sample(
+ self._clip_playback_time,
+ self.current_pose,
+ root_offset=clip.root_offset,
+ stream=self.engine.stream,
+ )
+ else:
+ self.player.sample(delta_time, self.current_pose, self.current_foot_contacts)
+ self._apply_target_pose_ik()
+ self._update_character_position()
+
+ def generate_to_target_poses(
+ self,
+ target_poses: wp.array,
+ inference_params: TargetPoseInferenceParams,
+ playback_source: PlaybackSource = PlaybackSource.GENERATED,
+ ) -> None:
+ """Generate from recent motion toward target poses placed in the scene.
+
+ Target pose IK pins the hands and feet in the target's ik_pin_mask to its
+ first pose. Other targets clear the pins. playback_source is CLIP_TRANSITION
+ when the motion leads into a clip.
+ """
+ if self._target_pose_ik_corrector is not None:
+ self._target_pose_ik_corrector.capture_pins(
+ target_poses[0],
+ inference_params.ik_pin_mask,
+ stream=self.engine.stream,
+ )
+ self.player.generate(
+ target_poses,
+ inference_params,
+ )
+ self._playback_source = playback_source
+ self.player.sample(0.0, self.current_pose, self.current_foot_contacts)
+ self._apply_target_pose_ik()
+ self._update_character_position()
+
+ def generate_clip_transition(
+ self,
+ clip: AnimationClip,
+ ) -> None:
+ """Place a clip ahead of the character and generate motion to its first frame."""
+
+ self._current_clip = clip
+ clip_ground_position = self.character_ground_position + self.actual_velocity
+ self._align_clip(
+ clip,
+ clip_ground_position,
+ self.movement.last_input_facing,
+ )
+ for frame in range(MODEL_POSES_PER_TOKEN):
+ clip.animation.sample(
+ frame / MODEL_SAMPLE_RATE,
+ self._clip_target_poses[frame],
+ root_offset=clip.root_offset,
+ stream=self.engine.stream,
+ )
+ self.generate_to_target_poses(
+ self._clip_target_poses,
+ _CLIP_TRANSITION_INFERENCE_PARAMS,
+ PlaybackSource.CLIP_TRANSITION,
+ )
+
+ def _target_pose_ik_weight(self) -> float:
+ playback_duration = self.player.playback_duration
+ if playback_duration <= 0.0:
+ return 1.0
+
+ progress = 1.0 - self.time_to_transition() / playback_duration
+ return wp.smoothstep(_TARGET_POSE_IK_BLEND_START_FRACTION, 1.0, progress)
+
+ def _apply_target_pose_ik(self) -> None:
+ # The corrector does nothing while the current target pins no hands or feet.
+ if self._target_pose_ik_corrector is None:
+ return
+
+ self._target_pose_ik_corrector.apply(
+ self.current_pose,
+ self._target_pose_ik_weight(),
+ stream=self.engine.stream,
+ )
+
+ def _align_clip(
+ self,
+ clip: AnimationClip,
+ ground_position: np.ndarray,
+ facing_direction: np.ndarray,
+ ) -> None:
+ # Turn the clip from the direction clips start facing to the requested facing.
+ yaw = math.atan2(facing_direction[1], facing_direction[0]) - CLIP_FACING_YAW
+ facing_rotation = wp.quat_from_axis_angle(
+ wp.vec3(0.0, 0.0, 1.0),
+ yaw,
+ )
+ target_ground = wp.transform(
+ wp.vec3(
+ float(ground_position[0]),
+ float(ground_position[1]),
+ 0.0,
+ ),
+ wp.mul(facing_rotation, clip.source_ground.q),
+ )
+ alignment = wp.mul(
+ target_ground,
+ wp.transform_inverse(clip.source_ground),
+ )
+ clip.root_offset = wp.mul(alignment, self.model_to_runtime)
+
+ def start_clip(
+ self,
+ clip: AnimationClip,
+ *,
+ loop: bool = False,
+ align_to_current_pose: bool = False,
+ ) -> None:
+ """Play a clip, optionally looping it or aligning its first root with the current root.
+
+ The motion history is kept for the next generation. Aligning the roots also
+ converts source coordinates to world space.
+ """
+
+ if align_to_current_pose:
+ first_pose = wp.empty_like(self.current_pose)
+ clip.animation.sample(0.0, first_pose, stream=self.engine.stream)
+ clip.root_offset = wp.mul(
+ _root_transform(self.current_pose),
+ wp.transform_inverse(_root_transform(first_pose)),
+ )
+ self._current_clip = clip
+ self._clip_playback_time = 0.0
+ self._clip_loop = loop
+ self._playback_source = PlaybackSource.CLIP
+ clip.animation.sample(
+ self._clip_playback_time,
+ self.current_pose,
+ root_offset=clip.root_offset,
+ stream=self.engine.stream,
+ )
+ self.current_foot_contacts.zero_()
+ self._update_character_position()
+
+ def initialize_clip_loop(
+ self,
+ clip: AnimationClip,
+ ) -> None:
+ """Start in an idle clip and fill the player's history with the starting pose."""
+
+ self._align_clip(
+ clip,
+ self.character_ground_position,
+ self.movement.last_input_facing,
+ )
+ self.start_clip(clip, loop=True)
+ self.player.seed_history_from_pose(self.current_pose)
+
+ def pose_facing(self) -> np.ndarray:
+ """Return the current pose's heading, from its root rotation."""
+
+ forward = wp.transform_vector(_root_transform(self.current_pose), self.root_forward_axis)
+ return ground_direction(
+ np.array([forward[0], forward[1], 0.0], dtype=np.float32), self.movement.current_facing,
+ )
+
+ def face_pose(self) -> None:
+ """Set every facing to the current pose's heading."""
+ self.movement.face(self.pose_facing())
+
+ def _update_character_velocity(
+ self,
+ previous_ground_position: np.ndarray,
+ delta_time: float,
+ ) -> None:
+ np.subtract(
+ self.character_ground_position,
+ previous_ground_position,
+ out=self.actual_velocity,
+ )
+ self.actual_velocity /= delta_time
+ self.actual_velocity[2] = 0.0
+
+ def _update_character_position(self) -> None:
+ if self._playback_source is PlaybackSource.CLIP:
+ clip = self._current_clip
+ position = sample_root_position(
+ clip.root_positions, self._clip_playback_time,
+ clip.animation.sample_rate, clip.root_offset,
+ )
+ else:
+ position = self.player.current_root_position()
+ self.character_ground_position[:] = position
+ self.character_ground_position[2] = 0.0
+
+
+__all__ = ["BaseCharacter"]
diff --git a/app/runtime/common/clip_registry.py b/app/runtime/common/clip_registry.py
new file mode 100644
index 0000000..799e237
--- /dev/null
+++ b/app/runtime/common/clip_registry.py
@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Load each clip once and share it."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import warp as wp
+
+import motionbricks.io.bvh as bvh_utils
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.csv import load_csv
+from motionbricks.model.contract import ModelRig
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+
+@dataclass(frozen=True)
+class ClipAsset:
+ """A source clip shared by target poses and playback. Its poses must not change."""
+
+ path: Path
+ animation: AnimationBuffer | DOFAnimationBuffer
+
+ @property
+ def name(self) -> str:
+ """Clip name, from its file name without the suffix."""
+ return self.path.stem
+
+ @property
+ def last_frame(self) -> int:
+ """Index of the clip's last frame."""
+ return self.animation.num_frames - 1
+
+ @property
+ def duration(self) -> float:
+ """Clip duration in seconds."""
+ return self.animation.duration
+
+
+class ClipLoadError(RuntimeError):
+ """Raised when a clip cannot be loaded for the registry's rig."""
+
+
+class ClipRegistry:
+ """Load each clip file once for one rig.
+
+ BVH clips are remapped to ``skeleton``. CSV clips must match ``joint_names``.
+ All clips use the registry's device. Edits such as loop correction go in
+ separate buffers.
+ """
+
+ def __init__(
+ self, rig: ModelRig, *, skeleton: Skeleton | None = None,
+ joint_names: tuple[str, ...] = (), device=None,
+ ) -> None:
+ """Create a registry for one rig's clips.
+
+ Args:
+ rig: Rig of the clips.
+ skeleton: Skeleton that SOMA clips are remapped to. SOMA requires it. Its
+ device holds the clips.
+ joint_names: Joint order that G1 clips must match. G1 requires it.
+ device: Device for G1 clips. None uses the current device. SOMA ignores it.
+ """
+ self.rig = ModelRig(rig)
+ if self.rig is ModelRig.SOMA:
+ if skeleton is None or joint_names:
+ raise ValueError("SOMA clips need a skeleton, without joint_names.")
+ self.suffix = ".bvh"
+ self.device = skeleton.reference_local_transforms.device
+ else:
+ if skeleton is not None or not joint_names:
+ raise ValueError("Unitree G1 clips need joint_names, without a skeleton.")
+ self.suffix = ".csv"
+ self.device = wp.get_device(device)
+ self.skeleton = skeleton
+ self.joint_names = tuple(joint_names)
+ self._clips: dict[Path, ClipAsset] = {}
+
+ def load(self, path: str | Path) -> ClipAsset:
+ """Return the clip at path, loading it on first use.
+
+ Failures raise ClipLoadError.
+ """
+ path = Path(path).expanduser().resolve()
+ if path.suffix.lower() != self.suffix:
+ raise ClipLoadError(f"This registry loads {self.suffix} clips: {path}.")
+ clip = self._clips.get(path)
+ if clip is None:
+ if not path.is_file():
+ raise ClipLoadError(f"Could not find clip: {path}.")
+ try:
+ with wp.ScopedDevice(self.device):
+ if self.rig is ModelRig.SOMA:
+ animation = bvh_utils.load_bvh(path, self.skeleton)
+ else:
+ animation = load_csv(path, device=self.device)
+ if animation.joint_names != self.joint_names:
+ raise ValueError("CSV joint order must match the G1 model's joint order.")
+ except (KeyError, OSError, RuntimeError, ValueError) as exc:
+ raise ClipLoadError(f"Could not load clip {path}: {exc}") from exc
+ clip = ClipAsset(path, animation)
+ self._clips[path] = clip
+ return clip
+
+ def load_looping(self, path: str | Path) -> AnimationBuffer | DOFAnimationBuffer:
+ """Return a copy of the clip at path whose last frame joins its first.
+
+ Each call returns a new copy, so the shared clip keeps its poses. Failures raise
+ ClipLoadError.
+ """
+ looping = self.load(path).animation.copy()
+ looping.make_loopable()
+ return looping
diff --git a/app/runtime/common/interaction.py b/app/runtime/common/interaction.py
new file mode 100644
index 0000000..a6e95a0
--- /dev/null
+++ b/app/runtime/common/interaction.py
@@ -0,0 +1,100 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Place the probe box ahead of a character to find Smart Primitive interaction boxes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import warp as wp
+
+from motionbricks.runtime.smart_primitive import InteractionBox
+
+
+def _write_interaction_box_kernel(
+ segment_start: wp.vec3,
+ segment_end: wp.vec3,
+ width: wp.float32,
+ height: wp.float32,
+ output_box: wp.array(dtype=InteractionBox),
+):
+ direction = segment_end - segment_start
+ depth = wp.length(direction)
+ center = 0.5 * (segment_start + segment_end)
+ center.z = 0.5 * height
+
+ # The box's local X is its width, Y its depth, and Z its height.
+ yaw = wp.atan2(direction.y, direction.x) - 0.5 * wp.pi
+ box = InteractionBox()
+ box.transform = wp.transform(
+ center,
+ wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), yaw),
+ )
+ box.half_extents = 0.5 * wp.vec3(width, depth, height)
+ output_box[0] = box
+
+
+@dataclass(frozen=True, slots=True)
+class InteractionProbe:
+ """How far ahead a character looks for Smart Primitive interaction boxes.
+
+ Attributes:
+ box_width: Width of the probe box in meters.
+ box_min_depth: Smallest depth of the box in meters.
+ box_height: Height of the box in meters while standing.
+ near_distance: Distance from the character to the near end of the box, in meters.
+ lookahead_time: Seconds of travel at the desired speed that the box reaches.
+ extra_lookahead_min_speed: Speed in m/s above which the box reaches further.
+ extra_lookahead_time: Extra seconds of travel for the speed above
+ extra_lookahead_min_speed.
+ """
+
+ box_width: float
+ box_min_depth: float
+ box_height: float
+ near_distance: float
+ lookahead_time: float
+ extra_lookahead_min_speed: float
+ extra_lookahead_time: float
+
+ def segment(
+ self,
+ ground_position: np.ndarray,
+ direction: np.ndarray,
+ speed: float,
+ ) -> tuple[np.ndarray, np.ndarray]:
+ """Return the near and far ends of the probe on the ground."""
+ reach = speed * self.lookahead_time
+ reach += max(0.0, speed - self.extra_lookahead_min_speed) * self.extra_lookahead_time
+ far = max(self.near_distance + self.box_min_depth, reach)
+ return (
+ ground_position + direction * self.near_distance,
+ ground_position + direction * far,
+ )
+
+ def write_box(
+ self,
+ segment: tuple[np.ndarray, np.ndarray],
+ height_scale: float,
+ output_box: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Write the box that covers the segment, standing on the ground."""
+ wp.launch(
+ _write_interaction_box_kernel,
+ dim=1,
+ inputs=[
+ wp.vec3(*segment[0]),
+ wp.vec3(*segment[1]),
+ self.box_width,
+ self.box_height * height_scale,
+ ],
+ outputs=[output_box],
+ stream=stream,
+ )
+
+
+__all__ = ["InteractionProbe"]
diff --git a/app/runtime/common/io/__init__.py b/app/runtime/common/io/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/app/runtime/common/io/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/app/runtime/common/io/document_io.py b/app/runtime/common/io/document_io.py
new file mode 100644
index 0000000..f11a69f
--- /dev/null
+++ b/app/runtime/common/io/document_io.py
@@ -0,0 +1,372 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""File handling and JSON validation for shared application documents."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+import json
+import math
+import os
+from pathlib import Path
+import uuid
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import ModelRig
+
+
+_CAMERA_FIELDS = ("pos", "pivot", "pitch", "yaw", "fov", "near", "far")
+_HEADER_FIELDS = ("format", "schema_version", "name", "rig", "editor")
+TRANSFORM_FIELDS = ("translation", "rotation_xyzw")
+
+
+class DocumentError(ValueError):
+ """Raised for invalid document data or failed file operations."""
+
+
+def integer(value, location: str, minimum: int | None = None, maximum: int | None = None) -> int:
+ """Return value as an integer within the given limits, or raise DocumentError."""
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise DocumentError(f"{location} must be an integer.")
+ if minimum is not None and value < minimum:
+ raise DocumentError(f"{location} must be at least {minimum}.")
+ if maximum is not None and value > maximum:
+ raise DocumentError(f"{location} must be at most {maximum}.")
+ return value
+
+
+def number(value, location: str) -> float:
+ """Return value as a finite float, or raise DocumentError."""
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+ raise DocumentError(f"{location} must be a finite number.")
+ return float(value)
+
+
+def number_vector(value, size: int, location: str) -> list[float]:
+ """Return value as a list of size finite floats, or raise DocumentError."""
+ if not isinstance(value, (list, tuple)) or len(value) != size:
+ raise DocumentError(f"{location} must be an array of {size} numbers.")
+ return [number(item, f"{location}[{index}]") for index, item in enumerate(value)]
+
+
+def string(value, location: str, *, allow_empty: bool = False) -> str:
+ """Return value as a string, or raise DocumentError.
+
+ It must be non-empty unless allow_empty is set.
+ """
+ if not isinstance(value, str) or (not allow_empty and not value.strip()):
+ kind = "string" if allow_empty else "non-empty string"
+ raise DocumentError(f"{location} must be a {kind}.")
+ return value
+
+
+def _boolean(value, location: str) -> bool:
+ if not isinstance(value, bool):
+ raise DocumentError(f"{location} must be a boolean.")
+ return value
+
+
+def _color(value, location: str) -> list[float]:
+ values = number_vector(value, 3, location)
+ if any(not 0.0 <= channel <= 1.0 for channel in values):
+ raise DocumentError(f"{location} values must be 0 to 1.")
+ return values
+
+
+def serialize_color(color: wp.vec3, location: str) -> list[float]:
+ """Return an RGB color as JSON values, or raise DocumentError when a channel is outside 0 to 1."""
+ return _color(list(color), location)
+
+
+class DocumentObject:
+ """Read JSON fields, with errors that point to the invalid field."""
+
+ def __init__(self, value, location: str, fields) -> None:
+ """Check that a JSON object holds exactly the given fields."""
+ if not isinstance(value, dict):
+ raise DocumentError(f"{location} must be an object.")
+ for field in fields:
+ if field not in value:
+ raise DocumentError(f"Missing {location}.{field}.")
+ unexpected = sorted(set(value) - set(fields))
+ if unexpected:
+ names = ", ".join(repr(field) for field in unexpected)
+ raise DocumentError(f"Unexpected fields in {location}: {names}.")
+ self._data = value
+ self.location = location
+
+ def field_location(self, field: str) -> str:
+ """Return the location of a field, for error messages."""
+ return f"{self.location}.{field}"
+
+ def value(self, field: str):
+ """Return a field's value as stored."""
+ return self._data[field]
+
+ def object(self, field: str, fields) -> DocumentObject:
+ """Return a field as a DocumentObject with the given fields."""
+ return DocumentObject(self.value(field), self.field_location(field), fields)
+
+ def array(self, field: str) -> list:
+ """Return a field as a list, or raise DocumentError."""
+ value = self.value(field)
+ if not isinstance(value, list):
+ raise DocumentError(f"{self.field_location(field)} must be an array.")
+ return value
+
+ def object_array(self, field: str, fields) -> list[DocumentObject]:
+ """Return a field as a list of DocumentObject values with the given fields."""
+ return [
+ DocumentObject(value, f"{self.field_location(field)}[{index}]", fields)
+ for index, value in enumerate(self.array(field))
+ ]
+
+ def string(self, field: str, *, allow_empty: bool = False) -> str:
+ """Return a field checked with string()."""
+ return string(self.value(field), self.field_location(field), allow_empty=allow_empty)
+
+ def boolean(self, field: str) -> bool:
+ """Return a field as a boolean, or raise DocumentError."""
+ return _boolean(self.value(field), self.field_location(field))
+
+ def integer(self, field: str, minimum: int | None = None, maximum: int | None = None) -> int:
+ """Return a field checked with integer()."""
+ return integer(self.value(field), self.field_location(field), minimum, maximum)
+
+ def number(self, field: str) -> float:
+ """Return a field checked with number()."""
+ return number(self.value(field), self.field_location(field))
+
+ def number_vector(self, field: str, size: int) -> list[float]:
+ """Return a field checked with number_vector()."""
+ return number_vector(self.value(field), size, self.field_location(field))
+
+ def color(self, field: str) -> wp.vec3:
+ """Return a field as an RGB color with channels from 0 to 1, or raise DocumentError."""
+ return wp.vec3(*_color(self.value(field), self.field_location(field)))
+
+ def bool_vector(self, field: str, size: int) -> list[bool]:
+ """Return a field as a list of size booleans, or raise DocumentError."""
+ values = self.array(field)
+ location = self.field_location(field)
+ if len(values) != size:
+ raise DocumentError(f"{location} must contain exactly {size} booleans.")
+ return [_boolean(value, f"{location}[{index}]") for index, value in enumerate(values)]
+
+
+def validate_transforms(values: np.ndarray, location: str) -> None:
+ """Require finite transforms with unit quaternions (within 1e-3), or raise DocumentError.
+
+ Args:
+ values: Transforms as 7 values each: position, then XYZW quaternion.
+ location: Where the transforms are, for error messages.
+ """
+ if not np.all(np.isfinite(values)):
+ raise DocumentError(f"{location} contains non-finite values.")
+ quaternion_norms = np.linalg.norm(values[..., 3:7], axis=-1)
+ if np.any(np.abs(quaternion_norms - 1.0) > 1.0e-3):
+ raise DocumentError(f"{location} contains a non-unit quaternion.")
+
+
+def object_type(value, location: str) -> str:
+ """Return the type field of a JSON object whose other fields depend on its type.
+
+ A value that is not an object, or that has no type field, raises DocumentError.
+ """
+ if not isinstance(value, dict):
+ raise DocumentError(f"{location} must be an object.")
+ if "type" not in value:
+ raise DocumentError(f"Missing {location}.type.")
+ return string(value["type"], f"{location}.type")
+
+
+def serialize_transform(transform: wp.transform, location: str) -> dict:
+ """Return a transform as JSON values: translation and rotation_xyzw."""
+ validate_transforms(np.asarray(transform), location)
+ return {
+ "translation": list(transform.p),
+ "rotation_xyzw": list(transform.q),
+ }
+
+
+def load_transform(data: DocumentObject) -> wp.transform:
+ """Read a transform from its translation and rotation_xyzw fields."""
+ translation = data.number_vector("translation", 3)
+ rotation = data.number_vector("rotation_xyzw", 4)
+ transform = wp.transform(wp.vec3(*translation), wp.quat(*rotation))
+ validate_transforms(np.asarray(transform), data.location)
+ return transform
+
+
+def _load_camera(data: DocumentObject) -> dict:
+ """Read the saved camera state, and check its field of view and clip planes."""
+ state = {
+ "pos": data.number_vector("pos", 3),
+ "pivot": data.number_vector("pivot", 3),
+ "pitch": data.number("pitch"),
+ "yaw": data.number("yaw"),
+ "fov": data.number("fov"),
+ "near": data.number("near"),
+ "far": data.number("far"),
+ }
+ if not 0.0 < state["fov"] < 180.0:
+ raise DocumentError(f"{data.field_location('fov')} must be above 0 and below 180 degrees.")
+ if state["near"] <= 0.0:
+ raise DocumentError(f"{data.field_location('near')} must be greater than zero.")
+ if state["far"] <= state["near"]:
+ raise DocumentError(f"{data.field_location('far')} must be greater than the near plane.")
+ return state
+
+
+def serialize_reference(path: Path, document_path: Path) -> str:
+ """Store a path relative to the document, or absolute when no relative path exists."""
+ absolute_path = path.expanduser().resolve()
+ try:
+ return Path(os.path.relpath(absolute_path, document_path.parent)).as_posix()
+ except ValueError:
+ # Windows cannot form a relative path between different drives.
+ return absolute_path.as_posix()
+
+
+def resolve_reference(
+ data: DocumentObject, field: str, document_path: Path, *, kind: str,
+) -> Path | None:
+ """Return the referenced file, or None when the document has no reference."""
+ if data.value(field) is None:
+ return None
+ # Joining keeps an absolute path unchanged.
+ path = (document_path.parent / data.string(field)).resolve()
+ if not path.is_file():
+ raise DocumentError(f"Could not find the {kind} referenced by {data.field_location(field)}: {path}.")
+ return path
+
+
+@contextmanager
+def atomic_write(path: Path):
+ """Replace the destination only after the temporary file is fully written."""
+ temporary_path = path.parent / f".{path.name}.{uuid.uuid4().hex}.tmp"
+ try:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with temporary_path.open("xb") as stream:
+ yield stream
+ stream.flush()
+ os.fsync(stream.fileno())
+ os.replace(temporary_path, path)
+ finally:
+ temporary_path.unlink(missing_ok=True)
+
+
+def load_json(path: Path):
+ """Read a JSON document, or raise DocumentError."""
+ if not path.is_file():
+ raise DocumentError(f"Could not find document: {path}.")
+ try:
+ with path.open("r", encoding="utf-8") as stream:
+ return json.load(stream)
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+ raise DocumentError(f"Invalid JSON in {path}: {exc}") from exc
+ except OSError as exc:
+ raise DocumentError(f"Could not read {path}: {exc}") from exc
+
+
+def save_json(document: dict, path: Path) -> None:
+ """Write a JSON document atomically, or raise DocumentError."""
+ try:
+ data = (json.dumps(document, indent=2, allow_nan=False) + "\n").encode("utf-8")
+ except (TypeError, ValueError) as exc:
+ raise DocumentError(f"Could not serialize document for {path}: {exc}") from exc
+ try:
+ with atomic_write(path) as stream:
+ stream.write(data)
+ except OSError as exc:
+ raise DocumentError(f"Could not save document to {path}: {exc}") from exc
+
+
+@dataclass(frozen=True)
+class DocumentType:
+ """The header and file name rules of one kind of document.
+
+ Every document starts with the same header. Its editor field holds the selection and
+ the camera.
+
+ Attributes:
+ kind: Name of the document kind in messages and file dialogs, such as "Scene".
+ format: Value of the format field.
+ schema_version: Value of the schema_version field.
+ suffix: File name suffix, such as ".scene.json".
+ selected_field: Editor field that holds the selected item's ID.
+ """
+
+ kind: str
+ format: str
+ schema_version: int
+ suffix: str
+ selected_field: str
+
+ def normalize_path(self, path: str | Path) -> Path:
+ """Return path with the document suffix, completing a partial suffix such as .json."""
+ path = Path(path).expanduser()
+ lower_name = path.name.lower()
+ if lower_name.endswith(self.suffix):
+ return path
+ if lower_name.endswith(self.suffix.removesuffix(".json")):
+ return path.with_name(path.name + ".json")
+ if lower_name.endswith(".json"):
+ return path.with_name(path.name[:-5] + self.suffix)
+ return path.with_name(path.name + self.suffix)
+
+ def name_from_path(self, path: str | Path) -> str:
+ """Return the file name without the document suffix, or raise DocumentError."""
+ filename = Path(path).name
+ if not filename.lower().endswith(self.suffix):
+ raise DocumentError(f"{self.kind} documents must end in {self.suffix}.")
+ name = filename[: -len(self.suffix)]
+ if not name:
+ raise DocumentError(f"A {self.kind} document must have a name.")
+ return name
+
+ def header(self, document_path: Path, rig: ModelRig, selected_id: int, camera_state: dict) -> dict:
+ """Return the header of a document saved to document_path.
+
+ The camera is checked here, so a bad camera never reaches the file.
+ """
+ return {
+ "format": self.format,
+ "schema_version": self.schema_version,
+ "name": self.name_from_path(document_path),
+ "rig": rig.value,
+ "editor": {
+ self.selected_field: selected_id,
+ "camera": _load_camera(DocumentObject(camera_state, "document.editor.camera", _CAMERA_FIELDS)),
+ },
+ }
+
+ def read(self, document_path: Path, content_fields) -> tuple[DocumentObject, ModelRig, int, dict]:
+ """Read a document and check its header.
+
+ Args:
+ document_path: Resolved path of the document.
+ content_fields: Top-level fields that follow the header.
+
+ Returns:
+ The document, its rig, the selected item's ID, and the camera state.
+ """
+ self.name_from_path(document_path)
+ document = DocumentObject(load_json(document_path), "document", (*_HEADER_FIELDS, *content_fields))
+ document_format = document.string("format")
+ if document_format != self.format:
+ raise DocumentError(f"Unsupported {self.kind} format {document_format!r}.")
+ schema_version = document.integer("schema_version", minimum=1)
+ if schema_version != self.schema_version:
+ raise DocumentError(f"Unsupported {self.kind} schema version {schema_version}.")
+ rig = document.string("rig")
+ if rig not in ModelRig:
+ raise DocumentError(f"{document_path.name} uses unknown rig '{rig}'.")
+ editor = document.object("editor", (self.selected_field, "camera"))
+ selected_id = editor.integer(self.selected_field, minimum=1)
+ camera_state = _load_camera(editor.object("camera", _CAMERA_FIELDS))
+ return document, ModelRig(rig), selected_id, camera_state
diff --git a/app/runtime/common/io/scene_document.py b/app/runtime/common/io/scene_document.py
new file mode 100644
index 0000000..045c917
--- /dev/null
+++ b/app/runtime/common/io/scene_document.py
@@ -0,0 +1,490 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Scene documents shared by Scene Preview and the Scene Editor."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import ClassVar
+
+import warp as wp
+
+from motionbricks.model.contract import ModelRig
+
+from . import document_io
+from .document_io import DocumentError, DocumentObject, DocumentType
+from .smart_primitive_document import SMART_PRIMITIVE_DOCUMENT, load_smart_primitive_rig
+
+
+SCENE_DOCUMENT = DocumentType(
+ kind="Scene",
+ format="motionbricks.scene",
+ schema_version=1,
+ suffix=".scene.json",
+ selected_field="selected_item_id",
+)
+
+_CONTENT_FIELDS = ("character_start", "smart_primitives", "solid_cubes")
+_CHARACTER_START_FIELDS = ("id", "transform", "euler_degrees")
+_SMART_PRIMITIVE_FIELDS = (
+ "id",
+ "name",
+ "parent_id",
+ "transform",
+ "euler_degrees",
+ "reference",
+ "visibility",
+ "target_pose_color",
+ "behavior",
+)
+_VISIBILITY_FIELDS = ("target_poses", "interaction_boxes")
+_SOLID_CUBE_FIELDS = (
+ "id",
+ "name",
+ "parent_id",
+ "transform",
+ "euler_degrees",
+ "dimensions",
+ "color",
+)
+_SOLID_CUBE_DIMENSION_FIELDS = ("width", "depth", "height")
+
+
+class SceneDocumentError(DocumentError):
+ """Raised when a scene breaks a scene rule, such as unique item IDs or a single rig.
+
+ JSON and file problems raise DocumentError, the base class.
+ """
+
+
+def _default_solid_cube_transform() -> wp.transform:
+ return wp.transform(
+ wp.vec3(0.0, 0.0, 0.5),
+ wp.quat_identity(),
+ )
+
+
+@dataclass(slots=True)
+class CharacterStart:
+ """Where the character starts in the scene. It always stays at the top level."""
+
+ parent_id: ClassVar[None] = None
+ name: ClassVar[str] = "CharacterStart"
+ id: int = 1
+ transform: wp.transform = field(default_factory=wp.transform_identity)
+ euler_degrees: list[float] = field(
+ default_factory=lambda: [0.0, 0.0, 0.0]
+ )
+
+
+@dataclass(slots=True)
+class SmartPrimitiveInstance:
+ """A placed Smart Primitive, including its behavior class and display settings.
+
+ transform is relative to the parent item, or to world space without a parent.
+ """
+
+ id: int
+ name: str
+ transform: wp.transform = field(default_factory=wp.transform_identity)
+ euler_degrees: list[float] = field(
+ default_factory=lambda: [0.0, 0.0, 0.0]
+ )
+ reference: Path | None = None
+ show_target_poses: bool = True
+ show_interaction_boxes: bool = True
+ behavior: str = ""
+ target_pose_color: wp.vec3 = field(default_factory=lambda: wp.vec3(1.0, 0.30, 0.20))
+ parent_id: int | None = None
+
+
+@dataclass(slots=True)
+class SolidCube:
+ """A Solid Cube placed by its center, with its size in meters and its color.
+
+ transform is relative to the parent item, or to world space without a parent.
+ """
+
+ id: int
+ name: str
+ transform: wp.transform = field(default_factory=_default_solid_cube_transform)
+ euler_degrees: list[float] = field(
+ default_factory=lambda: [0.0, 0.0, 0.0]
+ )
+ width: float = 1.0
+ depth: float = 1.0
+ height: float = 1.0
+ color: wp.vec3 = field(default_factory=lambda: wp.vec3(0.45, 0.55, 0.70))
+ parent_id: int | None = None
+
+
+SceneItem = CharacterStart | SmartPrimitiveInstance | SolidCube
+
+
+@dataclass(slots=True)
+class SceneDefinition:
+ """The scene's CharacterStart, Smart Primitives, and Solid Cubes.
+
+ Every referenced Smart Primitive must use the scene's rig.
+ Smart Primitives and cubes can sit under one another to edit them together.
+ flatten() resolves that hierarchy into world transforms for runtime use.
+ """
+
+ rig: ModelRig = ModelRig.SOMA
+ character_start: CharacterStart = field(default_factory=CharacterStart)
+ smart_primitives: list[SmartPrimitiveInstance] = field(default_factory=list)
+ solid_cubes: list[SolidCube] = field(default_factory=list)
+ _next_id: int = field(init=False, repr=False)
+
+ def __post_init__(self) -> None:
+ self.rig = ModelRig(self.rig)
+ maximum_id = max(
+ [self.character_start.id]
+ + [instance.id for instance in self.smart_primitives]
+ + [cube.id for cube in self.solid_cubes]
+ )
+ self._next_id = maximum_id + 1
+
+ def add_smart_primitive(self) -> SmartPrimitiveInstance:
+ """Add a Smart Primitive item with a new ID and name, and return it."""
+ instance = SmartPrimitiveInstance(
+ id=self._next_id,
+ name=self._next_item_name("SmartPrimitive"),
+ )
+ self._next_id += 1
+ self.smart_primitives.append(instance)
+ return instance
+
+ def add_solid_cube(self) -> SolidCube:
+ """Add a Solid Cube with a new ID and name, and return it."""
+ cube = SolidCube(
+ id=self._next_id,
+ name=self._next_item_name("SolidCube"),
+ )
+ self._next_id += 1
+ self.solid_cubes.append(cube)
+ return cube
+
+ def remove_item(self, item_id: int) -> list[int]:
+ """Delete an item and every item under it, and return their IDs.
+
+ CharacterStart cannot be removed.
+ """
+ item = self.find_item(item_id)
+ if item is None or item is self.character_start:
+ return []
+ removed = [descendant.id for descendant in self.subtree(item)]
+ self.smart_primitives[:] = [instance for instance in self.smart_primitives if instance.id not in removed]
+ self.solid_cubes[:] = [cube for cube in self.solid_cubes if cube.id not in removed]
+ return removed
+
+ def find_item(self, item_id: int | None) -> SceneItem | None:
+ """Return the scene item with item_id, or None."""
+ if item_id == self.character_start.id:
+ return self.character_start
+ for item in (*self.smart_primitives, *self.solid_cubes):
+ if item.id == item_id:
+ return item
+ return None
+
+ def children(self, parent_id: int | None) -> list[SmartPrimitiveInstance | SolidCube]:
+ """Return direct children in creation order. None selects the top-level items."""
+ items = (*self.smart_primitives, *self.solid_cubes)
+ return sorted((item for item in items if item.parent_id == parent_id), key=lambda item: item.id)
+
+ def subtree(self, item: SceneItem) -> Iterator[SceneItem]:
+ """Visit an item, then every item under it."""
+ yield item
+ for child in self.children(item.id):
+ yield from self.subtree(child)
+
+ def world_transform(self, item: SceneItem) -> wp.transform:
+ """Return the item's position and rotation in world space."""
+ transform = wp.transform(item.transform)
+ parent = self.find_item(item.parent_id)
+ while parent is not None:
+ transform = wp.mul(parent.transform, transform)
+ parent = self.find_item(parent.parent_id)
+ return transform
+
+ def local_transform(self, item: SceneItem, world_transform: wp.transform) -> wp.transform:
+ """Convert a world transform to the item's parent space."""
+ parent = self.find_item(item.parent_id)
+ if parent is None:
+ return wp.transform(world_transform)
+ return wp.mul(wp.transform_inverse(self.world_transform(parent)), world_transform)
+
+ def set_parent(self, item: SceneItem, parent_id: int | None) -> bool:
+ """Change an item's parent while keeping its world placement.
+
+ None moves it to the top level. Return False if the parent is unchanged or invalid.
+ """
+ parent = self.find_item(parent_id)
+ if (
+ item is self.character_start
+ or parent is self.character_start
+ or (parent is None and parent_id is not None)
+ or item.parent_id == parent_id
+ or any(descendant is parent for descendant in self.subtree(item))
+ ):
+ return False
+ world_transform = self.world_transform(item)
+ item.parent_id = parent_id
+ item.transform = self.local_transform(item, world_transform)
+ return True
+
+ def flatten(self) -> SceneDefinition:
+ """Return a copy where every item is at the top level, placed by its world transform."""
+ return SceneDefinition(
+ rig=self.rig,
+ character_start=replace(self.character_start),
+ smart_primitives=[
+ replace(instance, transform=self.world_transform(instance), parent_id=None)
+ for instance in self.smart_primitives
+ ],
+ solid_cubes=[
+ replace(cube, transform=self.world_transform(cube), parent_id=None)
+ for cube in self.solid_cubes
+ ],
+ )
+
+ def _next_item_name(self, base_name: str) -> str:
+ names = {
+ item.name for item in (*self.smart_primitives, *self.solid_cubes)
+ }
+ if base_name not in names:
+ return base_name
+ suffix = 2
+ while f"{base_name}{suffix}" in names:
+ suffix += 1
+ return f"{base_name}{suffix}"
+
+
+def save_scene_document(
+ scene: SceneDefinition,
+ path: str | Path,
+ selected_item_id: int,
+ camera_state: dict,
+) -> Path:
+ """Save the scene and return the path it was saved to.
+
+ The path gets the .scene.json suffix when it lacks it. The previous file is replaced
+ only after the write succeeds.
+ """
+
+ _validate_scene(scene)
+ document_path = SCENE_DOCUMENT.normalize_path(path).resolve()
+ document = SCENE_DOCUMENT.header(document_path, scene.rig, selected_item_id, camera_state)
+ document["character_start"] = _serialize_character_start(scene.character_start)
+ document["smart_primitives"] = [
+ _serialize_smart_primitive(instance, document_path) for instance in scene.smart_primitives
+ ]
+ document["solid_cubes"] = [_serialize_solid_cube(cube) for cube in scene.solid_cubes]
+ document_io.save_json(document, document_path)
+ return document_path
+
+
+def load_scene_document(
+ path: str | Path,
+) -> tuple[SceneDefinition, int, dict]:
+ """Load a scene plus its editor selection and camera state."""
+
+ document_path = Path(path).expanduser().resolve()
+ document, rig, selected_item_id, camera_state = SCENE_DOCUMENT.read(document_path, _CONTENT_FIELDS)
+ scene = SceneDefinition(
+ rig=rig,
+ character_start=_load_character_start(
+ document.object("character_start", _CHARACTER_START_FIELDS)
+ ),
+ smart_primitives=[
+ _load_smart_primitive(data, document_path)
+ for data in document.object_array("smart_primitives", _SMART_PRIMITIVE_FIELDS)
+ ],
+ solid_cubes=[
+ _load_solid_cube(data)
+ for data in document.object_array("solid_cubes", _SOLID_CUBE_FIELDS)
+ ],
+ )
+ _validate_scene(scene)
+ if scene.find_item(selected_item_id) is None:
+ selected_item_id = scene.character_start.id
+ return scene, selected_item_id, camera_state
+
+
+def check_reference_rigs(scene: SceneDefinition) -> None:
+ """Check that every referenced Smart Primitive was saved for the scene's rig.
+
+ Only each document's rig is read, so this runs before any character or clip loads.
+ """
+
+ for instance in scene.smart_primitives:
+ if instance.reference is None:
+ continue
+ rig = load_smart_primitive_rig(instance.reference)
+ if rig is not scene.rig:
+ raise SceneDocumentError(
+ f"{instance.reference.name} was saved for the '{rig}' rig, "
+ f"but this scene uses '{scene.rig}'."
+ )
+
+
+def _serialize_character_start(item: CharacterStart) -> dict:
+ return {
+ "id": item.id,
+ "transform": document_io.serialize_transform(item.transform, "CharacterStart.transform"),
+ "euler_degrees": list(item.euler_degrees),
+ }
+
+
+def _serialize_smart_primitive(
+ instance: SmartPrimitiveInstance,
+ document_path: Path,
+) -> dict:
+ location = f"Smart Primitive {instance.name!r}"
+ return {
+ "id": instance.id,
+ "name": instance.name,
+ "parent_id": instance.parent_id,
+ "transform": document_io.serialize_transform(instance.transform, f"{location}.transform"),
+ "euler_degrees": list(instance.euler_degrees),
+ "reference": (
+ None
+ if instance.reference is None
+ else document_io.serialize_reference(instance.reference, document_path)
+ ),
+ "visibility": {
+ "target_poses": instance.show_target_poses,
+ "interaction_boxes": instance.show_interaction_boxes,
+ },
+ "target_pose_color": document_io.serialize_color(instance.target_pose_color, f"{location}.target_pose_color"),
+ "behavior": instance.behavior,
+ }
+
+
+def _serialize_solid_cube(cube: SolidCube) -> dict:
+ location = f"Solid Cube {cube.name!r}"
+ return {
+ "id": cube.id,
+ "name": cube.name,
+ "parent_id": cube.parent_id,
+ "transform": document_io.serialize_transform(cube.transform, f"{location}.transform"),
+ "euler_degrees": list(cube.euler_degrees),
+ "dimensions": {
+ "width": cube.width,
+ "depth": cube.depth,
+ "height": cube.height,
+ },
+ "color": document_io.serialize_color(cube.color, f"{location}.color"),
+ }
+
+
+def _load_character_start(data: DocumentObject) -> CharacterStart:
+ return CharacterStart(
+ id=data.integer("id", minimum=1),
+ transform=document_io.load_transform(data.object("transform", document_io.TRANSFORM_FIELDS)),
+ euler_degrees=data.number_vector("euler_degrees", 3),
+ )
+
+
+def _load_smart_primitive(
+ data: DocumentObject,
+ document_path: Path,
+) -> SmartPrimitiveInstance:
+ visibility = data.object("visibility", _VISIBILITY_FIELDS)
+ return SmartPrimitiveInstance(
+ id=data.integer("id", minimum=1),
+ name=data.string("name"),
+ transform=document_io.load_transform(data.object("transform", document_io.TRANSFORM_FIELDS)),
+ euler_degrees=data.number_vector("euler_degrees", 3),
+ reference=document_io.resolve_reference(data, "reference", document_path, kind="Smart Primitive"),
+ show_target_poses=visibility.boolean("target_poses"),
+ show_interaction_boxes=visibility.boolean("interaction_boxes"),
+ target_pose_color=data.color("target_pose_color"),
+ behavior=data.string("behavior", allow_empty=True),
+ parent_id=_load_parent_id(data),
+ )
+
+
+def _load_solid_cube(data: DocumentObject) -> SolidCube:
+ dimensions = data.object("dimensions", _SOLID_CUBE_DIMENSION_FIELDS)
+ return SolidCube(
+ id=data.integer("id", minimum=1),
+ name=data.string("name"),
+ transform=document_io.load_transform(data.object("transform", document_io.TRANSFORM_FIELDS)),
+ euler_degrees=data.number_vector("euler_degrees", 3),
+ width=dimensions.number("width"),
+ depth=dimensions.number("depth"),
+ height=dimensions.number("height"),
+ color=data.color("color"),
+ parent_id=_load_parent_id(data),
+ )
+
+
+def _load_parent_id(data: DocumentObject) -> int | None:
+ return None if data.value("parent_id") is None else data.integer("parent_id", minimum=1)
+
+
+def _validate_scene(scene: SceneDefinition) -> None:
+ if scene.character_start.id != 1:
+ raise SceneDocumentError("CharacterStart must use scene item ID 1.")
+
+ used_ids = {scene.character_start.id}
+ for index, instance in enumerate(scene.smart_primitives):
+ location = f"smart_primitives[{index}]"
+ if instance.id < 1 or instance.id in used_ids:
+ raise SceneDocumentError(f"{location}.id must be unique and positive.")
+ used_ids.add(instance.id)
+ if not instance.name.strip():
+ raise SceneDocumentError(f"{location}.name cannot be empty.")
+ if instance.reference is not None:
+ _validate_reference_path(instance.reference, f"{location}.reference")
+
+ for index, cube in enumerate(scene.solid_cubes):
+ location = f"solid_cubes[{index}]"
+ if cube.id < 1 or cube.id in used_ids:
+ raise SceneDocumentError(f"{location}.id must be unique and positive.")
+ used_ids.add(cube.id)
+ if not cube.name.strip():
+ raise SceneDocumentError(f"{location}.name cannot be empty.")
+ for attribute, value in (("width", cube.width), ("depth", cube.depth), ("height", cube.height)):
+ if value <= 0.0:
+ raise SceneDocumentError(f"{location}.{attribute} must be greater than zero.")
+ _validate_hierarchy(scene)
+
+
+def _validate_hierarchy(scene: SceneDefinition) -> None:
+ items = {item.id: item for item in (*scene.smart_primitives, *scene.solid_cubes)}
+ for item in items.values():
+ ancestors = {item.id}
+ parent_id = item.parent_id
+ while parent_id is not None:
+ if parent_id not in items:
+ raise SceneDocumentError(f"{item.name!r} must have a Smart Primitive or Solid Cube as its parent.")
+ if parent_id in ancestors:
+ raise SceneDocumentError(f"{item.name!r} cannot sit under itself.")
+ ancestors.add(parent_id)
+ parent_id = items[parent_id].parent_id
+
+
+def _validate_reference_path(path: Path, location: str) -> None:
+ if not path.name.lower().endswith(SMART_PRIMITIVE_DOCUMENT.suffix):
+ raise SceneDocumentError(f"{location} must reference a {SMART_PRIMITIVE_DOCUMENT.suffix} file.")
+ if not path.is_file():
+ raise SceneDocumentError(f"Could not find the file {location} references: {path}.")
+
+
+__all__ = [
+ "SCENE_DOCUMENT",
+ "CharacterStart",
+ "SceneDefinition",
+ "SceneDocumentError",
+ "SceneItem",
+ "SolidCube",
+ "SmartPrimitiveInstance",
+ "check_reference_rigs",
+ "load_scene_document",
+ "save_scene_document",
+]
diff --git a/app/runtime/common/io/smart_primitive_document.py b/app/runtime/common/io/smart_primitive_document.py
new file mode 100644
index 0000000..ddba38a
--- /dev/null
+++ b/app/runtime/common/io/smart_primitive_document.py
@@ -0,0 +1,1350 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared Smart Primitive documents, clip loading, and runtime asset preparation."""
+
+from __future__ import annotations
+
+import colorsys
+import math
+import random
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import (
+ MODEL_MAX_TOKEN_COUNT,
+ MODEL_MIN_TOKEN_COUNT,
+ MODEL_POSES_PER_TOKEN,
+ MODEL_SAMPLE_RATE,
+ ModelRig,
+)
+from motionbricks.runtime.pivot import Axis, ConeSide, ConstraintType, OperationOrder, Pivot
+from motionbricks.runtime.smart_primitive import (
+ SmartPrimitive,
+ SmartPrimitiveAsset,
+ SmartPrimitiveData,
+ SmartPrimitiveSequence,
+)
+from motionbricks.runtime.target_pose import (
+ IKPin,
+ MAX_TRANSITION_EARLY_BY_FRAMES,
+ TargetPoseInferenceParams,
+)
+
+from . import document_io
+from ..clip_registry import ClipAsset, ClipLoadError, ClipRegistry
+from .document_io import DocumentError, DocumentObject, DocumentType
+
+
+_VELOCITY_EPSILON = 1.0e-6
+MIN_TRAJECTORY_SCALE = 1.0
+MAX_TRAJECTORY_SCALE = 4.0
+_DEFAULT_TRAJECTORY_SCALE = 2.0
+_DEFAULT_MIN_TOKENS = 6
+_DEFAULT_MAX_TOKENS = 14
+
+
+_TRAJECTORY_HISTORY_FRAMES = 10
+_TRAJECTORY_FUTURE_FRAMES = 10
+TRAJECTORY_POINT_COUNT = _TRAJECTORY_HISTORY_FRAMES + 1 + _TRAJECTORY_FUTURE_FRAMES
+
+
+SMART_PRIMITIVE_DOCUMENT = DocumentType(
+ kind="Smart Primitive",
+ format="motionbricks.smart_primitive.authoring",
+ schema_version=1,
+ suffix=".smart_primitive.json",
+ selected_field="selected_node_id",
+)
+_TARGET_POSE_COMPONENT_TYPE = "target_pose"
+_INTERACTION_BOX_COMPONENT_TYPE = "interaction_box"
+_PIVOT_COMPONENT_TYPE = "pivot"
+
+
+
+_CONTENT_FIELDS = ("sequences", "root")
+_NODE_FIELDS = (
+ "id",
+ "name",
+ "local_transform",
+ "euler_degrees",
+ "visible",
+ "translation_locks",
+ "rotation_locks",
+ "components",
+ "children",
+)
+_TARGET_POSE_FIELDS = (
+ "type",
+ "id",
+ "clip",
+ "sample_time_seconds",
+ "frame_index",
+ "playback_mode",
+ "hips_constrained",
+ "num_poses_to_use",
+ "transition_early_by_frames",
+ "min_tokens",
+ "max_tokens",
+ "ik_pin_mask",
+ "show_mesh",
+ "show_skeletons",
+ "show_velocity",
+ "show_trajectory",
+ "trajectory_scale",
+ "color",
+)
+_INTERACTION_BOX_FIELDS = (
+ "type",
+ "id",
+ "width",
+ "depth",
+ "height",
+ "color",
+)
+_PIVOT_FIELDS = (
+ "type", "id", "motion_direction", "operation_order", "translation_axis", "translation_constraint",
+ "line_min_offset", "line_max_offset",
+ "rotation_axis", "rotation_constraint", "cone_half_angle_degrees", "cone_side",
+ "show_motion_direction", "show_translation_constraint", "show_rotation_constraint",
+)
+_SEQUENCE_FIELDS = ("id", "name", "node_ids", "pivot_node_id")
+
+
+def _random_color() -> wp.vec3:
+ return wp.vec3(*colorsys.hsv_to_rgb(random.random(), 0.65, 0.95))
+
+
+class PlaybackMode(Enum):
+ """How the editor shows a target pose's sample position: as a time or as a frame."""
+
+ TIME = "time"
+ FRAMES = "frames"
+
+
+class InteractionBoxComponent:
+ """An interaction box's size and color. Its node sets its placement."""
+
+ def __init__(self, component_id: int) -> None:
+ """Create a 1 m interaction box with a random color."""
+ self.id = component_id
+ self.width = 1.0
+ self.depth = 1.0
+ self.height = 1.0
+ self.color = _random_color()
+
+ def set_dimensions(self, width: float, depth: float, height: float) -> None:
+ """Set the box size in meters. Values must be finite and non-negative."""
+ dimensions = (float(width), float(depth), float(height))
+ if any(not math.isfinite(value) or value < 0.0 for value in dimensions):
+ raise ValueError(
+ "Interaction Box dimensions must be non-negative and finite."
+ )
+ self.width, self.depth, self.height = dimensions
+
+
+class TargetPoseComponent:
+ """A target pose's settings and the clip samples used to build it.
+
+ Poses use the layout of reference_pose, either local joint transforms or
+ joint coordinates, with the root first. up_index names the clip axis that
+ holds height.
+ """
+
+ def __init__(self, component_id: int, reference_pose: wp.array, up_index: int) -> None:
+ """Create a target pose without a clip, using all four poses and 6 to 14 tokens."""
+ self.id = component_id
+ self.clip: ClipAsset | None = None
+ self.num_poses_to_use = MODEL_POSES_PER_TOKEN
+ self.transition_early_by_frames = 0
+ self.min_tokens = _DEFAULT_MIN_TOKENS
+ self.max_tokens = _DEFAULT_MAX_TOKENS
+ self.ik_pin_mask = IKPin.NONE
+ self.show_mesh = True
+ self.show_velocity = False
+ self.show_trajectory = False
+ self.show_skeletons = False
+ self.trajectory_scale = _DEFAULT_TRAJECTORY_SCALE
+ self.sample_time = 0.0
+ self.playback_mode = PlaybackMode.TIME
+ self.hips_constrained = False
+ self.color = _random_color()
+ self.set_reference_pose(reference_pose, up_index)
+
+ def set_reference_pose(self, reference_pose: wp.array, up_index: int) -> None:
+ """Allocate pose buffers that match reference_pose, then resample."""
+ self.reference_pose = reference_pose
+ self._up_index = up_index
+ self.sampled_poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, *reference_pose.shape),
+ dtype=reference_pose.dtype,
+ device=reference_pose.device,
+ )
+ # The displayed pose is the first sample, taken at sample_time.
+ self.pose = self.sampled_poses[0]
+ self._trajectory_poses = wp.empty(
+ (TRAJECTORY_POINT_COUNT, *reference_pose.shape),
+ dtype=reference_pose.dtype,
+ device=reference_pose.device,
+ )
+ self._trajectory_transforms = wp.empty(
+ TRAJECTORY_POINT_COUNT,
+ dtype=wp.transform,
+ device=reference_pose.device,
+ )
+ self._sample()
+
+ @property
+ def frame(self) -> int:
+ """Clip frame nearest the sample time, or 0 without a clip."""
+ if self.clip is None:
+ return 0
+ return min(
+ round(self.sample_time * self.clip.animation.sample_rate),
+ self.clip.last_frame,
+ )
+
+ @property
+ def duration(self) -> float:
+ """Clip duration in seconds, or 0 without a clip."""
+ if self.clip is None:
+ return 0.0
+ return self.clip.duration
+
+ @property
+ def velocity(self) -> wp.vec3:
+ """Root velocity between the first two sampled poses, in m/s.
+
+ It is zero when only one pose is used.
+ """
+ if self.num_poses_to_use == 1:
+ return wp.vec3(0.0)
+ return self._sampled_velocity
+
+ @property
+ def velocity_magnitude(self) -> float:
+ """Length of velocity, in m/s."""
+ return float(wp.length(self.velocity))
+
+ @property
+ def has_velocity(self) -> bool:
+ """Whether velocity is above a small threshold."""
+ return self.velocity_magnitude > _VELOCITY_EPSILON
+
+ @property
+ def has_trajectory(self) -> bool:
+ """Whether a root trajectory is available, which needs a clip."""
+ return self.clip is not None
+
+ @property
+ def trajectory_transforms(self) -> wp.array:
+ """Sample the preview path on demand, reusing it until the target changes."""
+ if self._trajectory_dirty:
+ self._update_trajectory_samples()
+ self._trajectory_dirty = False
+ return self._trajectory_transforms
+
+ @property
+ def skeleton_count(self) -> int:
+ """Number of preview skeletons: the poses to use, or 1 without a clip."""
+ if self.clip is None:
+ return 1
+ return self.num_poses_to_use
+
+ def set_clip(self, clip: ClipAsset) -> None:
+ """Use a clip and sample it from its start."""
+ self.clip = clip
+ self.sample_time = 0.0
+ self._sample()
+
+ def restore_sample_state(
+ self,
+ clip: ClipAsset | None,
+ playback_mode: PlaybackMode,
+ sample_time: float,
+ frame_index: int,
+ hips_constrained: bool,
+ ) -> None:
+ """Restore saved clip settings, then resample the target pose once."""
+ self.clip = clip
+ self.playback_mode = playback_mode
+ self.hips_constrained = hips_constrained
+ self.sample_time = (
+ frame_index / clip.animation.sample_rate
+ if clip is not None and playback_mode is PlaybackMode.FRAMES
+ else sample_time
+ )
+ self._sample()
+
+ def set_time(self, sample_time: float) -> None:
+ """Sample the clip at sample_time (in seconds), clamped to its duration."""
+ self.sample_time = min(max(float(sample_time), 0.0), self.duration)
+ self._sample()
+
+ def constrain_hips(self, enabled: bool) -> None:
+ """Turn the root constraint on or off, then resample the clip."""
+ enabled = bool(enabled)
+ if enabled == self.hips_constrained:
+ return
+ self.hips_constrained = enabled
+ self._sample()
+
+ def set_num_poses_to_use(self, num_poses: int) -> None:
+ """Set the poses to use, clamped to 1 to 4."""
+ self.num_poses_to_use = min(
+ max(int(num_poses), 1),
+ MODEL_POSES_PER_TOKEN,
+ )
+
+ def set_token_range(self, min_tokens: int, max_tokens: int) -> None:
+ """Set the token counts the model may choose, clamped to 6 to 16.
+
+ The maximum never drops below the minimum.
+ """
+ self.min_tokens = min(max(int(min_tokens), MODEL_MIN_TOKEN_COUNT), MODEL_MAX_TOKEN_COUNT)
+ self.max_tokens = min(max(int(max_tokens), self.min_tokens), MODEL_MAX_TOKEN_COUNT)
+
+ def set_ik_pin_enabled(self, pin: IKPin, enabled: bool) -> None:
+ """Pin or unpin one hand or foot for this target pose."""
+
+ pin = IKPin(pin)
+ if enabled:
+ self.ik_pin_mask |= pin
+ else:
+ self.ik_pin_mask &= ~pin
+
+ def set_trajectory_scale(self, scale: float) -> None:
+ """Set the spacing of the trajectory preview points, in frames at the model's sample rate.
+
+ It must be MIN_TRAJECTORY_SCALE to MAX_TRAJECTORY_SCALE.
+ """
+ scale = float(scale)
+ if (
+ not math.isfinite(scale)
+ or scale < MIN_TRAJECTORY_SCALE
+ or scale > MAX_TRAJECTORY_SCALE
+ ):
+ raise ValueError(
+ "Trajectory scale must be finite, from "
+ f"{MIN_TRAJECTORY_SCALE:.1f} to {MAX_TRAJECTORY_SCALE:.1f}."
+ )
+ if scale == self.trajectory_scale:
+ return
+ self.trajectory_scale = scale
+ self._trajectory_dirty = True
+
+ def _sample(self) -> None:
+ """Sample four 30 Hz poses from sample_time."""
+ self._root_offset = wp.transform_identity()
+ if self.clip is None:
+ for frame in range(MODEL_POSES_PER_TOKEN):
+ wp.copy(self.sampled_poses[frame], self.reference_pose)
+ else:
+ animation = self.clip.animation
+ if self.hips_constrained:
+ # Remove the root's offset along the ground, keeping its height.
+ animation.sample(self.sample_time, self.pose)
+ offset = -self.pose.numpy().reshape(-1)[:3]
+ offset[self._up_index] = 0.0
+ self._root_offset = wp.transform(wp.vec3(*offset), wp.quat_identity())
+ for frame in range(MODEL_POSES_PER_TOKEN):
+ animation.sample(
+ self.sample_time + frame / MODEL_SAMPLE_RATE,
+ self.sampled_poses[frame],
+ root_offset=self._root_offset,
+ )
+
+ roots = self.sampled_poses.numpy().reshape(MODEL_POSES_PER_TOKEN, -1)[:, :3]
+ self.hips_position = wp.vec3(*roots[0])
+ self._sampled_velocity = (wp.vec3(*roots[1]) - wp.vec3(*roots[0])) * MODEL_SAMPLE_RATE
+ self._trajectory_dirty = True
+
+ def _update_trajectory_samples(self) -> None:
+ if self.clip is None:
+ return
+
+ interval = self.trajectory_scale / MODEL_SAMPLE_RATE
+ for point in range(TRAJECTORY_POINT_COUNT):
+ self.clip.animation.sample(
+ self.sample_time + (point - _TRAJECTORY_HISTORY_FRAMES) * interval,
+ self._trajectory_poses[point],
+ root_offset=self._root_offset,
+ )
+ roots = self._trajectory_poses.numpy().reshape(TRAJECTORY_POINT_COUNT, -1)[:, :7]
+ self._trajectory_transforms.assign(np.ascontiguousarray(roots))
+
+
+class PivotComponent:
+ """Pivot rules and preview visibility for a hierarchy node."""
+
+ def __init__(self, component_id: int) -> None:
+ """Create a pivot with default rules and every preview shown."""
+ self.id = component_id
+ self.pivot = Pivot()
+ self.show_motion_direction = True
+ self.show_translation_constraint = True
+ self.show_rotation_constraint = True
+
+
+class SceneNode:
+ """A node's local transform, components, and children."""
+
+ def __init__(
+ self,
+ node_id: int,
+ name: str,
+ parent: SceneNode | None,
+ local_xform: wp.transform | None = None,
+ ) -> None:
+ """Create a visible node without components under parent."""
+ self.id = node_id
+ self.name = name
+ self.parent = parent
+ self.visible = True
+ self.translation_locks = [False, False, False]
+ self.rotation_locks = [False, False, False]
+ self.euler_degrees: list[float] | None = None
+ self.children: list[SceneNode] = []
+ # A node holds at most one component of each kind. An empty slot is None.
+ self.target_pose: TargetPoseComponent | None = None
+ self.interaction_box: InteractionBoxComponent | None = None
+ self.pivot: PivotComponent | None = None
+ self.local_xform = (
+ wp.transform_identity()
+ if local_xform is None
+ else wp.transform(local_xform)
+ )
+
+ @property
+ def components(self) -> tuple[TargetPoseComponent | InteractionBoxComponent | PivotComponent, ...]:
+ """The filled slots: Target Pose, Interaction Box, then Pivot."""
+ return tuple(
+ component for component in (self.target_pose, self.interaction_box, self.pivot) if component is not None
+ )
+
+
+@dataclass(slots=True)
+class TargetPoseSequence:
+ """Targets in generation order, with an optional pivot to align them."""
+
+ id: int
+ name: str
+ node_ids: list[int]
+ pivot_node_id: int | None = None
+
+
+class SmartPrimitiveDocument:
+ """The editable hierarchy, components, and target pose sequences."""
+
+ def __init__(self, rig: ModelRig, reference_pose: wp.array, model_to_runtime: wp.transform) -> None:
+ """Create an empty document that holds only the root node.
+
+ Args:
+ rig: Rig the document is authored for.
+ reference_pose: Reference pose that sets the pose layout, either local joint
+ transforms or joint coordinates.
+ model_to_runtime: Transform that places clip poses in world space.
+ """
+ self._next_id = 1
+ self._nodes: dict[int, SceneNode] = {}
+ self.root = SceneNode(self._new_id(), "Root", None)
+ self._nodes[self.root.id] = self.root
+ self.sequences: list[TargetPoseSequence] = []
+ self.set_rig(rig, reference_pose, model_to_runtime)
+
+ def set_rig(self, rig: ModelRig, reference_pose: wp.array, model_to_runtime: wp.transform) -> None:
+ """Switch the rig and reset every target to its reference pose.
+
+ No target may have a clip.
+ """
+ rig = ModelRig(rig)
+ targets = [component for _, component in self.iter_target_poses()]
+ if any(target.clip is not None for target in targets):
+ raise ValueError("Cannot change the rig while a target has a clip.")
+ self.rig = rig
+ self.reference_pose = reference_pose
+ self.model_to_runtime = wp.transform(model_to_runtime)
+ # Clips store height along Y (BVH) or Z (CSV). Find the clip axis that model_to_runtime turns into Z.
+ up = wp.quat_rotate_inv(self.model_to_runtime.q, wp.vec3(0.0, 0.0, 1.0))
+ self.up_index = int(np.argmax(np.abs(np.asarray(up))))
+ for target in targets:
+ target.set_reference_pose(reference_pose, self.up_index)
+
+ def set_contents(self, root: SceneNode, sequences: list[TargetPoseSequence], next_id: int) -> None:
+ """Replace the hierarchy and the sequences, such as with ones loaded from a file.
+
+ next_id must exceed every ID in use. New nodes, components, and sequences take
+ their IDs from it.
+ """
+ self.root = root
+ self._nodes = {node.id: node for node in self.iter_subtree(root)}
+ self.sequences = sequences
+ self._next_id = next_id
+
+ def _new_id(self) -> int:
+ item_id = self._next_id
+ self._next_id += 1
+ return item_id
+
+ def add_node(self, parent: SceneNode | None = None) -> SceneNode:
+ """Add a node under parent, or under the root node, and return it."""
+ parent = parent or self.root
+ node_id = self._new_id()
+ node = SceneNode(node_id, f"Node {node_id}", parent)
+ parent.children.append(node)
+ self._nodes[node.id] = node
+ return node
+
+ def remove_node(self, node: SceneNode) -> None:
+ """Delete a node with its descendants, and drop them from every sequence.
+
+ The root node stays.
+ """
+ if node is self.root:
+ return
+ node.parent.children.remove(node)
+ removed_node_ids = {descendant.id for descendant in self.iter_subtree(node)}
+ for descendant in self.iter_subtree(node):
+ self._nodes.pop(descendant.id, None)
+ for sequence in self.sequences:
+ if sequence.pivot_node_id in removed_node_ids:
+ sequence.pivot_node_id = None
+ sequence.node_ids[:] = [
+ node_id
+ for node_id in sequence.node_ids
+ if node_id not in removed_node_ids
+ ]
+
+ def find_node(self, node_id: int | None) -> SceneNode | None:
+ """Return the node with node_id, or None."""
+ return self._nodes.get(node_id)
+
+ def iter_nodes(self) -> Iterator[SceneNode]:
+ """Visit the root and descendants with every parent before its children."""
+ return self.iter_subtree(self.root)
+
+ @staticmethod
+ def iter_subtree(root: SceneNode) -> Iterator[SceneNode]:
+ """Visit parents before children, preserving the authored sibling order."""
+ pending = [root]
+ while pending:
+ node = pending.pop()
+ yield node
+ pending.extend(reversed(node.children))
+
+ @staticmethod
+ def iter_ancestors(node: SceneNode) -> Iterator[SceneNode]:
+ """Visit a node, then walk up through its parents."""
+ current: SceneNode | None = node
+ while current is not None:
+ yield current
+ current = current.parent
+
+ def world_xform(self, node: SceneNode) -> wp.transform:
+ """Return the node's transform composed through all of its parents."""
+ world_xform = wp.transform(node.local_xform)
+ parent = node.parent
+ while parent is not None:
+ world_xform = wp.mul(parent.local_xform, world_xform)
+ parent = parent.parent
+ return world_xform
+
+ def target_pose_world_xform(self, node: SceneNode) -> wp.transform:
+ """Return the transform that places the node's clip poses in world space."""
+ return wp.mul(self.world_xform(node), self.model_to_runtime)
+
+ def is_visible(self, node: SceneNode) -> bool:
+ """Return whether the node and all of its ancestors are visible."""
+ return all(ancestor.visible for ancestor in self.iter_ancestors(node))
+
+ def can_reparent(self, node: SceneNode, new_parent: SceneNode) -> bool:
+ """Return whether node can move under new_parent without forming a cycle."""
+ if node is self.root or node.parent is new_parent:
+ return False
+ return all(ancestor is not node for ancestor in self.iter_ancestors(new_parent))
+
+ def reparent(self, node: SceneNode, new_parent: SceneNode) -> bool:
+ """Move node under new_parent, keeping its placement.
+
+ Return whether the node moved.
+ """
+ if not self.can_reparent(node, new_parent):
+ return False
+
+ world_xform = self.world_xform(node)
+ new_parent_world = self.world_xform(new_parent)
+ node.parent.children.remove(node)
+ node.parent = new_parent
+ new_parent.children.append(node)
+ node.local_xform = wp.mul(
+ wp.transform_inverse(new_parent_world),
+ world_xform,
+ )
+ return True
+
+ def add_target_pose(self, node: SceneNode) -> TargetPoseComponent:
+ """Return the node's Target Pose component, adding one when it has none."""
+ if node.target_pose is None:
+ node.target_pose = TargetPoseComponent(self._new_id(), self.reference_pose, self.up_index)
+ return node.target_pose
+
+ def add_interaction_box(self, node: SceneNode) -> InteractionBoxComponent:
+ """Return the node's Interaction Box component, adding one when it has none."""
+ if node.interaction_box is None:
+ node.interaction_box = InteractionBoxComponent(self._new_id())
+ return node.interaction_box
+
+ def add_pivot(self, node: SceneNode) -> PivotComponent:
+ """Return the node's Pivot component, adding one when it has none."""
+ if node.pivot is None:
+ node.pivot = PivotComponent(self._new_id())
+ return node.pivot
+
+ def remove_component(
+ self,
+ node: SceneNode,
+ component: TargetPoseComponent | InteractionBoxComponent | PivotComponent,
+ ) -> None:
+ """Remove a component from a node, and drop every sequence reference to it."""
+ if component is node.target_pose:
+ node.target_pose = None
+ for sequence in self.sequences:
+ sequence.node_ids[:] = [
+ node_id for node_id in sequence.node_ids if node_id != node.id
+ ]
+ elif component is node.interaction_box:
+ node.interaction_box = None
+ elif component is node.pivot:
+ node.pivot = None
+ for sequence in self.sequences:
+ if sequence.pivot_node_id == node.id:
+ sequence.pivot_node_id = None
+
+ def add_sequence(self) -> TargetPoseSequence:
+ """Add an empty sequence with the next free name, and return it."""
+ existing_names = {sequence.name for sequence in self.sequences}
+ sequence_number = 1
+ while f"Sequence {sequence_number}" in existing_names:
+ sequence_number += 1
+ sequence = TargetPoseSequence(
+ self._new_id(),
+ f"Sequence {sequence_number}",
+ [],
+ )
+ self.sequences.append(sequence)
+ return sequence
+
+ def find_sequence(self, sequence_id: int | None) -> TargetPoseSequence | None:
+ """Return the sequence with sequence_id, or None."""
+ return next(
+ (
+ sequence
+ for sequence in self.sequences
+ if sequence.id == sequence_id
+ ),
+ None,
+ )
+
+ def remove_sequence(self, sequence: TargetPoseSequence) -> None:
+ """Delete a sequence."""
+ self.sequences.remove(sequence)
+
+ def add_sequence_node(
+ self,
+ sequence: TargetPoseSequence,
+ node: SceneNode,
+ ) -> None:
+ """Append a node that has a Target Pose to a sequence."""
+ if self.find_sequence(sequence.id) is not sequence:
+ raise ValueError("The sequence must belong to this Smart Primitive.")
+ if self.find_node(node.id) is not node:
+ raise ValueError("The node must belong to this Smart Primitive.")
+ if node.target_pose is None:
+ raise ValueError("Sequence nodes must own a Target Pose component.")
+ sequence.node_ids.append(node.id)
+
+ def set_sequence_pivot(
+ self, sequence: TargetPoseSequence, node: SceneNode | None,
+ ) -> None:
+ """Set the node whose pivot aligns the sequence. None removes the pivot."""
+ if self.find_sequence(sequence.id) is not sequence:
+ raise ValueError("The sequence must belong to this Smart Primitive.")
+ if node is not None:
+ if self.find_node(node.id) is not node or node.pivot is None:
+ raise ValueError("The pivot node must belong here and own a Pivot component.")
+ sequence.pivot_node_id = None if node is None else node.id
+
+ @staticmethod
+ def remove_sequence_node(
+ sequence: TargetPoseSequence,
+ index: int,
+ ) -> None:
+ """Remove the step at index from a sequence."""
+ if not 0 <= index < len(sequence.node_ids):
+ raise IndexError(f"Sequence node index {index!r} is out of range.")
+ sequence.node_ids.pop(index)
+
+ @staticmethod
+ def move_sequence_node(
+ sequence: TargetPoseSequence,
+ source_index: int,
+ destination_index: int,
+ ) -> None:
+ """Move a sequence step from one index to another."""
+ node_count = len(sequence.node_ids)
+ if not 0 <= source_index < node_count:
+ raise IndexError(f"Sequence node index {source_index!r} is out of range.")
+ if not 0 <= destination_index < node_count:
+ raise IndexError(
+ f"Sequence destination index {destination_index!r} is out of range."
+ )
+ node_id = sequence.node_ids.pop(source_index)
+ sequence.node_ids.insert(destination_index, node_id)
+
+ def sequences_referencing(
+ self,
+ node: SceneNode,
+ ) -> Iterator[TargetPoseSequence]:
+ """Yield each sequence that uses node as a step or as its pivot."""
+ for sequence in self.sequences:
+ if node.id in sequence.node_ids or node.id == sequence.pivot_node_id:
+ yield sequence
+
+ def iter_target_poses(self) -> Iterator[tuple[SceneNode, TargetPoseComponent]]:
+ """Yield each node with its Target Pose component, parents before children."""
+ return ((node, node.target_pose) for node in self.iter_nodes() if node.target_pose is not None)
+
+ def iter_interaction_boxes(self) -> Iterator[tuple[SceneNode, InteractionBoxComponent]]:
+ """Yield each node with its Interaction Box component, parents before children."""
+ return ((node, node.interaction_box) for node in self.iter_nodes() if node.interaction_box is not None)
+
+ def iter_pivots(self) -> Iterator[tuple[SceneNode, PivotComponent]]:
+ """Yield each node with its Pivot component, parents before children."""
+ return ((node, node.pivot) for node in self.iter_nodes() if node.pivot is not None)
+
+
+class SmartPrimitiveDocumentError(DocumentError):
+ """Raised when a Smart Primitive breaks a document rule or cannot be prepared for runtime.
+
+ A clip that fails to load also raises it. JSON and file problems raise DocumentError, the
+ base class.
+ """
+
+
+def _serialize_target_pose(
+ component: TargetPoseComponent,
+ document_path: Path,
+) -> dict:
+ return {
+ "type": _TARGET_POSE_COMPONENT_TYPE,
+ "id": component.id,
+ "clip": (
+ None
+ if component.clip is None
+ else document_io.serialize_reference(component.clip.path, document_path)
+ ),
+ "sample_time_seconds": component.sample_time,
+ "frame_index": component.frame,
+ "playback_mode": component.playback_mode.value,
+ "hips_constrained": component.hips_constrained,
+ "num_poses_to_use": component.num_poses_to_use,
+ "transition_early_by_frames": component.transition_early_by_frames,
+ "min_tokens": component.min_tokens,
+ "max_tokens": component.max_tokens,
+ "ik_pin_mask": int(component.ik_pin_mask),
+ "show_mesh": component.show_mesh,
+ "show_skeletons": component.show_skeletons,
+ "show_velocity": component.show_velocity,
+ "show_trajectory": component.show_trajectory,
+ "trajectory_scale": component.trajectory_scale,
+ "color": document_io.serialize_color(component.color, f"Target Pose {component.id}.color"),
+ }
+
+
+def _serialize_interaction_box(
+ component: InteractionBoxComponent,
+) -> dict:
+ return {
+ "type": _INTERACTION_BOX_COMPONENT_TYPE,
+ "id": component.id,
+ "width": component.width,
+ "depth": component.depth,
+ "height": component.height,
+ "color": document_io.serialize_color(component.color, f"Interaction Box {component.id}.color"),
+ }
+
+
+def _serialize_pivot(component: PivotComponent) -> dict:
+ pivot = component.pivot
+ return {
+ "type": _PIVOT_COMPONENT_TYPE,
+ "id": component.id,
+ "motion_direction": list(pivot.motion_direction),
+ "operation_order": pivot.operation_order.value,
+ "translation_axis": pivot.translation_axis.value,
+ "translation_constraint": pivot.translation_constraint.value,
+ "line_min_offset": pivot.line_min_offset,
+ "line_max_offset": pivot.line_max_offset,
+ "rotation_axis": pivot.rotation_axis.value,
+ "rotation_constraint": pivot.rotation_constraint.value,
+ "cone_half_angle_degrees": pivot.cone_half_angle_degrees,
+ "cone_side": pivot.cone_side.value,
+ "show_motion_direction": component.show_motion_direction,
+ "show_translation_constraint": component.show_translation_constraint,
+ "show_rotation_constraint": component.show_rotation_constraint,
+ }
+
+
+def _serialize_scene_node(node: SceneNode, document_path: Path) -> dict:
+ components = []
+ if node.target_pose is not None:
+ components.append(_serialize_target_pose(node.target_pose, document_path))
+ if node.interaction_box is not None:
+ components.append(_serialize_interaction_box(node.interaction_box))
+ if node.pivot is not None:
+ components.append(_serialize_pivot(node.pivot))
+
+ return {
+ "id": node.id,
+ "name": node.name,
+ "local_transform": document_io.serialize_transform(node.local_xform, f"Node {node.name!r}.local_transform"),
+ "euler_degrees": (
+ None
+ if node.euler_degrees is None
+ else [float(value) for value in node.euler_degrees]
+ ),
+ "visible": node.visible,
+ "translation_locks": list(node.translation_locks),
+ "rotation_locks": list(node.rotation_locks),
+ "components": components,
+ "children": [
+ _serialize_scene_node(child, document_path) for child in node.children
+ ],
+ }
+
+
+def _serialize_sequence(sequence: TargetPoseSequence) -> dict:
+ return {
+ "id": sequence.id,
+ "name": sequence.name,
+ "node_ids": list(sequence.node_ids),
+ "pivot_node_id": sequence.pivot_node_id,
+ }
+
+
+def _prepare_runtime_target_poses(
+ authoring: SmartPrimitiveDocument,
+ targets: list[tuple[SceneNode, TargetPoseComponent]],
+) -> tuple[np.ndarray, tuple[TargetPoseInferenceParams, ...]]:
+ pose_shape = authoring.reference_pose.numpy().shape
+ packed_poses = np.empty(
+ (len(targets) * MODEL_POSES_PER_TOKEN, *pose_shape),
+ dtype=np.float32,
+ )
+ inference_params = []
+
+ for target_index, (node, component) in enumerate(targets):
+ if component.clip is None:
+ raise SmartPrimitiveDocumentError(
+ f"Target Pose on node {node.name!r} has no clip."
+ )
+
+ sampled_poses = component.sampled_poses.numpy()
+ # Checks every joint of local joint transforms, or the root of joint coordinates.
+ document_io.validate_transforms(sampled_poses[..., :7], f"Target Pose on node {node.name!r}")
+ if not np.all(np.isfinite(sampled_poses)):
+ raise SmartPrimitiveDocumentError(
+ f"Target Pose on node {node.name!r} contains non-finite values."
+ )
+
+ frame_offset = target_index * MODEL_POSES_PER_TOKEN
+ target_slice = packed_poses[
+ frame_offset : frame_offset + MODEL_POSES_PER_TOKEN
+ ]
+ target_slice[:] = sampled_poses
+
+ # Only the root moves to world space. Joint transforms and angles stay unchanged.
+ roots = target_slice.reshape(MODEL_POSES_PER_TOKEN, -1)[:, :7]
+ for frame in range(MODEL_POSES_PER_TOKEN):
+ roots[frame] = wp.mul(authoring.model_to_runtime, wp.transform(*roots[frame]))
+
+ inference_params.append(TargetPoseInferenceParams(
+ transition_early_by_frames=component.transition_early_by_frames,
+ num_poses_to_use=component.num_poses_to_use,
+ ik_pin_mask=component.ik_pin_mask,
+ allowed_token_counts=tuple(range(component.min_tokens, component.max_tokens + 1)),
+ ))
+
+ return packed_poses, tuple(inference_params)
+
+
+def _prepare_runtime_sequences(
+ authoring: SmartPrimitiveDocument,
+ node_indices: dict[SceneNode, int],
+) -> tuple[SmartPrimitiveSequence, ...]:
+ """Map saved node IDs to runtime indices while preserving sequence and step order."""
+ prepared = []
+ for sequence in authoring.sequences:
+ if not sequence.node_ids:
+ raise SmartPrimitiveDocumentError(
+ f"Sequence {sequence.name!r} must contain at least one Target Pose."
+ )
+ nodes = [authoring.find_node(node_id) for node_id in sequence.node_ids]
+ start_speed = nodes[0].target_pose.velocity_magnitude
+ if not math.isfinite(start_speed):
+ raise SmartPrimitiveDocumentError(
+ f"Sequence {sequence.name!r} has a non-finite start speed."
+ )
+ pivot_node_index = -1
+ if sequence.pivot_node_id is not None:
+ pivot_node_index = node_indices[authoring.find_node(sequence.pivot_node_id)]
+ prepared.append(SmartPrimitiveSequence(
+ name=sequence.name,
+ node_indices=tuple(node_indices[node] for node in nodes),
+ start_speed=start_speed,
+ pivot_node_index=pivot_node_index,
+ ))
+ return tuple(prepared)
+
+
+def build_runtime_smart_primitive_data(
+ authoring: SmartPrimitiveDocument,
+) -> SmartPrimitiveData:
+ """Prepare the hierarchy, sampled poses, and interaction settings for playback."""
+
+ # Runtime transforms require parents before children. IDs reflect creation
+ # order, so derive indices from the hierarchy, including after reparenting.
+ nodes = list(authoring.iter_nodes())
+ node_indices = {node: index for index, node in enumerate(nodes)}
+
+ node_local_transforms = np.array([list(node.local_xform) for node in nodes], dtype=np.float32)
+ node_parent_indices = np.asarray(
+ [
+ -1 if node.parent is None else node_indices[node.parent]
+ for node in nodes
+ ],
+ dtype=np.int32,
+ )
+ node_names = tuple(node.name for node in nodes)
+ if len(set(node_names)) != len(node_names):
+ raise SmartPrimitiveDocumentError("Runtime node names must be unique.")
+ sequences = _prepare_runtime_sequences(authoring, node_indices)
+
+ pivot_components = list(authoring.iter_pivots())
+ pivot_node_indices = np.asarray([node_indices[node] for node, _ in pivot_components], dtype=np.int32)
+ pivots = tuple(component.pivot for _, component in pivot_components)
+
+ targets = list(authoring.iter_target_poses())
+ target_node_indices = np.asarray(
+ [node_indices[node] for node, _ in targets],
+ dtype=np.int32,
+ )
+ target_poses, target_inference_params = _prepare_runtime_target_poses(authoring, targets)
+
+ boxes = list(authoring.iter_interaction_boxes())
+ box_node_indices = np.asarray(
+ [node_indices[node] for node, _ in boxes],
+ dtype=np.int32,
+ )
+ box_half_extents = np.asarray(
+ [
+ (0.5 * component.width, 0.5 * component.depth, 0.5 * component.height)
+ for _, component in boxes
+ ],
+ dtype=np.float32,
+ ).reshape((len(boxes), 3))
+
+ return SmartPrimitiveData(
+ rig=authoring.rig,
+ node_local_transforms=node_local_transforms,
+ node_parent_indices=node_parent_indices,
+ node_names=node_names,
+ target_node_indices=target_node_indices,
+ target_poses=target_poses,
+ target_inference_params=target_inference_params,
+ box_node_indices=box_node_indices,
+ box_half_extents=box_half_extents,
+ pivot_node_indices=pivot_node_indices,
+ pivots=pivots,
+ sequences=sequences,
+ )
+
+
+def save_smart_primitive_document(
+ authoring: SmartPrimitiveDocument,
+ path: str | Path,
+ selected_node_id: int,
+ camera_state: dict,
+) -> Path:
+ """Save the document and editor settings, then return the file path."""
+ document_path = SMART_PRIMITIVE_DOCUMENT.normalize_path(path).resolve()
+ document = SMART_PRIMITIVE_DOCUMENT.header(document_path, authoring.rig, selected_node_id, camera_state)
+ document["sequences"] = [_serialize_sequence(sequence) for sequence in authoring.sequences]
+ document["root"] = _serialize_scene_node(authoring.root, document_path)
+ document_io.save_json(document, document_path)
+ return document_path
+
+
+class _SmartPrimitiveDocumentLoader:
+ def __init__(
+ self,
+ clip_registry: ClipRegistry,
+ reference_pose: wp.array,
+ model_to_runtime: wp.transform,
+ document_path: Path,
+ ) -> None:
+ self.clip_registry = clip_registry
+ self.reference_pose = reference_pose
+ self.model_to_runtime = model_to_runtime
+ self.document_path = document_path
+ self.used_ids: set[int] = set()
+ self.maximum_id = 0
+ self.nodes: dict[int, SceneNode] = {}
+
+ def load(self) -> tuple[SmartPrimitiveDocument, int, dict]:
+ document, rig, selected_node_id, camera_state = SMART_PRIMITIVE_DOCUMENT.read(
+ self.document_path, _CONTENT_FIELDS,
+ )
+ # Check the rig before loading any clips.
+ if rig != self.clip_registry.rig:
+ raise SmartPrimitiveDocumentError(
+ f"{self.document_path.name} was saved for the '{rig}' rig, "
+ f"but this app uses '{self.clip_registry.rig}'."
+ )
+
+ authoring = SmartPrimitiveDocument(
+ self.clip_registry.rig,
+ self.reference_pose,
+ self.model_to_runtime,
+ )
+ root = self._load_node(
+ document.object("root", _NODE_FIELDS),
+ None,
+ authoring,
+ )
+ sequences = [
+ self._load_sequence(data, authoring)
+ for data in document.object_array("sequences", _SEQUENCE_FIELDS)
+ ]
+ sequence_names = [sequence.name for sequence in sequences]
+ if len(set(sequence_names)) != len(sequence_names):
+ raise SmartPrimitiveDocumentError("Sequence names must be unique.")
+ authoring.set_contents(root, sequences, self.maximum_id + 1)
+ if authoring.find_node(selected_node_id) is None:
+ selected_node_id = authoring.root.id
+ return authoring, selected_node_id, camera_state
+
+ def _load_sequence(
+ self,
+ data: DocumentObject,
+ authoring: SmartPrimitiveDocument,
+ ) -> TargetPoseSequence:
+ sequence = TargetPoseSequence(
+ self._claim_id(data),
+ data.string("name"),
+ [],
+ )
+ for index, value in enumerate(data.array("node_ids")):
+ location = f"{data.field_location('node_ids')}[{index}]"
+ node_id = document_io.integer(value, location, minimum=1)
+ node = self.nodes.get(node_id)
+ if node is None:
+ raise SmartPrimitiveDocumentError(
+ f"{location} does not identify a hierarchy node."
+ )
+ if node.target_pose is None:
+ raise SmartPrimitiveDocumentError(
+ f"{location} identifies node {node.name!r}, which has no Target Pose."
+ )
+ sequence.node_ids.append(node_id)
+ if data.value("pivot_node_id") is not None:
+ pivot_id = data.integer("pivot_node_id", minimum=1)
+ node = self.nodes.get(pivot_id)
+ if node is None or node.pivot is None:
+ raise SmartPrimitiveDocumentError(
+ f"{data.field_location('pivot_node_id')} must identify a node with a Pivot component."
+ )
+ sequence.pivot_node_id = pivot_id
+ return sequence
+
+ def _claim_id(self, data: DocumentObject) -> int:
+ item_id = data.integer("id", minimum=1)
+ if item_id in self.used_ids:
+ raise SmartPrimitiveDocumentError(
+ f"Duplicate ID {item_id} at {data.field_location('id')}."
+ )
+ self.used_ids.add(item_id)
+ self.maximum_id = max(self.maximum_id, item_id)
+ return item_id
+
+ def _load_node(
+ self,
+ data: DocumentObject,
+ parent: SceneNode | None,
+ authoring: SmartPrimitiveDocument,
+ ) -> SceneNode:
+ node_id = self._claim_id(data)
+ node = SceneNode(
+ node_id,
+ data.string("name"),
+ parent,
+ document_io.load_transform(data.object("local_transform", document_io.TRANSFORM_FIELDS)),
+ )
+ node.visible = data.boolean("visible")
+ node.translation_locks = data.bool_vector("translation_locks", 3)
+ node.rotation_locks = data.bool_vector("rotation_locks", 3)
+ euler_degrees = data.value("euler_degrees")
+ node.euler_degrees = (
+ None if euler_degrees is None else data.number_vector("euler_degrees", 3)
+ )
+ self.nodes[node.id] = node
+
+ components_location = data.field_location("components")
+ for index, value in enumerate(data.array("components")):
+ location = f"{components_location}[{index}]"
+ component_type = document_io.object_type(value, location)
+ if component_type == _TARGET_POSE_COMPONENT_TYPE:
+ if node.target_pose is not None:
+ raise SmartPrimitiveDocumentError(f"{data.location} contains more than one Target Pose.")
+ node.target_pose = self._load_target_pose_component(
+ DocumentObject(value, location, _TARGET_POSE_FIELDS), authoring,
+ )
+ elif component_type == _INTERACTION_BOX_COMPONENT_TYPE:
+ if node.interaction_box is not None:
+ raise SmartPrimitiveDocumentError(f"{data.location} contains more than one Interaction Box.")
+ node.interaction_box = self._load_interaction_box_component(
+ DocumentObject(value, location, _INTERACTION_BOX_FIELDS),
+ )
+ elif component_type == _PIVOT_COMPONENT_TYPE:
+ if node.pivot is not None:
+ raise SmartPrimitiveDocumentError(f"{data.location} contains more than one Pivot.")
+ node.pivot = self._load_pivot_component(DocumentObject(value, location, _PIVOT_FIELDS))
+ else:
+ raise SmartPrimitiveDocumentError(f"Unsupported component type {component_type!r} at {location}.")
+
+ for child_data in data.object_array("children", _NODE_FIELDS):
+ child = self._load_node(child_data, node, authoring)
+ node.children.append(child)
+ return node
+
+ def _load_pivot_component(self, data: DocumentObject) -> PivotComponent:
+ component = PivotComponent(self._claim_id(data))
+ try:
+ component.pivot = Pivot(
+ motion_direction=tuple(data.number_vector("motion_direction", 3)),
+ operation_order=OperationOrder(data.string("operation_order")),
+ translation_axis=Axis(data.string("translation_axis")),
+ translation_constraint=ConstraintType(data.string("translation_constraint")),
+ line_min_offset=data.number("line_min_offset"),
+ line_max_offset=data.number("line_max_offset"),
+ rotation_axis=Axis(data.string("rotation_axis")),
+ rotation_constraint=ConstraintType(data.string("rotation_constraint")),
+ cone_half_angle_degrees=data.number("cone_half_angle_degrees"),
+ cone_side=ConeSide(data.string("cone_side")),
+ )
+ except ValueError as exc:
+ raise SmartPrimitiveDocumentError(f"Invalid Pivot at {data.location}: {exc}") from exc
+ component.show_motion_direction = data.boolean("show_motion_direction")
+ component.show_translation_constraint = data.boolean("show_translation_constraint")
+ component.show_rotation_constraint = data.boolean("show_rotation_constraint")
+ return component
+
+ def _load_target_pose_component(
+ self,
+ data: DocumentObject,
+ authoring: SmartPrimitiveDocument,
+ ) -> TargetPoseComponent:
+ component_id = self._claim_id(data)
+ component = TargetPoseComponent(component_id, authoring.reference_pose, authoring.up_index)
+ playback_mode = self._load_playback_mode(data)
+ sample_time = data.number("sample_time_seconds")
+ if sample_time < 0.0:
+ raise SmartPrimitiveDocumentError(
+ f"{data.field_location('sample_time_seconds')} cannot be negative."
+ )
+ frame_index = data.integer("frame_index", minimum=0)
+ hips_constrained = data.boolean("hips_constrained")
+ self._load_target_pose_properties(component, data)
+
+ clip = self._load_clip(data)
+ self._validate_sample_position(
+ clip,
+ sample_time,
+ frame_index,
+ data.location,
+ )
+ component.restore_sample_state(
+ clip,
+ playback_mode,
+ sample_time,
+ frame_index,
+ hips_constrained,
+ )
+ return component
+
+ def _load_interaction_box_component(
+ self,
+ data: DocumentObject,
+ ) -> InteractionBoxComponent:
+ component = InteractionBoxComponent(self._claim_id(data))
+ dimension_fields = ("width", "depth", "height")
+ dimensions = [data.number(field) for field in dimension_fields]
+ for field, value in zip(dimension_fields, dimensions):
+ if value < 0.0:
+ raise SmartPrimitiveDocumentError(
+ f"{data.field_location(field)} cannot be negative."
+ )
+ component.set_dimensions(*dimensions)
+ component.color = data.color("color")
+ return component
+
+ @staticmethod
+ def _load_playback_mode(data: DocumentObject) -> PlaybackMode:
+ value = data.string("playback_mode")
+ try:
+ return PlaybackMode(value)
+ except ValueError as exc:
+ raise SmartPrimitiveDocumentError(
+ f"{data.field_location('playback_mode')} must be 'time' or 'frames'."
+ ) from exc
+
+ def _load_target_pose_properties(
+ self,
+ component: TargetPoseComponent,
+ data: DocumentObject,
+ ) -> None:
+ component.num_poses_to_use = data.integer(
+ "num_poses_to_use",
+ minimum=1,
+ maximum=MODEL_POSES_PER_TOKEN,
+ )
+ component.transition_early_by_frames = data.integer(
+ "transition_early_by_frames",
+ minimum=0,
+ maximum=MAX_TRANSITION_EARLY_BY_FRAMES,
+ )
+ component.min_tokens = data.integer("min_tokens", minimum=MODEL_MIN_TOKEN_COUNT, maximum=MODEL_MAX_TOKEN_COUNT)
+ component.max_tokens = data.integer("max_tokens", minimum=component.min_tokens, maximum=MODEL_MAX_TOKEN_COUNT)
+ ik_pin_mask = data.integer("ik_pin_mask", minimum=0)
+ if ik_pin_mask & ~int(IKPin.ALL):
+ raise SmartPrimitiveDocumentError(
+ f"{data.field_location('ik_pin_mask')} contains unsupported bits."
+ )
+ component.ik_pin_mask = IKPin(ik_pin_mask)
+ component.show_mesh = data.boolean("show_mesh")
+ component.show_skeletons = data.boolean("show_skeletons")
+ component.show_velocity = data.boolean("show_velocity")
+ component.show_trajectory = data.boolean("show_trajectory")
+
+ trajectory_scale = data.number("trajectory_scale")
+ try:
+ component.set_trajectory_scale(trajectory_scale)
+ except ValueError as exc:
+ raise SmartPrimitiveDocumentError(
+ f"{data.field_location('trajectory_scale')} must be "
+ f"{MIN_TRAJECTORY_SCALE:.1f} to {MAX_TRAJECTORY_SCALE:.1f}."
+ ) from exc
+
+ component.color = data.color("color")
+
+ @staticmethod
+ def _validate_sample_position(
+ clip: ClipAsset | None,
+ sample_time: float,
+ frame_index: int,
+ location: str,
+ ) -> None:
+ if clip is None:
+ if sample_time != 0.0 or frame_index != 0:
+ raise SmartPrimitiveDocumentError(
+ f"{location} cannot select a frame without a clip."
+ )
+ return
+
+ if frame_index > clip.last_frame:
+ raise SmartPrimitiveDocumentError(
+ f"{location}.frame_index exceeds the clip's last frame."
+ )
+ if sample_time > clip.duration + 1.0e-6:
+ raise SmartPrimitiveDocumentError(
+ f"{location}.sample_time_seconds exceeds the clip duration."
+ )
+
+ def _load_clip(self, data: DocumentObject) -> ClipAsset | None:
+ resolved_path = document_io.resolve_reference(data, "clip", self.document_path, kind="clip")
+ if resolved_path is None:
+ return None
+
+ try:
+ return self.clip_registry.load(resolved_path)
+ except ClipLoadError as exc:
+ raise SmartPrimitiveDocumentError(str(exc)) from exc
+
+
+def load_smart_primitive_rig(path: str | Path) -> ModelRig:
+ """Return the rig a document was saved for, reading only its header."""
+ _, rig, _, _ = SMART_PRIMITIVE_DOCUMENT.read(Path(path).expanduser().resolve(), _CONTENT_FIELDS)
+ return rig
+
+
+def load_smart_primitive_document(
+ clip_registry: ClipRegistry,
+ reference_pose: wp.array,
+ model_to_runtime: wp.transform,
+ path: str | Path,
+) -> tuple[SmartPrimitiveDocument, int, dict]:
+ """Load a document for the registry's rig, checking it before loading clips."""
+ return _SmartPrimitiveDocumentLoader(
+ clip_registry,
+ reference_pose,
+ model_to_runtime,
+ Path(path).expanduser().resolve(),
+ ).load()
+
+
+class SmartPrimitiveAssetPool:
+ """Load documents and clips once and share prepared data between runtime instances."""
+
+ def __init__(
+ self,
+ clip_registry: ClipRegistry,
+ reference_pose: wp.array,
+ model_to_runtime: wp.transform,
+ ) -> None:
+ """Create an empty pool for one rig's clip registry."""
+ self.clip_registry = clip_registry
+ self.reference_pose = reference_pose
+ self.device = clip_registry.device
+ self.model_to_runtime = wp.transform(model_to_runtime)
+ self._assets: dict[Path, SmartPrimitiveAsset] = {}
+
+ def load(self, path: str | Path) -> SmartPrimitiveAsset:
+ """Return the Smart Primitive asset for path, preparing it on first use."""
+ resolved_path = Path(path).expanduser().resolve()
+ asset = self._assets.get(resolved_path)
+ if asset is None:
+ with wp.ScopedDevice(self.device):
+ authoring, _, _ = load_smart_primitive_document(
+ self.clip_registry,
+ self.reference_pose,
+ self.model_to_runtime,
+ resolved_path,
+ )
+ asset = SmartPrimitiveAsset(
+ build_runtime_smart_primitive_data(authoring), device=self.device,
+ )
+ self._assets[resolved_path] = asset
+ return asset
+
+ def instantiate(
+ self,
+ path: str | Path,
+ smart_primitive_type: type[SmartPrimitive] = SmartPrimitive,
+ ) -> SmartPrimitive:
+ """Return a new Smart Primitive instance of smart_primitive_type that shares the asset at path."""
+ return smart_primitive_type(self.load(path))
diff --git a/app/runtime/common/motion.py b/app/runtime/common/motion.py
new file mode 100644
index 0000000..dedb7d2
--- /dev/null
+++ b/app/runtime/common/motion.py
@@ -0,0 +1,510 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Locomotion modes, movement smoothing, and clip data for the characters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import math
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import MODEL_MAX_TOKEN_COUNT, MODEL_MIN_TOKEN_COUNT, MODEL_POSES_PER_TOKEN, ModelRig
+from motionbricks.runtime.blend_spaces import BlendSpace, BlendSpaceType, prepare_directional_poses
+from motionbricks.utils.math_utils import critical_spring_angle, critical_spring_damper_exact, project_to_plane
+
+if TYPE_CHECKING:
+ from motionbricks.animation.animation_buffer import AnimationBuffer
+ from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+ from .io.smart_primitive_document import SmartPrimitiveAssetPool
+
+
+# Directions, speeds, and input lengths at or below this count as zero.
+MOVEMENT_EPSILON = 1.0e-6
+
+LINEAR_LOCOMOTION_MODE = "linear_1d"
+DIRECTIONAL_LOCOMOTION_MODE = "directional_2d"
+CROUCH_LOCOMOTION_MODE = "crouch_directional_2d"
+
+# Strafing and Crouching share these targets, with Idle first.
+DIRECTIONAL_TARGET_VALUES = (
+ ("Idle", (0.0, 0.0)),
+ ("Forward", (1.0, 0.0)),
+ ("Backward", (-1.0, 0.0)),
+ ("Left", (0.0, 1.0)),
+ ("Right", (0.0, -1.0)),
+)
+
+# Clips face -Y at their start, once model_to_runtime is applied.
+CLIP_FACING_YAW = -0.5 * math.pi
+
+
+class PlaybackSource(Enum):
+ """Where the character's current pose comes from."""
+
+ GENERATED = "generated"
+ CLIP_TRANSITION = "clip_transition"
+ CLIP = "clip"
+
+
+@dataclass(frozen=True, slots=True)
+class LocomotionCommand:
+ """What the controls ask the character to do this frame.
+
+ Attributes:
+ facing_direction: Ground direction the character faces in the 2D modes, in world
+ space. Scene Preview passes the camera direction.
+ movement: Movement input along the ground in world space. Its length is the input
+ strength from 0 to 1. None, or a length of about zero, means no movement.
+ use_max_speed: Base the speed on the mode's maximum speed instead of its default
+ speed.
+ requested_mode: Name of the mode to switch to. None keeps the current mode.
+ """
+
+ facing_direction: np.ndarray
+ movement: np.ndarray | None
+ use_max_speed: bool = False
+ requested_mode: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LocomotionSettings:
+ """How quickly movement responds to input and when to generate new motion."""
+
+ facing_halflife: float = 0.15
+ velocity_direction_halflife: float = 0.2
+ speed_acceleration_halflife: float = 0.6
+ speed_deceleration_halflife: float = 0.4
+ speed_regeneration_fraction: float = 0.3
+ minimum_speed_regeneration_fraction: float = 0.1
+ direction_regeneration_dot: float = 0.92
+ maximum_direction_change_speed_reduction: float = 0.25
+
+
+@dataclass(frozen=True, slots=True)
+class LocomotionMode:
+ """Blend targets, blend space settings, and speed limits for one locomotion mode.
+
+ Attributes:
+ name: Mode name, such as linear_1d.
+ smart_primitive_path: Smart Primitive document that holds the blend targets.
+ blend_space_type: 1D blend space or 2D directional blend space.
+ target_values: Name and blend value of each blend target.
+ max_speed: Maximum speed in m/s.
+ default_speed: Speed when input does not request maximum speed, in m/s.
+ minimum_speed: Slowest speed while there is movement input, in m/s.
+ transition_early_by_frames: Transition Early By for each generation.
+ allowed_token_counts: Token counts the model may choose.
+ velocity_scale: Scale on the desired velocity for target speed and placement.
+ position_scale: How far ahead the targets sit, in seconds of travel at the scaled
+ desired velocity.
+ label: Name shown in the apps.
+ """
+
+ name: str
+ smart_primitive_path: Path
+ blend_space_type: BlendSpaceType
+ target_values: tuple[tuple[str, tuple[float, float]], ...]
+ max_speed: float
+ default_speed: float
+ minimum_speed: float = 0.0
+ transition_early_by_frames: int = 8
+ allowed_token_counts: tuple[int, ...] = tuple(range(8, 15))
+ velocity_scale: float = 1.0
+ position_scale: float = 1.0
+ label: str = ""
+
+ def __post_init__(self) -> None:
+ if not self.name:
+ raise ValueError("Locomotion mode name cannot be empty.")
+ if not self.target_values:
+ raise ValueError("Locomotion mode target_values cannot be empty.")
+ if self.max_speed <= 0.0:
+ raise ValueError("Locomotion mode max_speed must be positive.")
+ if not 0.0 < self.default_speed <= self.max_speed:
+ raise ValueError("Locomotion mode default_speed must be positive and at most max_speed.")
+ if not 0.0 <= self.minimum_speed <= self.default_speed:
+ raise ValueError("Locomotion mode minimum_speed must be 0 to default_speed.")
+ if self.transition_early_by_frames < 0:
+ raise ValueError("Locomotion mode transition_early_by_frames cannot be negative.")
+ if self.velocity_scale < 0.0:
+ raise ValueError("Locomotion mode velocity_scale cannot be negative.")
+ if self.position_scale < 0.0:
+ raise ValueError("Locomotion mode position_scale cannot be negative.")
+ if not self.allowed_token_counts:
+ raise ValueError("Locomotion mode allowed_token_counts cannot be empty.")
+ if not all(MODEL_MIN_TOKEN_COUNT <= count <= MODEL_MAX_TOKEN_COUNT for count in self.allowed_token_counts):
+ raise ValueError(
+ f"Locomotion mode allowed_token_counts must be {MODEL_MIN_TOKEN_COUNT} to {MODEL_MAX_TOKEN_COUNT}."
+ )
+
+
+def style_locomotion_mode(
+ target: str,
+ smart_primitive_path: Path,
+ minimum_speed: float,
+ max_speed: float,
+ *,
+ velocity_scale: float = 1.0,
+ position_scale: float = 1.5,
+ transition_early_by_frames: int = 2,
+ allowed_token_counts: tuple[int, ...] = tuple(range(6, 16)),
+) -> LocomotionMode:
+ """Return a 1D mode that blends from the Idle target at 0 to the style target at 1.
+
+ Args:
+ target: Name of the style's blend target, such as Skipping. It also names the
+ mode, as in skipping_1d.
+ smart_primitive_path: Smart Primitive document that holds Idle and the style
+ target.
+ minimum_speed: Slowest speed while there is movement input, in m/s.
+ max_speed: Maximum speed and default speed, in m/s. The style pose shows in full
+ at this speed.
+ velocity_scale: Scale on the desired velocity for target speed and placement.
+ position_scale: How far ahead the targets sit, in seconds of travel at the scaled
+ desired velocity. The default keeps each style close to the speed of its clip.
+ transition_early_by_frames: Transition Early By. The default lets the motion come
+ close to the style pose.
+ allowed_token_counts: Token counts the model may choose.
+ """
+ return LocomotionMode(
+ name=f"{target.lower().replace(' ', '_')}_1d",
+ smart_primitive_path=smart_primitive_path,
+ blend_space_type=BlendSpaceType.LINEAR_1D,
+ target_values=(("Idle", (0.0, 0.0)), (target, (1.0, 0.0))),
+ max_speed=max_speed,
+ default_speed=max_speed,
+ minimum_speed=minimum_speed,
+ transition_early_by_frames=transition_early_by_frames,
+ allowed_token_counts=allowed_token_counts,
+ velocity_scale=velocity_scale,
+ position_scale=position_scale,
+ label=target,
+ )
+
+
+@dataclass(slots=True)
+class AnimationClip:
+ """A loaded clip and the data used to place it in world space."""
+
+ animation: AnimationBuffer | DOFAnimationBuffer
+ source_ground: wp.transform
+ duration: float
+ root_offset: wp.transform
+ root_positions: np.ndarray
+
+
+def make_animation_clip(
+ animation: AnimationBuffer | DOFAnimationBuffer,
+ model_to_runtime: wp.transform,
+) -> AnimationClip:
+ """Describe a clip and where it starts on the ground."""
+ # The roots are in source coordinates.
+ roots = animation.root_transforms()
+ first_root = wp.transform(*roots[0])
+ return AnimationClip(
+ animation=animation,
+ source_ground=project_to_plane(wp.mul(model_to_runtime, first_root), wp.vec3(0.0, 0.0, 1.0)),
+ duration=max(animation.num_frames - 1, 1) / animation.sample_rate,
+ root_offset=wp.transform_identity(),
+ root_positions=roots[:, :3].copy(),
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class LocomotionModeRuntime:
+ """The blend space and target poses used by a locomotion mode."""
+
+ definition: LocomotionMode
+ blend_space: BlendSpace
+ target_poses: wp.array
+
+
+def load_locomotion_mode(
+ mode: LocomotionMode,
+ asset_pool: SmartPrimitiveAssetPool,
+) -> LocomotionModeRuntime:
+ """Load a mode's target poses from its Smart Primitive and build its blend space."""
+ smart_primitive = asset_pool.instantiate(mode.smart_primitive_path)
+ reference_pose = asset_pool.reference_pose
+ target_poses = wp.empty(
+ (len(mode.target_values), MODEL_POSES_PER_TOKEN, *reference_pose.shape),
+ dtype=reference_pose.dtype,
+ device=asset_pool.device,
+ )
+ blend_space = BlendSpace(mode.blend_space_type, device=asset_pool.device)
+ for data_index, (node_name, value) in enumerate(mode.target_values):
+ node_index = smart_primitive.node_index(node_name)
+ if node_index < 0 or not smart_primitive.has_target_pose(node_index):
+ raise ValueError(
+ f"The {mode.name!r} Smart Primitive has no target named {node_name!r}."
+ )
+ params = smart_primitive.get_local_target_poses(node_index, target_poses[data_index])
+ # Blending mixes whole targets, so every locomotion target needs all four poses.
+ if params.num_poses_to_use != MODEL_POSES_PER_TOKEN:
+ raise ValueError(
+ f"The {mode.name!r} target {node_name!r} must use {MODEL_POSES_PER_TOKEN} poses."
+ )
+ blend_space.add_target(wp.vec2(*value), data_index)
+ blend_space.compile()
+ if smart_primitive.rig is ModelRig.SOMA and mode.blend_space_type is BlendSpaceType.DIRECTIONAL_2D:
+ prepare_directional_poses(target_poses, reference_pose)
+ return LocomotionModeRuntime(mode, blend_space, target_poses)
+
+
+def ground_direction(
+ direction: np.ndarray,
+ fallback: np.ndarray,
+) -> np.ndarray:
+ """Return a ground direction of length one, using fallback when needed."""
+
+ for candidate in (direction, fallback):
+ ground = np.array(
+ [float(candidate[0]), float(candidate[1]), 0.0],
+ dtype=np.float32,
+ )
+ length = float(np.linalg.norm(ground))
+ if np.isfinite(length) and length > MOVEMENT_EPSILON:
+ return ground / length
+ raise ValueError("direction and fallback have no valid ground direction.")
+
+
+def character_start_position_and_facing(
+ transform: wp.transform,
+) -> tuple[np.ndarray, np.ndarray]:
+ """Return the ground position and facing of a scene's CharacterStart."""
+ ground_transform = project_to_plane(transform, wp.vec3(0.0, 0.0, 1.0))
+ position = np.array(ground_transform.p, dtype=np.float32)
+ world_facing = wp.transform_vector(ground_transform, wp.vec3(1.0, 0.0, 0.0))
+ facing = ground_direction(
+ np.array(world_facing, dtype=np.float32),
+ np.array([1.0, 0.0, 0.0], dtype=np.float32),
+ )
+ return position, facing
+
+
+def directional_blend_space_value(
+ facing_direction: np.ndarray,
+ desired_velocity: np.ndarray,
+ max_speed: float,
+) -> wp.vec2:
+ """Express movement as a forward and left blend value relative to facing."""
+ normalized_velocity = desired_velocity / max_speed
+ facing_left = np.array(
+ [-facing_direction[1], facing_direction[0], 0.0],
+ dtype=np.float32,
+ )
+ return wp.vec2(
+ float(np.clip(np.dot(normalized_velocity, facing_direction), -1.0, 1.0)),
+ float(np.clip(np.dot(normalized_velocity, facing_left), -1.0, 1.0)),
+ )
+
+
+def _speed_reduction_scale(speed: float, max_speed: float, maximum_reduction: float) -> float:
+ speed_fraction = min(max(speed / max_speed, 0.0), 1.0)
+ return 1.0 - maximum_reduction * speed_fraction
+
+
+class MovementControl:
+ """Smooth movement commands into the desired velocity and facing.
+
+ Critically damped springs ease the speed, the velocity direction, and the
+ facing. Locomotion places its targets from desired_velocity and current_facing.
+ Directions lie on the ground in world space. Speeds are in meters per second,
+ and angles in radians.
+
+ Attributes:
+ settings: Spring half lives, and the speed reduction on sharp turns.
+ input_speed: Speed the movement input asks for. It is 0 without movement input.
+ input_velocity_direction: Direction of the latest movement input.
+ desired_facing: Facing that current_facing turns toward.
+ last_input_facing: Facing at the latest movement input. Idle clips face
+ this way.
+ current_facing: Smoothed facing. current_facing_angle and current_facing_rate
+ hold its angle and turn rate.
+ desired_velocity_direction: Smoothed velocity direction.
+ desired_velocity_angle and desired_velocity_direction_rate hold its angle
+ and turn rate.
+ desired_speed: Smoothed speed the character aims for. desired_speed_rate holds
+ its rate of change.
+ desired_velocity: desired_velocity_direction times desired_speed.
+ """
+
+ def __init__(self, facing: np.ndarray, settings: LocomotionSettings = LocomotionSettings()) -> None:
+ """Start at rest, facing along the ground direction facing."""
+ self.settings = settings
+ angle = math.atan2(float(facing[1]), float(facing[0]))
+ self.input_speed = 0.0
+ self.input_velocity_direction = facing.copy()
+ self.desired_facing = facing.copy()
+ self.last_input_facing = facing.copy()
+ self.current_facing = facing.copy()
+ self.current_facing_angle = angle
+ self.current_facing_rate = 0.0
+ self.desired_velocity_direction = facing.copy()
+ self.desired_velocity_angle = angle
+ self.desired_velocity_direction_rate = 0.0
+ self.desired_speed = 0.0
+ self.desired_speed_rate = 0.0
+ self.desired_velocity = np.zeros(3, dtype=np.float32)
+
+ @property
+ def input_velocity(self) -> np.ndarray:
+ """Input velocity on the ground before smoothing, in meters per second."""
+ return self.input_velocity_direction * self.input_speed
+
+ def update(
+ self,
+ command: LocomotionCommand,
+ mode: LocomotionMode,
+ delta_time: float,
+ previous_mode: LocomotionMode | None = None,
+ ) -> None:
+ """Apply one frame of movement input for the active mode.
+
+ previous_mode is the mode this frame switched away from, or None. The switch
+ eases in.
+ """
+ self._read_input(command, mode)
+ if previous_mode is not None:
+ self._ease_mode_switch(mode, previous_mode)
+ self._smooth(mode, delta_time)
+
+ def realign(self, velocity: np.ndarray, mode: LocomotionMode) -> None:
+ """Resume locomotion from the character's actual velocity. The input stays as it is."""
+ speed = float(np.linalg.norm(velocity[:2]))
+ direction = ground_direction(velocity, self.current_facing)
+ angle = math.atan2(direction[1], direction[0])
+ self.desired_speed = speed
+ self.desired_speed_rate = 0.0
+ self.desired_velocity_direction[:] = direction
+ self.desired_velocity_angle = angle
+ self.desired_velocity_direction_rate = 0.0
+ np.multiply(direction, speed, out=self.desired_velocity)
+ if mode.blend_space_type is BlendSpaceType.LINEAR_1D:
+ self._set_current_facing(direction, angle, 0.0)
+
+ def face(self, direction: np.ndarray) -> None:
+ """Set every facing to direction at once."""
+ self.desired_facing = direction.copy()
+ self.last_input_facing = direction.copy()
+ self._set_current_facing(direction, math.atan2(float(direction[1]), float(direction[0])), 0.0)
+
+ def reset_desired_velocity(self) -> None:
+ """Reset the desired velocity and the desired speed to zero."""
+ self.desired_speed = 0.0
+ self.desired_speed_rate = 0.0
+ self.desired_velocity.fill(0.0)
+
+ def _set_current_facing(self, direction: np.ndarray, angle: float, rate: float) -> None:
+ self.current_facing[:] = direction
+ self.current_facing_angle = angle
+ self.current_facing_rate = rate
+
+ def _read_input(self, command: LocomotionCommand, mode: LocomotionMode) -> None:
+ facing_direction = ground_direction(command.facing_direction, self.desired_facing)
+ movement_amount = 0.0 if command.movement is None else float(np.linalg.norm(command.movement[:2]))
+ # Written as "not above", so a NaN input also counts as no movement.
+ if not movement_amount > MOVEMENT_EPSILON:
+ if mode.blend_space_type is BlendSpaceType.DIRECTIONAL_2D or self.desired_speed <= 0.0:
+ self.desired_facing = facing_direction
+ self.input_speed = 0.0
+ return
+
+ movement_direction = ground_direction(command.movement, self.input_velocity_direction)
+ self.input_velocity_direction = movement_direction
+ # 1D modes face the way they move. The 2D modes, Strafing and Crouching, face the camera direction.
+ self.desired_facing = (
+ movement_direction if mode.blend_space_type is BlendSpaceType.LINEAR_1D else facing_direction
+ )
+ self.last_input_facing = self.desired_facing.copy()
+ requested_speed = mode.max_speed if command.use_max_speed else mode.default_speed
+ self.input_speed = max(requested_speed * min(movement_amount, 1.0), mode.minimum_speed)
+
+ def _ease_mode_switch(self, mode: LocomotionMode, previous_mode: LocomotionMode) -> None:
+ if mode.blend_space_type is BlendSpaceType.DIRECTIONAL_2D:
+ facing = self.desired_facing
+ self._set_current_facing(facing, math.atan2(facing[1], facing[0]), 0.0)
+ # A switch to a mode that is not faster slows down a little, as a sharp turn does.
+ if mode.max_speed <= previous_mode.max_speed:
+ speed_scale = _speed_reduction_scale(
+ self.desired_speed, mode.max_speed, self.settings.maximum_direction_change_speed_reduction,
+ )
+ self.desired_speed = min(self.desired_speed * speed_scale, mode.max_speed)
+ self.desired_speed_rate *= speed_scale
+
+ def _smooth(self, mode: LocomotionMode, delta_time: float) -> None:
+ settings = self.settings
+ self.desired_velocity_angle, self.desired_velocity_direction_rate = critical_spring_angle(
+ self.desired_velocity_angle,
+ self.desired_velocity_direction_rate,
+ self.input_velocity_direction,
+ settings.velocity_direction_halflife,
+ delta_time,
+ )
+ self.desired_velocity_direction[0] = math.cos(self.desired_velocity_angle)
+ self.desired_velocity_direction[1] = math.sin(self.desired_velocity_angle)
+
+ if mode.blend_space_type is BlendSpaceType.LINEAR_1D:
+ self._set_current_facing(
+ self.desired_velocity_direction, self.desired_velocity_angle, self.desired_velocity_direction_rate,
+ )
+ else:
+ self.current_facing_angle, self.current_facing_rate = critical_spring_angle(
+ self.current_facing_angle,
+ self.current_facing_rate,
+ self.desired_facing,
+ settings.facing_halflife,
+ delta_time,
+ )
+ self.current_facing[0] = math.cos(self.current_facing_angle)
+ self.current_facing[1] = math.sin(self.current_facing_angle)
+
+ # A sharp turn slows the character until the velocity direction catches up.
+ speed_goal = self.input_speed
+ turn_dot = float(np.dot(self.desired_velocity_direction, self.input_velocity_direction))
+ if turn_dot < settings.direction_regeneration_dot:
+ speed_goal *= _speed_reduction_scale(
+ self.desired_speed, mode.max_speed, settings.maximum_direction_change_speed_reduction,
+ )
+ speed_halflife = (
+ settings.speed_acceleration_halflife
+ if speed_goal > self.desired_speed
+ else settings.speed_deceleration_halflife
+ )
+ self.desired_speed, self.desired_speed_rate = critical_spring_damper_exact(
+ self.desired_speed, self.desired_speed_rate, speed_goal, speed_halflife, delta_time,
+ )
+ if self.desired_speed > mode.max_speed:
+ self.desired_speed = mode.max_speed
+ self.desired_speed_rate = min(self.desired_speed_rate, 0.0)
+ np.multiply(self.desired_velocity_direction, self.desired_speed, out=self.desired_velocity)
+
+
+__all__ = [
+ "AnimationClip",
+ "CLIP_FACING_YAW",
+ "CROUCH_LOCOMOTION_MODE",
+ "DIRECTIONAL_LOCOMOTION_MODE",
+ "DIRECTIONAL_TARGET_VALUES",
+ "LINEAR_LOCOMOTION_MODE",
+ "LocomotionCommand",
+ "LocomotionMode",
+ "LocomotionModeRuntime",
+ "LocomotionSettings",
+ "MOVEMENT_EPSILON",
+ "MovementControl",
+ "PlaybackSource",
+ "character_start_position_and_facing",
+ "directional_blend_space_value",
+ "make_animation_clip",
+ "load_locomotion_mode",
+ "ground_direction",
+ "style_locomotion_mode",
+]
diff --git a/app/runtime/common/rig.py b/app/runtime/common/rig.py
new file mode 100644
index 0000000..3f7b8a5
--- /dev/null
+++ b/app/runtime/common/rig.py
@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Load each rig's character and clip registry, place its model space in world space, and draw it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import warp as wp
+
+import motionbricks.io.utils as io_utils
+from motionbricks.model.contract import ModelRig
+from motionbricks.model.soma.contract import SOMA_N1_FOOT_CONTACT_JOINTS
+from motionbricks.model.unitree_g1.contract import (
+ UNITREE_G1_N1_CONTRACT,
+ UNITREE_G1_N1_FOOT_CONTACT_BODIES,
+ UNITREE_G1_N1_FOOT_CONTACT_OFFSETS,
+)
+from motionbricks.renderers.dof_mesh_renderer import DOFMeshRenderer
+from motionbricks.renderers.foot_contact_renderer import (
+ DOFFootContactRenderer,
+ SkeletonFootContactRenderer,
+ body_sole_outlines,
+ skeletal_mesh_sole_outlines,
+)
+from motionbricks.renderers.skeletal_mesh_renderer import SkeletalMeshRenderer
+from motionbricks.renderers.skeleton_renderer import DOFSkeletonRenderer, SkeletonRenderer
+from motionbricks.utils.space_conversion_utils import FacingDirectionType, SpaceConverter
+
+from .clip_registry import ClipRegistry
+
+if TYPE_CHECKING:
+ import newton
+
+ from motionbricks.animation.mesh import SkeletalMesh
+
+
+# The repository's assets folder, separate from the assets of the motionbricks package.
+ASSETS_ROOT = Path(__file__).resolve().parents[3] / "assets"
+RIG_LABELS = {ModelRig.SOMA: "SOMA", ModelRig.UNITREE_G1: "Unitree G1"}
+# SOMA draws in gray. None draws the robot in its own colors.
+CHARACTER_COLORS = {ModelRig.SOMA: wp.vec3(0.7, 0.7, 0.7), ModelRig.UNITREE_G1: None}
+
+
+def model_to_runtime(rig: ModelRig) -> wp.transform:
+ """Return the transform from a rig's model space to world space, which is Z up.
+
+ SOMA model space and BVH clips are Y up. The MuJoCo convention turns them to
+ face the same way as G1 and its CSV clips, which need no conversion.
+ """
+ if rig is ModelRig.SOMA:
+ return SpaceConverter(FacingDirectionType.MUJOCO).convert_transform(wp.transform_identity())
+ return wp.transform_identity()
+
+
+@dataclass(frozen=True)
+class RigAssets:
+ """What load_rig_assets() loads for one rig.
+
+ Attributes:
+ model: The SOMA skeletal mesh, or the G1 Newton model.
+ clip_registry: Registry for the rig's clips. It starts empty.
+ reference_pose: Reference pose of the rig. It sets the pose layout.
+ model_to_runtime: Transform from the rig's model space to world space.
+ """
+
+ model: SkeletalMesh | newton.Model
+ clip_registry: ClipRegistry
+ reference_pose: wp.array
+ model_to_runtime: wp.transform
+
+
+def load_rig_assets(rig: ModelRig) -> RigAssets:
+ """Load a rig's skeletal mesh or Newton model, and create an empty clip registry for it."""
+ if rig is ModelRig.SOMA:
+ skeletal_mesh = io_utils.get_soma_human_model()
+ return RigAssets(
+ skeletal_mesh,
+ ClipRegistry(rig, skeleton=skeletal_mesh.skeleton),
+ skeletal_mesh.skeleton.reference_local_transforms,
+ model_to_runtime(rig),
+ )
+ robot = io_utils.get_unitree_g1_model()
+ return RigAssets(
+ robot,
+ ClipRegistry(rig, joint_names=UNITREE_G1_N1_CONTRACT.joint_names),
+ wp.clone(robot.joint_q),
+ model_to_runtime(rig),
+ )
+
+
+def create_mesh_renderer(rig: ModelRig, model) -> SkeletalMeshRenderer | DOFMeshRenderer:
+ """Create the renderer that draws the rig's skeletal mesh or robot.
+
+ Args:
+ rig: Rig of the model.
+ model: The SOMA skeletal mesh, or the G1 Newton model.
+ """
+ if rig is ModelRig.SOMA:
+ renderer = SkeletalMeshRenderer(model)
+ # Draw relaxed fingers. The pose data keeps the motion's fingers.
+ renderer.set_override_pose("RelaxedHands", mask="Fingers")
+ return renderer
+ return DOFMeshRenderer(model)
+
+
+def create_skeleton_renderer(rig: ModelRig, model, *, max_instances: int = 1) -> SkeletonRenderer | DOFSkeletonRenderer:
+ """Create the renderer that draws the rig's poses as bone lines.
+
+ Args:
+ rig: Rig of the model.
+ model: The SOMA skeletal mesh, or the G1 Newton model.
+ max_instances: Number of poses one draw call can hold.
+ """
+ if rig is ModelRig.SOMA:
+ return SkeletonRenderer(model.skeleton, max_instances=max_instances)
+ return DOFSkeletonRenderer(model, max_instances=max_instances)
+
+
+def create_foot_contact_renderer(
+ rig: ModelRig, name: str, model,
+) -> SkeletonFootContactRenderer | DOFFootContactRenderer:
+ """Create the renderer that draws the rig's foot contacts on its soles.
+
+ Args:
+ rig: Rig of the model.
+ name: Viewer name of the outline lines.
+ model: The SOMA skeletal mesh, or the G1 Newton model.
+ """
+ if rig is ModelRig.SOMA:
+ return SkeletonFootContactRenderer(
+ name, model.skeleton, skeletal_mesh_sole_outlines(model, SOMA_N1_FOOT_CONTACT_JOINTS),
+ )
+ return DOFFootContactRenderer(
+ name, model, body_sole_outlines(model, UNITREE_G1_N1_FOOT_CONTACT_BODIES, UNITREE_G1_N1_FOOT_CONTACT_OFFSETS),
+ )
+
+
+__all__ = [
+ "ASSETS_ROOT",
+ "CHARACTER_COLORS",
+ "RIG_LABELS",
+ "RigAssets",
+ "create_foot_contact_renderer",
+ "create_mesh_renderer",
+ "create_skeleton_renderer",
+ "load_rig_assets",
+ "model_to_runtime",
+]
diff --git a/app/runtime/common/smart_primitive_behaviors.py b/app/runtime/common/smart_primitive_behaviors.py
new file mode 100644
index 0000000..3b8d655
--- /dev/null
+++ b/app/runtime/common/smart_primitive_behaviors.py
@@ -0,0 +1,172 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Example behaviors that scenes choose for each Smart Primitive by class name."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import ModelRig
+from motionbricks.runtime.smart_primitive import CharacterProperties, SmartPrimitive, SmartPrimitiveAsset
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+
+from .rig import ASSETS_ROOT
+
+if TYPE_CHECKING:
+ from .states import InteractionState
+
+
+_MOTION_ROOT = ASSETS_ROOT / "motions"
+_SITTING_CLIPS = {
+ ModelRig.SOMA: _MOTION_ROOT / "soma/sitting/sit_on_chair_loop.bvh",
+ ModelRig.UNITREE_G1: _MOTION_ROOT / "unitree_g1/sitting/sit_on_chair_loop.csv",
+}
+
+
+class SmartPrimitiveBehavior(SmartPrimitive):
+ """Define how a character interacts with this Smart Primitive.
+
+ Scenes choose a subclass by its class name. Every subclass appears in the
+ Scene Editor's Behavior list once its module is imported.
+
+ Override enter() to start a target pose sequence or a clip.
+ Override interact() to respond when the user interacts again.
+ Use self.interaction_state to play sequences and clips or finish the interaction.
+
+ By default, the character follows the targets from get_targets(),
+ then returns to locomotion or idle.
+ """
+
+ required_sequences: tuple[str, ...] = ()
+ clip_paths: tuple[Path, ...] = ()
+
+ def __init__(self, asset: SmartPrimitiveAsset) -> None:
+ """Create the runtime instance, and check that the required sequences exist."""
+ super().__init__(asset)
+ self._interaction_state: InteractionState | None = None
+ for name in self.required_sequences:
+ if self.sequence_index(name) < 0:
+ raise ValueError(f"{type(self).__name__} requires sequence {name!r}.")
+
+ @property
+ def interaction_state(self) -> InteractionState:
+ """Interaction state that runs this behavior while it is active."""
+ if self._interaction_state is None:
+ raise RuntimeError("Cannot access the interaction state without an active interaction.")
+ return self._interaction_state
+
+ def bind(self, interaction_state: InteractionState) -> None:
+ """Give the behavior the interaction state that runs it. Interactions call this on entry."""
+ self._interaction_state = interaction_state
+
+ def unbind(self) -> None:
+ """Release the interaction state. Interactions call this on exit."""
+ self._interaction_state = None
+
+ def get_targets(
+ self,
+ character_properties: CharacterProperties,
+ output_target_poses: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> tuple[TargetPoseInferenceParams, ...]:
+ """Write an interaction's targets and return their generation settings.
+
+ The base class returns no targets. Subclasses select their targets, update the
+ hierarchy, and write the poses in the same order as the returned settings.
+
+ Args:
+ character_properties: The approaching character.
+ output_target_poses: Array that receives four poses per target.
+ stream: Stream for the work. None uses the current stream.
+ """
+ return ()
+
+ def enter(self) -> None:
+ """Start the interaction.
+
+ The default plays the sequence that get_targets() chooses.
+ """
+ self.interaction_state.play_target_pose_sequence()
+
+ def interact(self) -> None:
+ """Respond when the user interacts again before this behavior has finished."""
+
+
+class VelocityMatchingSequenceBehavior(SmartPrimitiveBehavior):
+ """Pick the sequence closest to the character's speed, then align its pivot."""
+
+ def __init__(self, asset: SmartPrimitiveAsset) -> None:
+ """Create the runtime instance. The document needs at least one sequence."""
+ super().__init__(asset)
+ if self.sequence_count == 0:
+ raise ValueError("Velocity Matching Sequence behavior requires at least one Target Pose sequence.")
+
+ def get_targets(
+ self,
+ character_properties: CharacterProperties,
+ output_target_poses: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> tuple[TargetPoseInferenceParams, ...]:
+ character_speed = float(
+ np.linalg.norm(character_properties.velocity)
+ )
+ sequence_index = min(
+ range(self.sequence_count),
+ key=lambda index: abs(
+ self.sequence_start_speed(index) - character_speed
+ ),
+ )
+ self.align_sequence_pivot(sequence_index, character_properties, stream)
+ return self.get_world_target_poses_for_sequence(
+ sequence_index,
+ output_target_poses,
+ stream,
+ )
+
+
+class SittingBehavior(SmartPrimitiveBehavior):
+ """Sit down, stay seated, and stand up when the user interacts again."""
+
+ required_sequences = ("Sit", "Stand")
+
+ @property
+ def clip_paths(self) -> tuple[Path, ...]:
+ """The rig's looping sitting clip."""
+ return (_SITTING_CLIPS[self.rig],)
+
+ def enter(self) -> None:
+ self.interaction_state.play_target_pose_sequence("Sit", on_complete=self._start_sitting)
+
+ def _start_sitting(self) -> None:
+ self.interaction_state.play_clip(_SITTING_CLIPS[self.rig], loop=True, align_to_current_pose=True)
+
+ def interact(self) -> None:
+ if self.interaction_state.is_looping:
+ self.interaction_state.play_target_pose_sequence("Stand")
+
+
+def behavior_types(
+ base: type[SmartPrimitiveBehavior] = SmartPrimitiveBehavior,
+) -> dict[str, type[SmartPrimitiveBehavior]]:
+ """Find every subclass of base by class name, in definition order.
+
+ A subclass is found once its module has been imported.
+ """
+ types = {}
+ for behavior in base.__subclasses__():
+ types[behavior.__name__] = behavior
+ types.update(behavior_types(behavior))
+ return types
+
+
+__all__ = [
+ "SmartPrimitiveBehavior",
+ "VelocityMatchingSequenceBehavior",
+ "SittingBehavior",
+ "behavior_types",
+]
diff --git a/app/runtime/common/state_machine.py b/app/runtime/common/state_machine.py
new file mode 100644
index 0000000..7dac6b3
--- /dev/null
+++ b/app/runtime/common/state_machine.py
@@ -0,0 +1,218 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""State machines that switch a character between idle, locomotion, and interactions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import warp as wp
+
+from .motion import (
+ CROUCH_LOCOMOTION_MODE,
+ DIRECTIONAL_LOCOMOTION_MODE,
+ LINEAR_LOCOMOTION_MODE,
+ AnimationClip,
+ LocomotionCommand,
+ LocomotionModeRuntime,
+)
+from .states import IdleState, InteractionState, LocomotionState, State
+
+# A crouching character is shorter, so its probe box is this fraction as tall.
+_CROUCH_PROBE_HEIGHT_SCALE = 0.6
+
+
+@dataclass(frozen=True, slots=True)
+class _MovementStatePair:
+ idle: IdleState
+ locomotion: LocomotionState
+ probe_box_height_scale: float = 1.0
+
+
+class StateMachine:
+ """Switch between idle, locomotion, and interactions while standing or crouching.
+
+ The caller loads the locomotion modes and the idle clips. The states generate
+ motion, and this machine decides which one runs. A state change exits the old
+ state before it enters the new one.
+ """
+
+ def __init__(
+ self,
+ mode_runtimes: tuple[LocomotionModeRuntime, ...],
+ initial_mode: str = LINEAR_LOCOMOTION_MODE,
+ *,
+ standing_idle_clips: tuple[AnimationClip, ...],
+ crouching_idle_clips: tuple[AnimationClip, ...],
+ pose: wp.array,
+ ) -> None:
+ """Create the idle and locomotion states for standing and crouching.
+
+ The interaction state is shared by both. The state machine starts in the idle state
+ of initial_mode. Call start() to begin its idle loop.
+
+ Args:
+ mode_runtimes: Loaded locomotion modes. They must include Forward, Strafing,
+ and Crouching. Any other mode is a standing style mode, listed in
+ style_modes in the order given.
+ initial_mode: Name of the mode to start in.
+ standing_idle_clips: Looping clips for the standing idle state.
+ crouching_idle_clips: Looping clips for the crouching idle state.
+ pose: Pose with the layout of the character's poses. It sizes the target
+ pose buffers.
+ """
+ modes_by_name = {runtime.definition.name: runtime for runtime in mode_runtimes}
+ if len(modes_by_name) != len(mode_runtimes):
+ raise ValueError("Locomotion mode names must be unique.")
+
+ core_names = (
+ LINEAR_LOCOMOTION_MODE,
+ DIRECTIONAL_LOCOMOTION_MODE,
+ CROUCH_LOCOMOTION_MODE,
+ )
+ missing_names = set(core_names).difference(modes_by_name)
+ if missing_names:
+ missing = ", ".join(sorted(missing_names))
+ raise ValueError(f"Required locomotion modes are missing: {missing}.")
+ if initial_mode not in modes_by_name:
+ raise ValueError(f"Unknown initial locomotion mode {initial_mode!r}.")
+
+ self.style_modes = tuple(name for name in modes_by_name if name not in core_names)
+ standing_names = (LINEAR_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE, *self.style_modes)
+ self.standing_idle_state = IdleState("Idle", standing_idle_clips)
+ self.standing_locomotion_state = LocomotionState(
+ "Locomotion",
+ tuple(modes_by_name[name] for name in standing_names),
+ initial_mode if initial_mode != CROUCH_LOCOMOTION_MODE else LINEAR_LOCOMOTION_MODE,
+ pose,
+ )
+ self.crouching_idle_state = IdleState("Crouching Idle", crouching_idle_clips)
+ self.crouching_locomotion_state = LocomotionState(
+ "Crouching Locomotion",
+ (modes_by_name[CROUCH_LOCOMOTION_MODE],),
+ CROUCH_LOCOMOTION_MODE,
+ pose,
+ )
+ self.interaction_state = InteractionState()
+
+ self._standing_pair = _MovementStatePair(
+ self.standing_idle_state,
+ self.standing_locomotion_state,
+ )
+ self._crouching_pair = _MovementStatePair(
+ self.crouching_idle_state,
+ self.crouching_locomotion_state,
+ probe_box_height_scale=_CROUCH_PROBE_HEIGHT_SCALE,
+ )
+ self._movement_pairs_by_mode = {name: self._standing_pair for name in standing_names}
+ self._movement_pairs_by_mode[CROUCH_LOCOMOTION_MODE] = self._crouching_pair
+ self._active_movement_pair = self._movement_pairs_by_mode[initial_mode]
+ self._state: State = self._active_movement_pair.idle
+
+ @property
+ def state(self) -> State:
+ """Current state."""
+ return self._state
+
+ @property
+ def active_locomotion_state(self) -> LocomotionState:
+ """Locomotion state of the active movement pair, standing or crouching."""
+ return self._active_movement_pair.locomotion
+
+ @property
+ def probe_box_height_scale(self) -> float:
+ """Scale of the probe box height for the active movement pair, standing or crouching."""
+ return self._active_movement_pair.probe_box_height_scale
+
+ @property
+ def is_locomoting(self) -> bool:
+ """Whether a locomotion state is current."""
+ return self.state in (
+ self.standing_locomotion_state,
+ self.crouching_locomotion_state,
+ )
+
+ @property
+ def is_interacting(self) -> bool:
+ """Whether the interaction state is current."""
+ return self.state is self.interaction_state
+
+ def start(self, character) -> None:
+ """Start the character in the initial idle loop."""
+ self._active_movement_pair.idle.start(character)
+
+ def transition_to(self, character, next_state: State) -> None:
+ """Exit the current state and enter next_state, unless next_state is already current."""
+ if next_state is self._state:
+ return
+ self._state.exit(character, self)
+ self._state = next_state
+ next_state.enter(character, self)
+
+ def update(
+ self,
+ character,
+ delta_time: float,
+ command: LocomotionCommand,
+ ) -> None:
+ """Switch modes as the command asks, smooth the movement, then update the current state.
+
+ Movement smooths in every state, so it carries into the next one.
+ """
+ previous_pair = self._active_movement_pair
+ previous_mode = previous_pair.locomotion.active_mode
+ if command.requested_mode is not None:
+ self._active_movement_pair = self._movement_pairs_by_mode[command.requested_mode]
+ self._active_movement_pair.locomotion.select_mode(command.requested_mode)
+
+ mode = self.active_locomotion_state.active_mode
+ character.movement.update(command, mode, delta_time, previous_mode if mode is not previous_mode else None)
+
+ movement_pair_changed = previous_pair is not self._active_movement_pair
+ if movement_pair_changed and self.state in (
+ previous_pair.idle,
+ previous_pair.locomotion,
+ ):
+ self.resume_movement(character)
+
+ self.state.update(character, self, delta_time)
+
+ def transition_to_idle(self, character) -> None:
+ """Switch to the idle state of the active movement pair."""
+ self.transition_to(character, self._active_movement_pair.idle)
+
+ def transition_to_locomotion(self, character) -> None:
+ """Switch to the locomotion state of the active movement pair."""
+ self.transition_to(character, self._active_movement_pair.locomotion)
+
+ def resume_movement(self, character) -> None:
+ """Switch to locomotion when there is movement input, or to idle otherwise."""
+ if character.movement.input_speed > 0.0:
+ self.transition_to_locomotion(character)
+ else:
+ self.transition_to_idle(character)
+
+ def start_interaction(
+ self,
+ character,
+ primitive,
+ ) -> None:
+ """Let a Smart Primitive control the character until it calls finish()."""
+
+ if self.is_interacting:
+ raise RuntimeError("Cannot start an interaction while another is active.")
+ self.interaction_state.configure(character, primitive)
+ try:
+ self.transition_to(character, self.interaction_state)
+ except Exception:
+ self.resume_movement(character)
+ raise
+
+ def interact(self) -> None:
+ """Pass an interaction press to the active Smart Primitive behavior."""
+ if self.is_interacting:
+ self.interaction_state.primitive.interact()
+
+
+__all__ = ["StateMachine"]
diff --git a/app/runtime/common/states.py b/app/runtime/common/states.py
new file mode 100644
index 0000000..a5f3744
--- /dev/null
+++ b/app/runtime/common/states.py
@@ -0,0 +1,426 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Idle, locomotion, and interaction states shared by both rigs."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import random
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN
+from motionbricks.runtime.smart_primitive import CharacterProperties
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+
+from .motion import (
+ MOVEMENT_EPSILON,
+ AnimationClip,
+ LocomotionMode,
+ LocomotionModeRuntime,
+ LocomotionSettings,
+ MovementControl,
+)
+
+if TYPE_CHECKING:
+ from .smart_primitive_behaviors import SmartPrimitiveBehavior
+ from .state_machine import StateMachine
+
+
+class State:
+ """Common entry, exit, and update methods for states."""
+
+ name = "State"
+
+ def enter(self, character, state_machine: StateMachine) -> None:
+ """Run when the state machine switches to this state."""
+
+ def exit(self, character, state_machine: StateMachine) -> None:
+ """Run when the state machine leaves this state."""
+
+ def update(self, character, state_machine: StateMachine, delta_time: float) -> None:
+ """Advance the state by delta_time (in seconds)."""
+ raise NotImplementedError
+
+
+class IdleState(State):
+ """Generate a transition into an idle clip, then loop the clip."""
+
+ def __init__(self, name: str, clips: tuple[AnimationClip, ...]) -> None:
+ """Create an idle state that picks from the given looping clips."""
+ if not clips:
+ raise ValueError("Idle state requires at least one clip.")
+ self.name = name
+ self.clips = clips
+ self._random = random.Random()
+
+ def start(self, character) -> None:
+ """Start in an idle loop, without a generated transition."""
+ character.movement.reset_desired_velocity()
+ character.initialize_clip_loop(self.choose_clip(character))
+
+ def enter(
+ self,
+ character,
+ state_machine: StateMachine,
+ ) -> None:
+ character.movement.reset_desired_velocity()
+ character.generate_clip_transition(self.choose_clip(character))
+
+ def update(
+ self,
+ character,
+ state_machine: StateMachine,
+ delta_time: float,
+ ) -> None:
+ if character.movement.input_speed > 0.0:
+ state_machine.transition_to_locomotion(character)
+ return
+
+ if character.clip_transition_ends_within(delta_time):
+ character.start_clip(character.current_clip, loop=True)
+
+ def choose_clip(self, character) -> AnimationClip:
+ """Pick a random idle clip, preferring one other than the current clip."""
+ clips = self.clips
+ candidates = tuple(
+ clip for clip in clips if clip is not character.current_clip
+ )
+ return self._random.choice(candidates or clips)
+
+
+class LocomotionState(State):
+ """Place target poses ahead along the desired velocity, and generate toward them.
+
+ The character's MovementControl smooths the input into that velocity.
+ """
+
+ def __init__(
+ self,
+ name: str,
+ mode_runtimes: tuple[LocomotionModeRuntime, ...],
+ initial_mode: str,
+ pose: wp.array,
+ settings: LocomotionSettings = LocomotionSettings(),
+ ) -> None:
+ """Create a locomotion state with its loaded modes, initial mode, and regeneration settings.
+
+ pose has the layout of the character's poses. It sizes the target pose buffers.
+ """
+ self.name = name
+ self.settings = settings
+ self.mode_runtimes = {runtime.definition.name: runtime for runtime in mode_runtimes}
+ self.active_mode_runtime = self.mode_runtimes[initial_mode]
+ self._blended_target_poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, *pose.shape),
+ dtype=pose.dtype,
+ device=pose.device,
+ )
+ self._target_poses = wp.empty_like(self._blended_target_poses)
+ self._previous_generation_desired_velocity = np.zeros(
+ 3,
+ dtype=np.float32,
+ )
+ self._force_regeneration = True
+
+ @property
+ def active_mode(self) -> LocomotionMode:
+ """Definition of the active mode."""
+ return self.active_mode_runtime.definition
+
+ def select_mode(self, name: str) -> None:
+ """Make a mode active. A new mode generates new motion on the next update."""
+ mode_runtime = self.mode_runtimes[name]
+ if mode_runtime is not self.active_mode_runtime:
+ self.active_mode_runtime = mode_runtime
+ self._force_regeneration = True
+
+ def enter(
+ self,
+ character,
+ state_machine: StateMachine,
+ ) -> None:
+ character.movement.realign(character.actual_velocity, self.active_mode)
+ self._generate(character)
+
+ def update(
+ self,
+ character,
+ state_machine: StateMachine,
+ delta_time: float,
+ ) -> None:
+ if character.movement.input_speed <= 0.0:
+ state_machine.transition_to_idle(character)
+ return
+
+ if (
+ self._force_regeneration
+ or character.time_to_transition() <= delta_time
+ or self._needs_regeneration(character.movement)
+ ):
+ self._generate(character)
+
+ def evaluate_current_target_poses(
+ self,
+ character,
+ blended_poses: wp.array,
+ target_poses: wp.array,
+ ) -> None:
+ """Blend and place the active mode's targets for generation or debug display."""
+ character.target_pose_blender.evaluate(character, self.active_mode_runtime, blended_poses, target_poses)
+
+ def _generate(
+ self,
+ character,
+ ) -> None:
+ self.evaluate_current_target_poses(
+ character,
+ self._blended_target_poses,
+ self._target_poses,
+ )
+ character.generate_to_target_poses(
+ self._target_poses,
+ TargetPoseInferenceParams(
+ transition_early_by_frames=self.active_mode.transition_early_by_frames,
+ num_poses_to_use=MODEL_POSES_PER_TOKEN,
+ allowed_token_counts=self.active_mode.allowed_token_counts,
+ ),
+ )
+ self._previous_generation_desired_velocity[:] = character.movement.desired_velocity
+ self._force_regeneration = False
+
+ def _needs_regeneration(self, movement: MovementControl) -> bool:
+ settings = self.settings
+ previous_speed = float(
+ np.linalg.norm(self._previous_generation_desired_velocity)
+ )
+ max_speed = self.active_mode.max_speed
+ locomotion_started = (
+ movement.desired_speed > 0.0
+ and previous_speed <= MOVEMENT_EPSILON
+ )
+ speed_delta = movement.desired_speed - previous_speed
+ remaining_speed_range = (
+ max_speed - previous_speed
+ if speed_delta > 0.0
+ else previous_speed
+ )
+ regeneration_threshold = max(
+ remaining_speed_range * settings.speed_regeneration_fraction,
+ max_speed * settings.minimum_speed_regeneration_fraction,
+ )
+ if locomotion_started or abs(speed_delta) > regeneration_threshold:
+ return True
+
+ if previous_speed <= MOVEMENT_EPSILON:
+ return False
+ previous_direction = (
+ self._previous_generation_desired_velocity / previous_speed
+ )
+ return (
+ float(
+ np.dot(
+ movement.desired_velocity_direction,
+ previous_direction,
+ )
+ )
+ < settings.direction_regeneration_dot
+ )
+
+
+class InteractionState(State):
+ """Run a Smart Primitive's sequences and clips until the behavior finishes.
+
+ The behavior chooses the next sequence or clip. This state generates motion
+ toward each target. The character plays that motion and records its recent poses.
+ """
+
+ name = "Interaction"
+
+ def __init__(self) -> None:
+ self.primitive: SmartPrimitiveBehavior | None = None
+ self._character = None
+ self._state_machine: StateMachine | None = None
+ self._target_poses: wp.array | None = None
+ self._inference_params: tuple[TargetPoseInferenceParams, ...] = ()
+ self._target_index = -1
+ self._playing_clip = False
+ self._clip_loop = False
+ self._clips: dict[tuple[Path, bool], AnimationClip] = {}
+ self._on_complete: Callable[[], None] | None = None
+
+ @property
+ def character(self):
+ """Character in the active interaction."""
+ if self._character is None:
+ raise RuntimeError("Cannot access the character without an active interaction.")
+ return self._character
+
+ @property
+ def is_looping(self) -> bool:
+ """Whether a looping clip is playing."""
+ return self._playing_clip and self._clip_loop
+
+ def prepare(self, character, primitive: SmartPrimitiveBehavior) -> None:
+ """Load each clip and its looping version before an interaction needs them."""
+ for path in primitive.clip_paths:
+ path = Path(path).resolve()
+ for loop in (False, True):
+ if (path, loop) not in self._clips:
+ self._clips[path, loop] = character.load_clip(path, loop=loop)
+
+ def configure(self, character, primitive: SmartPrimitiveBehavior) -> None:
+ """Prepare a Smart Primitive behavior for the next interaction.
+
+ Load its clips and size the target pose buffers for it.
+ """
+ pose = character.current_pose
+ self.prepare(character, primitive)
+ capacity = max(1, primitive.target_pose_count, primitive.max_sequence_length)
+ required_frames = capacity * MODEL_POSES_PER_TOKEN
+ if self._target_poses is None or self._target_poses.shape[0] < required_frames:
+ self._target_poses = wp.empty(
+ (required_frames, *pose.shape),
+ dtype=pose.dtype,
+ device=character.engine.device,
+ )
+ self.primitive = primitive
+
+ def enter(self, character, state_machine: StateMachine) -> None:
+ self._character = character
+ self._state_machine = state_machine
+ self.primitive.bind(self)
+ self.primitive.enter()
+
+ def exit(self, character, state_machine: StateMachine) -> None:
+ self._stop_target_pose_sequence(character)
+ # Behaviors can turn the character, so movement continues from the pose's heading.
+ character.face_pose()
+ self.primitive.unbind()
+ self.primitive = None
+ self._character = None
+ self._state_machine = None
+ self._inference_params = ()
+ self._playing_clip = False
+
+ def play_target_pose_sequence(
+ self,
+ name: str | None = None,
+ *,
+ on_complete: Callable[[], None] | None = None,
+ ) -> None:
+ """Generate motion through a target pose sequence, then call on_complete.
+
+ Without a name, use the targets returned by the behavior's get_targets().
+ Without a callback, return to locomotion or idle when the sequence ends.
+ """
+ character = self.character
+ primitive = self.primitive
+ properties = CharacterProperties(
+ position=character.character_ground_position,
+ velocity=character.actual_velocity,
+ facing=character.movement.current_facing,
+ desired_velocity=character.movement.desired_velocity,
+ probe_segment=character.probe_segment,
+ )
+ if name is None:
+ params = primitive.get_targets(
+ properties, self._target_poses, stream=character.engine.stream,
+ )
+ else:
+ index = primitive.sequence_index(name)
+ if index < 0:
+ raise ValueError(f"Smart Primitive has no sequence named {name!r}.")
+ primitive.align_sequence_pivot(index, properties, stream=character.engine.stream)
+ params = primitive.get_world_target_poses_for_sequence(
+ index, self._target_poses, stream=character.engine.stream,
+ )
+ params = tuple(params)
+ # A behavior that does not override get_targets() returns no targets.
+ if not params:
+ raise ValueError("The Smart Primitive behavior returned no targets.")
+
+ self._stop_target_pose_sequence(character)
+ self._playing_clip = False
+ self._inference_params = params
+ self._target_index = 0
+ self._on_complete = on_complete if on_complete is not None else self.finish
+ self._generate_current_target(character)
+
+ def play_clip(
+ self,
+ path: Path,
+ *,
+ loop: bool = False,
+ align_to_current_pose: bool = True,
+ on_complete: Callable[[], None] | None = None,
+ ) -> None:
+ """Play a clip once, or keep repeating it when loop=True.
+
+ Add the path to the behavior's clip_paths so the clip loads with the scene.
+ By default, the clip's first root pose lines up with the character's
+ current root, in both position and rotation. When a clip played once ends,
+ on_complete runs. Without a callback, the character returns to locomotion
+ or idle.
+ """
+ character = self.character
+ path = Path(path).resolve()
+ if (path, loop) not in self._clips:
+ raise ValueError(f"Cannot play {path}. Declare it in the behavior's clip_paths first.")
+ self._stop_target_pose_sequence(character)
+ character.start_clip(
+ self._clips[path, loop], loop=loop, align_to_current_pose=align_to_current_pose,
+ )
+ self._playing_clip = True
+ self._clip_loop = loop
+ self._on_complete = on_complete if on_complete is not None else self.finish
+
+ def finish(self) -> None:
+ """End the interaction and return to locomotion or idle."""
+ self._state_machine.resume_movement(self.character)
+
+ def update(self, character, state_machine: StateMachine, delta_time: float) -> None:
+ if self._playing_clip:
+ if character.clip_ends_within(delta_time):
+ self._complete_playback(character)
+ return
+
+ if self._target_index < 0 or character.time_to_transition() > delta_time:
+ return
+
+ self._target_index += 1
+ if self._target_index < len(self._inference_params):
+ self._generate_current_target(character)
+ else:
+ self._complete_playback(character)
+
+ def _complete_playback(self, character) -> None:
+ on_complete = self._on_complete
+ # Clear the finished playback first, because the callback may start a new sequence or clip.
+ self._playing_clip = False
+ self._stop_target_pose_sequence(character)
+ on_complete()
+
+ def _stop_target_pose_sequence(self, character) -> None:
+ self._target_index = -1
+ self._on_complete = None
+ character.clear_ik_pins()
+
+ def _generate_current_target(self, character) -> None:
+ frame_offset = self._target_index * MODEL_POSES_PER_TOKEN
+ character.generate_to_target_poses(
+ self._target_poses[frame_offset : frame_offset + MODEL_POSES_PER_TOKEN],
+ self._inference_params[self._target_index],
+ )
+
+
+__all__ = [
+ "IdleState",
+ "InteractionState",
+ "LocomotionState",
+ "State",
+]
diff --git a/app/runtime/common/target_pose_blender.py b/app/runtime/common/target_pose_blender.py
new file mode 100644
index 0000000..e62eb23
--- /dev/null
+++ b/app/runtime/common/target_pose_blender.py
@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Blend a locomotion mode's target poses and place them ahead of the character."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+import warp as wp
+
+from motionbricks.runtime.blend_spaces import BlendSample, BlendSpaceType
+
+from .motion import LocomotionModeRuntime, directional_blend_space_value
+
+
+class BaseTargetPoseBlender(ABC):
+ """Turn a locomotion mode and the character's desired velocity into target poses.
+
+ evaluate() runs the shared steps. Each rig overrides the blend, speed, and
+ placement steps for its pose layout.
+ """
+
+ def evaluate(
+ self,
+ character,
+ mode_runtime: LocomotionModeRuntime,
+ blended_poses: wp.array,
+ target_poses: wp.array,
+ ) -> None:
+ """Blend the mode's targets for the desired velocity and place them in target_poses."""
+ mode = mode_runtime.definition
+ stream = character.engine.stream
+ movement = character.movement
+ speed = float(np.linalg.norm(movement.desired_velocity))
+ if mode.blend_space_type is BlendSpaceType.LINEAR_1D:
+ sample = mode_runtime.blend_space.evaluate(wp.vec2(speed / mode.max_speed, 0.0))
+ self.blend_linear(mode_runtime.target_poses, sample, blended_poses, stream)
+ else:
+ sample = mode_runtime.blend_space.evaluate(
+ directional_blend_space_value(movement.current_facing, movement.desired_velocity, mode.max_speed)
+ )
+ self.blend_directional(mode_runtime.target_poses, sample, blended_poses, stream)
+ self.adjust_speed(blended_poses, speed * mode.velocity_scale, stream)
+ ground_position = character.character_ground_position + (
+ movement.desired_velocity * mode.velocity_scale * mode.position_scale
+ )
+ ground_position[2] = 0.0
+ self.place(wp.vec3(*ground_position), wp.vec3(*movement.current_facing), blended_poses, target_poses, stream)
+
+ @abstractmethod
+ def blend_linear(self, target_poses: wp.array, sample: BlendSample, output: wp.array, stream) -> None:
+ """Blend the targets of a 1D blend space into output."""
+
+ @abstractmethod
+ def blend_directional(self, target_poses: wp.array, sample: BlendSample, output: wp.array, stream) -> None:
+ """Blend the targets of a 2D blend space into output.
+
+ When the blend weights add up to less than one, a base pose fills the rest. SOMA
+ uses its reference pose, and G1 uses the Idle target.
+ """
+
+ @abstractmethod
+ def adjust_speed(self, poses: wp.array, speed: float, stream) -> None:
+ """Scale the root's motion along the ground to a mean speed."""
+
+ @abstractmethod
+ def place(
+ self,
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_poses: wp.array,
+ target_poses: wp.array,
+ stream,
+ ) -> None:
+ """Copy the blended poses into target_poses, placed on the ground and turned to face a direction.
+
+ One placement moves every root, so the roots keep their offsets from one another.
+ Other joint values stay as they are.
+ """
+
+
+__all__ = ["BaseTargetPoseBlender"]
diff --git a/app/runtime/soma/__init__.py b/app/runtime/soma/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/app/runtime/soma/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/app/runtime/soma/character.py b/app/runtime/soma/character.py
new file mode 100644
index 0000000..891231a
--- /dev/null
+++ b/app/runtime/soma/character.py
@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""SOMA character animated by the MotionBricks SOMA model."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import warp as wp
+
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.runtime.motion_player import GeneratedMotionPlayer
+from motionbricks.runtime.target_pose import (
+ TargetPoseIKCorrector,
+ create_soma_target_pose_ik_rig,
+)
+
+from ..common.character import BaseCharacter
+from ..common.interaction import InteractionProbe
+from ..common.io.smart_primitive_document import SmartPrimitiveAssetPool
+from ..common.motion import LINEAR_LOCOMOTION_MODE, LocomotionMode
+from .presets import (
+ DEFAULT_CROUCH_IDLE_CLIPS, DEFAULT_IDLE_CLIPS, DEFAULT_LOCOMOTION_MODES, INTERACTION_PROBE,
+)
+from .target_pose_blender import SOMATargetPoseBlender
+
+
+class SOMACharacter(BaseCharacter):
+ """SOMA character animated by the MotionBricks SOMA model, with target pose IK for pinned hands and feet."""
+
+ root_forward_axis = wp.vec3(0.0, 1.0, 0.0)
+
+ def __init__(
+ self,
+ engine: MotionBricksSOMAEngine,
+ *,
+ asset_pool: SmartPrimitiveAssetPool,
+ initial_transform: wp.transform = wp.transform_identity(),
+ modes: tuple[LocomotionMode, ...] = DEFAULT_LOCOMOTION_MODES,
+ initial_mode: str = LINEAR_LOCOMOTION_MODE,
+ idle_paths: tuple[str | Path, ...] = DEFAULT_IDLE_CLIPS,
+ crouch_idle_paths: tuple[str | Path, ...] = DEFAULT_CROUCH_IDLE_CLIPS,
+ interaction_probe: InteractionProbe = INTERACTION_PROBE,
+ current_pose: wp.array | None = None,
+ ) -> None:
+ """Create the SOMA character with its target pose blender and target pose IK.
+
+ The arguments are as BaseCharacter takes them. The defaults are the SOMA presets.
+ """
+ self.skeleton = asset_pool.clip_registry.skeleton
+ self.target_pose_blender = SOMATargetPoseBlender(self.skeleton.reference_local_transforms)
+ super().__init__(
+ engine,
+ asset_pool=asset_pool,
+ initial_transform=initial_transform,
+ modes=modes,
+ initial_mode=initial_mode,
+ idle_paths=idle_paths,
+ crouch_idle_paths=crouch_idle_paths,
+ interaction_probe=interaction_probe,
+ target_pose_ik_corrector=TargetPoseIKCorrector(
+ self.skeleton,
+ create_soma_target_pose_ik_rig(self.skeleton),
+ ),
+ current_pose=current_pose,
+ )
+
+ def _create_player(self) -> GeneratedMotionPlayer:
+ return GeneratedMotionPlayer(self.engine, self.skeleton)
+
+
+__all__ = ["SOMACharacter"]
diff --git a/app/runtime/soma/presets.py b/app/runtime/soma/presets.py
new file mode 100644
index 0000000..af65a6b
--- /dev/null
+++ b/app/runtime/soma/presets.py
@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Default locomotion modes, idle clips, and settings for the SOMA character."""
+
+from motionbricks.runtime.blend_spaces import BlendSpaceType
+
+from ..common.interaction import InteractionProbe
+from ..common.motion import (
+ CROUCH_LOCOMOTION_MODE,
+ DIRECTIONAL_LOCOMOTION_MODE,
+ DIRECTIONAL_TARGET_VALUES,
+ LINEAR_LOCOMOTION_MODE,
+ LocomotionMode,
+ style_locomotion_mode,
+)
+from ..common.rig import ASSETS_ROOT
+
+
+_SMART_PRIMITIVE_ROOT = ASSETS_ROOT / "smart_primitives" / "soma"
+_IDLE_ROOT = ASSETS_ROOT / "motions" / "soma" / "locomotion" / "idle"
+DEFAULT_IDLE_CLIPS = (
+ _IDLE_ROOT / "idle_loop_001__A268.bvh",
+ _IDLE_ROOT / "neutral_looking_around_R_001__A542.bvh",
+ _IDLE_ROOT / "warm_up_neck_001__A359.bvh",
+ _IDLE_ROOT / "legs_relax_002__A407.bvh",
+)
+DEFAULT_CROUCH_IDLE_CLIPS = (
+ _IDLE_ROOT / "crouch_idle_001__A529.bvh",
+)
+
+_NORMAL_DEFAULT_SPEED = 2.3
+_NORMAL_MAX_SPEED = 4.5
+_NORMAL_MIN_SPEED = 0.8 * _NORMAL_DEFAULT_SPEED
+
+_STRAFE_DEFAULT_SPEED = 2.3
+_STRAFE_MAX_SPEED = 3.0
+_STRAFE_MIN_SPEED = 0.8 * _STRAFE_DEFAULT_SPEED
+
+_CROUCH_DEFAULT_SPEED = 1.5
+_CROUCH_MAX_SPEED = 2.5
+_CROUCH_MIN_SPEED = _CROUCH_DEFAULT_SPEED * 0.8
+
+_LINEAR_TARGET_VALUES = (
+ ("Idle", (0.0, 0.0)),
+ ("Walk", (_NORMAL_DEFAULT_SPEED / _NORMAL_MAX_SPEED, 0.0)),
+ ("Jog", (3.0 / _NORMAL_MAX_SPEED, 0.0)),
+ ("Run", (1.0, 0.0)),
+)
+
+LINEAR_LOCOMOTION = LocomotionMode(
+ name=LINEAR_LOCOMOTION_MODE,
+ smart_primitive_path=_SMART_PRIMITIVE_ROOT / "locomotion_bs1_linear.smart_primitive.json",
+ blend_space_type=BlendSpaceType.LINEAR_1D,
+ target_values=_LINEAR_TARGET_VALUES,
+ max_speed=_NORMAL_MAX_SPEED,
+ default_speed=_NORMAL_DEFAULT_SPEED,
+ minimum_speed=_NORMAL_MIN_SPEED,
+ velocity_scale=0.97,
+ transition_early_by_frames=10,
+ label="Forward",
+)
+DIRECTIONAL_LOCOMOTION = LocomotionMode(
+ name=DIRECTIONAL_LOCOMOTION_MODE,
+ smart_primitive_path=_SMART_PRIMITIVE_ROOT / "locomotion_bs2_directional.smart_primitive.json",
+ blend_space_type=BlendSpaceType.DIRECTIONAL_2D,
+ target_values=DIRECTIONAL_TARGET_VALUES,
+ max_speed=_STRAFE_MAX_SPEED,
+ default_speed=_STRAFE_DEFAULT_SPEED,
+ minimum_speed=_STRAFE_MIN_SPEED,
+ velocity_scale=0.95,
+ position_scale=0.9,
+ label="Strafing",
+)
+CROUCH_LOCOMOTION = LocomotionMode(
+ name=CROUCH_LOCOMOTION_MODE,
+ smart_primitive_path=_SMART_PRIMITIVE_ROOT / "locomotion_bs2_directional_crouch.smart_primitive.json",
+ blend_space_type=BlendSpaceType.DIRECTIONAL_2D,
+ target_values=DIRECTIONAL_TARGET_VALUES,
+ max_speed=_CROUCH_MAX_SPEED,
+ default_speed=_CROUCH_DEFAULT_SPEED,
+ minimum_speed=_CROUCH_MIN_SPEED,
+ velocity_scale=0.9,
+ position_scale=0.8,
+ label="Crouching",
+)
+_STYLE_PATH = _SMART_PRIMITIVE_ROOT / "locomotion_style_variations_bs1_linear.smart_primitive.json"
+STYLE_LOCOMOTION_MODES = (
+ style_locomotion_mode(
+ "Skipping", _STYLE_PATH, minimum_speed=1.3, max_speed=1.45, position_scale=1.32,
+ allowed_token_counts=tuple(range(6, 14)),
+ ),
+ style_locomotion_mode("Vogue", _STYLE_PATH, minimum_speed=1.2, max_speed=1.3, position_scale=1.3),
+ style_locomotion_mode(
+ "Injured Torso", _STYLE_PATH, minimum_speed=0.7, max_speed=0.8, position_scale=1.2,
+ transition_early_by_frames=6, allowed_token_counts=tuple(range(8, 17)),
+ ),
+ style_locomotion_mode("Injured Leg", _STYLE_PATH, minimum_speed=0.7, max_speed=0.8, position_scale=1.2),
+ style_locomotion_mode("Zombie", _STYLE_PATH, minimum_speed=0.7, max_speed=0.85, position_scale=1.3),
+ style_locomotion_mode("Combat", _STYLE_PATH, minimum_speed=0.7, max_speed=1.0, position_scale=1.7),
+)
+DEFAULT_LOCOMOTION_MODES = (LINEAR_LOCOMOTION, DIRECTIONAL_LOCOMOTION, CROUCH_LOCOMOTION, *STYLE_LOCOMOTION_MODES)
+
+INTERACTION_PROBE = InteractionProbe(
+ box_width=1.0,
+ box_min_depth=0.75,
+ box_height=1.6,
+ near_distance=0.15,
+ lookahead_time=1.0,
+ extra_lookahead_min_speed=2.3,
+ extra_lookahead_time=0.25,
+)
+
+
+__all__ = [
+ "CROUCH_LOCOMOTION",
+ "DEFAULT_CROUCH_IDLE_CLIPS",
+ "DEFAULT_IDLE_CLIPS",
+ "DEFAULT_LOCOMOTION_MODES",
+ "DIRECTIONAL_LOCOMOTION",
+ "INTERACTION_PROBE",
+ "LINEAR_LOCOMOTION",
+ "STYLE_LOCOMOTION_MODES",
+]
diff --git a/app/runtime/soma/target_pose_blender.py b/app/runtime/soma/target_pose_blender.py
new file mode 100644
index 0000000..d5a8fa9
--- /dev/null
+++ b/app/runtime/soma/target_pose_blender.py
@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Blend and place SOMA locomotion target poses."""
+
+from __future__ import annotations
+
+import warp as wp
+
+from motionbricks.runtime.blend_spaces import BlendSample, directional_2d_pose_blend, linear_1d_pose_blend
+from motionbricks.runtime.target_pose import adjust_target_pose_speed, place_target_poses
+
+from ..common.target_pose_blender import BaseTargetPoseBlender
+
+
+class SOMATargetPoseBlender(BaseTargetPoseBlender):
+ """Blend SOMA local joint transforms around the skeleton's reference pose."""
+
+ def __init__(self, reference_pose: wp.array) -> None:
+ """Keep the skeleton's reference pose for directional blending."""
+ self.reference_pose = reference_pose
+
+ def blend_linear(self, target_poses: wp.array, sample: BlendSample, output: wp.array, stream) -> None:
+ linear_1d_pose_blend(target_poses, sample, output, stream=stream)
+
+ def blend_directional(self, target_poses: wp.array, sample: BlendSample, output: wp.array, stream) -> None:
+ directional_2d_pose_blend(target_poses, sample, self.reference_pose, output, stream=stream)
+
+ def adjust_speed(self, poses: wp.array, speed: float, stream) -> None:
+ adjust_target_pose_speed(poses, speed, stream=stream)
+
+ def place(
+ self,
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_poses: wp.array,
+ target_poses: wp.array,
+ stream,
+ ) -> None:
+ place_target_poses(ground_position, facing_direction, blended_poses, target_poses, stream=stream)
+
+
+__all__ = ["SOMATargetPoseBlender"]
diff --git a/app/runtime/unitree_g1/__init__.py b/app/runtime/unitree_g1/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/app/runtime/unitree_g1/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/app/runtime/unitree_g1/character.py b/app/runtime/unitree_g1/character.py
new file mode 100644
index 0000000..acbc589
--- /dev/null
+++ b/app/runtime/unitree_g1/character.py
@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unitree G1 character animated by the MotionBricks G1 model."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import warp as wp
+
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+from motionbricks.runtime.motion_player import GeneratedDOFMotionPlayer
+
+from ..common.character import BaseCharacter
+from ..common.interaction import InteractionProbe
+from ..common.io.smart_primitive_document import SmartPrimitiveAssetPool
+from ..common.motion import LINEAR_LOCOMOTION_MODE, LocomotionMode
+from .presets import (
+ DEFAULT_CROUCH_IDLE_CLIPS, DEFAULT_IDLE_CLIPS, DEFAULT_LOCOMOTION_MODES, INTERACTION_PROBE,
+)
+from .target_pose_blender import G1TargetPoseBlender
+
+
+class UnitreeG1Character(BaseCharacter):
+ """Unitree G1 character animated by the MotionBricks G1 model."""
+
+ root_forward_axis = wp.vec3(1.0, 0.0, 0.0)
+
+ def __init__(
+ self,
+ engine: MotionBricksUnitreeG1Engine,
+ *,
+ asset_pool: SmartPrimitiveAssetPool,
+ initial_transform: wp.transform = wp.transform_identity(),
+ modes: tuple[LocomotionMode, ...] = DEFAULT_LOCOMOTION_MODES,
+ initial_mode: str = LINEAR_LOCOMOTION_MODE,
+ idle_paths: tuple[str | Path, ...] = DEFAULT_IDLE_CLIPS,
+ crouch_idle_paths: tuple[str | Path, ...] = DEFAULT_CROUCH_IDLE_CLIPS,
+ interaction_probe: InteractionProbe = INTERACTION_PROBE,
+ current_pose: wp.array | None = None,
+ ) -> None:
+ """Create the G1 character with its target pose blender.
+
+ The arguments are as BaseCharacter takes them. The defaults are the G1 presets.
+ """
+ self.target_pose_blender = G1TargetPoseBlender()
+ super().__init__(
+ engine,
+ asset_pool=asset_pool,
+ initial_transform=initial_transform,
+ modes=modes,
+ initial_mode=initial_mode,
+ idle_paths=idle_paths,
+ crouch_idle_paths=crouch_idle_paths,
+ interaction_probe=interaction_probe,
+ current_pose=current_pose,
+ )
+
+ def _create_player(self) -> GeneratedDOFMotionPlayer:
+ return GeneratedDOFMotionPlayer(self.engine, self.current_pose)
+
+
+__all__ = ["UnitreeG1Character"]
diff --git a/app/runtime/unitree_g1/presets.py b/app/runtime/unitree_g1/presets.py
new file mode 100644
index 0000000..2e6d493
--- /dev/null
+++ b/app/runtime/unitree_g1/presets.py
@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Default locomotion modes, idle clips, and settings for the G1 character."""
+
+from motionbricks.runtime.blend_spaces import BlendSpaceType
+
+from ..common.interaction import InteractionProbe
+from ..common.motion import (
+ CROUCH_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE, DIRECTIONAL_TARGET_VALUES, LINEAR_LOCOMOTION_MODE,
+ LocomotionMode, style_locomotion_mode,
+)
+from ..common.rig import ASSETS_ROOT
+
+
+_SMART_PRIMITIVE_ROOT = ASSETS_ROOT / "smart_primitives/unitree_g1"
+_MOTION_ROOT = ASSETS_ROOT / "motions/unitree_g1"
+_IDLE_ROOT = _MOTION_ROOT / "locomotion/idle"
+DEFAULT_IDLE_CLIPS = (
+ _IDLE_ROOT / "idle_loop_001__A268.csv",
+ _IDLE_ROOT / "neutral_looking_around_R_001__A542.csv",
+ _IDLE_ROOT / "legs_relax_002__A407.csv",
+)
+DEFAULT_CROUCH_IDLE_CLIPS = (_IDLE_ROOT / "crouch_idle_001__A529.csv",)
+
+LINEAR_LOCOMOTION = LocomotionMode(
+ name=LINEAR_LOCOMOTION_MODE,
+ smart_primitive_path=_SMART_PRIMITIVE_ROOT / "locomotion_bs1_linear.smart_primitive.json",
+ blend_space_type=BlendSpaceType.LINEAR_1D,
+ target_values=(("Idle", (0.0, 0.0)), ("Walk", (1.3 / 3.4, 0.0)),
+ ("Jog", (2.0 / 3.4, 0.0)), ("Run", (1.0, 0.0))),
+ max_speed=3.4,
+ default_speed=1.3,
+ minimum_speed=1.3,
+ transition_early_by_frames=10,
+ label="Forward",
+)
+
+DIRECTIONAL_LOCOMOTION = LocomotionMode(
+ name=DIRECTIONAL_LOCOMOTION_MODE,
+ smart_primitive_path=_SMART_PRIMITIVE_ROOT / "locomotion_bs2_directional.smart_primitive.json",
+ blend_space_type=BlendSpaceType.DIRECTIONAL_2D,
+ target_values=DIRECTIONAL_TARGET_VALUES,
+ max_speed=2.3,
+ default_speed=1.3,
+ minimum_speed=1.3,
+ transition_early_by_frames=10,
+ label="Strafing",
+)
+CROUCH_LOCOMOTION = LocomotionMode(
+ name=CROUCH_LOCOMOTION_MODE,
+ smart_primitive_path=_SMART_PRIMITIVE_ROOT / "locomotion_bs2_directional_crouch.smart_primitive.json",
+ blend_space_type=BlendSpaceType.DIRECTIONAL_2D,
+ target_values=DIRECTIONAL_TARGET_VALUES,
+ max_speed=1.5,
+ default_speed=0.8,
+ minimum_speed=0.8,
+ transition_early_by_frames=10,
+ label="Crouching",
+)
+_STYLE_PATH = _SMART_PRIMITIVE_ROOT / "locomotion_style_variations_bs1_linear.smart_primitive.json"
+STYLE_LOCOMOTION_MODES = (
+ style_locomotion_mode("Skipping", _STYLE_PATH, minimum_speed=1.3, max_speed=1.45, transition_early_by_frames=0),
+ style_locomotion_mode("Vogue", _STYLE_PATH, minimum_speed=0.8, max_speed=0.9, position_scale=1.3),
+ style_locomotion_mode("Injured Torso", _STYLE_PATH, minimum_speed=0.4, max_speed=0.45),
+ style_locomotion_mode("Injured Leg", _STYLE_PATH, minimum_speed=0.4, max_speed=0.6),
+ style_locomotion_mode("Zombie", _STYLE_PATH, minimum_speed=0.4, max_speed=0.45),
+ style_locomotion_mode("Combat", _STYLE_PATH, minimum_speed=0.65, max_speed=0.75),
+)
+DEFAULT_LOCOMOTION_MODES = (LINEAR_LOCOMOTION, DIRECTIONAL_LOCOMOTION, CROUCH_LOCOMOTION, *STYLE_LOCOMOTION_MODES)
+
+INTERACTION_PROBE = InteractionProbe(
+ box_width=0.79,
+ box_min_depth=0.59,
+ box_height=1.26,
+ near_distance=0.12,
+ lookahead_time=1.0,
+ extra_lookahead_min_speed=1.3,
+ extra_lookahead_time=0.25,
+)
+
+
+__all__ = [
+ "CROUCH_LOCOMOTION",
+ "DEFAULT_CROUCH_IDLE_CLIPS",
+ "DEFAULT_IDLE_CLIPS",
+ "DEFAULT_LOCOMOTION_MODES",
+ "DIRECTIONAL_LOCOMOTION",
+ "INTERACTION_PROBE",
+ "LINEAR_LOCOMOTION",
+ "STYLE_LOCOMOTION_MODES",
+]
diff --git a/app/runtime/unitree_g1/target_pose_blender.py b/app/runtime/unitree_g1/target_pose_blender.py
new file mode 100644
index 0000000..4ee1dca
--- /dev/null
+++ b/app/runtime/unitree_g1/target_pose_blender.py
@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Blend and place Unitree G1 locomotion target poses."""
+
+from __future__ import annotations
+
+import warp as wp
+
+from motionbricks.runtime.blend_spaces import BlendSample, directional_2d_dof_blend, linear_1d_dof_blend
+from motionbricks.runtime.target_pose import adjust_target_dof_speed, place_target_dof
+
+from ..common.target_pose_blender import BaseTargetPoseBlender
+
+
+class G1TargetPoseBlender(BaseTargetPoseBlender):
+ """Blend G1 joint coordinates around the Idle target of each 2D directional blend space."""
+
+ def blend_linear(self, target_poses: wp.array, sample: BlendSample, output: wp.array, stream) -> None:
+ linear_1d_dof_blend(target_poses, sample, output, stream=stream)
+
+ def blend_directional(self, target_poses: wp.array, sample: BlendSample, output: wp.array, stream) -> None:
+ # DIRECTIONAL_TARGET_VALUES lists the Idle target first.
+ directional_2d_dof_blend(target_poses, sample, target_poses[0][0], output, stream=stream)
+
+ def adjust_speed(self, poses: wp.array, speed: float, stream) -> None:
+ adjust_target_dof_speed(poses, speed, stream=stream)
+
+ def place(
+ self,
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_poses: wp.array,
+ target_poses: wp.array,
+ stream,
+ ) -> None:
+ place_target_dof(ground_position, facing_direction, blended_poses, target_poses, stream=stream)
+
+
+__all__ = ["G1TargetPoseBlender"]
diff --git a/app/scene_editor.py b/app/scene_editor.py
new file mode 100644
index 0000000..89f277f
--- /dev/null
+++ b/app/scene_editor.py
@@ -0,0 +1,830 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Build scenes with Smart Primitives, Solid Cubes, and a CharacterStart."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+import math
+from pathlib import Path
+
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, ModelRig
+from motionbricks.renderers.base_renderer import BaseRenderer
+from motionbricks.renderers.wire_box_renderer import WireBoxRenderer
+from motionbricks.renderers.picking import raycast_lines
+from motionbricks.renderers.solid_box_renderer import SolidBoxRenderer
+from motionbricks.runtime.smart_primitive import (
+ InteractionBox,
+ SmartPrimitive,
+)
+
+from .utils.cli import configure_logging, create_gl_parser
+from .utils.file_dialog import choose_file
+from .runtime.common.rig import RigAssets, create_mesh_renderer, load_rig_assets
+from .runtime.common.smart_primitive_behaviors import behavior_types
+from .runtime.common.io.smart_primitive_document import (
+ SMART_PRIMITIVE_DOCUMENT,
+ SmartPrimitiveAssetPool,
+ load_smart_primitive_rig,
+)
+from .runtime.common.io.scene_document import (
+ SCENE_DOCUMENT,
+ SceneDefinition,
+ SceneItem,
+ SolidCube,
+ SmartPrimitiveInstance,
+ check_reference_rigs,
+ load_scene_document,
+ save_scene_document,
+)
+
+from .authoring.common import (
+ EditorViewer,
+ InlineRename,
+ NAME_TEXT_COLOR,
+ PROPERTIES_WINDOW_HEIGHT,
+ PROPERTIES_WINDOW_WIDTH,
+ WINDOW_MARGIN,
+ accept_drop,
+ apply_transform_locks,
+ drag_source,
+ draw_add_remove_buttons,
+ draw_box_dimensions,
+ draw_character_selector,
+ draw_clip_selector,
+ draw_transform_editor,
+ draw_tree_row,
+ log_transform_gizmo,
+ transforms_equal,
+)
+
+
+_SCENE_WINDOW_WIDTH = 320.0
+_SCENE_WINDOW_HEIGHT = 380.0
+_MIN_SOLID_CUBE_DIMENSION = 0.01
+_CHARACTER_START_RADIUS = 0.35
+_CHARACTER_START_CIRCLE_SEGMENTS = 32
+_CHARACTER_START_ARROW_LENGTH = 0.8
+_CHARACTER_START_MARKER_HEIGHT = 0.01
+_CHARACTER_START_COLOR = wp.vec3(0.25, 0.85, 1.0)
+_INTERACTION_BOX_COLOR = wp.vec3(1.0, 0.15, 0.10)
+_SCENE_ITEM_PAYLOAD = "SCENE_ITEM"
+
+
+def _transform_marker_lines_kernel(
+ transform: wp.transform,
+ local_starts: wp.array(dtype=wp.vec3),
+ local_ends: wp.array(dtype=wp.vec3),
+ world_starts: wp.array(dtype=wp.vec3),
+ world_ends: wp.array(dtype=wp.vec3),
+):
+ index = wp.tid()
+ world_starts[index] = wp.transform_point(transform, local_starts[index])
+ world_ends[index] = wp.transform_point(transform, local_ends[index])
+
+
+class _CharacterStartRenderer(BaseRenderer):
+ _NAME = "/scene_character_start"
+
+ def __init__(self, device=None) -> None:
+ super().__init__()
+ starts = []
+ ends = []
+ for segment in range(_CHARACTER_START_CIRCLE_SEGMENTS):
+ angle0 = math.tau * segment / _CHARACTER_START_CIRCLE_SEGMENTS
+ angle1 = math.tau * (segment + 1) / _CHARACTER_START_CIRCLE_SEGMENTS
+ starts.append(
+ (
+ _CHARACTER_START_RADIUS * math.cos(angle0),
+ _CHARACTER_START_RADIUS * math.sin(angle0),
+ _CHARACTER_START_MARKER_HEIGHT,
+ )
+ )
+ ends.append(
+ (
+ _CHARACTER_START_RADIUS * math.cos(angle1),
+ _CHARACTER_START_RADIUS * math.sin(angle1),
+ _CHARACTER_START_MARKER_HEIGHT,
+ )
+ )
+
+ arrow_length = _CHARACTER_START_ARROW_LENGTH
+ arrow_head_x = arrow_length - 0.18
+ starts.extend(
+ (
+ (0.0, 0.0, _CHARACTER_START_MARKER_HEIGHT),
+ (arrow_length, 0.0, _CHARACTER_START_MARKER_HEIGHT),
+ (arrow_length, 0.0, _CHARACTER_START_MARKER_HEIGHT),
+ )
+ )
+ ends.extend(
+ (
+ (arrow_length, 0.0, _CHARACTER_START_MARKER_HEIGHT),
+ (arrow_head_x, 0.12, _CHARACTER_START_MARKER_HEIGHT),
+ (arrow_head_x, -0.12, _CHARACTER_START_MARKER_HEIGHT),
+ )
+ )
+
+ self._pick_lines = [(wp.vec3(*start), wp.vec3(*end)) for start, end in zip(starts, ends)]
+
+ self.local_starts = wp.array(starts, dtype=wp.vec3, device=device)
+ self.local_ends = wp.array(ends, dtype=wp.vec3, device=device)
+ self.world_starts = wp.empty_like(self.local_starts)
+ self.world_ends = wp.empty_like(self.local_ends)
+ self.colors = wp.array(
+ [_CHARACTER_START_COLOR] * len(starts),
+ dtype=wp.vec3,
+ device=device,
+ )
+
+ def raycast(self, transform: wp.transform, origin: wp.vec3, direction: wp.vec3, max_distance: float) -> float:
+ return raycast_lines(transform, self._pick_lines, origin, direction, max_distance)
+
+ def draw(self, viewer, transform: wp.transform) -> None:
+ wp.launch(
+ _transform_marker_lines_kernel,
+ dim=self.local_starts.shape[0],
+ inputs=[transform, self.local_starts, self.local_ends],
+ outputs=[self.world_starts, self.world_ends],
+ device=self.local_starts.device,
+ )
+ self._log_visible(
+ viewer.log_lines,
+ self._NAME,
+ self.world_starts,
+ self.world_ends,
+ self.colors,
+ )
+
+ def clear(self, viewer) -> None:
+ self._clear(viewer.lines)
+
+
+class _SceneSmartPrimitiveView:
+ """Draw one placed Smart Primitive and keep its previews up to date."""
+
+ def __init__(
+ self,
+ definition: SmartPrimitiveInstance,
+ runtime: SmartPrimitive,
+ model,
+ reference_pose: wp.array,
+ transform: wp.transform,
+ ) -> None:
+ self.definition = definition
+ self.runtime = runtime
+ with wp.ScopedDevice(runtime.device):
+ self.target_poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, *reference_pose.shape),
+ dtype=reference_pose.dtype,
+ )
+ self.interaction_boxes = wp.empty(
+ max(1, runtime.interaction_box_count),
+ dtype=InteractionBox,
+ )
+ self.mesh_renderer = create_mesh_renderer(runtime.rig, model)
+ self.wire_box_renderer = WireBoxRenderer(
+ max_boxes=max(1, runtime.interaction_box_count)
+ )
+ self._target_pose_sequence_index: int | None = None
+ self._target_pose_node_indices: frozenset[int] | None = None
+ self.set_transform(transform)
+
+ @property
+ def target_pose_sequence_index(self) -> int | None:
+ """The previewed sequence, or None to show all target poses."""
+
+ return self._target_pose_sequence_index
+
+ @target_pose_sequence_index.setter
+ def target_pose_sequence_index(self, sequence_index: int | None) -> None:
+ if sequence_index is None:
+ self._target_pose_sequence_index = None
+ self._target_pose_node_indices = None
+ return
+
+ target_names = self.runtime.target_names_for_sequence(sequence_index)
+ self._target_pose_sequence_index = sequence_index
+ self._target_pose_node_indices = frozenset(
+ self.runtime.node_index(name) for name in target_names
+ )
+
+ def set_transform(self, transform: wp.transform) -> None:
+ self.runtime.set_node_world_transform(0, transform)
+
+ def _target_is_visible(self, node_index: int) -> bool:
+ return self.definition.show_target_poses and (
+ self._target_pose_node_indices is None
+ or node_index in self._target_pose_node_indices
+ )
+
+ def raycast(self, origin: wp.vec3, direction: wp.vec3, max_distance: float) -> float:
+ for node_index in range(self.runtime.node_count):
+ if self.runtime.has_target_pose(node_index) and self._target_is_visible(node_index):
+ self.runtime.get_world_target_poses(node_index, self.target_poses)
+ max_distance = self.mesh_renderer.raycast_pose(
+ self.target_poses[0], wp.transform_identity(), origin, direction, max_distance,
+ )
+ box_count = self.runtime.interaction_box_count
+ if self.definition.show_interaction_boxes and box_count:
+ self.runtime.get_world_interaction_boxes(self.interaction_boxes)
+ max_distance = self.wire_box_renderer.raycast_batch(
+ self.interaction_boxes, box_count, origin, direction, max_distance,
+ )
+ return max_distance
+
+ def draw(self, viewer) -> None:
+ runtime = self.runtime
+ definition = self.definition
+ for node_index in range(runtime.node_count):
+ if not runtime.has_target_pose(node_index):
+ continue
+ renderer_id = f"scene_{definition.id}_target_{node_index}"
+ if self._target_is_visible(node_index):
+ runtime.get_world_target_poses(
+ node_index,
+ self.target_poses,
+ )
+ self.mesh_renderer.draw_pose(
+ viewer,
+ self.target_poses[0],
+ wp.transform_identity(),
+ definition.target_pose_color,
+ renderer_id,
+ )
+ else:
+ self.mesh_renderer.hide(viewer, renderer_id)
+
+ box_count = runtime.interaction_box_count
+ renderer_id = f"scene_{definition.id}_interaction_boxes"
+ if definition.show_interaction_boxes and box_count:
+ runtime.get_world_interaction_boxes(self.interaction_boxes)
+ self.wire_box_renderer.draw_batch(
+ viewer,
+ self.interaction_boxes,
+ box_count,
+ _INTERACTION_BOX_COLOR,
+ renderer_id,
+ )
+ else:
+ self.wire_box_renderer.hide(viewer, renderer_id)
+
+ def clear(self, viewer) -> None:
+ self.mesh_renderer.clear(viewer)
+ self.wire_box_renderer.clear(viewer)
+
+
+class SceneEditor(EditorViewer):
+ """Place and edit scene items in a MotionBricks scene."""
+
+ _OUTLINER_WINDOW_TITLE = "Scene"
+ _EDITOR_TITLE = "MotionBricks - Scene Editor"
+ _DOCUMENT_TYPE = SCENE_DOCUMENT
+
+ def __init__(self, viewer, scene_path: str | Path | None = None) -> None:
+ """Open the editor with a new scene, or with the scene at scene_path."""
+ super().__init__(viewer)
+ self.device = wp.get_device()
+ self._rig_assets: RigAssets | None = None
+ self._asset_pool: SmartPrimitiveAssetPool | None = None
+ self.scene = SceneDefinition()
+ self.selected_item_id = self.scene.character_start.id
+ self._runtime_views: dict[int, _SceneSmartPrimitiveView] = {}
+ self._rename = InlineRename()
+ self._reveal_item_ids: set[int] = set()
+ self._gizmo_item_id: int | None = None
+ self._gizmo_source_transform: wp.transform | None = None
+ self._gizmo_transform: wp.transform | None = None
+ # Axis locks are editing preferences and are not saved with the scene.
+ self._transform_locks = defaultdict(lambda: ([False] * 3, [False] * 3))
+ self.character_start_renderer = _CharacterStartRenderer(
+ device=self.device
+ )
+ self.solid_box_renderer = SolidBoxRenderer(
+ device=self.device
+ )
+ self._viewer_ui.on_scene_click = self._select_scene_item
+
+ if scene_path is not None:
+ self._open_document(scene_path)
+
+ @property
+ def selected(self) -> SceneItem:
+ """Selected scene item, or CharacterStart when nothing is selected."""
+ return (
+ self.scene.find_item(self.selected_item_id)
+ or self.scene.character_start
+ )
+
+ def _new_document(self) -> None:
+ scene = SceneDefinition(rig=self.scene.rig)
+ self._replace_scene(
+ scene,
+ selected_item_id=scene.character_start.id,
+ document_path=None,
+ runtime_views={},
+ )
+
+ def _save_document(self, path: str | Path) -> Path:
+ return save_scene_document(self.scene, path, self.selected_item_id, self._capture_camera_state())
+
+ def _open_document(self, path: str | Path) -> None:
+ try:
+ document_path = Path(path).expanduser().resolve()
+ scene, selected_item_id, camera_state = load_scene_document(
+ document_path
+ )
+ check_reference_rigs(scene)
+ runtime_views = self._create_runtime_views(scene)
+ except ValueError as exc:
+ self._status = f"Open failed: {exc}"
+ return
+
+ self._replace_scene(
+ scene,
+ selected_item_id,
+ document_path,
+ runtime_views,
+ )
+ self._apply_camera_state(camera_state)
+
+ def _replace_scene(
+ self,
+ scene: SceneDefinition,
+ selected_item_id: int,
+ document_path: Path | None,
+ runtime_views: dict[int, _SceneSmartPrimitiveView],
+ ) -> None:
+ self._clear_runtime_views()
+ self.solid_box_renderer.clear(self.viewer)
+ self.scene = scene
+ self.selected_item_id = selected_item_id
+ self._runtime_views = runtime_views
+ self._rename = InlineRename()
+ self._reveal_item_ids = set()
+ self._gizmo_item_id = None
+ self._gizmo_source_transform = None
+ self._gizmo_transform = None
+ self._transform_locks.clear()
+ self._set_document_path(document_path)
+
+ def _create_runtime_views(
+ self,
+ scene: SceneDefinition,
+ ) -> dict[int, _SceneSmartPrimitiveView]:
+ views = {}
+ for instance in scene.smart_primitives:
+ if instance.reference is not None:
+ views[instance.id] = self._create_runtime_view(instance, scene.rig, scene.world_transform(instance))
+ return views
+
+ def _create_runtime_view(
+ self,
+ instance: SmartPrimitiveInstance,
+ rig: ModelRig,
+ transform: wp.transform,
+ ) -> _SceneSmartPrimitiveView:
+ model, asset_pool = self._rig_for(rig)
+ runtime = asset_pool.instantiate(instance.reference)
+ return _SceneSmartPrimitiveView(instance, runtime, model, asset_pool.reference_pose, transform)
+
+ def _rig_for(self, rig: ModelRig) -> tuple[object, SmartPrimitiveAssetPool]:
+ """Return the rig's model and asset pool. Another rig replaces the current one."""
+ if self._rig_assets is None or self._rig_assets.clip_registry.rig is not rig:
+ with wp.ScopedDevice(self.device):
+ assets = load_rig_assets(rig)
+ self._rig_assets = assets
+ self._asset_pool = SmartPrimitiveAssetPool(
+ assets.clip_registry, assets.reference_pose, assets.model_to_runtime,
+ )
+ return self._rig_assets.model, self._asset_pool
+
+ def _assign_reference(
+ self,
+ instance: SmartPrimitiveInstance,
+ path: str | Path,
+ ) -> None:
+ resolved_path = Path(path).expanduser().resolve()
+ # The first reference chooses the rig. Later references must match it.
+ character_is_fixed = self._has_references()
+ previous_reference = instance.reference
+ instance.reference = resolved_path
+ try:
+ if character_is_fixed:
+ check_reference_rigs(self.scene)
+ rig = self.scene.rig
+ else:
+ rig = load_smart_primitive_rig(resolved_path)
+ view = self._create_runtime_view(instance, rig, self.scene.world_transform(instance))
+ except ValueError as exc:
+ instance.reference = previous_reference
+ self._status = f"Reference failed: {exc}"
+ return
+
+ self.scene.rig = rig
+ previous_view = self._runtime_views.get(instance.id)
+ if previous_view is not None:
+ previous_view.clear(self.viewer)
+ self._runtime_views[instance.id] = view
+ self._status = None
+
+ def _clear_runtime_views(self) -> None:
+ for view in self._runtime_views.values():
+ view.clear(self.viewer)
+ self._runtime_views.clear()
+
+ def _delete_item(self, item_id: int) -> None:
+ """Delete an item and every item under it."""
+ removed_ids = self.scene.remove_item(item_id)
+ for removed_id in removed_ids:
+ view = self._runtime_views.pop(removed_id, None)
+ if view is not None:
+ view.clear(self.viewer)
+ self._transform_locks.pop(removed_id, None)
+ if removed_ids:
+ self.selected_item_id = self.scene.character_start.id
+ self._rename.item_id = None
+
+ def _set_parent(self, item_id: int, parent_id: int | None) -> None:
+ item = self.scene.find_item(item_id)
+ if item is not None and self.scene.set_parent(item, parent_id):
+ self.selected_item_id = item.id
+
+ def _set_item_transform(self, item: SceneItem, transform: wp.transform) -> None:
+ """Set the local transform and update the whole branch."""
+ item.transform = wp.transform(transform)
+ for moved in self.scene.subtree(item):
+ world_transform = self.scene.world_transform(moved)
+ view = self._runtime_views.get(moved.id)
+ if view is not None:
+ view.set_transform(world_transform)
+ if moved.id == self._gizmo_item_id and self._gizmo_transform is not None:
+ self._gizmo_transform[:] = world_transform
+ self._gizmo_source_transform[:] = world_transform
+
+ def _select_scene_item(self, origin: wp.vec3, direction: wp.vec3) -> None:
+ nearest = self.viewer.camera.far
+ for view in self._runtime_views.values():
+ distance = view.raycast(origin, direction, nearest)
+ if distance < nearest:
+ nearest = distance
+ self.selected_item_id = view.definition.id
+ for cube in self.scene.solid_cubes:
+ distance = self.solid_box_renderer.raycast(
+ self.scene.world_transform(cube), wp.vec3(cube.width, cube.depth, cube.height),
+ origin, direction, nearest,
+ )
+ if distance < nearest:
+ nearest = distance
+ self.selected_item_id = cube.id
+ start = self.scene.character_start
+ distance = self.character_start_renderer.raycast(start.transform, origin, direction, nearest)
+ if distance < nearest:
+ self.selected_item_id = start.id
+ self._reveal_selected()
+
+ def _reveal_selected(self) -> None:
+ """Open the tree down to the selected item and scroll to it."""
+ item = self.selected
+ self._reveal_item_ids = set()
+ while item is not None:
+ self._reveal_item_ids.add(item.id)
+ item = self.scene.find_item(item.parent_id)
+
+ def _draw_editor_scene(self) -> None:
+ self.character_start_renderer.draw(
+ self.viewer,
+ self.scene.character_start.transform,
+ )
+ for view in self._runtime_views.values():
+ view.draw(self.viewer)
+ self.solid_box_renderer.draw_batch(
+ self.viewer,
+ [self.scene.world_transform(cube) for cube in self.scene.solid_cubes],
+ [
+ wp.vec3(cube.width, cube.depth, cube.height)
+ for cube in self.scene.solid_cubes
+ ],
+ [cube.color for cube in self.scene.solid_cubes],
+ "scene",
+ )
+
+ def _draw_selection_gizmo(self) -> None:
+ item = self.selected
+ self._gizmo_item_id = item.id
+ self._gizmo_source_transform = self.scene.world_transform(item)
+ self._gizmo_transform = wp.transform(self._gizmo_source_transform)
+ translation_locks, rotation_locks = self._transform_locks[item.id]
+ parent = self.scene.find_item(item.parent_id)
+ log_transform_gizmo(
+ self.viewer,
+ "scene_selection",
+ self._gizmo_transform,
+ translation_locks=translation_locks,
+ rotation_locks=rotation_locks,
+ axes_rotation=None if parent is None else self.scene.world_transform(parent).q,
+ )
+
+ def _apply_selection_gizmo(self) -> None:
+ item = self.scene.find_item(self._gizmo_item_id)
+ if (
+ item is None
+ or self._gizmo_source_transform is None
+ or self._gizmo_transform is None
+ or transforms_equal(
+ self._gizmo_source_transform,
+ self._gizmo_transform,
+ )
+ ):
+ return
+ transform, item.euler_degrees = apply_transform_locks(
+ item.transform, self.scene.local_transform(item, self._gizmo_transform), item.euler_degrees,
+ *self._transform_locks[item.id],
+ )
+ self._set_item_transform(item, transform)
+
+ def _draw_outliner_window(self, ui, dpi_scale: float) -> None:
+ self._set_initial_panel_geometry(
+ ui,
+ dpi_scale,
+ _SCENE_WINDOW_WIDTH,
+ _SCENE_WINDOW_HEIGHT,
+ WINDOW_MARGIN,
+ )
+ window_visible, _ = ui.begin(self._OUTLINER_WINDOW_TITLE)
+ delete_id = None
+ if window_visible:
+ self._draw_character_selector(ui)
+ delete_id = self._draw_scene_toolbar(ui)
+ self._draw_status(ui)
+ ui.separator()
+ for item in (self.scene.character_start, *self.scene.children(None)):
+ delete_id = self._draw_scene_item(ui, item) or delete_id
+ self._draw_root_drop_target(ui)
+ ui.end()
+ if delete_id is not None:
+ self._delete_item(delete_id)
+
+ def _has_references(self) -> bool:
+ return any(instance.reference is not None for instance in self.scene.smart_primitives)
+
+ def _draw_character_selector(self, ui) -> None:
+ self.scene.rig = draw_character_selector(
+ ui,
+ self.scene.rig,
+ "Smart Primitive references lock the Character selector. Delete those Smart Primitives or start a "
+ "new scene to change it."
+ if self._has_references() else None,
+ )
+
+ def _draw_scene_toolbar(self, ui) -> int | None:
+ selected = self.selected
+ add, remove_selected = draw_add_remove_buttons(ui, selected is not self.scene.character_start)
+ if add:
+ ui.open_popup("##AddSceneItem")
+ if ui.begin_popup("##AddSceneItem"):
+ add_smart_primitive, _ = ui.menu_item(
+ "Smart Primitive",
+ "",
+ False,
+ )
+ add_solid_cube, _ = ui.menu_item(
+ "Solid Cube",
+ "",
+ False,
+ )
+ ui.end_popup()
+ if add_smart_primitive:
+ item = self.scene.add_smart_primitive()
+ self.selected_item_id = item.id
+ elif add_solid_cube:
+ item = self.scene.add_solid_cube()
+ self.selected_item_id = item.id
+ return selected.id if remove_selected else None
+
+ def _draw_scene_item(self, ui, item: SceneItem) -> int | None:
+ """Draw a branch and return the item requested for deletion."""
+ ui.push_id(item.id)
+ children = self.scene.children(item.id)
+ renaming = item.id == self._rename.item_id
+ is_start = item is self.scene.character_start
+ node_open, clicked, name = draw_tree_row(
+ ui, item.name, item.id, self._rename, self._reveal_item_ids,
+ selected=item.id == self.selected_item_id, leaf=not children, renamable=not is_start,
+ )
+ if clicked:
+ self.selected_item_id = item.id
+ if name:
+ item.name = name
+
+ delete_id = None
+ if not renaming and not is_start:
+ # Drop an item onto another to place it under that item.
+ drag_source(ui, _SCENE_ITEM_PAYLOAD, item.id, item.name)
+ dropped_id = accept_drop(ui, _SCENE_ITEM_PAYLOAD)
+ if dropped_id is not None:
+ self._set_parent(dropped_id, item.id)
+ delete_id = self._draw_item_context_menu(ui, item)
+
+ if node_open:
+ for child in children:
+ delete_id = self._draw_scene_item(ui, child) or delete_id
+ ui.tree_pop()
+ ui.pop_id()
+ return delete_id
+
+ def _draw_root_drop_target(self, ui) -> None:
+ """Accept drops below the tree to move an item to the top level."""
+ space = ui.get_content_region_avail()
+ size = ui.ImVec2(max(space.x, 1.0), max(space.y, ui.get_frame_height()))
+ ui.invisible_button("##SceneRoot", size)
+ dropped_id = accept_drop(ui, _SCENE_ITEM_PAYLOAD)
+ if dropped_id is not None:
+ self._set_parent(dropped_id, None)
+
+ def _draw_item_context_menu(self, ui, item: SmartPrimitiveInstance | SolidCube) -> int | None:
+ if not ui.begin_popup_context_item("##SceneItemContext"):
+ return None
+ self.selected_item_id = item.id
+ move_to_root, _ = ui.menu_item("Move to Root", "", False, item.parent_id is not None)
+ delete_requested, _ = ui.menu_item("Delete", "", False)
+ ui.end_popup()
+ if move_to_root:
+ self._set_parent(item.id, None)
+ return item.id if delete_requested else None
+
+ def _draw_properties_window(self, ui, dpi_scale: float) -> None:
+ self._set_initial_panel_geometry(
+ ui,
+ dpi_scale,
+ PROPERTIES_WINDOW_WIDTH,
+ PROPERTIES_WINDOW_HEIGHT,
+ _SCENE_WINDOW_HEIGHT + 2.0 * WINDOW_MARGIN,
+ )
+ item = self.selected
+ window_visible, _ = ui.begin("Properties")
+ reference_requested = False
+ if window_visible:
+ ui.push_id(item.id)
+ try:
+ ui.text_colored(ui.ImVec4(*NAME_TEXT_COLOR), item.name)
+ if ui.collapsing_header(
+ "Transform",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ self._draw_transform_details(ui, item, dpi_scale)
+ if isinstance(item, SmartPrimitiveInstance):
+ reference_requested = self._draw_smart_primitive_details(ui, item)
+ elif isinstance(item, SolidCube):
+ if ui.collapsing_header(
+ "Solid Cube",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ self._draw_solid_cube_details(ui, item, dpi_scale)
+ finally:
+ ui.pop_id()
+ ui.end()
+
+ if reference_requested:
+ path = choose_file(
+ "Reference Smart Primitive", "Smart Primitive documents", SMART_PRIMITIVE_DOCUMENT.suffix,
+ item.reference,
+ )
+ if path:
+ self._assign_reference(item, path)
+
+ def _draw_smart_primitive_details(self, ui, item: SmartPrimitiveInstance) -> bool:
+ """Draw the Smart Primitive, Visibility, and Runtime sections.
+
+ Returns:
+ Whether the button that picks the referenced document was clicked.
+ """
+ reference_requested = False
+ if ui.collapsing_header(
+ "Smart Primitive",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ reference = item.reference
+ reference_requested = draw_clip_selector(
+ ui, reference.name if reference else "None", reference, item.id, label="Reference",
+ )
+ if ui.collapsing_header(
+ "Visibility",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ _, item.show_target_poses = ui.checkbox(
+ "Show Target Poses",
+ item.show_target_poses,
+ )
+ ui.same_line()
+ view = self._runtime_views.get(item.id)
+ sequence_names = (
+ tuple(
+ view.runtime.sequence_name(index)
+ for index in range(view.runtime.sequence_count)
+ )
+ if view is not None
+ else ()
+ )
+ selected_sequence = (
+ 0
+ if view is None
+ or view.target_pose_sequence_index is None
+ else view.target_pose_sequence_index + 1
+ )
+ ui.begin_disabled(
+ not item.show_target_poses or not sequence_names
+ )
+ ui.set_next_item_width(max(
+ 1.0,
+ ui.get_content_region_avail().x
+ - ui.get_frame_height()
+ - ui.get_style().item_spacing.x,
+ ))
+ changed, selected_sequence = ui.combo(
+ "##TargetPoseSequence",
+ selected_sequence,
+ ("All",) + sequence_names,
+ )
+ ui.end_disabled()
+ if changed and view is not None:
+ view.target_pose_sequence_index = (
+ None
+ if selected_sequence == 0
+ else selected_sequence - 1
+ )
+ ui.same_line()
+ changed, color = ui.color_edit3(
+ "Target Pose Color",
+ item.target_pose_color,
+ ui.ColorEditFlags_.no_inputs | ui.ColorEditFlags_.no_label,
+ )
+ if changed:
+ item.target_pose_color = wp.vec3(*color)
+ _, item.show_interaction_boxes = ui.checkbox(
+ "Show Interaction Boxes",
+ item.show_interaction_boxes,
+ )
+ if ui.collapsing_header(
+ "Runtime",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ if ui.begin_combo("Behavior", item.behavior):
+ for name in behavior_types():
+ if ui.selectable(name, name == item.behavior)[0]:
+ item.behavior = name
+ ui.end_combo()
+ return reference_requested
+
+ def _draw_transform_details(
+ self,
+ ui,
+ item: SceneItem,
+ dpi_scale: float,
+ ) -> None:
+ changed, transform, item.euler_degrees = draw_transform_editor(
+ ui, item.transform, item.euler_degrees, dpi_scale,
+ *self._transform_locks[item.id],
+ )
+ if changed:
+ self._set_item_transform(item, transform)
+
+ @staticmethod
+ def _draw_solid_cube_details(
+ ui,
+ cube: SolidCube,
+ dpi_scale: float,
+ ) -> None:
+ _, (cube.width, cube.depth, cube.height) = draw_box_dimensions(
+ ui, (cube.width, cube.depth, cube.height), _MIN_SOLID_CUBE_DIMENSION, dpi_scale,
+ )
+ # The color fields accept typed values, so keep each channel from 0 to 1.
+ color_changed, color = ui.color_edit3("Color", cube.color)
+ if color_changed:
+ cube.color = wp.vec3(*(min(max(channel, 0.0), 1.0) for channel in color))
+
+
+def main() -> None:
+ """Parse the command line and open the Scene Editor."""
+ import newton.examples
+
+ parser = create_gl_parser()
+ parser.add_argument(
+ "scene",
+ type=Path,
+ nargs="?",
+ help="Scene document to open at startup.",
+ )
+ viewer, args = newton.examples.init(parser)
+ configure_logging(args)
+ viewer.hide_loading_splash()
+
+ SceneEditor(viewer, args.scene).run(args.num_frames if args.test else None)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/app/scene_preview.py b/app/scene_preview.py
new file mode 100644
index 0000000..04c15d4
--- /dev/null
+++ b/app/scene_preview.py
@@ -0,0 +1,1110 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Play a character in a saved scene and try its Smart Primitive interactions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import partial
+import math
+import time
+from pathlib import Path
+
+import newton
+import numpy as np
+from pyglet.math import Vec3
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, ModelRig
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+from motionbricks.renderers.dof_mesh_renderer import DOFMeshRenderer
+from motionbricks.renderers.foot_contact_renderer import (
+ DOFFootContactRenderer,
+ FootContactRenderer,
+ SkeletonFootContactRenderer,
+)
+from motionbricks.renderers.wire_box_renderer import WireBoxRenderer
+from motionbricks.renderers.skeletal_mesh_renderer import SkeletalMeshRenderer
+from motionbricks.renderers.skeleton_renderer import DOFSkeletonRenderer, SkeletonRenderer
+from motionbricks.renderers.solid_box_renderer import SolidBoxRenderer
+from motionbricks.renderers.vector_arrow_renderer import VectorArrowRenderer
+from motionbricks.runtime.smart_primitive import (
+ InteractionBox,
+ compute_interaction_box_overlaps,
+)
+from motionbricks.utils.math_utils import critical_spring_damper_exact
+
+from .authoring.common import WINDOW_MARGIN
+from .runtime.common.rig import (
+ ASSETS_ROOT,
+ CHARACTER_COLORS,
+ RigAssets,
+ create_foot_contact_renderer,
+ create_mesh_renderer,
+ create_skeleton_renderer,
+ load_rig_assets,
+)
+from .runtime.common.io.smart_primitive_document import SmartPrimitiveAssetPool
+from .runtime.common.io.scene_document import (
+ SCENE_DOCUMENT,
+ SceneDefinition,
+ SmartPrimitiveInstance,
+ check_reference_rigs,
+ load_scene_document,
+)
+from .utils.cli import add_model_precision_argument, configure_logging, create_gl_parser
+from .utils.file_dialog import choose_file
+from .utils.model_loading import create_engine, require_tensorrt
+from .utils.input import InputManager, LocomotionModeInput, camera_relative_movement
+from .runtime.soma.character import SOMACharacter
+from .runtime.unitree_g1.character import UnitreeG1Character
+
+_CHARACTER_TYPES = {ModelRig.SOMA: SOMACharacter, ModelRig.UNITREE_G1: UnitreeG1Character}
+from .runtime.common.motion import LocomotionCommand, ground_direction
+from .runtime.common.state_machine import StateMachine
+from .runtime.common.smart_primitive_behaviors import (
+ SmartPrimitiveBehavior,
+ behavior_types,
+)
+
+
+_CAMERA_DISTANCE = 5.0
+_CAMERA_ELEVATION_DEGREES = 25.0
+_CAMERA_PIVOT_Z_OFFSET = 0.8
+_CAMERA_VELOCITY_HALFLIFE = 0.15
+_CAMERA_PULL_SECONDS = 0.05
+_CONTROLLER_CAMERA_ORBIT_SPEED = 75.0
+_VELOCITY_ARROW_HEIGHT = 0.025
+_CHARACTER_VELOCITY_ARROW_COLOR = (1.0, 0.25, 0.1)
+_INPUT_VELOCITY_ARROW_COLOR = (0.15, 0.45, 1.0)
+_DESIRED_VELOCITY_ARROW_COLOR = (0.15, 1.0, 0.35)
+_CONTEXT_COLOR = wp.vec3(0.65, 0.3, 0.85)
+_TARGET_COLOR = wp.vec3(0.2, 0.75, 1.0)
+_BLENDSPACE_DEBUG_COLOR = wp.vec3(0.15, 1.0, 0.35)
+_INTERACTION_BOX_COLOR = wp.vec3(1.0, 0.25, 0.85)
+_INACTIVE_SMART_PRIMITIVE_BOX_COLOR = wp.vec3(1.0, 0.15, 0.10)
+_ACTIVE_SMART_PRIMITIVE_BOX_COLOR = wp.vec3(0.15, 1.0, 0.25)
+_PANEL_WIDTH = 340.0
+_PANEL_HEIGHT = 390.0
+_PANEL_ALPHA = 0.8
+_MAX_FRAME_SECONDS = 0.1
+_MIN_FRAME_SECONDS = 1.0e-6
+_SCENE_LAYER_ID = "scene_preview"
+_DEFAULT_SCENE = ASSETS_ROOT / "scenes" / "soma_gym.scene.json"
+
+
+class _RuntimeSceneSmartPrimitive:
+ """A placed Smart Primitive with its interaction boxes and debug previews.
+
+ reference_pose gives the character's pose layout, and target_pose_renderer
+ draws the rig's target poses.
+ """
+
+ def __init__(
+ self,
+ definition: SmartPrimitiveInstance,
+ runtime: SmartPrimitiveBehavior,
+ interaction_box_offset: int,
+ reference_pose: wp.array,
+ target_pose_renderer: SkeletonRenderer | DOFSkeletonRenderer,
+ stream: wp.Stream,
+ ) -> None:
+ self.definition = definition
+ self.runtime = runtime
+ self.interaction_box_offset = interaction_box_offset
+ self.interaction_box_count = runtime.interaction_box_count
+ self.interactable = False
+ self._interaction_boxes_dirty = True
+ runtime.set_node_world_transform(
+ 0,
+ definition.transform,
+ stream=stream,
+ )
+
+ self.target_pose_scratch = wp.empty(
+ (MODEL_POSES_PER_TOKEN, *reference_pose.shape),
+ dtype=reference_pose.dtype,
+ device=runtime.device,
+ )
+ self.target_pose_colors = wp.array([definition.target_pose_color], dtype=wp.vec3, device=runtime.device)
+ self.target_pose_renderer = target_pose_renderer
+
+ self.wire_box_renderer = WireBoxRenderer(
+ max_boxes=max(1, self.interaction_box_count)
+ )
+
+ def distance_squared_to(self, position: np.ndarray) -> float:
+ root_position = np.array(self.definition.transform.p, dtype=np.float32)
+ offset = root_position - position
+ return float(np.dot(offset, offset))
+
+ def refresh_interaction_boxes(
+ self,
+ scene_interaction_boxes: wp.array,
+ stream: wp.Stream,
+ nodes_moved: bool = False,
+ ) -> None:
+ """Update the interaction boxes on the first call, or when nodes_moved says their nodes moved."""
+
+ if self.interaction_box_count == 0 or not (nodes_moved or self._interaction_boxes_dirty):
+ return
+ start = self.interaction_box_offset
+ end = start + self.interaction_box_count
+ self.runtime.get_world_interaction_boxes(
+ scene_interaction_boxes[start:end],
+ stream=stream,
+ )
+ self._interaction_boxes_dirty = False
+
+ def draw(
+ self,
+ viewer,
+ scene_interaction_boxes: wp.array,
+ stream: wp.Stream,
+ show_target_poses: bool,
+ show_interaction_boxes: bool,
+ ) -> None:
+ runtime = self.runtime
+ instance_id = self.definition.id
+ for node_index in range(runtime.node_count):
+ if not runtime.has_target_pose(node_index):
+ continue
+ renderer_id = f"scene_{instance_id}_target_{node_index}"
+ if show_target_poses and self.definition.show_target_poses:
+ runtime.get_world_target_poses(
+ node_index,
+ self.target_pose_scratch,
+ stream=stream,
+ )
+ # Only each target's first pose is drawn, so the targets stay readable.
+ self.target_pose_renderer.draw_batch(
+ viewer,
+ self.target_pose_scratch,
+ 1,
+ wp.transform_identity(),
+ self.target_pose_colors,
+ renderer_id,
+ )
+ else:
+ self.target_pose_renderer.hide(viewer, renderer_id)
+
+ renderer_id = f"scene_{instance_id}_interaction_boxes"
+ box_count = self.interaction_box_count
+ if (
+ show_interaction_boxes
+ and self.definition.show_interaction_boxes
+ and box_count
+ ):
+ start = self.interaction_box_offset
+ boxes = scene_interaction_boxes[start : start + box_count]
+ color = (
+ _ACTIVE_SMART_PRIMITIVE_BOX_COLOR
+ if self.interactable
+ else _INACTIVE_SMART_PRIMITIVE_BOX_COLOR
+ )
+ self.wire_box_renderer.draw_batch(
+ viewer,
+ boxes,
+ box_count,
+ color,
+ renderer_id,
+ )
+ else:
+ self.wire_box_renderer.hide(viewer, renderer_id)
+
+
+@dataclass(slots=True)
+class _SceneSession:
+ """The character, scene items, and rendering buffers for one loaded scene.
+
+ Poses are local joint transforms for SOMA and joint coordinates for Unitree G1.
+ context_poses shows the poses in the character's context token. target_poses shows
+ the poses in its target token.
+ """
+
+ path: Path
+ definition: SceneDefinition
+ state_machine: StateMachine
+ character: SOMACharacter | UnitreeG1Character
+ smart_primitives: tuple[_RuntimeSceneSmartPrimitive, ...]
+ interaction_boxes: wp.array
+ interaction_overlap_results: wp.array
+ interaction_box_count: int
+ character_color: wp.vec3 | None
+ context_poses: wp.array
+ target_poses: wp.array
+ blended_target_poses: wp.array
+ blendspace_target_poses: wp.array
+ solid_box_renderer: SolidBoxRenderer
+ mesh_renderer: SkeletalMeshRenderer | DOFMeshRenderer
+ context_renderer: SkeletonRenderer | DOFSkeletonRenderer
+ target_renderer: SkeletonRenderer | DOFSkeletonRenderer
+ blendspace_renderer: SkeletonRenderer | DOFSkeletonRenderer
+ interaction_box_renderer: WireBoxRenderer
+ foot_contact_renderer: SkeletonFootContactRenderer | DOFFootContactRenderer
+ model: object
+ simulation_state: object
+
+
+def _check_scene(scene: SceneDefinition) -> None:
+ """Check each Smart Primitive's reference, behavior, and rig before anything loads."""
+
+ for definition in scene.smart_primitives:
+ if definition.reference is None:
+ raise ValueError(
+ f"Smart Primitive {definition.name!r} has no reference."
+ )
+ if definition.behavior not in behavior_types():
+ raise ValueError(
+ f"Smart Primitive {definition.name!r} uses unknown behavior "
+ f"{definition.behavior!r}."
+ )
+ check_reference_rigs(scene)
+
+
+def _camera_pivot_position(ground_position: np.ndarray) -> np.ndarray:
+ pivot_position = np.asarray(ground_position, dtype=np.float32).copy()
+ pivot_position[2] += _CAMERA_PIVOT_Z_OFFSET
+ return pivot_position
+
+
+def _format_vector3(vector: np.ndarray) -> str:
+ return f"({vector[0]:.2f}, {vector[1]:.2f}, {vector[2]:.2f})"
+
+
+class ScenePreview:
+ """Move a character through a saved scene and interact with its Smart Primitives.
+
+ The scene's rig chooses the character. One rig and its engine are loaded at a
+ time. A scene for the other rig closes the current engine before the new one loads.
+ """
+
+ _scene_session: _SceneSession
+
+ def __init__(
+ self,
+ viewer,
+ scene_path: str | Path,
+ *,
+ fp16: bool = False,
+ ) -> None:
+ """Open Scene Preview on a graphical viewer and load the scene at scene_path.
+
+ fp16 selects the mixed FP16 models.
+ """
+ if isinstance(viewer, newton.viewer.ViewerNull):
+ raise RuntimeError("Scene Preview requires a graphical viewer.")
+
+ self.viewer = viewer
+ self._rig_assets: RigAssets | None = None
+ self._engine: MotionBricksSOMAEngine | MotionBricksUnitreeG1Engine | None = None
+ self._pending_scene_path: Path | None = None
+ self.scene_error: str | None = None
+
+ self.show_context_poses = False
+ self.show_target_poses = False
+ self.show_blendspace_targets = False
+ self.show_probe_box = False
+ self.show_actual_velocity = True
+ self.show_input_velocity = True
+ self.show_desired_velocity = True
+ self.show_foot_contacts = False
+ self.foot_contact_threshold = FootContactRenderer.DEFAULT_THRESHOLD
+ self.show_scene_object_target_poses = False
+ self.show_scene_object_interaction_boxes = True
+ self.auto_interaction = True
+ self.fp16 = fp16
+
+ self.context_colors = wp.array(
+ [_CONTEXT_COLOR] * MODEL_POSES_PER_TOKEN,
+ dtype=wp.vec3,
+ )
+ self.target_colors = wp.array(
+ [_TARGET_COLOR] * MODEL_POSES_PER_TOKEN,
+ dtype=wp.vec3,
+ )
+ self.blendspace_debug_colors = wp.array(
+ [_BLENDSPACE_DEBUG_COLOR],
+ dtype=wp.vec3,
+ )
+ self.character_velocity_renderer = VectorArrowRenderer(
+ "actual_velocity", wp.vec3(*_CHARACTER_VELOCITY_ARROW_COLOR),
+ )
+ self.input_velocity_renderer = VectorArrowRenderer(
+ "input_velocity", wp.vec3(*_INPUT_VELOCITY_ARROW_COLOR),
+ )
+ self.desired_velocity_renderer = VectorArrowRenderer(
+ "desired_velocity", wp.vec3(*_DESIRED_VELOCITY_ARROW_COLOR),
+ )
+
+ self.viewer.camera_speed = 0.0
+ self.viewer.vsync = False
+ self.viewer.renderer.set_title("MotionBricks - Scene Preview")
+ self._input = InputManager.from_pyglet(self.viewer.is_key_down)
+ try:
+ self.load_scene(scene_path)
+ except BaseException:
+ self.close()
+ raise
+ # The camera follows the character, so wait for the first scene.
+ self.viewer.renderer.register_mouse_drag(self._on_mouse_drag)
+
+ def close(self) -> None:
+ """Release the input devices and the engine."""
+
+ self._input.close()
+ if self._engine is not None:
+ self._engine.close()
+ self._engine = None
+
+ def load_scene(self, path: str | Path) -> None:
+ """Load a scene and replace the current one.
+
+ Failures in _prepare_scene() keep the current scene. Failures after it mean a
+ broken installation, such as a missing asset or a failed TensorRT build.
+ """
+
+ self._start_scene(*self._prepare_scene(path))
+
+ def _prepare_scene(self, path: str | Path) -> tuple[Path, SceneDefinition, RigAssets, SmartPrimitiveAssetPool]:
+ """Read and check a scene, then load its rig and every Smart Primitive it uses.
+
+ Nothing here needs an engine, so the current scene keeps running if it fails.
+ """
+
+ scene_path = Path(path).expanduser().resolve()
+ scene, _, _ = load_scene_document(scene_path)
+ # Parenting only helps editing. Runtime items are placed by their world transforms.
+ scene = scene.flatten()
+ _check_scene(scene)
+ assets = self._rig_assets
+ if assets is None or assets.clip_registry.rig is not scene.rig:
+ assets = load_rig_assets(scene.rig)
+ asset_pool = SmartPrimitiveAssetPool(assets.clip_registry, assets.reference_pose, assets.model_to_runtime)
+ for definition in scene.smart_primitives:
+ asset_pool.load(definition.reference)
+ return scene_path, scene, assets, asset_pool
+
+ def _start_scene(
+ self,
+ path: Path,
+ scene: SceneDefinition,
+ assets: RigAssets,
+ asset_pool: SmartPrimitiveAssetPool,
+ ) -> None:
+ self._use_rig(assets)
+ with wp.ScopedStream(self._engine.stream):
+ session = self._create_scene_session(path, scene, asset_pool)
+ self._activate_scene_session(session)
+
+ def _use_rig(self, assets: RigAssets) -> None:
+ """Make assets the current rig. For the other rig, close its engine before loading this one."""
+
+ if assets is self._rig_assets:
+ return
+ if self._engine is not None:
+ self._engine.synchronize()
+ self._engine.close()
+ self._engine = None
+ self._rig_assets = assets
+ self._engine = create_engine(self.viewer, assets.clip_registry.rig, self.fp16)
+
+ def _create_scene_session(
+ self,
+ path: Path,
+ scene: SceneDefinition,
+ asset_pool: SmartPrimitiveAssetPool,
+ ) -> _SceneSession:
+ engine = self._engine
+ assets = self._rig_assets
+ start = scene.character_start.transform
+ character = _CHARACTER_TYPES[scene.rig](engine, asset_pool=asset_pool, initial_transform=start)
+ character_color = CHARACTER_COLORS[scene.rig]
+ mesh_renderer = create_mesh_renderer(scene.rig, assets.model)
+ skeleton_renderer = partial(create_skeleton_renderer, scene.rig, assets.model)
+ foot_contact_renderer = create_foot_contact_renderer(scene.rig, "foot_contacts", assets.model)
+ context_poses = character.player.context.poses
+ target_poses = character.player.target.poses
+ state_machine = character.state_machine
+ smart_primitives, interaction_box_count = (
+ self._create_smart_primitive_instances(
+ scene,
+ asset_pool,
+ skeleton_renderer,
+ engine.stream,
+ )
+ )
+ for instance in smart_primitives:
+ state_machine.interaction_state.prepare(character, instance.runtime)
+ interaction_box_capacity = max(1, interaction_box_count)
+ pose = character.current_pose
+ blended_target_poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, *pose.shape),
+ dtype=pose.dtype,
+ device=engine.device,
+ )
+
+ builder = newton.ModelBuilder()
+ builder.add_ground_plane()
+ model = builder.finalize()
+ return _SceneSession(
+ path=path,
+ definition=scene,
+ state_machine=state_machine,
+ character=character,
+ smart_primitives=smart_primitives,
+ interaction_boxes=wp.empty(
+ interaction_box_capacity,
+ dtype=InteractionBox,
+ device=engine.device,
+ ),
+ interaction_overlap_results=wp.empty(
+ interaction_box_capacity,
+ dtype=wp.int32,
+ device=engine.device,
+ ),
+ interaction_box_count=interaction_box_count,
+ character_color=character_color,
+ context_poses=context_poses,
+ target_poses=target_poses,
+ blended_target_poses=blended_target_poses,
+ blendspace_target_poses=wp.empty_like(blended_target_poses),
+ solid_box_renderer=SolidBoxRenderer(
+ max_boxes=max(1, len(scene.solid_cubes)),
+ device=engine.device,
+ ),
+ mesh_renderer=mesh_renderer,
+ context_renderer=skeleton_renderer(max_instances=MODEL_POSES_PER_TOKEN),
+ target_renderer=skeleton_renderer(max_instances=MODEL_POSES_PER_TOKEN),
+ blendspace_renderer=skeleton_renderer(max_instances=1),
+ interaction_box_renderer=WireBoxRenderer(),
+ foot_contact_renderer=foot_contact_renderer,
+ model=model,
+ simulation_state=model.state(),
+ )
+
+ def _activate_scene_session(self, session: _SceneSession) -> None:
+ # The previous scene may run on another engine's stream. Finish its
+ # work before its buffers are released.
+ wp.synchronize_device(session.character.engine.device)
+ if _SCENE_LAYER_ID in self.viewer.layers:
+ self.viewer.remove_layer(_SCENE_LAYER_ID)
+ self.viewer.activate(_SCENE_LAYER_ID)
+ self.viewer.set_model(session.model)
+ self.viewer.set_world_offsets([0, 0, 0])
+
+ self._scene_session = session
+
+ self.time = 0.0
+ self._mode_input = LocomotionModeInput(session.state_machine.style_modes)
+ self._interaction_down = False
+ self._active_interaction = None
+ self._auto_interaction_blocked: set[int] = set()
+ self.camera_facing = session.character.movement.current_facing.copy()
+ self.scene_error = None
+ self._initialize_camera()
+ self._update_smart_primitive_interaction()
+ self._last_frame_time = time.perf_counter()
+
+ # Removing a model from ViewerGL also removes our callbacks.
+ self.viewer.register_ui_callback(self.gui, position="free")
+
+ def _request_scene_load(self) -> None:
+ try:
+ selected = choose_file("Open Scene", "Scene documents", SCENE_DOCUMENT.suffix, self._scene_session.path)
+ except Exception as exc:
+ self.scene_error = str(exc)
+ return
+ if selected:
+ self._pending_scene_path = Path(selected)
+
+ def _load_pending_scene(self) -> None:
+ path = self._pending_scene_path
+ if path is None:
+ return
+ self._pending_scene_path = None
+ try:
+ prepared = self._prepare_scene(path)
+ except Exception as exc:
+ self.scene_error = str(exc)
+ return
+ self._start_scene(*prepared)
+
+ def _create_smart_primitive_instances(
+ self,
+ scene: SceneDefinition,
+ asset_pool: SmartPrimitiveAssetPool,
+ skeleton_renderer,
+ stream: wp.Stream,
+ ) -> tuple[tuple[_RuntimeSceneSmartPrimitive, ...], int]:
+ instances = []
+ interaction_box_offset = 0
+ for definition in scene.smart_primitives:
+ runtime = asset_pool.instantiate(
+ definition.reference,
+ behavior_types()[definition.behavior],
+ )
+ instances.append(
+ _RuntimeSceneSmartPrimitive(
+ definition,
+ runtime,
+ interaction_box_offset,
+ asset_pool.reference_pose,
+ skeleton_renderer(max_instances=MODEL_POSES_PER_TOKEN),
+ stream,
+ )
+ )
+ interaction_box_offset += runtime.interaction_box_count
+ return tuple(instances), interaction_box_offset
+
+ def _initialize_camera(self) -> None:
+ character = self._scene_session.character
+ self._camera_target = character.character_ground_position.copy()
+ self._camera_velocity = np.zeros(2)
+ self._camera_acceleration = np.zeros(2)
+ elevation = math.radians(_CAMERA_ELEVATION_DEGREES)
+ horizontal_distance = _CAMERA_DISTANCE * math.cos(elevation)
+ height = _CAMERA_DISTANCE * math.sin(elevation)
+ pivot_position = _camera_pivot_position(
+ character.character_ground_position
+ )
+ position = pivot_position - character.movement.current_facing * horizontal_distance
+ position[2] += height
+
+ camera = self.viewer.camera
+ camera.pos = Vec3(*position)
+ camera.look_at(pivot_position)
+
+ def _follow_character(self, frame_dt: float) -> None:
+ """Move the camera's followed point smoothly with the character.
+
+ A damped spring smooths the character's velocity. The point moves at that velocity and
+ settles on the character, so the sway of each stride does not reach the camera.
+ """
+ character = self._scene_session.character
+ for axis in range(2):
+ self._camera_velocity[axis], self._camera_acceleration[axis] = critical_spring_damper_exact(
+ self._camera_velocity[axis],
+ self._camera_acceleration[axis],
+ float(character.actual_velocity[axis]),
+ _CAMERA_VELOCITY_HALFLIFE,
+ frame_dt,
+ )
+ self._camera_target[:2] += self._camera_velocity * frame_dt
+ pull = 1.0 - math.exp(-frame_dt / _CAMERA_PULL_SECONDS)
+ self._camera_target += (character.character_ground_position - self._camera_target) * pull
+
+ def _update_camera(self) -> None:
+ camera = self.viewer.camera
+ pivot = np.asarray(camera.pivot, dtype=np.float32)
+ pivot_offset = _camera_pivot_position(self._camera_target) - pivot
+ if float(np.dot(pivot_offset, pivot_offset)) > 1.0e-12:
+ camera.translate(pivot_offset)
+ self.camera_facing = ground_direction(
+ camera.get_front(),
+ self.camera_facing,
+ )
+
+ def _on_mouse_drag(self, _x, _y, _dx, _dy, _buttons, _modifiers) -> None:
+ self._update_camera()
+
+ def _orbit_camera(
+ self,
+ camera_orbit: tuple[float, float],
+ frame_dt: float,
+ ) -> None:
+ right, up = camera_orbit
+ if right == 0.0 and up == 0.0:
+ return
+ self.viewer.camera.orbit(
+ delta_yaw=-right * _CONTROLLER_CAMERA_ORBIT_SPEED * frame_dt,
+ delta_pitch=up * _CONTROLLER_CAMERA_ORBIT_SPEED * frame_dt,
+ )
+ self._update_camera()
+
+ def _requested_locomotion_mode(self) -> str | None:
+ locomotion = self._scene_session.state_machine.active_locomotion_state
+ return self._mode_input.poll(self._input, locomotion.active_mode.name)
+
+ def _interaction_pressed(self) -> bool:
+ down = self._input.is_interaction_down()
+ manually_requested = down and not self._interaction_down
+ self._interaction_down = down
+ return manually_requested
+
+ def _update_smart_primitive_interaction(self) -> None:
+ session = self._scene_session
+ character = session.character
+ stream = character.engine.stream
+ box_count = session.interaction_box_count
+ if box_count == 0:
+ self._nearest_interactable = None
+ return
+
+ for instance in session.smart_primitives:
+ # A running behavior can move its nodes, so the active Smart Primitive's boxes refresh every frame.
+ instance.refresh_interaction_boxes(
+ session.interaction_boxes,
+ stream,
+ nodes_moved=instance is self._active_interaction,
+ )
+ compute_interaction_box_overlaps(
+ session.interaction_boxes[:box_count],
+ character.probe_box,
+ session.interaction_overlap_results[:box_count],
+ stream,
+ )
+ overlap_results = session.interaction_overlap_results.numpy()
+ for instance in session.smart_primitives:
+ start = instance.interaction_box_offset
+ end = start + instance.interaction_box_count
+ instance.interactable = bool(np.any(overlap_results[start:end]))
+
+ interactable_instances = (
+ instance
+ for instance in session.smart_primitives
+ if instance.interactable
+ )
+ self._nearest_interactable = min(
+ interactable_instances,
+ key=lambda instance: instance.distance_squared_to(
+ character.character_ground_position
+ ),
+ default=None,
+ )
+
+ def _start_smart_primitive_interaction(
+ self,
+ instance: _RuntimeSceneSmartPrimitive,
+ ) -> None:
+ session = self._scene_session
+ session.state_machine.start_interaction(
+ session.character, instance.runtime,
+ )
+ self._active_interaction = instance
+
+ def _dispatch_interaction_input(self) -> None:
+ """Handle the interaction button, I or the controller's X button.
+
+ A press starts an interaction with the nearest Smart Primitive in range, or
+ passes the press to the running one. Auto Interact only starts
+ interactions, once per approach.
+ """
+ session = self._scene_session
+ machine = session.state_machine
+ pressed = self._interaction_pressed()
+
+ if self._active_interaction is not None and not machine.is_interacting:
+ finished = self._active_interaction
+ self._auto_interaction_blocked.add(finished.definition.id)
+ self._active_interaction = None
+ for instance in session.smart_primitives:
+ if not instance.interactable:
+ self._auto_interaction_blocked.discard(instance.definition.id)
+
+ if machine.is_interacting:
+ if pressed:
+ machine.interact()
+ else:
+ instance = self._nearest_interactable
+ if instance is not None and (
+ pressed or (
+ self.auto_interaction
+ and instance.definition.id not in self._auto_interaction_blocked
+ )
+ ):
+ self._start_smart_primitive_interaction(instance)
+
+ def step(self) -> None:
+ """Read input, then advance the character and the camera.
+
+ Each step covers the time since the last frame.
+ """
+ session = self._scene_session
+ frame_time = time.perf_counter()
+ frame_dt = min(max(frame_time - self._last_frame_time, _MIN_FRAME_SECONDS), _MAX_FRAME_SECONDS)
+ self._last_frame_time = frame_time
+ self.time += frame_dt
+
+ input_frame = self._input.poll()
+ self._update_camera()
+ self._orbit_camera(input_frame.camera_orbit, frame_dt)
+ command = LocomotionCommand(
+ facing_direction=self.camera_facing,
+ movement=camera_relative_movement(self.camera_facing, input_frame.movement),
+ use_max_speed=input_frame.use_max_speed,
+ requested_mode=self._requested_locomotion_mode(),
+ )
+ session.character.step(frame_dt, command)
+ self._follow_character(frame_dt)
+ self._update_camera()
+
+ self._update_smart_primitive_interaction()
+ self._dispatch_interaction_input()
+
+ if self.show_blendspace_targets and session.state_machine.is_locomoting:
+ session.state_machine.active_locomotion_state.evaluate_current_target_poses(
+ session.character,
+ session.blended_target_poses,
+ session.blendspace_target_poses,
+ )
+
+ def _draw_smart_primitives(self) -> None:
+ session = self._scene_session
+ stream = session.character.engine.stream
+ for instance in session.smart_primitives:
+ instance.draw(
+ self.viewer,
+ session.interaction_boxes,
+ stream,
+ self.show_scene_object_target_poses,
+ self.show_scene_object_interaction_boxes,
+ )
+
+ def _draw_solid_cubes(self) -> None:
+ session = self._scene_session
+ cubes = session.definition.solid_cubes
+ session.solid_box_renderer.draw_batch(
+ self.viewer,
+ [cube.transform for cube in cubes],
+ [wp.vec3(cube.width, cube.depth, cube.height) for cube in cubes],
+ [cube.color for cube in cubes],
+ "scene",
+ )
+
+ def _draw_character_target_poses(self) -> None:
+ session = self._scene_session
+ target = session.character.player.target
+ if self.show_target_poses and target.num_poses > 0:
+ session.target_renderer.draw_batch(
+ self.viewer,
+ session.target_poses,
+ target.num_poses,
+ wp.transform_identity(),
+ self.target_colors,
+ "target",
+ )
+ else:
+ session.target_renderer.hide(self.viewer, "target")
+
+ def _draw_character_context_poses(self) -> None:
+ session = self._scene_session
+ player = session.character.player
+ if self.show_context_poses:
+ player.refresh_context()
+ session.context_renderer.draw_batch(
+ self.viewer,
+ session.context_poses,
+ player.context.num_poses,
+ wp.transform_identity(),
+ self.context_colors,
+ "context",
+ )
+ else:
+ session.context_renderer.hide(self.viewer, "context")
+
+ def _draw_foot_contacts(self) -> None:
+ """Draw the model's predicted foot contacts on the character.
+
+ Outlines show only during generated motion. Clips have no foot contacts.
+ """
+ session = self._scene_session
+ if not self.show_foot_contacts:
+ session.foot_contact_renderer.hide(self.viewer)
+ return
+ character = session.character
+ session.foot_contact_renderer.threshold = self.foot_contact_threshold
+ session.foot_contact_renderer.draw_pose(self.viewer, character.current_pose, character.current_foot_contacts)
+
+ def render(self) -> None:
+ """Draw the character, the scene items, and the debug overlays for one frame."""
+ session = self._scene_session
+ character = session.character
+ self.viewer.begin_frame(self.time)
+ session.mesh_renderer.draw_pose(
+ self.viewer,
+ character.current_pose,
+ wp.transform_identity(),
+ session.character_color,
+ 0,
+ )
+ self._draw_foot_contacts()
+ self._draw_solid_cubes()
+ self._draw_smart_primitives()
+ self._draw_character_context_poses()
+ self._draw_character_target_poses()
+
+ if self.show_blendspace_targets and session.state_machine.is_locomoting:
+ session.blendspace_renderer.draw_batch(
+ self.viewer,
+ session.blendspace_target_poses,
+ 1,
+ wp.transform_identity(),
+ self.blendspace_debug_colors,
+ "blendspace_locomotion",
+ )
+ else:
+ session.blendspace_renderer.hide(
+ self.viewer,
+ "blendspace_locomotion",
+ )
+
+ if self.show_probe_box and session.state_machine.is_locomoting:
+ session.interaction_box_renderer.draw_batch(
+ self.viewer,
+ character.probe_box,
+ 1,
+ _INTERACTION_BOX_COLOR,
+ "character_interaction",
+ )
+ else:
+ session.interaction_box_renderer.hide(
+ self.viewer,
+ "character_interaction",
+ )
+
+ origin = wp.vec3(*character.character_ground_position) + wp.vec3(0.0, 0.0, _VELOCITY_ARROW_HEIGHT)
+ for renderer, visible, velocity in (
+ (self.character_velocity_renderer, self.show_actual_velocity, character.actual_velocity),
+ (self.input_velocity_renderer, self.show_input_velocity, character.movement.input_velocity),
+ (self.desired_velocity_renderer, self.show_desired_velocity, character.movement.desired_velocity),
+ ):
+ if visible:
+ renderer.draw(self.viewer, 0, wp.transform_identity(), origin, wp.vec3(*velocity))
+ else:
+ renderer.hide(self.viewer, 0)
+ self.viewer.log_state(session.simulation_state)
+ self.viewer.end_frame()
+
+ def gui(self, ui) -> None:
+ """Draw the Scene Preview window."""
+ session = self._scene_session
+ dpi_scale = max(1.0, float(ui.get_style().font_scale_dpi))
+ viewport = ui.get_main_viewport()
+ margin = WINDOW_MARGIN * dpi_scale
+
+ ui.set_next_window_pos(
+ ui.ImVec2(
+ viewport.pos.x + margin,
+ viewport.pos.y + viewport.size.y - margin,
+ ),
+ ui.Cond_.first_use_ever,
+ pivot=ui.ImVec2(0.0, 1.0),
+ )
+ ui.set_next_window_size(
+ ui.ImVec2(_PANEL_WIDTH * dpi_scale, _PANEL_HEIGHT * dpi_scale),
+ ui.Cond_.first_use_ever,
+ )
+ ui.set_next_window_bg_alpha(_PANEL_ALPHA)
+ # Double-clicking the title bar collapses the window, as in the Newton viewer.
+ expanded, _ = ui.begin("Scene Preview")
+ if not expanded:
+ ui.end()
+ return
+
+ table_flags = (
+ ui.TableFlags_.sizing_fixed_fit
+ | ui.TableFlags_.no_saved_settings
+ | ui.TableFlags_.no_pad_outer_x
+ )
+ if ui.collapsing_header(
+ "Status",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ character = session.character
+ mode = session.state_machine.active_locomotion_state.active_mode
+ values = (
+ ("State:", session.state_machine.state.name),
+ ("Locomotion:", mode.label or mode.name),
+ ("Time To Transition:", f"{character.time_to_transition():.2f} s"),
+ (
+ "Position:",
+ f"{_format_vector3(character.character_ground_position)} m",
+ ),
+ (
+ "Speed:",
+ f"{np.linalg.norm(character.actual_velocity):.2f} m/s",
+ ),
+ )
+ if ui.begin_table("##StatusValues", 2, table_flags):
+ for label, value in values:
+ ui.table_next_row()
+ ui.table_set_column_index(0)
+ ui.text(label)
+ ui.table_set_column_index(1)
+ ui.text(value)
+ ui.end_table()
+
+ ui.separator()
+ if ui.collapsing_header(
+ "Scene",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ ui.align_text_to_frame_padding()
+ ui.text("Scene:")
+ ui.same_line()
+ ui.text(session.path.name)
+ ui.same_line()
+ if ui.button("...##LoadScene"):
+ self._request_scene_load()
+ _, self.auto_interaction = ui.checkbox(
+ "Auto Interact",
+ self.auto_interaction,
+ )
+ if self.scene_error is not None:
+ # The same red as the editors' error status.
+ ui.push_style_color(ui.Col_.text, ui.ImVec4(1.0, 0.35, 0.35, 1.0))
+ ui.text_wrapped(f"Open failed: {self.scene_error}")
+ ui.pop_style_color()
+
+ ui.separator()
+ if ui.collapsing_header(
+ "Visibility",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ ui.text("Character")
+ _, self.show_target_poses = ui.checkbox(
+ "Show Target Poses##Character",
+ self.show_target_poses,
+ )
+ _, self.show_context_poses = ui.checkbox(
+ "Show Context Poses",
+ self.show_context_poses,
+ )
+ _, self.show_blendspace_targets = ui.checkbox(
+ "Show Blend Space Poses",
+ self.show_blendspace_targets,
+ )
+ _, self.show_probe_box = ui.checkbox(
+ "Show Probe Box",
+ self.show_probe_box,
+ )
+ _, self.show_actual_velocity = ui.checkbox(
+ "Show Actual Velocity",
+ self.show_actual_velocity,
+ )
+ _, self.show_input_velocity = ui.checkbox(
+ "Show Input Velocity",
+ self.show_input_velocity,
+ )
+ _, self.show_desired_velocity = ui.checkbox(
+ "Show Desired Velocity",
+ self.show_desired_velocity,
+ )
+ _, self.show_foot_contacts = ui.checkbox(
+ "Show Foot Contacts",
+ self.show_foot_contacts,
+ )
+ ui.same_line()
+ ui.set_next_item_width(80 * dpi_scale)
+ ui.begin_disabled(not self.show_foot_contacts)
+ _, self.foot_contact_threshold = ui.slider_float(
+ "##FootContactThreshold",
+ self.foot_contact_threshold,
+ 0.0,
+ 1.0,
+ "%.2f",
+ flags=ui.SliderFlags_.always_clamp,
+ )
+ ui.end_disabled()
+
+ ui.spacing()
+ ui.text("Smart Primitives")
+ _, self.show_scene_object_target_poses = ui.checkbox(
+ "Show Target Poses##SceneObjects",
+ self.show_scene_object_target_poses,
+ )
+ _, self.show_scene_object_interaction_boxes = ui.checkbox(
+ "Show Interaction Boxes",
+ self.show_scene_object_interaction_boxes,
+ )
+
+ ui.separator()
+ if ui.collapsing_header(
+ "Model Stats",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ stage_times = session.character.engine.timer.milliseconds
+ timings = (
+ ("Encode:", stage_times["encode"]),
+ ("Inference:", stage_times["inference"]),
+ ("Decode:", stage_times["decode"]),
+ ("Post-Process:", stage_times["post_process"]),
+ )
+ total_model_execution_ms = sum(value for _, value in timings)
+ if ui.begin_table("##RuntimeTimings", 2, table_flags):
+ ui.table_next_row()
+ ui.table_set_column_index(0)
+ ui.text("Precision:")
+ ui.table_set_column_index(1)
+ ui.text("Mixed FP16" if self.fp16 else "FP32")
+
+ for label, value in timings:
+ ui.table_next_row()
+ ui.table_set_column_index(0)
+ ui.text(label)
+ ui.table_set_column_index(1)
+ ui.text(f"{value:.3f} ms")
+
+ ui.table_next_row()
+ for column in range(2):
+ ui.table_set_column_index(column)
+ ui.separator()
+
+ ui.table_next_row()
+ ui.table_set_column_index(0)
+ ui.text("Total:")
+ ui.table_set_column_index(1)
+ ui.text(f"{total_model_execution_ms:.3f} ms")
+ ui.end_table()
+ ui.end()
+
+ def run(self, max_frames: int | None = None) -> None:
+ """Step and draw frames until the window closes or max_frames is reached."""
+ try:
+ frame = 0
+ while self.viewer.is_running() and (
+ max_frames is None or frame < max_frames
+ ):
+ # Loading can build another engine and switch streams, so it
+ # runs between frames, outside the active engine's stream.
+ self._load_pending_scene()
+ with wp.ScopedStream(self._scene_session.character.engine.stream):
+ self.step()
+ self.render()
+ frame += 1
+ finally:
+ session = self._scene_session
+ if session.state_machine.is_interacting:
+ with wp.ScopedStream(session.character.engine.stream):
+ session.state_machine.interaction_state.exit(
+ session.character, session.state_machine,
+ )
+ self.close()
+ self.viewer.close()
+
+
+def main() -> None:
+ """Parse the command line and open Scene Preview."""
+ import newton.examples
+
+ parser = create_gl_parser()
+ add_model_precision_argument(parser)
+ parser.add_argument(
+ "--scene",
+ type=Path,
+ default=_DEFAULT_SCENE,
+ help="Scene document to open. Its rig selects SOMA or Unitree G1.",
+ )
+ viewer, args = newton.examples.init(parser)
+ configure_logging(args)
+ require_tensorrt()
+ ScenePreview(viewer, args.scene, fp16=args.model_precision == "fp16").run(
+ args.num_frames if args.test else None
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/app/smart_primitive_editor.py b/app/smart_primitive_editor.py
new file mode 100644
index 0000000..f0b70eb
--- /dev/null
+++ b/app/smart_primitive_editor.py
@@ -0,0 +1,1584 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Build Smart Primitives by placing clip poses, pivots, and interaction boxes."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+
+import newton
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, ModelRig
+from motionbricks.renderers.base_renderer import BaseRenderer
+from motionbricks.renderers.wire_box_renderer import WireBoxRenderer
+from motionbricks.renderers.vector_arrow_renderer import VectorArrowRenderer
+from motionbricks.runtime.pivot import Axis, ConeSide, ConstraintType, OperationOrder
+from motionbricks.runtime.smart_primitive import InteractionBox
+from motionbricks.runtime.target_pose import (
+ IKPin,
+ IK_PINS,
+ MAX_TRANSITION_EARLY_BY_FRAMES,
+ create_soma_target_pose_ik_rig,
+)
+
+from .utils.cli import configure_logging, create_gl_parser
+from .runtime.common.clip_registry import ClipLoadError, ClipRegistry
+from .runtime.common.rig import create_mesh_renderer, create_skeleton_renderer, load_rig_assets
+from .authoring.common import (
+ EditorViewer,
+ InlineRename,
+ NAME_TEXT_COLOR,
+ POSES_TO_USE_TOOLTIP,
+ PROPERTIES_WINDOW_HEIGHT,
+ PROPERTIES_WINDOW_WIDTH,
+ RIGHT_DOCK_RATIO,
+ WINDOW_MARGIN,
+ accept_drop,
+ choose_clip,
+ apply_transform_locks,
+ drag_source,
+ draw_add_remove_buttons,
+ draw_box_dimensions,
+ draw_character_selector,
+ draw_clip_scrubber,
+ draw_clip_selector,
+ draw_int_slider_property,
+ draw_label,
+ draw_token_range_property,
+ draw_transform_editor,
+ draw_tree_row,
+ log_transform_gizmo,
+ transforms_equal,
+)
+from .runtime.common.io.smart_primitive_document import (
+ MAX_TRAJECTORY_SCALE,
+ MIN_TRAJECTORY_SCALE,
+ SMART_PRIMITIVE_DOCUMENT,
+ TRAJECTORY_POINT_COUNT,
+ InteractionBoxComponent,
+ PivotComponent,
+ PlaybackMode,
+ SceneNode,
+ SmartPrimitiveDocument,
+ TargetPoseComponent,
+ TargetPoseSequence,
+ load_smart_primitive_document,
+ load_smart_primitive_rig,
+ save_smart_primitive_document,
+)
+from .runtime.common.io.document_io import DocumentError
+
+
+_TRAJECTORY_COLOR = wp.vec3(1.0, 0.8, 0.0)
+_IK_PIN_COLOR = wp.vec3(1.0, 0.0, 0.0)
+_IK_PIN_SPHERE_RADIUS = 0.05
+_TRAJECTORY_FRAME_SCALE = 0.075
+_MIN_INTERACTION_BOX_SIZE = 0.0
+_PIVOT_CONE_SEGMENTS = 64
+_PIVOT_CONE_RADIUS = 1.5
+_PIVOT_ARROW_LIFT = 0.03
+
+
+_HIERARCHY_WINDOW_WIDTH = 320
+_HIERARCHY_WINDOW_HEIGHT = 380
+_SEQUENCES_WINDOW_WIDTH = 360
+_SEQUENCES_WINDOW_HEIGHT = 300
+_PROPERTIES_DOCK_RATIO = 0.38
+_SEQUENCES_DOCK_RATIO = 0.48
+_TREE_PAYLOAD = "SMART_PRIMITIVE_NODE"
+_SEQUENCE_STEP_PAYLOAD = "SMART_PRIMITIVE_SEQUENCE_STEP"
+
+
+def _update_ik_pin_transforms_kernel(
+ pin_joint_indices: wp.array(dtype=wp.int32),
+ world_transforms: wp.array(dtype=wp.transform),
+ output_transforms: wp.array(dtype=wp.transform),
+):
+ pin_index = wp.tid()
+ output_transforms[pin_index] = world_transforms[
+ pin_joint_indices[pin_index]
+ ]
+
+
+def _update_hips_trajectory_kernel(
+ world_xform: wp.transform,
+ hips_transforms: wp.array(dtype=wp.transform),
+ frame_scale: float,
+ trajectory_color: wp.vec3,
+ trajectory_starts: wp.array(dtype=wp.vec3),
+ trajectory_ends: wp.array(dtype=wp.vec3),
+ trajectory_colors: wp.array(dtype=wp.vec3),
+ frame_starts: wp.array(dtype=wp.vec3),
+ frame_ends: wp.array(dtype=wp.vec3),
+ frame_colors: wp.array(dtype=wp.vec3),
+):
+ point_index = wp.tid()
+ hips_world = wp.mul(world_xform, hips_transforms[point_index])
+ frame_line = point_index * 3
+
+ frame_starts[frame_line] = hips_world.p
+ frame_starts[frame_line + 1] = hips_world.p
+ frame_starts[frame_line + 2] = hips_world.p
+ frame_ends[frame_line] = wp.transform_point(hips_world, wp.vec3(frame_scale, 0.0, 0.0))
+ frame_ends[frame_line + 1] = wp.transform_point(hips_world, wp.vec3(0.0, frame_scale, 0.0))
+ frame_ends[frame_line + 2] = wp.transform_point(hips_world, wp.vec3(0.0, 0.0, frame_scale))
+ frame_colors[frame_line] = wp.vec3(1.0, 0.0, 0.0)
+ frame_colors[frame_line + 1] = wp.vec3(0.0, 1.0, 0.0)
+ frame_colors[frame_line + 2] = wp.vec3(0.0, 0.0, 1.0)
+
+ if point_index + 1 < TRAJECTORY_POINT_COUNT:
+ next_hips_world = wp.mul(
+ world_xform,
+ hips_transforms[point_index + 1],
+ )
+ trajectory_starts[point_index] = hips_world.p
+ trajectory_ends[point_index] = next_hips_world.p
+ trajectory_colors[point_index] = trajectory_color
+
+
+def _ik_pin_label(pin: IKPin) -> str:
+ return "".join(part.title() for part in pin.name.split("_"))
+
+
+def _update_pivot_cone_kernel(
+ world_xform: wp.transform,
+ motion_direction: wp.vec3,
+ rotation_axis: wp.vec3,
+ half_angle: float,
+ first_center: float,
+ starts: wp.array(dtype=wp.vec3),
+ ends: wp.array(dtype=wp.vec3),
+ colors: wp.array(dtype=wp.vec3),
+):
+ line = wp.tid()
+ cone = line // (_PIVOT_CONE_SEGMENTS + 2)
+ segment = line % (_PIVOT_CONE_SEGMENTS + 2)
+ center = first_center + float(cone) * wp.pi
+ direction = _PIVOT_CONE_RADIUS * wp.transform_vector(world_xform, motion_direction)
+ origin = world_xform.p
+ axis = wp.transform_vector(world_xform, rotation_axis)
+ if segment < _PIVOT_CONE_SEGMENTS:
+ angle = center - half_angle + 2.0 * half_angle * float(segment) / float(_PIVOT_CONE_SEGMENTS)
+ next_angle = angle + 2.0 * half_angle / float(_PIVOT_CONE_SEGMENTS)
+ starts[line] = origin + wp.quat_rotate(wp.quat_from_axis_angle(axis, angle), direction)
+ ends[line] = origin + wp.quat_rotate(wp.quat_from_axis_angle(axis, next_angle), direction)
+ else:
+ # Join the arc's ends to the pivot. A full circle needs no closing lines.
+ angle = center - half_angle
+ if segment == _PIVOT_CONE_SEGMENTS + 1:
+ angle = center + half_angle
+ starts[line] = origin
+ ends[line] = origin
+ if half_angle < wp.pi:
+ ends[line] = origin + wp.quat_rotate(wp.quat_from_axis_angle(axis, angle), direction)
+ colors[line] = wp.vec3(1.0, 0.0, 0.0)
+
+
+class _PivotRenderer(BaseRenderer):
+ """Draw the pivot's direction and constraints using its placement in the editor."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self.direction = VectorArrowRenderer("pivot_motion_direction", wp.vec3(1.0, 0.8, 0.0))
+ self._cone_buffers = {}
+ self._line_buffers = {}
+
+ def draw(self, viewer, component: PivotComponent, world_xform: wp.transform, visible: bool) -> None:
+ pivot = component.pivot
+ direction = wp.vec3(*pivot.motion_direction)
+ if visible and component.show_motion_direction:
+ lifted = wp.transform(world_xform.p + wp.vec3(0.0, 0.0, _PIVOT_ARROW_LIFT), world_xform.q)
+ self.direction.draw(viewer, component.id, lifted, wp.vec3(0.0), direction)
+ else:
+ self.direction.hide(viewer, component.id)
+
+ self._draw_line(viewer, component, world_xform, visible)
+ name = f"/pivot_rotation_constraint_{component.id}"
+ buffers = self._cone_buffers.get(component.id)
+ if not (
+ visible and component.show_rotation_constraint
+ and pivot.rotation_axis is not Axis.NONE
+ and pivot.rotation_constraint is ConstraintType.CONE
+ ):
+ if buffers is not None:
+ self._log_hidden_once(viewer.log_lines, name, *buffers)
+ return
+
+ if buffers is None:
+ buffers = tuple(wp.empty(2 * (_PIVOT_CONE_SEGMENTS + 2), dtype=wp.vec3) for _ in range(3))
+ self._cone_buffers[component.id] = buffers
+ cone_count = 2 if pivot.cone_side is ConeSide.BOTH else 1
+ line_count = cone_count * (_PIVOT_CONE_SEGMENTS + 2)
+ first_center = math.pi if pivot.cone_side is ConeSide.MIRRORED else 0.0
+ local_axis = newton.Axis.from_string(pivot.rotation_axis.value).to_vec3()
+ wp.launch(
+ _update_pivot_cone_kernel,
+ dim=line_count,
+ inputs=[world_xform, direction, local_axis, math.radians(pivot.cone_half_angle_degrees), first_center],
+ outputs=list(buffers),
+ )
+ self._log_visible(viewer.log_lines, name, *(buffer[:line_count] for buffer in buffers))
+
+ def _draw_line(self, viewer, component: PivotComponent, world_xform: wp.transform, visible: bool) -> None:
+ pivot = component.pivot
+ name = f"/pivot_translation_constraint_{component.id}"
+ buffers = self._line_buffers.get(component.id)
+ if not (
+ visible and component.show_translation_constraint
+ and pivot.translation_axis is not Axis.NONE
+ and pivot.translation_constraint is ConstraintType.LINE_PROJECTION
+ ):
+ if buffers is not None:
+ self._log_hidden_once(viewer.log_lines, name, *buffers)
+ return
+
+ if buffers is None:
+ buffers = (
+ wp.empty(1, dtype=wp.vec3),
+ wp.empty(1, dtype=wp.vec3),
+ wp.full(1, wp.vec3(1.0, 0.0, 0.0), dtype=wp.vec3),
+ )
+ self._line_buffers[component.id] = buffers
+ start, end = pivot.line_endpoints(world_xform)
+ buffers[0].fill_(start)
+ buffers[1].fill_(end)
+ self._log_visible(viewer.log_lines, name, *buffers)
+
+ def clear(self, viewer) -> None:
+ self.direction.clear(viewer)
+ self._clear(viewer.lines)
+ self._cone_buffers.clear()
+ self._line_buffers.clear()
+
+
+class _InteractionBoxRenderer(WireBoxRenderer):
+ """Draw the 12 edges of each Interaction Box."""
+
+ _NAME_PREFIX = "/interaction_box_"
+
+ def __init__(self) -> None:
+ super().__init__(max_boxes=1)
+ self._box = wp.empty(1, dtype=InteractionBox)
+
+ def draw(
+ self,
+ viewer,
+ component: InteractionBoxComponent,
+ world_xform: wp.transform,
+ ) -> None:
+ box = InteractionBox()
+ box.transform = world_xform
+ box.half_extents = wp.vec3(0.5 * component.width, 0.5 * component.depth, 0.5 * component.height)
+ self._box.fill_(box)
+ self.draw_batch(
+ viewer,
+ self._box,
+ 1,
+ component.color,
+ component.id,
+ )
+
+
+class _IKPinRenderer(BaseRenderer):
+ """Mark pinned hands and feet on the first sampled pose with spheres."""
+
+ def __init__(self, skeleton: Skeleton) -> None:
+ super().__init__()
+ rig = create_soma_target_pose_ik_rig(skeleton)
+ self._skeleton = skeleton
+ self._tip_indices = {chain.pin: chain.tip_index for chain in rig}
+ self._world_transforms = wp.empty(
+ skeleton.num_joints,
+ dtype=wp.transform,
+ )
+ self._pin_transforms = wp.empty(len(rig), dtype=wp.transform)
+ self._pin_colors = wp.array(
+ [_IK_PIN_COLOR] * len(rig),
+ dtype=wp.vec3,
+ )
+ self._indices_by_mask: dict[IKPin, wp.array] = {}
+ self._pin_counts: dict[int, int] = {}
+
+ @staticmethod
+ def _name(component_id: int | str) -> str:
+ return f"/target_pose_ik_pins_{component_id}"
+
+ def draw(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ ) -> None:
+ mask = component.ik_pin_mask
+ joint_indices = self._indices_by_mask.get(mask)
+ if joint_indices is None:
+ selected_indices = [
+ tip_index
+ for pin, tip_index in self._tip_indices.items()
+ if mask & pin
+ ]
+ joint_indices = wp.array(selected_indices, dtype=wp.int32)
+ self._indices_by_mask[mask] = joint_indices
+
+ self._skeleton.compute_world_transforms(
+ component.pose,
+ self._world_transforms,
+ root_tx=world_xform,
+ )
+ num_pins = joint_indices.shape[0]
+ wp.launch(
+ _update_ik_pin_transforms_kernel,
+ dim=num_pins,
+ inputs=[
+ joint_indices,
+ self._world_transforms,
+ ],
+ outputs=[self._pin_transforms],
+ )
+ self._pin_counts[component.id] = num_pins
+ self._log_visible(
+ viewer.log_shapes,
+ self._name(component.id),
+ newton.GeoType.SPHERE,
+ _IK_PIN_SPHERE_RADIUS,
+ self._pin_transforms[:num_pins],
+ self._pin_colors[:num_pins],
+ geo_is_solid=True,
+ )
+
+ def hide(self, viewer, component_id: int) -> None:
+ pin_count = self._pin_counts.get(component_id)
+ if pin_count is None:
+ return
+ self._log_hidden_once(
+ viewer.log_shapes,
+ self._name(component_id),
+ newton.GeoType.SPHERE,
+ _IK_PIN_SPHERE_RADIUS,
+ self._pin_transforms[:pin_count],
+ self._pin_colors[:pin_count],
+ geo_is_solid=True,
+ )
+
+ def clear(self, viewer) -> None:
+ self._clear(viewer.objects)
+ self._indices_by_mask.clear()
+ self._pin_counts.clear()
+
+
+class _HipsTrajectoryRenderer(BaseRenderer):
+ """Draw the root path and small axis markers along it."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self._buffers = {}
+
+ @staticmethod
+ def _trajectory_name(component_id: int) -> str:
+ return f"/target_pose_trajectory_{component_id}"
+
+ @staticmethod
+ def _frames_name(component_id: int) -> str:
+ return f"/target_pose_trajectory_frames_{component_id}"
+
+ def draw(
+ self,
+ viewer,
+ component_id: int,
+ world_xform: wp.transform,
+ hips_transforms: wp.array,
+ ) -> None:
+ buffers = self._buffers.get(component_id)
+ if buffers is None:
+ # The path and the axis markers each have line starts, ends, and colors.
+ buffers = (
+ tuple(wp.empty(TRAJECTORY_POINT_COUNT - 1, dtype=wp.vec3) for _ in range(3)),
+ tuple(wp.empty(TRAJECTORY_POINT_COUNT * 3, dtype=wp.vec3) for _ in range(3)),
+ )
+ self._buffers[component_id] = buffers
+
+ path, frames = buffers
+ wp.launch(
+ _update_hips_trajectory_kernel,
+ dim=TRAJECTORY_POINT_COUNT,
+ inputs=[world_xform, hips_transforms, _TRAJECTORY_FRAME_SCALE, _TRAJECTORY_COLOR],
+ outputs=[*path, *frames],
+ )
+ self._log_visible(viewer.log_lines, self._trajectory_name(component_id), *path)
+ self._log_visible(viewer.log_lines, self._frames_name(component_id), *frames)
+
+ def hide(self, viewer, component_id: int) -> None:
+ buffers = self._buffers.get(component_id)
+ if buffers is None:
+ return
+
+ path, frames = buffers
+ self._log_hidden_once(viewer.log_lines, self._trajectory_name(component_id), *path)
+ self._log_hidden_once(viewer.log_lines, self._frames_name(component_id), *frames)
+
+ def clear(self, viewer) -> None:
+ self._clear(viewer.lines)
+ self._buffers.clear()
+
+
+class _TargetPoseRenderers:
+ """Draw a target pose's mesh, skeletons, velocity, and other previews.
+
+ The mesh and skeleton renderers match the rig's poses: local joint transforms
+ for SOMA or joint coordinates for G1. IK pins apply only to SOMA poses.
+ """
+
+ def __init__(self, mesh, skeleton, ik_pins: _IKPinRenderer | None = None) -> None:
+ self.mesh = mesh
+ self.skeleton = skeleton
+ self.ik_pins = ik_pins
+ self.velocity = VectorArrowRenderer("target_pose_velocity", wp.vec3(1.0, 0.0, 0.0))
+ self.trajectory = _HipsTrajectoryRenderer()
+ self._skeleton_colors = wp.empty(MODEL_POSES_PER_TOKEN, dtype=wp.vec3)
+
+ def draw(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ visible: bool,
+ ) -> None:
+ self._draw_mesh(viewer, component, world_xform, visible)
+ self._draw_velocity(viewer, component, world_xform, visible)
+ self._draw_trajectory(viewer, component, world_xform, visible)
+ self._draw_skeletons(viewer, component, world_xform, visible)
+ self._draw_ik_pins(viewer, component, world_xform, visible)
+
+ def clear(self, viewer) -> None:
+ self.mesh.clear(viewer)
+ self.velocity.clear(viewer)
+ self.trajectory.clear(viewer)
+ self.skeleton.clear(viewer)
+ if self.ik_pins is not None:
+ self.ik_pins.clear(viewer)
+
+ def _draw_mesh(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ visible: bool,
+ ) -> None:
+ if visible and component.show_mesh:
+ self.mesh.draw_pose(
+ viewer,
+ component.pose,
+ world_xform,
+ component.color,
+ component.id,
+ )
+ else:
+ self.mesh.hide(viewer, component.id)
+
+ def _draw_velocity(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ visible: bool,
+ ) -> None:
+ if visible and component.show_velocity and component.has_velocity:
+ self.velocity.draw(
+ viewer,
+ component.id,
+ world_xform,
+ component.hips_position,
+ component.velocity,
+ )
+ else:
+ self.velocity.hide(viewer, component.id)
+
+ def _draw_trajectory(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ visible: bool,
+ ) -> None:
+ if visible and component.show_trajectory and component.has_trajectory:
+ self.trajectory.draw(
+ viewer,
+ component.id,
+ world_xform,
+ component.trajectory_transforms,
+ )
+ else:
+ self.trajectory.hide(viewer, component.id)
+
+ def _draw_skeletons(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ visible: bool,
+ ) -> None:
+ name = f"target_pose_{component.id}"
+ if not (visible and component.show_skeletons):
+ self.skeleton.hide(viewer, name)
+ else:
+ self._skeleton_colors.fill_(component.color)
+ self.skeleton.draw_batch(
+ viewer, component.sampled_poses, component.skeleton_count, world_xform, self._skeleton_colors, name,
+ )
+
+ def _draw_ik_pins(
+ self,
+ viewer,
+ component: TargetPoseComponent,
+ world_xform: wp.transform,
+ visible: bool,
+ ) -> None:
+ if self.ik_pins is None:
+ return
+ if visible and component.ik_pin_mask != IKPin.NONE:
+ self.ik_pins.draw(viewer, component, world_xform)
+ else:
+ self.ik_pins.hide(viewer, component.id)
+
+
+@dataclass(frozen=True)
+class _Rig:
+ """The clips, reference pose, and target pose previews of the current rig."""
+
+ clip_registry: ClipRegistry
+ reference_pose: wp.array
+ model_to_runtime: wp.transform
+ target_pose_renderers: _TargetPoseRenderers
+
+
+class SmartPrimitiveEditor(EditorViewer):
+ """Edit a Smart Primitive document.
+
+ A document holds the node hierarchy with its Target Poses, Interaction Boxes, and
+ Pivots, plus the sequences.
+ """
+
+ _EDITOR_TITLE = "MotionBricks - Smart Primitive Editor"
+ _OUTLINER_WINDOW_TITLE = "Hierarchy"
+ _DOCUMENT_TYPE = SMART_PRIMITIVE_DOCUMENT
+
+ def __init__(self, viewer) -> None:
+ """Open the editor with a new SOMA document."""
+ super().__init__(viewer)
+ self.viewer.renderer.arrow_scale = 1.5
+ self.rig = self._load_rig(ModelRig.SOMA)
+ self.interaction_box_renderer = _InteractionBoxRenderer()
+ self.pivot_renderer = _PivotRenderer()
+ self.authoring = SmartPrimitiveDocument(
+ self.rig.clip_registry.rig, self.rig.reference_pose, self.rig.model_to_runtime,
+ )
+ self.selected_id = self.authoring.root.id
+ self._reveal_node_ids: set[int] = set()
+ self.selected_sequence_id: int | None = None
+ self._node_rename = InlineRename()
+ self._sequence_rename = InlineRename()
+ self._dragged_sequence_step: tuple[int, int] | None = None
+ self._pivot_direction_edit: tuple[int, list[float]] | None = None
+ self._gizmo_item_id: int | None = None
+ self._gizmo_xform: wp.transform | None = None
+ self._viewer_ui.on_scene_click = self._select_scene_item
+
+ @property
+ def selected(self) -> SceneNode:
+ """Selected node, or the root node when nothing is selected."""
+ return self.authoring.find_node(self.selected_id) or self.authoring.root
+
+ def _rig_for(self, name: ModelRig) -> _Rig:
+ """Return the current rig when it matches name. Otherwise, load the named rig."""
+ if self.rig.clip_registry.rig is name:
+ return self.rig
+ return self._load_rig(name)
+
+ def _load_rig(self, name: ModelRig) -> _Rig:
+ """Load a rig with its preview renderers. The current rig stays until it is replaced."""
+ assets = load_rig_assets(name)
+ renderers = _TargetPoseRenderers(
+ create_mesh_renderer(name, assets.model),
+ create_skeleton_renderer(name, assets.model, max_instances=MODEL_POSES_PER_TOKEN),
+ # Only SOMA has target pose IK.
+ _IKPinRenderer(assets.model.skeleton) if name is ModelRig.SOMA else None,
+ )
+ return _Rig(assets.clip_registry, assets.reference_pose, assets.model_to_runtime, renderers)
+
+ def _use_rig(self, rig: _Rig) -> None:
+ """Switch a document whose target poses have no clips to another rig."""
+ self.authoring.set_rig(rig.clip_registry.rig, rig.reference_pose, rig.model_to_runtime)
+ self.rig.target_pose_renderers.clear(self.viewer)
+ self.rig = rig
+
+ def _build_initial_dock_layout(self, ui, dockspace_id: int) -> None:
+ dock_builder = ui.internal
+ _, right_dock_id, _ = dock_builder.dock_builder_split_node_py(
+ dockspace_id,
+ ui.Dir.right,
+ RIGHT_DOCK_RATIO,
+ )
+ _, properties_dock_id, upper_dock_id = (
+ dock_builder.dock_builder_split_node_py(
+ right_dock_id,
+ ui.Dir.down,
+ _PROPERTIES_DOCK_RATIO,
+ )
+ )
+ _, sequences_dock_id, hierarchy_dock_id = (
+ dock_builder.dock_builder_split_node_py(
+ upper_dock_id,
+ ui.Dir.down,
+ _SEQUENCES_DOCK_RATIO,
+ )
+ )
+ dock_builder.dock_builder_dock_window(self._OUTLINER_WINDOW_TITLE, hierarchy_dock_id)
+ dock_builder.dock_builder_dock_window("Sequences", sequences_dock_id)
+ dock_builder.dock_builder_dock_window("Properties", properties_dock_id)
+ dock_builder.dock_builder_finish(dockspace_id)
+
+ def _draw_additional_windows(self, ui, dpi_scale: float) -> None:
+ self._draw_sequences_window(ui, dpi_scale)
+
+ def _new_document(self) -> None:
+ authoring = SmartPrimitiveDocument(
+ self.authoring.rig,
+ self.authoring.reference_pose,
+ self.authoring.model_to_runtime,
+ )
+ self._replace_scene(authoring, authoring.root.id, None)
+
+ def _save_document(self, path: str | Path) -> Path:
+ return save_smart_primitive_document(self.authoring, path, self.selected_id, self._capture_camera_state())
+
+ def _open_document(self, path: str | Path) -> None:
+ try:
+ document_path = Path(path).expanduser().resolve()
+ rig = self._rig_for(load_smart_primitive_rig(document_path))
+ authoring, selected_id, camera_state = load_smart_primitive_document(
+ rig.clip_registry,
+ rig.reference_pose,
+ rig.model_to_runtime,
+ document_path,
+ )
+ except DocumentError as exc:
+ self._status = f"Open failed: {exc}"
+ return
+
+ # Replacing the scene clears the previous rig's previews.
+ self._replace_scene(authoring, selected_id, document_path)
+ self.rig = rig
+ self._apply_camera_state(camera_state)
+
+ def _replace_scene(
+ self,
+ authoring: SmartPrimitiveDocument,
+ selected_id: int,
+ document_path: Path | None,
+ ) -> None:
+ """Switch documents and clear any unfinished edits from the previous one."""
+ self._clear_component_renderers()
+ self.authoring = authoring
+ self.selected_id = selected_id
+ self._reveal_node_ids = set()
+ self.selected_sequence_id = (
+ authoring.sequences[0].id if authoring.sequences else None
+ )
+ self._node_rename = InlineRename()
+ self._sequence_rename = InlineRename()
+ self._dragged_sequence_step = None
+ self._pivot_direction_edit = None
+ self._gizmo_item_id = None
+ self._gizmo_xform = None
+ self._set_document_path(document_path)
+
+ def _draw_editor_scene(self) -> None:
+ self._draw_interaction_boxes()
+ self._draw_target_poses()
+ self._draw_pivots()
+
+ def _draw_pivots(self) -> None:
+ for node, component in self.authoring.iter_pivots():
+ self.pivot_renderer.draw(
+ self.viewer, component, self.authoring.world_xform(node), self.authoring.is_visible(node),
+ )
+
+ def _draw_interaction_boxes(self) -> None:
+ for node, component in self.authoring.iter_interaction_boxes():
+ if self.authoring.is_visible(node):
+ self.interaction_box_renderer.draw(
+ self.viewer,
+ component,
+ self.authoring.world_xform(node),
+ )
+ else:
+ self.interaction_box_renderer.hide(
+ self.viewer,
+ component.id,
+ )
+
+ def _select_and_reveal_node(self, node: SceneNode) -> None:
+ self.selected_id = node.id
+ self._reveal_node_ids = {
+ ancestor.id for ancestor in self.authoring.iter_ancestors(node)
+ }
+
+ def _select_scene_item(self, origin: wp.vec3, direction: wp.vec3) -> None:
+ nearest = self.viewer.camera.far
+ picked_node = None
+ for node, component in self.authoring.iter_target_poses():
+ if not self.authoring.is_visible(node) or not component.show_mesh:
+ continue
+ distance = self.rig.target_pose_renderers.mesh.raycast_pose(
+ component.pose,
+ self.authoring.target_pose_world_xform(node),
+ origin, direction, nearest,
+ )
+ if distance < nearest:
+ nearest = distance
+ picked_node = node
+ for node, component in self.authoring.iter_interaction_boxes():
+ if not self.authoring.is_visible(node):
+ continue
+ distance = self.interaction_box_renderer.raycast(
+ self.authoring.world_xform(node),
+ wp.vec3(component.width, component.depth, component.height),
+ origin, direction, nearest,
+ )
+ if distance < nearest:
+ nearest = distance
+ picked_node = node
+ if picked_node is not None:
+ self._select_and_reveal_node(picked_node)
+
+ def _draw_target_poses(self) -> None:
+ for node, component in self.authoring.iter_target_poses():
+ self.rig.target_pose_renderers.draw(
+ self.viewer,
+ component,
+ self.authoring.target_pose_world_xform(node),
+ self.authoring.is_visible(node),
+ )
+
+ def _clear_component_renderers(self) -> None:
+ self.rig.target_pose_renderers.clear(self.viewer)
+ self.interaction_box_renderer.clear(self.viewer)
+ self.pivot_renderer.clear(self.viewer)
+
+ def _clear_component_renderer(
+ self,
+ node: SceneNode,
+ component: TargetPoseComponent | InteractionBoxComponent | PivotComponent,
+ ) -> None:
+ if component is node.target_pose:
+ self.rig.target_pose_renderers.clear(self.viewer)
+ elif component is node.pivot:
+ self.pivot_renderer.clear(self.viewer)
+ else:
+ self.interaction_box_renderer.clear(self.viewer)
+
+ def _draw_selection_gizmo(self) -> None:
+ selected = self.selected
+ if not self.authoring.is_visible(selected):
+ self._gizmo_item_id = None
+ self._gizmo_xform = None
+ return
+
+ self._gizmo_item_id = selected.id
+ self._gizmo_xform = self.authoring.world_xform(selected)
+ log_transform_gizmo(
+ self.viewer,
+ "selection",
+ self._gizmo_xform,
+ translation_locks=selected.translation_locks,
+ rotation_locks=selected.rotation_locks,
+ axes_rotation=None if selected.parent is None else self.authoring.world_xform(selected.parent).q,
+ )
+
+ def _apply_selection_gizmo(self) -> None:
+ gizmo_node = self.authoring.find_node(self._gizmo_item_id)
+ if (
+ gizmo_node is None
+ or self._gizmo_xform is None
+ or transforms_equal(self.authoring.world_xform(gizmo_node), self._gizmo_xform)
+ ):
+ return
+
+ gizmo_local, gizmo_node.euler_degrees = apply_transform_locks(
+ self._local_xform(gizmo_node), self._local_xform(gizmo_node, self._gizmo_xform),
+ gizmo_node.euler_degrees, gizmo_node.translation_locks, gizmo_node.rotation_locks,
+ )
+ self._set_local_xform(gizmo_node, gizmo_local)
+
+ def _draw_sequences_window(self, ui, dpi_scale: float) -> None:
+ self._set_initial_panel_geometry(
+ ui,
+ dpi_scale,
+ _SEQUENCES_WINDOW_WIDTH,
+ _SEQUENCES_WINDOW_HEIGHT,
+ _HIERARCHY_WINDOW_HEIGHT + 2 * WINDOW_MARGIN,
+ )
+ window_visible, _ = ui.begin("Sequences")
+ sequence_to_remove = None
+ if window_visible:
+ selected_sequence = self.authoring.find_sequence(self.selected_sequence_id)
+ add, remove_selected = draw_add_remove_buttons(ui, selected_sequence is not None)
+ if add:
+ sequence = self.authoring.add_sequence()
+ self.selected_sequence_id = sequence.id
+ self._sequence_rename.begin(sequence.id, sequence.name)
+ if remove_selected:
+ sequence_to_remove = selected_sequence
+
+ ui.separator()
+ if not self.authoring.sequences:
+ ui.text_disabled("No target pose sequences.")
+ for sequence in list(self.authoring.sequences):
+ if self._draw_sequence(ui, sequence):
+ sequence_to_remove = sequence
+ ui.end()
+
+ if sequence_to_remove is not None:
+ self.authoring.remove_sequence(sequence_to_remove)
+ self.selected_sequence_id = None
+ self._sequence_rename.item_id = None
+
+ def _draw_sequence(self, ui, sequence: TargetPoseSequence) -> bool:
+ ui.push_id(sequence.id)
+ try:
+ flags = ui.TreeNodeFlags_.default_open
+ if sequence.id == self.selected_sequence_id:
+ flags |= ui.TreeNodeFlags_.selected
+ sequence_open = ui.collapsing_header(
+ f"{sequence.name}###Sequence",
+ flags=flags,
+ )
+ header_clicked = ui.is_item_clicked()
+ if header_clicked:
+ self.selected_sequence_id = sequence.id
+ self._accept_target_pose_node_drop(ui, sequence)
+ delete_sequence = self._draw_sequence_context_menu(ui, sequence)
+
+ if self._sequence_rename.item_id == sequence.id:
+ if name := self._sequence_rename.draw(ui):
+ if any(
+ other is not sequence and other.name == name
+ for other in self.authoring.sequences
+ ):
+ self._status = f"Cannot rename the sequence. {name!r} is already in use."
+ else:
+ sequence.name = name
+ self._status = None
+
+ if sequence_open:
+ self._draw_sequence_pivot(ui, sequence)
+ remove_index = None
+ for index, node_id in enumerate(list(sequence.node_ids)):
+ if self._draw_sequence_step(ui, sequence, index, node_id):
+ remove_index = index
+ if remove_index is not None:
+ self.authoring.remove_sequence_node(sequence, remove_index)
+
+ if ui.button("+ Add Target Pose"):
+ ui.open_popup("##AddTargetPose")
+ self._draw_add_target_pose_popup(ui, sequence)
+ return delete_sequence
+ finally:
+ ui.pop_id()
+
+ def _draw_sequence_pivot(self, ui, sequence: TargetPoseSequence) -> None:
+ node = self.authoring.find_node(sequence.pivot_node_id)
+ draw_label(ui, "Pivot")
+ opened = ui.begin_combo("##Pivot", "None" if node is None else node.name)
+ if ui.is_item_clicked() and node is not None:
+ self._select_and_reveal_node(node)
+ self.selected_sequence_id = sequence.id
+ if opened:
+ choices = [(None, "None")] + [
+ (pivot_node, pivot_node.name) for pivot_node, _ in self.authoring.iter_pivots()
+ ]
+ for choice, label in choices:
+ choice_id = None if choice is None else choice.id
+ selected, _ = ui.selectable(f"{label}##{choice_id}", choice_id == sequence.pivot_node_id)
+ if selected:
+ self.authoring.set_sequence_pivot(sequence, choice)
+ self.selected_sequence_id = sequence.id
+ if choice is not None:
+ self._select_and_reveal_node(choice)
+ ui.end_combo()
+ else:
+ choice = self.authoring.find_node(accept_drop(ui, _TREE_PAYLOAD))
+ if choice is not None and choice.pivot is not None:
+ self.authoring.set_sequence_pivot(sequence, choice)
+ self._select_and_reveal_node(choice)
+ self.selected_sequence_id = sequence.id
+
+ def _draw_sequence_context_menu(
+ self,
+ ui,
+ sequence: TargetPoseSequence,
+ ) -> bool:
+ if not ui.begin_popup_context_item("##SequenceContext"):
+ return False
+ self.selected_sequence_id = sequence.id
+ rename_sequence, _ = ui.menu_item("Rename", "", False)
+ delete_sequence, _ = ui.menu_item("Delete", "", False)
+ ui.end_popup()
+ if rename_sequence:
+ self._sequence_rename.begin(sequence.id, sequence.name)
+ return delete_sequence
+
+ def _draw_sequence_step(
+ self,
+ ui,
+ sequence: TargetPoseSequence,
+ index: int,
+ node_id: int,
+ ) -> bool:
+ node = self.authoring.find_node(node_id)
+ ui.push_id(index)
+ try:
+ available_width = ui.get_content_region_avail().x
+ remove_width = ui.calc_text_size("x").x + 20.0
+ clicked, _ = ui.selectable(
+ f"{index + 1} - {node.name}##TargetPose",
+ node_id == self.selected_id,
+ size=ui.ImVec2(max(1.0, available_width - remove_width), 0.0),
+ )
+ if clicked:
+ self._select_and_reveal_node(node)
+ self.selected_sequence_id = sequence.id
+ if drag_source(ui, _SEQUENCE_STEP_PAYLOAD, node_id, f"{index + 1} - {node.name}"):
+ self._dragged_sequence_step = (sequence.id, index)
+ self._accept_sequence_step_drop(ui, sequence, index)
+
+ ui.same_line()
+ return ui.small_button("x")
+ finally:
+ ui.pop_id()
+
+ def _accept_target_pose_node_drop(self, ui, sequence: TargetPoseSequence) -> None:
+ node = self.authoring.find_node(accept_drop(ui, _TREE_PAYLOAD))
+ if node is not None and node.target_pose is not None:
+ self.authoring.add_sequence_node(sequence, node)
+ self._select_and_reveal_node(node)
+ self.selected_sequence_id = sequence.id
+
+ def _accept_sequence_step_drop(
+ self,
+ ui,
+ sequence: TargetPoseSequence,
+ destination_index: int,
+ ) -> None:
+ dropped = accept_drop(ui, _SEQUENCE_STEP_PAYLOAD) is not None
+ dragged = self._dragged_sequence_step
+ if dropped and dragged is not None and dragged[0] == sequence.id:
+ source_index = dragged[1]
+ if source_index != destination_index:
+ self.authoring.move_sequence_node(sequence, source_index, destination_index)
+ self._dragged_sequence_step = None
+
+ def _draw_add_target_pose_popup(
+ self,
+ ui,
+ sequence: TargetPoseSequence,
+ ) -> None:
+ if not ui.begin_popup("##AddTargetPose"):
+ return
+ targets = list(self.authoring.iter_target_poses())
+ if not targets:
+ ui.text_disabled("No hierarchy nodes own a Target Pose.")
+ for node, _component in targets:
+ selected, _ = ui.selectable(f"{node.name}###{node.id}", False)
+ if selected:
+ self.authoring.add_sequence_node(sequence, node)
+ self._select_and_reveal_node(node)
+ self.selected_sequence_id = sequence.id
+ ui.close_current_popup()
+ ui.end_popup()
+
+ def _draw_outliner_window(self, ui, dpi_scale: float) -> None:
+ self._set_initial_panel_geometry(
+ ui,
+ dpi_scale,
+ _HIERARCHY_WINDOW_WIDTH,
+ _HIERARCHY_WINDOW_HEIGHT,
+ WINDOW_MARGIN,
+ )
+ window_visible, _ = ui.begin(self._OUTLINER_WINDOW_TITLE)
+
+ delete_id = None
+ if window_visible:
+ self._draw_character_selector(ui)
+ delete_id = self._draw_hierarchy_toolbar(ui)
+ self._draw_status(ui)
+ ui.separator()
+ tree_delete_id = self._draw_tree_node(ui, self.authoring.root)
+ if tree_delete_id is not None:
+ delete_id = tree_delete_id
+ ui.end()
+
+ node = self.authoring.find_node(delete_id)
+ if node is not None:
+ self._clear_component_renderers()
+ self.authoring.remove_node(node)
+ self._node_rename.item_id = None
+ self.selected_id = self.authoring.root.id
+
+ def _draw_hierarchy_toolbar(self, ui) -> int | None:
+ add, remove_selected = draw_add_remove_buttons(ui, self.selected is not self.authoring.root)
+ if add:
+ self.selected_id = self.authoring.add_node(self.selected).id
+ return self.selected.id if remove_selected else None
+
+ def _draw_character_selector(self, ui) -> None:
+ has_clips = any(target.clip is not None for _, target in self.authoring.iter_target_poses())
+ rig = draw_character_selector(
+ ui,
+ self.authoring.rig,
+ "Target Poses with clips lock the Character selector. Remove those Target Poses or start a new "
+ "document to change it."
+ if has_clips else None,
+ )
+ if rig is not self.authoring.rig:
+ self._use_rig(self._rig_for(rig))
+
+ def _draw_tree_node(self, ui, node: SceneNode) -> int | None:
+ ui.push_id(node.id)
+ _, node.visible = ui.checkbox("##Visible", node.visible)
+ ui.same_line()
+ renaming = node.id == self._node_rename.item_id
+ node_open, clicked, name = draw_tree_row(
+ ui, node.name, node.id, self._node_rename, self._reveal_node_ids,
+ selected=node.id == self.selected_id, hidden=not node.visible,
+ )
+ if clicked:
+ self.selected_id = node.id
+ if name:
+ node.name = name
+
+ delete_id = None
+ if not renaming:
+ self._draw_tree_node_drag_drop(ui, node)
+ delete_id = self._draw_tree_node_context_menu(ui, node)
+
+ if node_open:
+ for child in list(node.children):
+ child_delete_id = self._draw_tree_node(ui, child)
+ if child_delete_id is not None:
+ delete_id = child_delete_id
+ ui.tree_pop()
+ ui.pop_id()
+ return delete_id
+
+ def _draw_tree_node_drag_drop(self, ui, node: SceneNode) -> None:
+ if node is not self.authoring.root:
+ drag_source(ui, _TREE_PAYLOAD, node.id, node.name)
+ dragged = self.authoring.find_node(accept_drop(ui, _TREE_PAYLOAD))
+ if dragged is not None and self.authoring.reparent(dragged, node):
+ self.selected_id = dragged.id
+
+ def _draw_tree_node_context_menu(self, ui, node: SceneNode) -> int | None:
+ if not ui.begin_popup_context_item("##NodeContext"):
+ return None
+
+ self.selected_id = node.id
+ delete_node, _ = ui.menu_item(
+ "Delete",
+ "",
+ False,
+ node is not self.authoring.root,
+ )
+ add_child, _ = ui.menu_item("Add Child", "", False)
+ ui.end_popup()
+
+ if add_child:
+ self.selected_id = self.authoring.add_node(node).id
+ return node.id if delete_node else None
+
+ def _draw_properties_window(self, ui, dpi_scale: float) -> None:
+ self._set_initial_panel_geometry(
+ ui,
+ dpi_scale,
+ PROPERTIES_WINDOW_WIDTH,
+ PROPERTIES_WINDOW_HEIGHT,
+ _HIERARCHY_WINDOW_HEIGHT
+ + _SEQUENCES_WINDOW_HEIGHT
+ + 3 * WINDOW_MARGIN,
+ )
+ node = self.selected
+ remove_component: TargetPoseComponent | InteractionBoxComponent | PivotComponent | None = None
+ window_visible, _ = ui.begin("Properties")
+ if window_visible:
+ # Give each node its own widget IDs so switching nodes cannot carry
+ # an unfinished text edit into the new selection.
+ ui.push_id(node.id)
+ try:
+ ui.text_colored(ui.ImVec4(*NAME_TEXT_COLOR), node.name)
+ if ui.collapsing_header(
+ "Transform",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ self._draw_transform_details(ui, node, dpi_scale)
+
+ if node.target_pose is not None and self._draw_target_pose_component(
+ ui, node.target_pose, dpi_scale,
+ ):
+ remove_component = node.target_pose
+ if node.interaction_box is not None and self._draw_interaction_box_component(
+ ui, node.interaction_box, dpi_scale,
+ ):
+ remove_component = node.interaction_box
+ if node.pivot is not None and self._draw_pivot_component(ui, node.pivot, dpi_scale):
+ remove_component = node.pivot
+
+ if not node.components:
+ ui.text_disabled("Right click empty space to add a component.")
+
+ self._draw_sequence_references(ui, node)
+ self._draw_add_component_popup(ui, node)
+ finally:
+ ui.pop_id()
+
+ ui.end()
+ if remove_component is not None:
+ self._clear_component_renderer(node, remove_component)
+ self.authoring.remove_component(node, remove_component)
+
+ def _draw_sequence_references(self, ui, node: SceneNode) -> None:
+ sequences = list(self.authoring.sequences_referencing(node))
+ if not sequences:
+ return
+ if not ui.collapsing_header(
+ "Referenced by",
+ flags=ui.TreeNodeFlags_.default_open,
+ ):
+ return
+ for sequence in sequences:
+ occurrence_count = sequence.node_ids.count(node.id)
+ suffix = "" if occurrence_count == 1 else f" ({occurrence_count} steps)"
+ if sequence.pivot_node_id == node.id:
+ suffix = " (Pivot)"
+ selected, _ = ui.selectable(
+ f"{sequence.name}{suffix}###{sequence.id}",
+ sequence.id == self.selected_sequence_id,
+ )
+ if selected:
+ self.selected_sequence_id = sequence.id
+
+ def _draw_add_component_popup(self, ui, node: SceneNode) -> None:
+ popup_flags = (
+ ui.PopupFlags_.mouse_button_right | ui.PopupFlags_.no_open_over_items
+ )
+ if not ui.begin_popup_context_window(
+ "##PropertiesContext",
+ popup_flags,
+ ):
+ return
+
+ if ui.begin_menu("Add"):
+ if ui.begin_menu("Components"):
+ add_target_pose, _ = ui.menu_item(
+ "Target Pose",
+ "",
+ False,
+ node.target_pose is None,
+ )
+ if add_target_pose:
+ self.authoring.add_target_pose(node)
+ add_interaction_box, _ = ui.menu_item(
+ "Interaction Box",
+ "",
+ False,
+ node.interaction_box is None,
+ )
+ if add_interaction_box:
+ self.authoring.add_interaction_box(node)
+ add_pivot, _ = ui.menu_item("Pivot", "", False, node.pivot is None)
+ if add_pivot:
+ self.authoring.add_pivot(node)
+ ui.end_menu()
+ ui.end_menu()
+ ui.end_popup()
+
+ def _draw_transform_details(
+ self,
+ ui,
+ node: SceneNode,
+ dpi_scale: float,
+ ) -> None:
+ changed, transform, node.euler_degrees = draw_transform_editor(
+ ui, self._local_xform(node), node.euler_degrees, dpi_scale,
+ node.translation_locks, node.rotation_locks,
+ )
+ if changed:
+ self._set_local_xform(node, transform)
+
+ def _draw_pivot_component(self, ui, component: PivotComponent, dpi_scale: float) -> bool:
+ opened, remove = self._draw_component_header(ui, "Pivot", component.id)
+ if not opened or remove:
+ return remove
+
+ pivot = component.pivot
+ direction = list(pivot.motion_direction)
+ if self._pivot_direction_edit is not None and self._pivot_direction_edit[0] == component.id:
+ direction = self._pivot_direction_edit[1]
+ draw_label(ui, "Motion Direction")
+ changed, direction = ui.input_float3(f"##MotionDirection{component.id}", direction, "%.3f")
+ if changed:
+ # Keep the typed numbers in the fields, but use a unit direction for previews and saving.
+ self._pivot_direction_edit = (component.id, list(direction))
+ try:
+ pivot.set_motion_direction(direction)
+ self._status = None
+ except ValueError as exc:
+ self._status = str(exc)
+ if ui.is_item_deactivated_after_edit():
+ self._pivot_direction_edit = None
+
+ draw_label(
+ ui, "Operation Order",
+ tooltip="Rotating first also turns the axis the pivot slides along.",
+ )
+ orders = list(OperationOrder)
+ _, index = ui.combo(
+ f"##OperationOrder{component.id}", orders.index(pivot.operation_order),
+ ["Translation -> Rotation", "Rotation -> Translation"],
+ )
+ pivot.operation_order = orders[index]
+
+ def draw_rule_row(label, axis, constraint, constraints, axis_labels):
+ draw_label(
+ ui, label, column=100.0 * dpi_scale, width=115.0 * dpi_scale,
+ tooltip="Axes are local to the pivot.",
+ )
+ axes = list(Axis)
+ _, index = ui.combo(
+ f"##{label.lower()}_axis{component.id}", axes.index(axis),
+ axis_labels,
+ )
+ axis = axes[index]
+ ui.same_line()
+ ui.set_next_item_width(-1.0)
+ ui.begin_disabled(axis is Axis.NONE)
+ _, index = ui.combo(
+ f"##{label.lower()}_constraint{component.id}", constraints.index(constraint),
+ [choice.value.replace("_", " ").title() for choice in constraints],
+ )
+ ui.end_disabled()
+ return axis, constraints[index]
+
+ pivot.translation_axis, pivot.translation_constraint = draw_rule_row(
+ "Translation", pivot.translation_axis, pivot.translation_constraint,
+ [ConstraintType.UNCONSTRAINED, ConstraintType.LINE_PROJECTION],
+ ["None", "TranslateX", "TranslateY", "TranslateZ"],
+ )
+ if pivot.translation_axis is not Axis.NONE and pivot.translation_constraint is ConstraintType.LINE_PROJECTION:
+ ui.indent(16.0 * dpi_scale)
+ draw_label(
+ ui, "Offsets (m)", tooltip="Signed distances from the authored pivot along its selected local axis.",
+ )
+ _, pivot.line_min_offset, pivot.line_max_offset = ui.drag_float_range2(
+ f"##LineOffsets{component.id}", pivot.line_min_offset, pivot.line_max_offset,
+ v_speed=0.01, format="Min: %.2f", format_max="Max: %.2f",
+ flags=ui.SliderFlags_.always_clamp,
+ )
+ ui.unindent(16.0 * dpi_scale)
+
+ pivot.rotation_axis, pivot.rotation_constraint = draw_rule_row(
+ "Rotation", pivot.rotation_axis, pivot.rotation_constraint,
+ [ConstraintType.UNCONSTRAINED, ConstraintType.CONE],
+ ["None", "RotateX", "RotateY", "RotateZ"],
+ )
+
+ show_cone = pivot.rotation_axis is not Axis.NONE and pivot.rotation_constraint is ConstraintType.CONE
+ if show_cone:
+ ui.indent(16.0 * dpi_scale)
+ draw_label(
+ ui, "Half Angle (\u00b0)",
+ tooltip="Maximum turn on each side of the center. 45 degrees makes a 90-degree cone.",
+ )
+ _, pivot.cone_half_angle_degrees = ui.slider_float(
+ f"##ConeHalfAngle{component.id}", pivot.cone_half_angle_degrees, 0.0, 180.0,
+ "%.1f", flags=ui.SliderFlags_.always_clamp,
+ )
+ draw_label(
+ ui, "Cone Side",
+ tooltip="Mirrored centers the cone 180 degrees from Motion Direction around the selected local axis.",
+ )
+ sides = list(ConeSide)
+ changed, index = ui.combo(
+ f"##ConeSide{component.id}", sides.index(pivot.cone_side),
+ ["Motion Direction", "Mirrored", "Both"],
+ )
+ if changed:
+ pivot.cone_side = sides[index]
+ ui.unindent(16.0 * dpi_scale)
+ ui.separator()
+ _, component.show_motion_direction = ui.checkbox(
+ f"Show Motion Direction##{component.id}", component.show_motion_direction,
+ )
+ _, component.show_translation_constraint = ui.checkbox(
+ f"Show Translation Constraint##{component.id}", component.show_translation_constraint,
+ )
+ _, component.show_rotation_constraint = ui.checkbox(
+ f"Show Rotation Constraint##{component.id}", component.show_rotation_constraint,
+ )
+ return False
+
+ def _draw_target_pose_component(
+ self,
+ ui,
+ component: TargetPoseComponent,
+ dpi_scale: float,
+ ) -> bool:
+ component_open, remove_component = self._draw_component_header(
+ ui,
+ "Target Pose",
+ component.id,
+ )
+ if not component_open or remove_component:
+ return remove_component
+
+ self._draw_clip_selector(ui, component)
+ self._draw_target_pose_timeline(ui, component, dpi_scale)
+ changed, hips_constrained = ui.checkbox(
+ "Constrain Root",
+ component.hips_constrained,
+ )
+ if changed:
+ component.constrain_hips(hips_constrained)
+ if component.clip is not None and self.authoring.rig is ModelRig.SOMA:
+ self._draw_target_pose_ik_pins(ui, component, dpi_scale)
+ ui.text_unformatted(
+ f"Speed: {component.velocity_magnitude:.3f} m/s"
+ )
+
+ ui.separator()
+ self._draw_target_pose_sampling_options(ui, component)
+ ui.separator()
+ self._draw_target_pose_visualization_options(ui, component)
+ return False
+
+ @staticmethod
+ def _draw_target_pose_ik_pins(
+ ui,
+ component: TargetPoseComponent,
+ dpi_scale: float,
+ ) -> None:
+ selected_pins = [pin for pin in IK_PINS if component.ik_pin_mask & pin]
+ if not selected_pins:
+ preview = "None"
+ elif len(selected_pins) == len(IK_PINS):
+ preview = "All"
+ else:
+ preview = ", ".join(_ik_pin_label(pin) for pin in selected_pins)
+
+ draw_label(ui, "IK Pins", column=80.0 * dpi_scale)
+ if not ui.begin_combo(f"##IKPins{component.id}", preview):
+ return
+
+ for pin in IK_PINS:
+ selected = bool(component.ik_pin_mask & pin)
+ changed, selected = ui.checkbox(
+ f"{_ik_pin_label(pin)}##IKPin{int(pin)}_{component.id}",
+ selected,
+ )
+ if changed:
+ component.set_ik_pin_enabled(pin, selected)
+ ui.end_combo()
+
+ @staticmethod
+ def _draw_component_header(
+ ui,
+ label: str,
+ component_id: int,
+ ) -> tuple[bool, bool]:
+ component_open = ui.collapsing_header(
+ f"{label}###{component_id}",
+ flags=ui.TreeNodeFlags_.default_open,
+ )
+
+ remove_component = False
+ if ui.begin_popup_context_item(f"##{label}Context{component_id}"):
+ remove_component, _ = ui.menu_item(
+ "Remove Component",
+ "",
+ False,
+ )
+ ui.end_popup()
+ return component_open, remove_component
+
+ def _draw_interaction_box_component(
+ self,
+ ui,
+ component: InteractionBoxComponent,
+ dpi_scale: float,
+ ) -> bool:
+ component_open, remove_component = self._draw_component_header(
+ ui,
+ "Interaction Box",
+ component.id,
+ )
+ if not component_open or remove_component:
+ return remove_component
+
+ changed, dimensions = draw_box_dimensions(
+ ui, (component.width, component.depth, component.height), _MIN_INTERACTION_BOX_SIZE, dpi_scale,
+ )
+ if changed:
+ component.set_dimensions(*dimensions)
+
+ color_changed, color = ui.color_edit3(
+ f"Color##InteractionBox{component.id}",
+ component.color,
+ ui.ColorEditFlags_.no_inputs,
+ )
+ if color_changed:
+ component.color = wp.vec3(*color)
+ return False
+
+ @staticmethod
+ def _draw_target_pose_timeline(
+ ui,
+ component: TargetPoseComponent,
+ dpi_scale: float,
+ ) -> None:
+ changed, sample_time, show_frames = draw_clip_scrubber(
+ ui,
+ component.clip.animation if component.clip is not None else None,
+ component.sample_time,
+ component.playback_mode is PlaybackMode.FRAMES,
+ dpi_scale,
+ )
+ component.playback_mode = PlaybackMode.FRAMES if show_frames else PlaybackMode.TIME
+ if changed:
+ component.set_time(sample_time)
+
+ def _draw_target_pose_sampling_options(
+ self,
+ ui,
+ component: TargetPoseComponent,
+ ) -> None:
+ num_poses_to_use = draw_int_slider_property(
+ ui,
+ "Poses to Use",
+ component.num_poses_to_use,
+ 1,
+ MODEL_POSES_PER_TOKEN,
+ component.id,
+ tooltip=POSES_TO_USE_TOOLTIP,
+ )
+ if num_poses_to_use != component.num_poses_to_use:
+ component.set_num_poses_to_use(num_poses_to_use)
+ component.transition_early_by_frames = draw_int_slider_property(
+ ui,
+ "Transition Early By (frames)",
+ component.transition_early_by_frames,
+ 0,
+ MAX_TRANSITION_EARLY_BY_FRAMES,
+ component.id,
+ tooltip="Move on to the next step this many frames before the generated motion ends.",
+ )
+ min_tokens, max_tokens = draw_token_range_property(
+ ui, component.min_tokens, component.max_tokens, component.id,
+ )
+ component.set_token_range(min_tokens, max_tokens)
+
+ @staticmethod
+ def _draw_target_pose_visualization_options(
+ ui,
+ component: TargetPoseComponent,
+ ) -> None:
+ color_changed, color = ui.color_edit3(
+ "Color",
+ component.color,
+ ui.ColorEditFlags_.no_inputs,
+ )
+ if color_changed:
+ component.color = wp.vec3(*color)
+
+ _, component.show_mesh = ui.checkbox("Show Mesh", component.show_mesh)
+ _, component.show_skeletons = ui.checkbox("Show Skeleton(s)", component.show_skeletons)
+ _, component.show_velocity = ui.checkbox("Show Velocity", component.show_velocity)
+ _, component.show_trajectory = ui.checkbox("Show Trajectory", component.show_trajectory)
+ ui.same_line()
+ ui.set_next_item_width(-1.0)
+ changed, trajectory_scale = ui.slider_float(
+ f"##TrajectoryScale{component.id}",
+ component.trajectory_scale,
+ MIN_TRAJECTORY_SCALE,
+ MAX_TRAJECTORY_SCALE,
+ "x %.1f",
+ flags=ui.SliderFlags_.always_clamp,
+ )
+ if changed:
+ component.set_trajectory_scale(trajectory_scale)
+
+ def _draw_clip_selector(self, ui, component: TargetPoseComponent) -> None:
+ clip = component.clip
+ if draw_clip_selector(
+ ui, clip.name if clip else "None", clip.path if clip else None,
+ component.id,
+ ):
+ path = self._choose_clip()
+ if path:
+ try:
+ component.set_clip(self.rig.clip_registry.load(path))
+ self._status = None
+ except ClipLoadError as exc:
+ self._status = f"Open failed: {exc}"
+
+ def _local_xform(
+ self,
+ node: SceneNode,
+ world_xform=None,
+ ) -> wp.transform:
+ if world_xform is None:
+ return wp.transform(node.local_xform)
+ if node.parent is None:
+ return wp.transform(world_xform)
+
+ return wp.mul(
+ wp.transform_inverse(self.authoring.world_xform(node.parent)),
+ world_xform,
+ )
+
+ def _set_local_xform(
+ self,
+ node: SceneNode,
+ local_xform: wp.transform,
+ ) -> None:
+ node.local_xform = wp.transform(local_xform)
+ if node.id == self._gizmo_item_id and self._gizmo_xform is not None:
+ self._gizmo_xform[:] = self.authoring.world_xform(node)
+
+ def _choose_clip(self) -> str:
+ return choose_clip(self.rig.clip_registry)
+
+
+def main() -> None:
+ """Parse the command line and open the Smart Primitive Editor."""
+ import newton.examples
+
+ parser = create_gl_parser()
+
+ viewer, args = newton.examples.init(parser)
+ configure_logging(args)
+ viewer.hide_loading_splash()
+
+ SmartPrimitiveEditor(viewer).run(
+ args.num_frames if args.test else None
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/app/utils/cli.py b/app/utils/cli.py
new file mode 100644
index 0000000..3e980d4
--- /dev/null
+++ b/app/utils/cli.py
@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared command line and logging setup for the MotionBricks apps."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+
+import warp as wp
+
+
+_HIDDEN_NEWTON_OPTIONS = frozenset(
+ {
+ "--viewer",
+ "--rerun-address",
+ "--output-path",
+ "--num-frames",
+ "--render-fps",
+ "--headless",
+ "--test",
+ "--paused",
+ "--benchmark",
+ "--warp-config",
+ "--realtime",
+ }
+)
+# Loggers that follow --quiet and --verbose. Other libraries only show warnings.
+_APP_LOGGERS = ("__main__", "app", "motionbricks")
+
+
+class _MessageFormatter(logging.Formatter):
+ """Show messages as they are, with the level in front of warnings and errors."""
+
+ def format(self, record: logging.LogRecord) -> str:
+ message = super().format(record)
+ return f"{record.levelname}: {message}" if record.levelno >= logging.WARNING else message
+
+
+def create_gl_parser() -> argparse.ArgumentParser:
+ """Use the OpenGL viewer, hide Newton's extra options, and add output levels."""
+
+ import newton.examples
+
+ parser = newton.examples.create_parser()
+ for action in parser._actions:
+ if _HIDDEN_NEWTON_OPTIONS.intersection(action.option_strings):
+ action.help = argparse.SUPPRESS
+ if "--viewer" in action.option_strings:
+ action.choices = ("gl",)
+ if "--quiet" in action.option_strings:
+ action.help = "Show only warnings and errors."
+ parser.add_argument(
+ "--verbose",
+ action="store_true",
+ help="Show detailed messages, such as each clip load, TensorRT output, and Warp module loads.",
+ )
+ return parser
+
+
+def add_model_precision_argument(parser: argparse.ArgumentParser) -> None:
+ """Add --model-precision, which selects the bundled FP32 or mixed FP16 models."""
+
+ parser.add_argument(
+ "--model-precision",
+ choices=("fp32", "fp16"),
+ default="fp32",
+ help="Precision of the bundled ONNX models.",
+ )
+
+
+def configure_logging(args: argparse.Namespace) -> None:
+ """Show app messages, only problems with --quiet, or every detail with --verbose.
+
+ Warp's module load messages are details too, so they only show with --verbose.
+ """
+
+ handler = logging.StreamHandler()
+ handler.setFormatter(_MessageFormatter())
+ logging.basicConfig(level=logging.WARNING, handlers=[handler], force=True)
+ level = logging.WARNING if args.quiet else logging.DEBUG if args.verbose else logging.INFO
+ for name in _APP_LOGGERS:
+ logging.getLogger(name).setLevel(level)
+ if not args.verbose:
+ wp.config.log_level = max(wp.config.log_level, wp.LOG_WARNING)
diff --git a/app/utils/file_dialog.py b/app/utils/file_dialog.py
new file mode 100644
index 0000000..58abfa4
--- /dev/null
+++ b/app/utils/file_dialog.py
@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""File dialogs shared by the MotionBricks apps."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def choose_file(
+ title: str,
+ label: str,
+ suffix: str,
+ current_path: Path | None = None,
+ *,
+ save: bool = False,
+) -> str:
+ """Show a native Open or Save dialog that lists one kind of file.
+
+ Args:
+ title: Dialog title.
+ label: Name of the file filter, such as "Scene documents".
+ suffix: File suffix that the dialog lists and adds, such as ".scene.json".
+ current_path: File whose folder the dialog opens in. The Save dialog also
+ starts with its name.
+ save: Show the Save dialog instead of the Open dialog.
+
+ Returns:
+ The chosen path, or an empty string when the dialog is canceled.
+ """
+
+ import tkinter as tk
+ from tkinter import filedialog
+
+ options = {"title": title, "defaultextension": suffix, "filetypes": ((label, f"*{suffix}"),)}
+ if current_path is not None:
+ options["initialdir"] = str(current_path.parent)
+ if save:
+ options["initialfile"] = current_path.name
+ root = tk.Tk()
+ root.withdraw()
+ try:
+ dialog = filedialog.asksaveasfilename if save else filedialog.askopenfilename
+ return dialog(**options)
+ finally:
+ root.destroy()
+
+
+__all__ = ["choose_file"]
diff --git a/app/utils/input.py b/app/utils/input.py
new file mode 100644
index 0000000..59fc004
--- /dev/null
+++ b/app/utils/input.py
@@ -0,0 +1,294 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Keyboard and controller input shared by the apps."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Callable, Literal, Protocol
+
+import numpy as np
+
+from ..runtime.common.motion import CROUCH_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE, LINEAR_LOCOMOTION_MODE
+
+DEFAULT_STICK_DEAD_ZONE = 0.20
+_ZERO_AXES = (0.0, 0.0)
+# Each key and its controller button switch between two modes.
+_MODE_TOGGLES = (
+ ("o", "y", LINEAR_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE),
+ ("p", "b", CROUCH_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE),
+)
+_STYLE_KEY, _STYLE_BUTTON = "[", "a"
+
+
+def camera_relative_movement(
+ camera_facing: np.ndarray, movement: tuple[float, float],
+) -> np.ndarray:
+ """Map (right, forward) movement onto the ground while retaining stick strength.
+
+ A stick at rest gives a zero vector, which MovementControl reads as no movement.
+ """
+ right, forward = movement
+ camera_right = np.array([camera_facing[1], -camera_facing[0], 0.0], dtype=np.float32)
+ return camera_facing * forward + camera_right * right
+
+
+class _Controller(Protocol):
+ leftx: float
+ lefty: float
+ rightx: float
+ righty: float
+ dpadx: float
+ dpady: float
+ a: bool
+ x: bool
+ y: bool
+ b: bool
+
+ def open(self) -> None: ...
+
+ def close(self) -> None: ...
+
+
+class _ControllerManager(Protocol):
+ def get_controllers(self) -> list[_Controller]: ...
+
+ def push_handlers(self, *args, **kwargs) -> None: ...
+
+ def remove_handlers(self, *args, **kwargs) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class InputFrame:
+ """Movement, camera, and speed input for this frame.
+
+ Movement uses (right, forward) and camera orbit uses (right, up). Each
+ vector's length is the stick strength after the dead zone.
+ """
+
+ movement: tuple[float, float]
+ camera_orbit: tuple[float, float]
+ use_max_speed: bool
+
+
+def apply_radial_dead_zone(x: float, y: float, dead_zone: float) -> tuple[float, float]:
+ """Ignore small stick movements and scale the remaining range from zero to one."""
+
+ if not 0.0 <= dead_zone < 1.0:
+ raise ValueError("dead_zone must be in the range [0, 1).")
+
+ length = math.hypot(x, y)
+ if length <= dead_zone:
+ return _ZERO_AXES
+
+ direction_x = x / length
+ direction_y = y / length
+ magnitude = (min(length, 1.0) - dead_zone) / (1.0 - dead_zone)
+ return direction_x * magnitude, direction_y * magnitude
+
+
+class InputManager:
+ """Read the keyboard and use the first available controller."""
+
+ def __init__(
+ self,
+ is_key_down: Callable[[str], bool],
+ controller_manager: _ControllerManager | None = None,
+ movement_dead_zone: float = DEFAULT_STICK_DEAD_ZONE,
+ camera_dead_zone: float = DEFAULT_STICK_DEAD_ZONE,
+ ) -> None:
+ """Read keys through is_key_down, and a controller through controller_manager.
+
+ The dead zones apply to the movement and camera sticks.
+ """
+ self._is_key_down = is_key_down
+ self._controller_manager = controller_manager
+ self._controller: _Controller | None = None
+ self.movement_dead_zone = movement_dead_zone
+ self.camera_dead_zone = camera_dead_zone
+
+ if controller_manager is not None:
+ controller_manager.push_handlers(self)
+ self._open_first_available_controller()
+
+ @classmethod
+ def from_pyglet(cls, is_key_down: Callable[[str | int], bool]) -> InputManager:
+ """Set up keyboard input and optional controller support.
+
+ The viewer reads letters, digits, and arrow keys by name. [ goes through its pyglet
+ key code.
+ """
+
+ from pyglet.window import key
+
+ key_codes = {"[": key.BRACKETLEFT}
+ try:
+ from pyglet.input import ControllerManager
+
+ controller_manager = ControllerManager()
+ except Exception:
+ controller_manager = None
+ return cls(lambda name: is_key_down(key_codes.get(name, name)), controller_manager)
+
+ def is_key_down(self, key: str) -> bool:
+ """Return whether a keyboard key is currently held."""
+
+ return self._is_key_down(key)
+
+ def is_interaction_down(self) -> bool:
+ """Return whether I or the controller's X button is held."""
+
+ return self.is_key_down("i") or self.is_controller_button_down("x")
+
+ def is_controller_button_down(self, button: Literal["a", "x", "y", "b"]) -> bool:
+ """Return whether one of the demo's controller buttons is held."""
+
+ controller = self._controller
+ return controller is not None and bool(
+ {"a": controller.a, "x": controller.x, "y": controller.y, "b": controller.b}[button]
+ )
+
+ def poll(self) -> InputFrame:
+ """Sample movement, camera, and speed input for one update."""
+
+ controller_movement = self._controller_movement()
+ if controller_movement == _ZERO_AXES:
+ # W, A, S, and D or the arrow keys give a full strength direction, so diagonals
+ # are not faster.
+ right = self.is_key_down("d") or self.is_key_down("right")
+ left = self.is_key_down("a") or self.is_key_down("left")
+ forward = self.is_key_down("w") or self.is_key_down("up")
+ backward = self.is_key_down("s") or self.is_key_down("down")
+ movement = apply_radial_dead_zone(float(right) - float(left), float(forward) - float(backward), 0.0)
+ else:
+ movement = controller_movement
+
+ return InputFrame(
+ movement=movement,
+ camera_orbit=self._controller_camera_orbit(),
+ use_max_speed=(
+ controller_movement != _ZERO_AXES
+ or self.is_key_down("space")
+ ),
+ )
+
+ def close(self) -> None:
+ """Stop listening for controller input and connection changes."""
+
+ if self._controller_manager is not None:
+ self._controller_manager.remove_handlers(self)
+ self._close_controller()
+
+ def on_connect(self, controller: _Controller) -> None:
+ """Use a newly connected controller when no controller is active."""
+
+ if self._controller is None:
+ self._open_controller(controller)
+
+ def on_disconnect(self, controller: _Controller) -> None:
+ """Drop a disconnected controller and select another if available."""
+
+ if controller is not self._controller:
+ return
+ self._controller = None
+ self._open_first_available_controller()
+
+ def _open_first_available_controller(self) -> None:
+ try:
+ controllers = self._controller_manager.get_controllers()
+ except Exception:
+ return
+ for controller in controllers:
+ if self._open_controller(controller):
+ return
+
+ def _open_controller(self, controller: _Controller) -> bool:
+ try:
+ controller.open()
+ except Exception:
+ return False
+ self._controller = controller
+ return True
+
+ def _close_controller(self) -> None:
+ controller = self._controller
+ self._controller = None
+ if controller is None:
+ return
+ try:
+ controller.close()
+ except Exception:
+ pass
+
+ def _controller_movement(self) -> tuple[float, float]:
+ controller = self._controller
+ if controller is None:
+ return _ZERO_AXES
+
+ movement = apply_radial_dead_zone(
+ float(controller.leftx),
+ float(controller.lefty),
+ self.movement_dead_zone,
+ )
+ if movement != _ZERO_AXES:
+ return movement
+
+ # The controller's D-pad can also move the character.
+ return apply_radial_dead_zone(
+ float(controller.dpadx),
+ float(controller.dpady),
+ self.movement_dead_zone,
+ )
+
+ def _controller_camera_orbit(self) -> tuple[float, float]:
+ controller = self._controller
+ if controller is None:
+ return _ZERO_AXES
+ return apply_radial_dead_zone(
+ float(controller.rightx),
+ float(controller.righty),
+ self.camera_dead_zone,
+ )
+
+
+class LocomotionModeInput:
+ """Change the locomotion mode once per key or button press.
+
+ O (Y on a controller) switches between Forward and Strafing. P (B on a
+ controller) switches between Crouching and Strafing. [ (A on a controller)
+ cycles through the style modes. From any other mode, it returns to the last
+ style used.
+ """
+
+ def __init__(self, style_modes: tuple[str, ...] = ()) -> None:
+ """Track the toggles. style_modes names the style modes in the order [ cycles them."""
+ self._style_modes = style_modes
+ self._last_style = style_modes[0] if style_modes else None
+ self._held = dict.fromkeys([key for key, *_ in _MODE_TOGGLES] + [_STYLE_KEY], False)
+
+ def poll(self, input_manager: InputManager, current_mode: str) -> str | None:
+ """Return the mode that a newly pressed toggle asks for, or None."""
+ if current_mode in self._style_modes:
+ self._last_style = current_mode
+ requested_mode = None
+ for key, button, first_mode, second_mode in _MODE_TOGGLES:
+ if self._pressed(input_manager, key, button):
+ requested_mode = second_mode if current_mode == first_mode else first_mode
+ if self._pressed(input_manager, _STYLE_KEY, _STYLE_BUTTON) and self._style_modes:
+ requested_mode = self._next_style(current_mode)
+ return requested_mode
+
+ def _pressed(self, input_manager: InputManager, key: str, button: str) -> bool:
+ """Return whether the key or its button went down since the last poll."""
+ down = input_manager.is_key_down(key) or input_manager.is_controller_button_down(button)
+ pressed = down and not self._held[key]
+ self._held[key] = down
+ return pressed
+
+ def _next_style(self, current_mode: str) -> str:
+ if current_mode not in self._style_modes:
+ return self._last_style
+ index = self._style_modes.index(current_mode)
+ return self._style_modes[(index + 1) % len(self._style_modes)]
diff --git a/app/utils/model_loading.py b/app/utils/model_loading.py
new file mode 100644
index 0000000..d8cd6f2
--- /dev/null
+++ b/app/utils/model_loading.py
@@ -0,0 +1,155 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Check TensorRT and load model engines while the viewer shows the build progress."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+import logging
+from pathlib import Path
+import time
+from typing import Any, TypeVar
+
+import newton
+import tensorrt as trt
+import warp as wp
+
+from motionbricks.inference.builder import TensorRTBuildOptions, create_logger
+from motionbricks.inference.engine import InferenceEngine
+from motionbricks.inference.progress import (
+ TensorRTBuildProgress,
+ TensorRTBuildProgressMonitor,
+)
+from motionbricks.model.contract import ModelRig
+from motionbricks.model.soma.contract import SOMA_N1_FP16_ONNX_PATH, SOMA_N1_FP32_ONNX_PATH
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.model.unitree_g1.contract import (
+ UNITREE_G1_N1_FP16_ONNX_PATH,
+ UNITREE_G1_N1_FP32_ONNX_PATH,
+)
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+
+from ..runtime.common.rig import RIG_LABELS, model_to_runtime
+
+
+logger = logging.getLogger(__name__)
+
+_EngineT = TypeVar("_EngineT", bound=InferenceEngine)
+# Each rig's engine class and its bundled FP32 and FP16 models.
+_ENGINES = {
+ ModelRig.SOMA: (MotionBricksSOMAEngine, SOMA_N1_FP32_ONNX_PATH, SOMA_N1_FP16_ONNX_PATH),
+ ModelRig.UNITREE_G1: (MotionBricksUnitreeG1Engine, UNITREE_G1_N1_FP32_ONNX_PATH, UNITREE_G1_N1_FP16_ONNX_PATH),
+}
+_BUILD_PROGRESS_BAR_WIDTH = 16
+_BUILD_PROGRESS_UPDATE_INTERVAL = 0.1
+
+
+def _format_engine_loading_text(progress: TensorRTBuildProgress) -> str:
+ if progress.phase_name is None:
+ return "Checking TensorRT plan cache..."
+
+ filled = int(progress.fraction * _BUILD_PROGRESS_BAR_WIDTH)
+ progress_bar = "#" * filled + "-" * (_BUILD_PROGRESS_BAR_WIDTH - filled)
+ percentage = int(progress.fraction * 100.0)
+ phase_name = progress.phase_name
+ if len(phase_name) > 36:
+ phase_name = phase_name[:33] + "..."
+ return (
+ f"Building TensorRT plan: {phase_name} "
+ f"[{progress_bar}] {percentage}%"
+ )
+
+
+def require_tensorrt() -> None:
+ """Exit with a console error unless TensorRT can start on the current device."""
+
+ device = wp.get_device()
+ if device.is_cuda:
+ try:
+ trt.Runtime(create_logger("ERROR"))
+ return
+ except Exception:
+ pass # TensorRT has already logged why it cannot start.
+ logger.error(
+ "TensorRT cannot run on %s. MotionBricks needs an NVIDIA GPU with a recent driver.", device.alias
+ )
+ raise SystemExit(1)
+
+
+def create_engine(
+ viewer: newton.viewer.ViewerGL, rig: ModelRig, fp16: bool,
+) -> MotionBricksSOMAEngine | MotionBricksUnitreeG1Engine:
+ """Create a rig's engine from its bundled ONNX model."""
+ logger.info(
+ "Loading MotionBricks %s in %s. The first run builds and caches a TensorRT plan.",
+ RIG_LABELS[rig], "mixed FP16" if fp16 else "FP32",
+ )
+ engine_type, fp32_path, fp16_path = _ENGINES[rig]
+ return create_model_engine(
+ viewer,
+ engine_type,
+ fp16_path if fp16 else fp32_path,
+ model_to_runtime=model_to_runtime(rig),
+ build_options=TensorRTBuildOptions(enable_fp16=fp16),
+ )
+
+
+def create_model_engine(
+ viewer: newton.viewer.ViewerGL,
+ engine_type: type[_EngineT],
+ onnx_path: str | Path,
+ **engine_options: Any,
+) -> _EngineT:
+ """Load an engine in a worker while drawing progress on the viewer thread.
+
+ Constructor options are forwarded to the engine, which must accept
+ ``build_progress_monitor`` for progress reporting and cancellation.
+ The viewer's UI is hidden during the build so it cannot start other work.
+ Closing the viewer cancels the load and raises SystemExit.
+ """
+
+ progress_monitor = TensorRTBuildProgressMonitor()
+ device = wp.get_device()
+ viewer_running = True
+ show_ui = viewer.show_ui
+ viewer.show_ui = False
+
+ def load_engine() -> _EngineT:
+ wp.set_device(device)
+ return engine_type(
+ onnx_path,
+ build_progress_monitor=progress_monitor,
+ **engine_options,
+ )
+
+ with ThreadPoolExecutor(max_workers=1) as executor:
+ future = executor.submit(load_engine)
+ try:
+ while not future.done():
+ if viewer_running:
+ viewer.show_loading_splash(
+ _format_engine_loading_text(progress_monitor.snapshot())
+ )
+ viewer.begin_frame(0.0)
+ viewer.end_frame()
+ viewer_running = viewer.is_running()
+ if not viewer_running:
+ progress_monitor.request_cancel()
+ time.sleep(_BUILD_PROGRESS_UPDATE_INTERVAL)
+ try:
+ engine = future.result()
+ except Exception:
+ if not viewer_running:
+ raise SystemExit(0) from None
+ raise
+ viewer_running = viewer_running and viewer.is_running()
+ finally:
+ if viewer_running:
+ viewer.hide_loading_splash()
+ viewer.show_ui = show_ui
+
+ if not viewer_running:
+ engine.close()
+ raise SystemExit(0)
+ return engine
diff --git a/app/utils/tooltips.py b/app/utils/tooltips.py
new file mode 100644
index 0000000..4e90eaf
--- /dev/null
+++ b/app/utils/tooltips.py
@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tooltips shared by the MotionBricks apps."""
+
+from __future__ import annotations
+
+import time
+
+TOOLTIP_DELAY_SECONDS = 1.0
+_WRAP_WIDTH_EM = 28.0
+# The hovered item, by text and position, and when the mouse arrived on it.
+_hover = {"item": None, "since": 0.0}
+
+
+def show_delayed_tooltip(ui, text: str, delay: float = TOOLTIP_DELAY_SECONDS) -> None:
+ """Show text in a tooltip once the mouse has rested on the last item for delay seconds.
+
+ The delay uses the wall clock, because the viewer does not give ImGui real frame times.
+ The text wraps into a short paragraph.
+ """
+ corner = ui.get_item_rect_min()
+ item = (text, corner.x, corner.y)
+ if not ui.is_item_hovered():
+ if _hover["item"] == item:
+ _hover["item"] = None
+ return
+ now = time.perf_counter()
+ if _hover["item"] != item:
+ _hover["item"], _hover["since"] = item, now
+ if now - _hover["since"] < delay:
+ return
+ ui.begin_tooltip()
+ ui.push_text_wrap_pos(ui.get_font_size() * _WRAP_WIDTH_EM)
+ ui.text_unformatted(text)
+ ui.pop_text_wrap_pos()
+ ui.end_tooltip()
diff --git a/assets/motions/LICENSE.txt b/assets/motions/LICENSE.txt
new file mode 100644
index 0000000..39469f1
--- /dev/null
+++ b/assets/motions/LICENSE.txt
@@ -0,0 +1,71 @@
+NVIDIA SAMPLE DATA EVALUATION LICENSE
+
+
+IMPORTANT NOTICE – PLEASE READ AND AGREE BEFORE USING THE SAMPLE DATASET.
+
+
+This NVIDIA Sample Data Evaluation License (“Agreement”) is a legal agreement between you, whether an individual or entity ("you”) and NVIDIA Corporation ("NVIDIA") and governs your use of the NVIDIA Sample Dataset, which may include video, image and audio files provided under this Agreement (the “Sample Dataset”).
+
+
+This Agreement can be accepted only by an adult of legal age of majority in the country in which the Sample Dataset is used. If you do not have the required age or authority to accept this Agreement or if you don’t accept all the terms and conditions of this Agreement, do not use the Sample Dataset.
+
+
+You agree to use the Sample Dataset only for purposes that are permitted by this Agreement and any applicable law or regulation in the relevant jurisdictions.
+
+
+1. License. Subject to the terms of this Agreement, NVIDIA grants you a limited, non-exclusive, revocable, non-transferable, non-sublicensable license to internally (a) use and reproduce the Sample Dataset, and (b) modify and create derivative works of the Sample Dataset (“Derivative Works”), in both cases solely to evaluate and test NVIDIA technologies (“Purpose”) and consistent with the limitations in Section 2 below.
+
+
+2. Limitations. Your license to use the Sample Dataset and Derivative Works is restricted. Except as expressly permitted in Section 1 above, you may not:
+(a) use the Sample Dataset or Derivative Works for any purpose other than the Purpose;
+(b) change or remove copyright or other proprietary notices in the Sample Dataset and Derivative Works;
+(c) sell, rent, sublicense, transfer, distribute, offer or otherwise make the Sample Dataset and Derivative Works available to others;
+(d) bypass, disable, or circumvent any technology limitation, encryption, security, digital rights management or authentication mechanism relating to the Sample Dataset or Derivative Works;
+(e) use the Sample Dataset or Derivative Works or assist or facilitate using the Sample Dataset or Derivative Works:
+(i) in any manner inconsistent with NVIDIA’s Trustworthy AI Terms available at https://www.nvidia.com/en-us/agreements/trustworthy-ai/terms/;
+(ii) to identify or attempt to identify any individual in the Sample Dataset or Derivative Works or combine it with any other dataset to profile or attempt to profile any individual in the Sample Dataset or Derivative Works, or de-anonymize or attempt to de-anonymize any Sample Dataset or Derivative Works;
+(iii) to generate likeness of the appearance or voice in the Sample Dataset or otherwise to generate digital replicas of individuals in the Sample Dataset, provided that regenerating the original audio-visual content of the Sample Dataset for the Purpose will not constitute a violation of this restriction;
+(iv) to infer, measure, detect or otherwise label the race, ethnicity, gender, age or health (or any other sensitive attributes) of individuals in the Sample Dataset or Derivative Works or perform any biometric processing;
+(v) to develop or evaluate any identity recognition technology;
+(vi) in violation of any applicable law or regulation in relevant jurisdictions;
+(vii) in any fraudulent, false, misleading or deceptive manner or practice;
+(viii) in connection with defamatory, obscene, pornographic, vulgar or offensive activities or content;
+(ix) to promote discrimination, bigotry, racism, hatred, harassment or harm against any individual or group;
+(x) to be violent or threatening or promote violence or actions that are threatening to any other person; or
+(xi) to promote illegal activities.
+
+
+3. Ownership. The Sample Dataset, including all intellectual property rights, are and will remain the sole and exclusive property of NVIDIA or its licensors. Except as expressly granted in this Agreement, (a) NVIDIA reserves all rights, interests, and remedies in connection with the Sample Dataset, and (b) no other license or right is granted to you by implication, estoppel or otherwise.
+
+
+4. Requests for Deletion or Correction. Upon NVIDIA’s request, you will cooperate with NVIDIA to honor any data subject request for deletion or correction of the Sample Dataset. If requested by NVIDIA, you will delete all copies and cease use of any Sample Dataset and provide reasonably requested information to verify your compliance with the terms of this Agreement.
+
+
+5. Feedback. You may, but you are not obligated to, provide suggestions, requests, fixes, modifications, enhancements, or other feedback regarding the Sample Dataset (collectively, “Feedback”). Feedback, even if designated as confidential by you, will not create any confidentiality obligation for NVIDIA or its affiliates. If you provide Feedback, you hereby grant NVIDIA, its affiliates and its designees a non-exclusive, perpetual, irrevocable, sublicensable, worldwide, royalty-free, fully paid-up and transferable license, under your intellectual property rights, to publicly perform, publicly display, reproduce, use, make, have made, sell, offer for sale, distribute (through multiple tiers of distribution), import, create derivative works of and otherwise commercialize and exploit the Feedback at NVIDIA’s discretion.
+
+
+6. Term and Termination. This Agreement will automatically terminate without notice from NVIDIA if you fail to comply with any of the terms in this Agreement or if you commence or participate in any legal proceeding against NVIDIA with respect to the Sample Dataset. Additionally, NVIDIA may terminate this Agreement at any time with prior written notice. Upon any termination, you must immediately stop using and destroy all copies of the Sample Dataset and Derivative Works. Upon written request, you will certify in writing that you have complied with your commitments under this section. All provisions will survive termination, except for the licenses granted to you.
+
+
+7. Disclaimer of Warranties. THE SAMPLE DATASET IS PROVIDED BY NVIDIA AS-IS AND WITH ALL FAULTS. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, NVIDIA DISCLAIMS ALL WARRANTIES AND REPRESENTATIONS OF ANY KIND, WHETHER EXPRESS, IMPLIED OR STATUTORY, RELATING TO OR ARISING UNDER THIS AGREEMENT, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF TITLE, NONINFRINGEMENT, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, USAGE OF TRADE AND COURSE OF DEALING.
+
+
+8. Limitations of Liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, WILL NVIDIA BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY TYPE ARISING OUT OF OR AS A RESULT OF THIS AGREEMENT OR THE USE OR INABILITY TO USE THE SAMPLE DATASET (INCLUDING BUT NOT LIMITED TO DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES), EVEN IF NVIDIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+
+9. Indemnity. You will indemnify and hold harmless NVIDIA, its affiliates, their employees, officers, directors and agents (“Indemnified Parties”) and, at NVIDIA’s election, defend the Indemnified Parties from all third-party claims or lawsuits, costs, damages, expenses, liabilities, including attorney’s fees, arising out of or in connection with your use of the Sample Dataset.
+
+
+10. Governing Law and Jurisdiction. This Agreement will be governed in all respects by the laws of the United States and the laws of the State of Delaware, without regard to conflict of laws principles or the United Nations Convention on Contracts for the International Sale of Goods. The state and federal courts residing in Santa Clara County, California will have exclusive jurisdiction over any dispute or claim arising out of or related to this Agreement, and the parties irrevocably consent to personal jurisdiction and venue in those courts; except that either party may apply for injunctive remedies or an equivalent type of urgent legal relief in any jurisdiction.
+
+
+11. No Assignment. NVIDIA may assign, delegate or transfer its rights or obligations under this Agreement by any means or operation of law. You may not, without NVIDIA’s prior written consent, assign, delegate or transfer any of your rights or obligations under this Agreement by any means or operation of law, and any attempt to do so is null and void.
+
+
+12. Trade Compliance. You agree to comply with all applicable export, import, trade and economic sanctions laws and regulations, as amended, including without limitation the Export Administration Regulations and Office of Foreign Assets Control regulations. These laws include restrictions on destinations, end-users and end-use.
+
+
+13. Entire Agreement. Regarding the subject matter of this Agreement, the parties agree that this Agreement constitutes the entire and exclusive agreement between the parties and supersedes all prior and contemporaneous communications. If a court of competent jurisdiction rules that a provision of this Agreement is unenforceable, that provision will be deemed modified to the extent necessary to make it enforceable and the remainder of this Agreement will continue in full force and effect. Any amendment to this Agreement must be in writing and signed by authorized representatives of both parties.
+
+
+(v. Jan. 16, 2026)
diff --git a/assets/motions/README.md b/assets/motions/README.md
new file mode 100644
index 0000000..67ceb7e
--- /dev/null
+++ b/assets/motions/README.md
@@ -0,0 +1,99 @@
+# Sample motion clips
+
+These human motion samples are derived from the Bones RigPlay 1 (RP1) dataset. NVIDIA fitted
+the human motions to SOMA and retargeted the robot motions to Unitree G1. The clips
+provide example animations and poses for the MotionBricks demos.
+
+The 38 BVH files and 37 CSV files listed below are provided under the
+[NVIDIA Sample Data Evaluation License](LICENSE.txt), separately from the source
+code and models. Read the license before using the clips.
+
+For the broader dataset and licensing options, see
+[BONES-SEED](https://huggingface.co/datasets/bones-studio/seed).
+
+## File coverage
+
+Paths below are relative to this directory. The sample-data notice covers only
+these listed motion files. It does not apply the sample license to model weights,
+ONNX models, robot assets, rig metadata, Smart Primitive documents, or scene files.
+
+### SOMA human clips
+
+- `soma/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.bvh`
+- `soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh`
+- `soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh`
+- `soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh`
+- `soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh`
+- `soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh`
+- `soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh`
+- `soma/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.bvh`
+- `soma/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.bvh`
+- `soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh`
+- `soma/locomotion/bs_1d_linear/run_loop_180_R_003__A326.bvh`
+- `soma/locomotion/bs_1d_linear/run_loop_180_R_003__A331.bvh`
+- `soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.bvh`
+- `soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.bvh`
+- `soma/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.bvh`
+- `soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.bvh`
+- `soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.bvh`
+- `soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.bvh`
+- `soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.bvh`
+- `soma/locomotion/idle/crouch_idle_001__A529.bvh`
+- `soma/locomotion/idle/idle_loop_001__A268.bvh`
+- `soma/locomotion/idle/legs_relax_002__A407.bvh`
+- `soma/locomotion/idle/neutral_looking_around_R_001__A542.bvh`
+- `soma/locomotion/idle/warm_up_neck_001__A359.bvh`
+- `soma/sitting/sit_on_chair_loop.bvh`
+- `soma/sitting/sit_on_chair_start_R_001__A047.bvh`
+- `soma/sitting/sit_on_chair_stop_R_001__A047.bvh`
+- `soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.bvh`
+- `soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.bvh`
+- `soma/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.bvh`
+- `soma/variations/angry_gun_walk_ff_loop_090_R_001__A393.bvh`
+- `soma/variations/combat_quickstep_ff_idle_180_R_002__A365.bvh`
+- `soma/variations/dance_vouge_vogue_sequence_180_R_002__A316.bvh`
+- `soma/variations/dancecards1_AB_injured_L_leg_001__A005.bvh`
+- `soma/variations/injured_L_leg_grab_walk_ff_180_002__A549.bvh`
+- `soma/variations/injured_torso_grab_walk_ff_180_001__A549.bvh`
+- `soma/variations/skipping_R_002__A360.bvh`
+- `soma/variations/zombie_walk_180_R_003__A330.bvh`
+
+### Unitree G1 robot clips
+
+- `unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.csv`
+- `unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.csv`
+- `unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv`
+- `unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv`
+- `unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv`
+- `unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv`
+- `unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv`
+- `unitree_g1/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.csv`
+- `unitree_g1/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.csv`
+- `unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv`
+- `unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A326.csv`
+- `unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A331.csv`
+- `unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.csv`
+- `unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.csv`
+- `unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.csv`
+- `unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.csv`
+- `unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.csv`
+- `unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.csv`
+- `unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.csv`
+- `unitree_g1/locomotion/idle/crouch_idle_001__A529.csv`
+- `unitree_g1/locomotion/idle/idle_loop_001__A268.csv`
+- `unitree_g1/locomotion/idle/legs_relax_002__A407.csv`
+- `unitree_g1/locomotion/idle/neutral_looking_around_R_001__A542.csv`
+- `unitree_g1/sitting/sit_on_chair_loop.csv`
+- `unitree_g1/sitting/sit_on_chair_start_R_001__A047.csv`
+- `unitree_g1/sitting/sit_on_chair_stop_R_001__A047.csv`
+- `unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.csv`
+- `unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.csv`
+- `unitree_g1/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.csv`
+- `unitree_g1/variations/angry_gun_walk_ff_loop_090_R_001__A393.csv`
+- `unitree_g1/variations/combat_quickstep_ff_idle_180_R_002__A365.csv`
+- `unitree_g1/variations/dance_vouge_vogue_sequence_180_R_002__A316.csv`
+- `unitree_g1/variations/dancecards1_AB_injured_L_leg_001__A005.csv`
+- `unitree_g1/variations/injured_L_leg_grab_walk_ff_180_002__A549.csv`
+- `unitree_g1/variations/injured_torso_grab_walk_ff_180_001__A549.csv`
+- `unitree_g1/variations/skipping_R_002__A360.csv`
+- `unitree_g1/variations/zombie_walk_180_R_003__A330.csv`
diff --git a/assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.bvh b/assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.bvh
new file mode 100644
index 0000000..b0a5ac2
--- /dev/null
+++ b/assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4560ddfc0a216e07356426ab1af83b3e13785ed76312a6657503d7bb97585cb9
+size 1577274
diff --git a/assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh b/assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh
new file mode 100644
index 0000000..0f4af9e
--- /dev/null
+++ b/assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1b9ad236e4b846b22c1f3b258d45b064f073f272759e254c7dd3386d8e471012
+size 2648450
diff --git a/assets/motions/soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh b/assets/motions/soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh
new file mode 100644
index 0000000..0b7b9eb
--- /dev/null
+++ b/assets/motions/soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:40f11025af983acf94c7028bdaee0743be7b9641e57545e45b67c0ef42e4413d
+size 1428924
diff --git a/assets/motions/soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh b/assets/motions/soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh
new file mode 100644
index 0000000..3bc9143
--- /dev/null
+++ b/assets/motions/soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ea888343a7adee808e96a792f704bbf7d058c4201c9476165eb3b61a62e9bc9
+size 1358894
diff --git a/assets/motions/soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh b/assets/motions/soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh
new file mode 100644
index 0000000..07f9cd7
--- /dev/null
+++ b/assets/motions/soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:74fa726177530e7eac029e879d1747529d5eb8cc71ec3d5dcf10f3b732bdb5d4
+size 1302608
diff --git a/assets/motions/soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh b/assets/motions/soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh
new file mode 100644
index 0000000..312ed90
--- /dev/null
+++ b/assets/motions/soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2cf169575f4efc2687eb54f5d133e33286b1b853dc9afe6952bf9518338f032a
+size 1341652
diff --git a/assets/motions/soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh b/assets/motions/soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh
new file mode 100644
index 0000000..4db2e4a
--- /dev/null
+++ b/assets/motions/soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:363ac41c75e741dde9dd047dc9a5ecf9bb9c94105876506f620309f3c277882b
+size 1331891
diff --git a/assets/motions/soma/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.bvh b/assets/motions/soma/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.bvh
new file mode 100644
index 0000000..0364719
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c0f4e63cec94c58196105a6d9f03a2ed1c94c8ff4fba15dd0a33cc512877904a
+size 2587387
diff --git a/assets/motions/soma/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.bvh b/assets/motions/soma/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.bvh
new file mode 100644
index 0000000..b18d686
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:321883221739a6bad5f786bdcc8edc5ff6c7d7a443d47b08d1dac03036840e2a
+size 1568243
diff --git a/assets/motions/soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh b/assets/motions/soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh
new file mode 100644
index 0000000..9347a63
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e7c98757c2c95f3cbbbaa2a63e329a937b8a7549fed0856c066164b1a5200f31
+size 3203080
diff --git a/assets/motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A326.bvh b/assets/motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A326.bvh
new file mode 100644
index 0000000..77560b7
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A326.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9151bb7ff149e62dc47d3beb555f890c72352f87980aedabbd4ce456a7f70976
+size 565877
diff --git a/assets/motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A331.bvh b/assets/motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A331.bvh
new file mode 100644
index 0000000..54f33b1
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A331.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:155bebc7049b794f1629fb385cdfe81e981e51acc3ee05d015716fceceae75e0
+size 541594
diff --git a/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.bvh b/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.bvh
new file mode 100644
index 0000000..f443188
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3c1f8b1657c053c8f7e2acb1dd015660a9e62cb2b3f28e231dead02a44b81054
+size 423599
diff --git a/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.bvh b/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.bvh
new file mode 100644
index 0000000..04ccbde
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:717b834da088e0190eff026997cec5c9872ebab7a27ba1dcd25a9b1f99cd4ec9
+size 421808
diff --git a/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.bvh b/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.bvh
new file mode 100644
index 0000000..5b8335c
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc6b95d3a731b56ea970cb41bb1e418384ef761e8c3995c3ff3dc4d6d44ff221
+size 516108
diff --git a/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.bvh b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.bvh
new file mode 100644
index 0000000..ba3762c
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f1d559dd6a89ba3bca10da79a9ba9fad42957869142c6b0571037493536d056
+size 1391071
diff --git a/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.bvh b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.bvh
new file mode 100644
index 0000000..68a8de2
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f0a9d3f2458294d0644d164d9be1c8ee20f7a62949d28a417e32388b8a5c964
+size 1633871
diff --git a/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.bvh b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.bvh
new file mode 100644
index 0000000..d25e6fd
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3818877d62da85e21f4e87eefb707deb41c432cf1acfa961240f5457f6141081
+size 1633704
diff --git a/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.bvh b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.bvh
new file mode 100644
index 0000000..82cc3a5
--- /dev/null
+++ b/assets/motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a53411f725891508af99e5e3e4176b1b279d35d30ca0c59dc163b03224b017f7
+size 1833169
diff --git a/assets/motions/soma/locomotion/idle/crouch_idle_001__A529.bvh b/assets/motions/soma/locomotion/idle/crouch_idle_001__A529.bvh
new file mode 100644
index 0000000..73956bd
--- /dev/null
+++ b/assets/motions/soma/locomotion/idle/crouch_idle_001__A529.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1c7ad4237ea40d54ca3658e441a46bfe614852d2154089efd667f9448858b660
+size 1733948
diff --git a/assets/motions/soma/locomotion/idle/idle_loop_001__A268.bvh b/assets/motions/soma/locomotion/idle/idle_loop_001__A268.bvh
new file mode 100644
index 0000000..0a91751
--- /dev/null
+++ b/assets/motions/soma/locomotion/idle/idle_loop_001__A268.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:defaa54c9eaa060f4c091868b86e6840ba4201edb6dcb89f7c496e997892ff80
+size 2710513
diff --git a/assets/motions/soma/locomotion/idle/legs_relax_002__A407.bvh b/assets/motions/soma/locomotion/idle/legs_relax_002__A407.bvh
new file mode 100644
index 0000000..3e0fed3
--- /dev/null
+++ b/assets/motions/soma/locomotion/idle/legs_relax_002__A407.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1fea14a5b427c1a434b20cd291e339dc86af7d7a95ce5773ba5bb6d331dd215e
+size 2864654
diff --git a/assets/motions/soma/locomotion/idle/neutral_looking_around_R_001__A542.bvh b/assets/motions/soma/locomotion/idle/neutral_looking_around_R_001__A542.bvh
new file mode 100644
index 0000000..83032dd
--- /dev/null
+++ b/assets/motions/soma/locomotion/idle/neutral_looking_around_R_001__A542.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0793dc27fc145c14b3a4ccbc9f2b5c95124cba903403aba329884f54c0fcd0f3
+size 2568791
diff --git a/assets/motions/soma/locomotion/idle/warm_up_neck_001__A359.bvh b/assets/motions/soma/locomotion/idle/warm_up_neck_001__A359.bvh
new file mode 100644
index 0000000..d740439
--- /dev/null
+++ b/assets/motions/soma/locomotion/idle/warm_up_neck_001__A359.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cf436bcf201a993c15d284f2651f7be47836e57cfb6c8db5059820235da63929
+size 8017352
diff --git a/assets/motions/soma/sitting/sit_on_chair_loop.bvh b/assets/motions/soma/sitting/sit_on_chair_loop.bvh
new file mode 100644
index 0000000..bbcc467
--- /dev/null
+++ b/assets/motions/soma/sitting/sit_on_chair_loop.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7fb7c39c9c7a89a51a4c22979d43289855d50fdd6cee5c08063a993e066f24c5
+size 1304791
diff --git a/assets/motions/soma/sitting/sit_on_chair_start_R_001__A047.bvh b/assets/motions/soma/sitting/sit_on_chair_start_R_001__A047.bvh
new file mode 100644
index 0000000..c169a5f
--- /dev/null
+++ b/assets/motions/soma/sitting/sit_on_chair_start_R_001__A047.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c7833fb129622564e04b4cce6c3c4cec917aaab5792b2b52ac396fdb2868fa2c
+size 2248065
diff --git a/assets/motions/soma/sitting/sit_on_chair_stop_R_001__A047.bvh b/assets/motions/soma/sitting/sit_on_chair_stop_R_001__A047.bvh
new file mode 100644
index 0000000..35646f1
--- /dev/null
+++ b/assets/motions/soma/sitting/sit_on_chair_stop_R_001__A047.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:30c34de41c680dd531a0a3dec0c5438dd655f3d63b9897597fd7b2d072ec6572
+size 1525805
diff --git a/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.bvh b/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.bvh
new file mode 100644
index 0000000..6e1001e
--- /dev/null
+++ b/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a55f4daa8b974b46663f58006d09cafa6656fc4a61fb27facd8f38438a94634
+size 1895332
diff --git a/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.bvh b/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.bvh
new file mode 100644
index 0000000..c34857c
--- /dev/null
+++ b/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37910baa14baa2107bcf374b8c70ca8fb2afbe46358b9bbd5e84d04d5cd042ad
+size 1888343
diff --git a/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.bvh b/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.bvh
new file mode 100644
index 0000000..0858e8f
--- /dev/null
+++ b/assets/motions/soma/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f27edaf169be89a25ff417a13e0a5e353ea816e0b738623af1f242579b24076
+size 2200303
diff --git a/assets/motions/soma/variations/angry_gun_walk_ff_loop_090_R_001__A393.bvh b/assets/motions/soma/variations/angry_gun_walk_ff_loop_090_R_001__A393.bvh
new file mode 100644
index 0000000..82f90d7
--- /dev/null
+++ b/assets/motions/soma/variations/angry_gun_walk_ff_loop_090_R_001__A393.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a9667f4d45e1f28e17320ee535bd0697e302ba2e41b44a21cce2427c5c8b968
+size 824397
diff --git a/assets/motions/soma/variations/combat_quickstep_ff_idle_180_R_002__A365.bvh b/assets/motions/soma/variations/combat_quickstep_ff_idle_180_R_002__A365.bvh
new file mode 100644
index 0000000..f95217e
--- /dev/null
+++ b/assets/motions/soma/variations/combat_quickstep_ff_idle_180_R_002__A365.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5e175607b1aad62a779b03fbfff7e37320a763529147d6e5b5d3aae3ff7138fa
+size 2241123
diff --git a/assets/motions/soma/variations/dance_vouge_vogue_sequence_180_R_002__A316.bvh b/assets/motions/soma/variations/dance_vouge_vogue_sequence_180_R_002__A316.bvh
new file mode 100644
index 0000000..3fa93d0
--- /dev/null
+++ b/assets/motions/soma/variations/dance_vouge_vogue_sequence_180_R_002__A316.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3eb042573216e5b01e32fd8e3e7c8fbc5ea0adad0c79170ac66e63f28039a34d
+size 1769220
diff --git a/assets/motions/soma/variations/dancecards1_AB_injured_L_leg_001__A005.bvh b/assets/motions/soma/variations/dancecards1_AB_injured_L_leg_001__A005.bvh
new file mode 100644
index 0000000..b7c1c60
--- /dev/null
+++ b/assets/motions/soma/variations/dancecards1_AB_injured_L_leg_001__A005.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:78678529a78e1b1288df3491e0d5506162520a98b6f6c997d2b104c61fbba14b
+size 32144465
diff --git a/assets/motions/soma/variations/injured_L_leg_grab_walk_ff_180_002__A549.bvh b/assets/motions/soma/variations/injured_L_leg_grab_walk_ff_180_002__A549.bvh
new file mode 100644
index 0000000..e267ac7
--- /dev/null
+++ b/assets/motions/soma/variations/injured_L_leg_grab_walk_ff_180_002__A549.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:581531db85a822a2dc3f52f3809783d76901cf168ac1b852ff284d01c5928470
+size 6077672
diff --git a/assets/motions/soma/variations/injured_torso_grab_walk_ff_180_001__A549.bvh b/assets/motions/soma/variations/injured_torso_grab_walk_ff_180_001__A549.bvh
new file mode 100644
index 0000000..47f6a68
--- /dev/null
+++ b/assets/motions/soma/variations/injured_torso_grab_walk_ff_180_001__A549.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:835405d588c5122a8c7dda5c96535419e62373081eab7cc19cd552839fb178ea
+size 7128875
diff --git a/assets/motions/soma/variations/skipping_R_002__A360.bvh b/assets/motions/soma/variations/skipping_R_002__A360.bvh
new file mode 100644
index 0000000..0df1191
--- /dev/null
+++ b/assets/motions/soma/variations/skipping_R_002__A360.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a20fcb9d92a27972dd31c23d6fac02bb1943608ec3c288ea0c7b7e82add9dada
+size 2884518
diff --git a/assets/motions/soma/variations/zombie_walk_180_R_003__A330.bvh b/assets/motions/soma/variations/zombie_walk_180_R_003__A330.bvh
new file mode 100644
index 0000000..c3ca33e
--- /dev/null
+++ b/assets/motions/soma/variations/zombie_walk_180_R_003__A330.bvh
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57871838f6dc3446fbfe3dc79f944ca970890ba72a171e038e3952a637d749e8
+size 4307610
diff --git a/assets/motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.csv b/assets/motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.csv
new file mode 100644
index 0000000..c1be6c2
--- /dev/null
+++ b/assets/motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ac8bd9863f2d8cc1169eb9ea2ca7ad85725f46440f669062cc7d64637207423
+size 274260
diff --git a/assets/motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.csv b/assets/motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.csv
new file mode 100644
index 0000000..248ece1
--- /dev/null
+++ b/assets/motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dfe2aa617dd3700ccc0ce04726d74eccf908690af0a19822109fd726990829bc
+size 462363
diff --git a/assets/motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv
new file mode 100644
index 0000000..a25e372
--- /dev/null
+++ b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d41da73bad909e976ba90ded038e18532992ce473b02931d0c07da1ca1f3fe5d
+size 248255
diff --git a/assets/motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv
new file mode 100644
index 0000000..92f9328
--- /dev/null
+++ b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abba2ef6c4184ead6a4ec3f5b2d60605de7ce1d2125500264092c1d4c44b905a
+size 236218
diff --git a/assets/motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv
new file mode 100644
index 0000000..cb25e1d
--- /dev/null
+++ b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0c8b3339fd5b4d8c3662befeb2d4e9d1c75341ea2dfdf91bd00336f7590e9074
+size 226867
diff --git a/assets/motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv
new file mode 100644
index 0000000..704cc40
--- /dev/null
+++ b/assets/motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f696fcca512713f0d9ab36dfe4fcfa46139240a815d486c081d883898f99c37
+size 232790
diff --git a/assets/motions/unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv b/assets/motions/unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv
new file mode 100644
index 0000000..1674284
--- /dev/null
+++ b/assets/motions/unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f49c3e4e46fd170d80f98422ea4eee3c808cb83739b2b587d7026c5a5ce59862
+size 231175
diff --git a/assets/motions/unitree_g1/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.csv b/assets/motions/unitree_g1/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.csv
new file mode 100644
index 0000000..5fd42f8
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_1d_linear/Neutral_walk_forward_002__A057.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:45fb2407adffee1cd7cca30adae662368f7f63361688fc8e14737f0787fe0565
+size 447511
diff --git a/assets/motions/unitree_g1/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.csv b/assets/motions/unitree_g1/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.csv
new file mode 100644
index 0000000..0473b7f
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2c203a9814c503989cbedfbd3dc92dd01256bcc2ac1351f708d2bb9e7ec491e8
+size 270580
diff --git a/assets/motions/unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv b/assets/motions/unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv
new file mode 100644
index 0000000..b80d29b
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9931f72eabf4b6948bfa386ec5bd9229b49c86c3573da2c3febc3387f3cc32de
+size 554533
diff --git a/assets/motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A326.csv b/assets/motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A326.csv
new file mode 100644
index 0000000..5365cb5
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A326.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1f6aed181181378ffacb79b7698a4e706b07a0b4328c5186d70e5ba6bac49f91
+size 97252
diff --git a/assets/motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A331.csv b/assets/motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A331.csv
new file mode 100644
index 0000000..2f81dba
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A331.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1284d2588648dd56b2a410057d9a98d5ae2154d2fed2ecc4faff18a7013a1bd3
+size 92466
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.csv
new file mode 100644
index 0000000..660b137
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:697c028cd81a7bc778996eac4f217ea1ef00fe4f90db81a3e9149531a42fce15
+size 71967
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.csv
new file mode 100644
index 0000000..b51b878
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e23920b8939168c10be4559dda0b7f8e6d55e5217e1c09415dcaed5a153eaebb
+size 71596
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.csv
new file mode 100644
index 0000000..0d4eb1e
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fbaf0c6e4f8dea435736709f633ea64b3a8c79b7313dc07ac69f4baed8e0ac23
+size 89007
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.csv
new file mode 100644
index 0000000..a5c7767
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f993c628974a3cab0ff099d1829939ad66ddf71d39b698bba8dba260066033a9
+size 240375
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.csv
new file mode 100644
index 0000000..fd66790
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08de28c4ed6deae20b9c6ce77cf8291ea91a84cf75cfa4e0de7c538aec7bdcd2
+size 283591
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.csv
new file mode 100644
index 0000000..6ea5874
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ae6a178dff90f9d77ac502781f30cc9110f911c0470b6f52a4b7d0f4f2b67768
+size 282304
diff --git a/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.csv b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.csv
new file mode 100644
index 0000000..205c20a
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:045b74c14c9adb5bed5d5fa04ee52a4df43d6376834885097fffe000d3e63ff2
+size 318295
diff --git a/assets/motions/unitree_g1/locomotion/idle/crouch_idle_001__A529.csv b/assets/motions/unitree_g1/locomotion/idle/crouch_idle_001__A529.csv
new file mode 100644
index 0000000..ccc5f77
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/idle/crouch_idle_001__A529.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:03c787220c647e54d0629d63bf068932ef1198ab2d6cc94ffa012c64dfcd7803
+size 303404
diff --git a/assets/motions/unitree_g1/locomotion/idle/idle_loop_001__A268.csv b/assets/motions/unitree_g1/locomotion/idle/idle_loop_001__A268.csv
new file mode 100644
index 0000000..c10ea28
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/idle/idle_loop_001__A268.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3579da426d322c342fe6ec91a08239b33e4d2a2826caad71f7f854971b68a003
+size 478862
diff --git a/assets/motions/unitree_g1/locomotion/idle/legs_relax_002__A407.csv b/assets/motions/unitree_g1/locomotion/idle/legs_relax_002__A407.csv
new file mode 100644
index 0000000..4a7c2d6
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/idle/legs_relax_002__A407.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:60fefbf8cb4ee7e62bc86aff429ad8339592b91272015ec527280c717e4a2ee4
+size 503025
diff --git a/assets/motions/unitree_g1/locomotion/idle/neutral_looking_around_R_001__A542.csv b/assets/motions/unitree_g1/locomotion/idle/neutral_looking_around_R_001__A542.csv
new file mode 100644
index 0000000..57f8ce2
--- /dev/null
+++ b/assets/motions/unitree_g1/locomotion/idle/neutral_looking_around_R_001__A542.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ade4f2259440d72f88c76c73919235190666d4aa3306b322c798778e75fbaeb
+size 447803
diff --git a/assets/motions/unitree_g1/sitting/sit_on_chair_loop.csv b/assets/motions/unitree_g1/sitting/sit_on_chair_loop.csv
new file mode 100644
index 0000000..79ddb91
--- /dev/null
+++ b/assets/motions/unitree_g1/sitting/sit_on_chair_loop.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3dda499982b42772094ff1f36a2bb3e3355f0ec53a1f3c1bd22087072d551bc
+size 226276
diff --git a/assets/motions/unitree_g1/sitting/sit_on_chair_start_R_001__A047.csv b/assets/motions/unitree_g1/sitting/sit_on_chair_start_R_001__A047.csv
new file mode 100644
index 0000000..42a8657
--- /dev/null
+++ b/assets/motions/unitree_g1/sitting/sit_on_chair_start_R_001__A047.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e1aece97a8a1aa5c99e0d51ddcfb802f5496c7c277138851a00ad84b4aaef198
+size 391726
diff --git a/assets/motions/unitree_g1/sitting/sit_on_chair_stop_R_001__A047.csv b/assets/motions/unitree_g1/sitting/sit_on_chair_stop_R_001__A047.csv
new file mode 100644
index 0000000..54c4502
--- /dev/null
+++ b/assets/motions/unitree_g1/sitting/sit_on_chair_stop_R_001__A047.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9e8a1c3108312dc675ebed5db6ee0bb48b4e9da17187e7c4561fa3ca0f98c9e4
+size 266131
diff --git a/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.csv b/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.csv
new file mode 100644
index 0000000..6a815de
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c9e8a50774dc8aa573fe7a15568b3b5a4b19c054964ccab2af0151122475a073
+size 329149
diff --git a/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.csv b/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.csv
new file mode 100644
index 0000000..3454baf
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_090_R_001__A365_M.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6b782622a631f94a37a52a90fd725e0295568b5d13d97bd5c92ab9fe97cc6a4e
+size 330190
diff --git a/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.csv b/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.csv
new file mode 100644
index 0000000..669c8cf
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/angry_combat_quickstep_ff_idle_360_R_001__A365.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4dce5dfc44f761cb917c1406a50db5795f3b4da968606dd9c9f129f43a80ab83
+size 381273
diff --git a/assets/motions/unitree_g1/variations/angry_gun_walk_ff_loop_090_R_001__A393.csv b/assets/motions/unitree_g1/variations/angry_gun_walk_ff_loop_090_R_001__A393.csv
new file mode 100644
index 0000000..dff717a
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/angry_gun_walk_ff_loop_090_R_001__A393.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5e3dbf523c1e5797194b2537def1625826f14a57dc1081173aa2928a7e07a3cd
+size 142083
diff --git a/assets/motions/unitree_g1/variations/combat_quickstep_ff_idle_180_R_002__A365.csv b/assets/motions/unitree_g1/variations/combat_quickstep_ff_idle_180_R_002__A365.csv
new file mode 100644
index 0000000..25a5a41
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/combat_quickstep_ff_idle_180_R_002__A365.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7e55a3dae40b87c079c19e468c4380aa28c9368a59b05fe88f1fe64a95ee632b
+size 388621
diff --git a/assets/motions/unitree_g1/variations/dance_vouge_vogue_sequence_180_R_002__A316.csv b/assets/motions/unitree_g1/variations/dance_vouge_vogue_sequence_180_R_002__A316.csv
new file mode 100644
index 0000000..23b3794
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/dance_vouge_vogue_sequence_180_R_002__A316.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2b28a3271ac199ad71d9b3aed230c172fe1ac5fb55d748b6d6ab86c007fd5c1c
+size 307690
diff --git a/assets/motions/unitree_g1/variations/dancecards1_AB_injured_L_leg_001__A005.csv b/assets/motions/unitree_g1/variations/dancecards1_AB_injured_L_leg_001__A005.csv
new file mode 100644
index 0000000..0085a44
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/dancecards1_AB_injured_L_leg_001__A005.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:55484adc3f2d4686e4e59c956b8538639a4a235c930232f62afb0a6a08965631
+size 5613110
diff --git a/assets/motions/unitree_g1/variations/injured_L_leg_grab_walk_ff_180_002__A549.csv b/assets/motions/unitree_g1/variations/injured_L_leg_grab_walk_ff_180_002__A549.csv
new file mode 100644
index 0000000..51fff1b
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/injured_L_leg_grab_walk_ff_180_002__A549.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a9b2ece0214be5242aec98ccc2535fa23967b112d32b0cab70115d09e830ec0
+size 1056521
diff --git a/assets/motions/unitree_g1/variations/injured_torso_grab_walk_ff_180_001__A549.csv b/assets/motions/unitree_g1/variations/injured_torso_grab_walk_ff_180_001__A549.csv
new file mode 100644
index 0000000..d312033
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/injured_torso_grab_walk_ff_180_001__A549.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:67ddbf27a3a6abade1e01163ff7fdb5d0a8f0420f1d1d24b7a50651d2023e1fa
+size 1237111
diff --git a/assets/motions/unitree_g1/variations/skipping_R_002__A360.csv b/assets/motions/unitree_g1/variations/skipping_R_002__A360.csv
new file mode 100644
index 0000000..392d3f5
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/skipping_R_002__A360.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18d5b6e6a7f0b653a20bab17f47990cce24f4e8038a076c288deddd79e371328
+size 499112
diff --git a/assets/motions/unitree_g1/variations/zombie_walk_180_R_003__A330.csv b/assets/motions/unitree_g1/variations/zombie_walk_180_R_003__A330.csv
new file mode 100644
index 0000000..be43010
--- /dev/null
+++ b/assets/motions/unitree_g1/variations/zombie_walk_180_R_003__A330.csv
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ddfa1a70b6216b0e1d489bcc364e0c61d06ff7f87bea035823f988096157aacd
+size 747370
diff --git a/assets/scenes/g1_gym.scene.json b/assets/scenes/g1_gym.scene.json
new file mode 100644
index 0000000..432f01e
--- /dev/null
+++ b/assets/scenes/g1_gym.scene.json
@@ -0,0 +1,319 @@
+{
+ "format": "motionbricks.scene",
+ "schema_version": 1,
+ "name": "g1_gym",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_item_id": 6,
+ "camera": {
+ "pos": [
+ 1.3158558838255157,
+ 4.088007802471593,
+ 3.0661328607754847
+ ],
+ "pivot": [
+ 1.7942775493069874,
+ 5.148268467176856,
+ 2.4349806209749962
+ ],
+ "pitch": -28.484203830036215,
+ "yaw": 65.71366455442579,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "character_start": {
+ "id": 1,
+ "transform": {
+ "translation": [
+ -6.281189441680908,
+ 3.140594720840454,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ]
+ },
+ "smart_primitives": [
+ {
+ "id": 2,
+ "name": "SmallJumpSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 3.140594720840454,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.707064688205719,
+ 0.7071489095687866
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99317932128906
+ ],
+ "reference": "../smart_primitives/unitree_g1/jump_0_5m.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.20000000298023224,
+ 0.5529412031173706,
+ 1.0
+ ],
+ "behavior": "VelocityMatchingSequenceBehavior"
+ },
+ {
+ "id": 5,
+ "name": "MidJumpSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 3.140594720840454,
+ 6.281189441680908,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7070855498313904,
+ 0.7071279883384705
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.9965591430664
+ ],
+ "reference": "../smart_primitives/unitree_g1/jump_0_75m.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.20000000298023224,
+ 0.5529412031173706,
+ 1.0
+ ],
+ "behavior": "VelocityMatchingSequenceBehavior"
+ },
+ {
+ "id": 10,
+ "name": "SitSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 3.140594720840454,
+ -6.281189441680908,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "reference": "../smart_primitives/unitree_g1/sit.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.48819881677627563,
+ 1.0,
+ 0.19999998807907104
+ ],
+ "behavior": "SittingBehavior"
+ },
+ {
+ "id": 12,
+ "name": "AvoidanceSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 3.140594720840454,
+ 12.562378883361816,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99999237060547
+ ],
+ "reference": "../smart_primitives/unitree_g1/avoidance.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.26708072423934937,
+ 0.6176074147224426,
+ 1.0
+ ],
+ "behavior": "VelocityMatchingSequenceBehavior"
+ }
+ ],
+ "solid_cubes": [
+ {
+ "id": 6,
+ "name": "Wall",
+ "parent_id": 5,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.3086724877357483
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7070855498313904,
+ 0.7071279883384705
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.9965591430664
+ ],
+ "dimensions": {
+ "width": 0.18000000715255737,
+ "depth": 1.5700000524520874,
+ "height": 0.6673763990402222
+ },
+ "color": [
+ 1.0,
+ 0.9914740920066833,
+ 0.31366461515426636
+ ]
+ },
+ {
+ "id": 9,
+ "name": "Box",
+ "parent_id": 2,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.15702974796295166
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.707064688205719,
+ 0.7071489095687866
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99317932128906
+ ],
+ "dimensions": {
+ "width": 0.4710892268454714,
+ "depth": 0.4710892268454714,
+ "height": 0.4710892268454714
+ },
+ "color": [
+ 0.45098039507865906,
+ 0.7019608020782471,
+ 0.47058823704719543
+ ]
+ },
+ {
+ "id": 11,
+ "name": "Seat",
+ "parent_id": 10,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.15229403972625732
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "dimensions": {
+ "width": 0.31405947676389623,
+ "depth": 0.31405947676389623,
+ "height": 0.31405947676389623
+ },
+ "color": [
+ 0.9299988150596619,
+ 0.4068322777748108,
+ 1.0
+ ]
+ },
+ {
+ "id": 13,
+ "name": "Bar",
+ "parent_id": 12,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 1.5310397148132324
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "dimensions": {
+ "width": 0.39257434010505676,
+ "depth": 0.39257434010505676,
+ "height": 0.7851486802101135
+ },
+ "color": [
+ 0.44999998807907104,
+ 0.5928571224212646,
+ 0.699999988079071
+ ]
+ }
+ ]
+}
diff --git a/assets/scenes/soma_gym.scene.json b/assets/scenes/soma_gym.scene.json
new file mode 100644
index 0000000..b35e634
--- /dev/null
+++ b/assets/scenes/soma_gym.scene.json
@@ -0,0 +1,319 @@
+{
+ "format": "motionbricks.scene",
+ "schema_version": 1,
+ "name": "soma_gym",
+ "rig": "soma",
+ "editor": {
+ "selected_item_id": 12,
+ "camera": {
+ "pos": [
+ -28.627241134643555,
+ 4.96978759765625,
+ 23.381349563598633
+ ],
+ "pivot": [
+ 1.6044341125431316,
+ -0.7897408613204506,
+ -2.4278371523663935
+ ],
+ "pitch": -39.98420383003624,
+ "yaw": -10.786335445574181,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "character_start": {
+ "id": 1,
+ "transform": {
+ "translation": [
+ -8.0,
+ 4.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ]
+ },
+ "smart_primitives": [
+ {
+ "id": 2,
+ "name": "SmallJumpSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 4.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.707064688205719,
+ 0.7071489095687866
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99317932128906
+ ],
+ "reference": "../smart_primitives/soma/jump_0_5m.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.20000000298023224,
+ 0.5529412031173706,
+ 1.0
+ ],
+ "behavior": "VelocityMatchingSequenceBehavior"
+ },
+ {
+ "id": 5,
+ "name": "MidJumpSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 4.0,
+ 8.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7070855498313904,
+ 0.7071279883384705
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.9965591430664
+ ],
+ "reference": "../smart_primitives/soma/jump_0_75m.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.20000000298023224,
+ 0.5529412031173706,
+ 1.0
+ ],
+ "behavior": "VelocityMatchingSequenceBehavior"
+ },
+ {
+ "id": 10,
+ "name": "SitSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 4.0,
+ -8.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "reference": "../smart_primitives/soma/sit.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.48819881677627563,
+ 1.0,
+ 0.19999998807907104
+ ],
+ "behavior": "SittingBehavior"
+ },
+ {
+ "id": 12,
+ "name": "AvoidanceSP",
+ "parent_id": null,
+ "transform": {
+ "translation": [
+ 4.0,
+ 16.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99999237060547
+ ],
+ "reference": "../smart_primitives/soma/avoidance.smart_primitive.json",
+ "visibility": {
+ "target_poses": true,
+ "interaction_boxes": true
+ },
+ "target_pose_color": [
+ 0.26708072423934937,
+ 0.6176074147224426,
+ 1.0
+ ],
+ "behavior": "VelocityMatchingSequenceBehavior"
+ }
+ ],
+ "solid_cubes": [
+ {
+ "id": 6,
+ "name": "Wall",
+ "parent_id": 5,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.39313891530036926
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7070855498313904,
+ 0.7071279883384705
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.9965591430664
+ ],
+ "dimensions": {
+ "width": 0.25,
+ "depth": 2.0,
+ "height": 0.8500000238418579
+ },
+ "color": [
+ 1.0,
+ 0.9914740920066833,
+ 0.31366461515426636
+ ]
+ },
+ {
+ "id": 9,
+ "name": "Box",
+ "parent_id": 2,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.20000003278255463
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.707064688205719,
+ 0.7071489095687866
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99317932128906
+ ],
+ "dimensions": {
+ "width": 0.6000000238418579,
+ "depth": 0.6000000238418579,
+ "height": 0.6000000238418579
+ },
+ "color": [
+ 0.45098039507865906,
+ 0.7019608020782471,
+ 0.47058823704719543
+ ]
+ },
+ {
+ "id": 11,
+ "name": "Seat",
+ "parent_id": 10,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.19396841526031494
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "dimensions": {
+ "width": 0.4000000059604645,
+ "depth": 0.4000000059604645,
+ "height": 0.4000000059604645
+ },
+ "color": [
+ 0.9299988150596619,
+ 0.4068322777748108,
+ 1.0
+ ]
+ },
+ {
+ "id": 13,
+ "name": "Bar",
+ "parent_id": 12,
+ "transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 1.9499998092651367
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "dimensions": {
+ "width": 0.5,
+ "depth": 0.5,
+ "height": 1.0
+ },
+ "color": [
+ 0.44999998807907104,
+ 0.5928571224212646,
+ 0.699999988079071
+ ]
+ }
+ ]
+}
diff --git a/assets/smart_primitives/soma/avoidance.smart_primitive.json b/assets/smart_primitives/soma/avoidance.smart_primitive.json
new file mode 100644
index 0000000..931171d
--- /dev/null
+++ b/assets/smart_primitives/soma/avoidance.smart_primitive.json
@@ -0,0 +1,502 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "avoidance",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 7,
+ "camera": {
+ "pos": [
+ 4.002395735496871,
+ -1.488658206748426,
+ 2.9335192329831097
+ ],
+ "pivot": [
+ -1.5875720204187522,
+ 0.5664674496174894,
+ -0.564981759956591
+ ],
+ "pitch": -30.5,
+ "yaw": -200.1999999999998,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 15,
+ "name": "Walk",
+ "node_ids": [
+ 5,
+ 6
+ ],
+ "pivot_node_id": 11
+ },
+ {
+ "id": 17,
+ "name": "Jog",
+ "node_ids": [
+ 7,
+ 8
+ ],
+ "pivot_node_id": 11
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Box",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 1.958346962928772
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 9,
+ "width": 0.5,
+ "depth": 0.5,
+ "height": 1.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.6372032761573792
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 11,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ -0.08050525188446045,
+ 0.09527856111526489,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ true,
+ true,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 16,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "rotation_then_translation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.20000000298023224,
+ "line_max_offset": 0.20000000298023224,
+ "rotation_axis": "z",
+ "rotation_constraint": "unconstrained",
+ "cone_half_angle_degrees": 45.0,
+ "cone_side": "forward",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 3,
+ "name": "Variation 0",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 5,
+ "name": "Entry0",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ -1.1901543140411377,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.3007056415081024,
+ -0.9537169933319092
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -34.99998092651367
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh",
+ "sample_time_seconds": 1.659999966621399,
+ "frame_index": 199,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.6297270655632019
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 6,
+ "name": "Action0",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 12,
+ "clip": "../../motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh",
+ "sample_time_seconds": 2.7300000190734863,
+ "frame_index": 328,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.6052522659301758,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Variation 1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 7,
+ "name": "Entry1",
+ "local_transform": {
+ "translation": [
+ -0.33566316962242126,
+ -3.085617780685425,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.9238795638084412,
+ 0.3826833963394165
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 135.00001525878906
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 13,
+ "clip": "../../motions/soma/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.bvh",
+ "sample_time_seconds": 1.840000033378601,
+ "frame_index": 221,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.8532445430755615,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 8,
+ "name": "Action1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 14,
+ "clip": "../../motions/soma/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.bvh",
+ "sample_time_seconds": 2.2899999618530273,
+ "frame_index": 275,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.8900744915008545,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/jump_0_5m.smart_primitive.json b/assets/smart_primitives/soma/jump_0_5m.smart_primitive.json
new file mode 100644
index 0000000..7c7fb41
--- /dev/null
+++ b/assets/smart_primitives/soma/jump_0_5m.smart_primitive.json
@@ -0,0 +1,626 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "jump_0_5m",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 3,
+ "camera": {
+ "pos": [
+ 4.5502753257751465,
+ -1.8978675603866577,
+ 3.2185232639312744
+ ],
+ "pivot": [
+ 1.2873131120352563,
+ 0.6858590854008708,
+ -0.11935067678243705
+ ],
+ "pitch": -39.372808780797484,
+ "yaw": 153.23098019458195,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 20,
+ "name": "Jump",
+ "node_ids": [
+ 14,
+ 15,
+ 16
+ ],
+ "pivot_node_id": 3
+ },
+ {
+ "id": 28,
+ "name": "Jump2",
+ "node_ids": [
+ 22,
+ 23,
+ 24
+ ],
+ "pivot_node_id": 3
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Box",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.25200000405311584
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 7,
+ "width": 0.699999988079071,
+ "depth": 0.699999988079071,
+ "height": 0.5,
+ "color": [
+ 0.6054707169532776,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 29,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "rotation_then_translation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.30000001192092896,
+ "line_max_offset": 0.30000001192092896,
+ "rotation_axis": "z",
+ "rotation_constraint": "unconstrained",
+ "cone_half_angle_degrees": 45.0,
+ "cone_side": "forward",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 13,
+ "name": "Variation1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 14,
+ "name": "Entry1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ -3.7251834869384766,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 8.901414548745379e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.98980712890625
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 17,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh",
+ "sample_time_seconds": 1.5916666666666666,
+ "frame_index": 191,
+ "playback_mode": "frames",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.7006987929344177,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 15,
+ "name": "Action1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 18,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh",
+ "sample_time_seconds": 2.1600000858306885,
+ "frame_index": 259,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.41935068368911743,
+ 0.15002314746379852,
+ 0.9472049474716187
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 16,
+ "name": "Exit1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 19,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_5m_R_002__A437.bvh",
+ "sample_time_seconds": 2.700000047683716,
+ "frame_index": 324,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.4283851385116577,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 21,
+ "name": "Variation2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 22,
+ "name": "Entry2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ -4.106581687927246,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 8.901414548745379e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.98980712890625
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 25,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh",
+ "sample_time_seconds": 2.5999999046325684,
+ "frame_index": 312,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.8760449886322021
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 23,
+ "name": "Action2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 26,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh",
+ "sample_time_seconds": 3.25,
+ "frame_index": 390,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.7384169697761536,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 24,
+ "name": "Exit2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 27,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_5m_R_001__A415.bvh",
+ "sample_time_seconds": 3.869999885559082,
+ "frame_index": 464,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.5244588255882263,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/jump_0_75m.smart_primitive.json b/assets/smart_primitives/soma/jump_0_75m.smart_primitive.json
new file mode 100644
index 0000000..fa0c76e
--- /dev/null
+++ b/assets/smart_primitives/soma/jump_0_75m.smart_primitive.json
@@ -0,0 +1,912 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "jump_0_75m",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 24,
+ "camera": {
+ "pos": [
+ 6.002796173095703,
+ 0.027540231123566628,
+ 1.9570131301879883
+ ],
+ "pivot": [
+ -5.531268823882381,
+ 2.793956549027582,
+ 1.837178194444564
+ ],
+ "pitch": -13.300000000000022,
+ "yaw": 166.5125297418001,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 11,
+ "name": "OneHandedJump0",
+ "node_ids": [
+ 4,
+ 5,
+ 6
+ ],
+ "pivot_node_id": 30
+ },
+ {
+ "id": 20,
+ "name": "OneHandedJump1",
+ "node_ids": [
+ 14,
+ 15,
+ 16
+ ],
+ "pivot_node_id": 30
+ },
+ {
+ "id": 28,
+ "name": "NoHandsJump",
+ "node_ids": [
+ 22,
+ 23,
+ 24
+ ],
+ "pivot_node_id": 3
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Box",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.4119263291358948
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 7,
+ "width": 2.0,
+ "depth": 0.30000001192092896,
+ "height": 0.8199999928474426,
+ "color": [
+ 0.6054707169532776,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 29,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "translation_then_rotation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.75,
+ "line_max_offset": 0.75,
+ "rotation_axis": "z",
+ "rotation_constraint": "cone",
+ "cone_half_angle_degrees": 60.0,
+ "cone_side": "both",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 21,
+ "name": "Variation3",
+ "local_transform": {
+ "translation": [
+ -1.4151737559586763e-09,
+ 0.0034429009538143873,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 22,
+ "name": "Entry3",
+ "local_transform": {
+ "translation": [
+ -0.0242862980812788,
+ -3.898669958114624,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 8.914057980291545e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.9897918701172
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 26,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh",
+ "sample_time_seconds": 1.4199999570846558,
+ "frame_index": 170,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.785788893699646
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 23,
+ "name": "Action3",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 27,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh",
+ "sample_time_seconds": 2.049999952316284,
+ "frame_index": 246,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 2,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.44947439432144165,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 24,
+ "name": "Exit3",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 2.8312206268310547e-06,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 25,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.bvh",
+ "sample_time_seconds": 3.109999895095825,
+ "frame_index": 373,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 6,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.7767921686172485,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 30,
+ "name": "Pivot2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": false,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 31,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "translation_then_rotation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.8999999761581421,
+ "line_max_offset": 0.8999999761581421,
+ "rotation_axis": "z",
+ "rotation_constraint": "cone",
+ "cone_half_angle_degrees": 30.0,
+ "cone_side": "both",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 12,
+ "name": "Variation1",
+ "local_transform": {
+ "translation": [
+ 0.3389788269996643,
+ -0.02500012144446373,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -1.909211277961731e-06,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 4,
+ "name": "Entry1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ -3.1444568634033203,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 8.901414548745379e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.98980712890625
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh",
+ "sample_time_seconds": 1.1833333333333333,
+ "frame_index": 142,
+ "playback_mode": "frames",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.7557507753372192
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 5,
+ "name": "Action1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh",
+ "sample_time_seconds": 2.009999990463257,
+ "frame_index": 241,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 2,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 1,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.9447892904281616,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 6,
+ "name": "Exit1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_75m_R_102__A416.bvh",
+ "sample_time_seconds": 2.740000009536743,
+ "frame_index": 329,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 6,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.737289309501648
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 13,
+ "name": "Variation2",
+ "local_transform": {
+ "translation": [
+ 0.25991976261138916,
+ -0.019999999552965164,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 14,
+ "name": "Entry2",
+ "local_transform": {
+ "translation": [
+ -1.1920928955078125e-07,
+ -3.4864559173583984,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 8.918272942537442e-05,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.010219587944447994
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 17,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh",
+ "sample_time_seconds": 1.7699999809265137,
+ "frame_index": 212,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.7006987929344177,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 15,
+ "name": "Action2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -1.7881390590446244e-07,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 18,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh",
+ "sample_time_seconds": 2.4100000858306885,
+ "frame_index": 289,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 2,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 1,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.41935068368911743,
+ 0.15002314746379852,
+ 0.9472049474716187
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 16,
+ "name": "Exit2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.5646217434550636e-05,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.001792924478650093
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 19,
+ "clip": "../../motions/soma/jump/jump_over_obstacle_0_75m_R_103__A416.bvh",
+ "sample_time_seconds": 3.0199999809265137,
+ "frame_index": 362,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 6,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.4283851385116577,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/locomotion_bs1_linear.smart_primitive.json b/assets/smart_primitives/soma/locomotion_bs1_linear.smart_primitive.json
new file mode 100644
index 0000000..18bf1a8
--- /dev/null
+++ b/assets/smart_primitives/soma/locomotion_bs1_linear.smart_primitive.json
@@ -0,0 +1,303 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_bs1_linear",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 5,
+ "camera": {
+ "pos": [
+ 2.092105387617055,
+ 3.0575950398492036,
+ 1.6459016029607894
+ ],
+ "pivot": [
+ -5.484649049047109,
+ -4.243556889127463,
+ -0.21634670639079312
+ ],
+ "pitch": -10.03655632473439,
+ "yaw": -136.0612412724968,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ -0.7071068286895752
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 270.00000762939453
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 6,
+ "clip": "../../motions/soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh",
+ "sample_time_seconds": 0.6200000047683716,
+ "frame_index": 74,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.8336944580078125,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Walk",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ -0.7071068286895752
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 270.00000762939453
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh",
+ "sample_time_seconds": 2.55,
+ "frame_index": 306,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.5838937759399414,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Jog",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ -0.7071068286895752
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 270.00000762939453
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/soma/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.bvh",
+ "sample_time_seconds": 1.9083333333333334,
+ "frame_index": 229,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.39405497908592224,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 5,
+ "name": "Run",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ -0.7071068286895752
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 270.00000762939453
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A326.bvh",
+ "sample_time_seconds": 0.4083333333333333,
+ "frame_index": 49,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.8557117581367493
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/locomotion_bs2_directional.smart_primitive.json b/assets/smart_primitives/soma/locomotion_bs2_directional.smart_primitive.json
new file mode 100644
index 0000000..280552a
--- /dev/null
+++ b/assets/smart_primitives/soma/locomotion_bs2_directional.smart_primitive.json
@@ -0,0 +1,363 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_bs2_directional",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 4,
+ "camera": {
+ "pos": [
+ 3.6425366401672363,
+ -4.171139717102051,
+ 2.9785895347595215
+ ],
+ "pivot": [
+ -3.772688876822216,
+ 9.07386333833163,
+ -3.7524537535790987
+ ],
+ "pitch": -23.913999046412506,
+ "yaw": 119.24231958680377,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/soma/locomotion/idle/idle_loop_001__A268.bvh",
+ "sample_time_seconds": 0.0,
+ "frame_index": 0,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.7873680591583252,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Forward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ -0.7071068286895752
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 270.00000762939453
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/soma/locomotion/bs_1d_linear/run_loop_180_R_003__A331.bvh",
+ "sample_time_seconds": 0.475,
+ "frame_index": 57,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.6103634238243103
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Backward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.bvh",
+ "sample_time_seconds": 0.8916666666666667,
+ "frame_index": 107,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.690045177936554,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 5,
+ "name": "Left",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 3.919656592188403e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.99551391601562
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.bvh",
+ "sample_time_seconds": 0.5083333333333333,
+ "frame_index": 61,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.9389123916625977
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Right",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 8.901414548745379e-05,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.010200269520282745
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 11,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.bvh",
+ "sample_time_seconds": 0.5083333333333333,
+ "frame_index": 61,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.37814974784851074
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/locomotion_bs2_directional_crouch.smart_primitive.json b/assets/smart_primitives/soma/locomotion_bs2_directional_crouch.smart_primitive.json
new file mode 100644
index 0000000..20b7a06
--- /dev/null
+++ b/assets/smart_primitives/soma/locomotion_bs2_directional_crouch.smart_primitive.json
@@ -0,0 +1,363 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_bs2_directional_crouch",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 6,
+ "camera": {
+ "pos": [
+ 4.231281280517578,
+ -0.8333141207695007,
+ 3.113799810409546
+ ],
+ "pivot": [
+ -9.199428457286295,
+ 2.3333025855984717,
+ -3.2719604842863514
+ ],
+ "pitch": -24.82934435391735,
+ "yaw": 166.7108980693576,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/soma/locomotion/idle/crouch_idle_001__A529.bvh",
+ "sample_time_seconds": 0.0,
+ "frame_index": 0,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.6641780138015747,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Forward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ -0.7071068286895752
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 270.00000762939453
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.bvh",
+ "sample_time_seconds": 1.55,
+ "frame_index": 186,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.8562536239624023,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Backward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.bvh",
+ "sample_time_seconds": 2.575,
+ "frame_index": 309,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.631855845451355,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 5,
+ "name": "Left",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 6.532761290145572e-06,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0007485992973670363
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.bvh",
+ "sample_time_seconds": 2.1,
+ "frame_index": 252,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.5850575566291809
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Right",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 2.0188339476590045e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.9976806640625
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 11,
+ "clip": "../../motions/soma/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.bvh",
+ "sample_time_seconds": 2.1,
+ "frame_index": 252,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.5451549887657166,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/locomotion_style_variations_bs1_linear.smart_primitive.json b/assets/smart_primitives/soma/locomotion_style_variations_bs1_linear.smart_primitive.json
new file mode 100644
index 0000000..52095c5
--- /dev/null
+++ b/assets/smart_primitives/soma/locomotion_style_variations_bs1_linear.smart_primitive.json
@@ -0,0 +1,483 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_style_variations_bs1_linear",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 6,
+ "camera": {
+ "pos": [
+ 1.0404224395751953,
+ 4.580280303955078,
+ 1.7830442190170288
+ ],
+ "pivot": [
+ -4.069553886384255,
+ -5.721371933551332,
+ -0.037505216816704046
+ ],
+ "pitch": -9.036557461407048,
+ "yaw": -121.7612385254833,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 15,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 16,
+ "clip": "../../motions/soma/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.bvh",
+ "sample_time_seconds": 0.6200000047683716,
+ "frame_index": 74,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.6086490750312805,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 2,
+ "name": "Skipping",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 3,
+ "clip": "../../motions/soma/variations/skipping_R_002__A360.bvh",
+ "sample_time_seconds": 3.191666666666667,
+ "frame_index": 383,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.845718264579773,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Vogue",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 5,
+ "clip": "../../motions/soma/variations/dance_vouge_vogue_sequence_180_R_002__A316.bvh",
+ "sample_time_seconds": 3.130000114440918,
+ "frame_index": 376,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.919316828250885,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Injured Torso",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/soma/variations/injured_torso_grab_walk_ff_180_001__A549.bvh",
+ "sample_time_seconds": 2.441666666666667,
+ "frame_index": 293,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.3363354802131653,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 9,
+ "name": "Injured Leg",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/soma/variations/injured_L_leg_grab_walk_ff_180_002__A549.bvh",
+ "sample_time_seconds": 5.550000190734863,
+ "frame_index": 666,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.5150863528251648
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 11,
+ "name": "Zombie",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 12,
+ "clip": "../../motions/soma/variations/zombie_walk_180_R_003__A330.bvh",
+ "sample_time_seconds": 6.039999961853027,
+ "frame_index": 725,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.8349377512931824
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 13,
+ "name": "Combat",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 14,
+ "clip": "../../motions/soma/variations/combat_quickstep_ff_idle_180_R_002__A365.bvh",
+ "sample_time_seconds": 3.6600000858306885,
+ "frame_index": 439,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.9720497131347656,
+ 0.24754062294960022,
+ 0.2745410203933716
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/soma/sit.smart_primitive.json b/assets/smart_primitives/soma/sit.smart_primitive.json
new file mode 100644
index 0000000..ea9ff28
--- /dev/null
+++ b/assets/smart_primitives/soma/sit.smart_primitive.json
@@ -0,0 +1,368 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "sit",
+ "rig": "soma",
+ "editor": {
+ "selected_node_id": 3,
+ "camera": {
+ "pos": [
+ 2.154998779296875,
+ 0.14840075373649597,
+ 0.48017385601997375
+ ],
+ "pivot": [
+ -2.669849499793556,
+ -0.24827196389527656,
+ 0.2434084729020971
+ ],
+ "pitch": -2.799929021090284,
+ "yaw": -175.29992380546045,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 9,
+ "name": "Sit",
+ "node_ids": [
+ 12,
+ 5
+ ],
+ "pivot_node_id": 3
+ },
+ {
+ "id": 10,
+ "name": "Stand",
+ "node_ids": [
+ 6
+ ],
+ "pivot_node_id": null
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "InteractionBox",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.20079441368579865
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 4,
+ "width": 0.30000001192092896,
+ "depth": 0.30000001192092896,
+ "height": 0.4000000059604645,
+ "color": [
+ 0.8164187073707581,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 11,
+ "motion_direction": [
+ -0.9803921565960564,
+ -0.19705638605468664,
+ 0.0
+ ],
+ "operation_order": "translation_then_rotation",
+ "translation_axis": "none",
+ "translation_constraint": "unconstrained",
+ "line_min_offset": -0.5,
+ "line_max_offset": 0.5,
+ "rotation_axis": "z",
+ "rotation_constraint": "unconstrained",
+ "cone_half_angle_degrees": 45.0,
+ "cone_side": "forward",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 5,
+ "name": "Sit",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/soma/sitting/sit_on_chair_loop.bvh",
+ "sample_time_seconds": 0.0,
+ "frame_index": 0,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 1,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.5966143608093262,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 6,
+ "name": "ToStand",
+ "local_transform": {
+ "translation": [
+ -0.015297919511795044,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/soma/sitting/sit_on_chair_stop_R_001__A047.bvh",
+ "sample_time_seconds": 1.9900000095367432,
+ "frame_index": 239,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": true,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.41747766733169556
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 12,
+ "name": "ToSit",
+ "local_transform": {
+ "translation": [
+ 0.020531408488750458,
+ -0.4032357633113861,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 13,
+ "clip": "../../motions/soma/sitting/sit_on_chair_start_R_001__A047.bvh",
+ "sample_time_seconds": 1.850000023841858,
+ "frame_index": 222,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 10,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.9285714030265808,
+ 0.4556344449520111,
+ 0.808134138584137
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/avoidance.smart_primitive.json b/assets/smart_primitives/unitree_g1/avoidance.smart_primitive.json
new file mode 100644
index 0000000..c821834
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/avoidance.smart_primitive.json
@@ -0,0 +1,502 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "avoidance",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 7,
+ "camera": {
+ "pos": [
+ 3.142475729403955,
+ -1.168818026312481,
+ 2.303248754147673
+ ],
+ "pivot": [
+ -1.2464800765702868,
+ 0.4447611704491608,
+ -0.44359468317270456
+ ],
+ "pitch": -30.5,
+ "yaw": -200.1999999999998,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 15,
+ "name": "Walk",
+ "node_ids": [
+ 5,
+ 6
+ ],
+ "pivot_node_id": 11
+ },
+ {
+ "id": 17,
+ "name": "Jog",
+ "node_ids": [
+ 7,
+ 8
+ ],
+ "pivot_node_id": 11
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Box",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 1.5375934839248657
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 9,
+ "width": 0.39257434010505676,
+ "depth": 0.39257434010505676,
+ "height": 0.7851486802101135,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.6372032761573792
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 11,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ -0.06320859491825104,
+ 0.07480783760547638,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ true,
+ true,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 16,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "rotation_then_translation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.15702973838194811,
+ "line_max_offset": 0.15702973838194811,
+ "rotation_axis": "z",
+ "rotation_constraint": "unconstrained",
+ "cone_half_angle_degrees": 45.0,
+ "cone_side": "forward",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 3,
+ "name": "Variation 0",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 5,
+ "name": "Entry0",
+ "local_transform": {
+ "translation": [
+ -0.000589326024055481,
+ -0.9261252284049988,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.3007056713104248,
+ -0.9537169933319092
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -34.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.csv",
+ "sample_time_seconds": 1.659999966621399,
+ "frame_index": 199,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.6297270655632019
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 6,
+ "name": "Action0",
+ "local_transform": {
+ "translation": [
+ -0.0070029497146606445,
+ 0.007735729217529297,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 12,
+ "clip": "../../motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.csv",
+ "sample_time_seconds": 2.7300000190734863,
+ "frame_index": 328,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.6052522659301758,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Variation 1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 7,
+ "name": "Entry1",
+ "local_transform": {
+ "translation": [
+ -0.2620046138763428,
+ -2.390129327774048,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.9238795042037964,
+ 0.3826833963394165
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 135.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 13,
+ "clip": "../../motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.csv",
+ "sample_time_seconds": 1.840000033378601,
+ "frame_index": 221,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.8532445430755615,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 8,
+ "name": "Action1",
+ "local_transform": {
+ "translation": [
+ 0.007033944129943848,
+ -0.008751392364501953,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999999403953552
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 14,
+ "clip": "../../motions/unitree_g1/avoidance/neutral_avoid_obstacle_bend_down_jog_ff_180_R_001__A544.csv",
+ "sample_time_seconds": 2.2899999618530273,
+ "frame_index": 275,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.8900744915008545,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/jump_0_5m.smart_primitive.json b/assets/smart_primitives/unitree_g1/jump_0_5m.smart_primitive.json
new file mode 100644
index 0000000..eef1803
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/jump_0_5m.smart_primitive.json
@@ -0,0 +1,626 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "jump_0_5m",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 3,
+ "camera": {
+ "pos": [
+ 3.5726426666250006,
+ -1.4901082102511722,
+ 2.527019292901187
+ ],
+ "pivot": [
+ 1.0107321909316556,
+ 0.5385013557126093,
+ -0.09370802635791428
+ ],
+ "pitch": -39.372808780797484,
+ "yaw": 153.23098019458195,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 20,
+ "name": "Jump",
+ "node_ids": [
+ 14,
+ 15,
+ 16
+ ],
+ "pivot_node_id": 3
+ },
+ {
+ "id": 28,
+ "name": "Jump2",
+ "node_ids": [
+ 22,
+ 23,
+ 24
+ ],
+ "pivot_node_id": 3
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Box",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.19785746932029724
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 7,
+ "width": 0.5496040667873778,
+ "depth": 0.5496040667873778,
+ "height": 0.39257434010505676,
+ "color": [
+ 0.6054707169532776,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 29,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "rotation_then_translation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.2355446134227357,
+ "line_max_offset": 0.2355446134227357,
+ "rotation_axis": "z",
+ "rotation_constraint": "unconstrained",
+ "cone_half_angle_degrees": 45.0,
+ "cone_side": "forward",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 13,
+ "name": "Variation1",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 14,
+ "name": "Entry1",
+ "local_transform": {
+ "translation": [
+ -0.0023678233847022057,
+ -2.9048373699188232,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.9999999403953552,
+ 8.89897346496582e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.98980712890625
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 17,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv",
+ "sample_time_seconds": 1.5916666666666666,
+ "frame_index": 191,
+ "playback_mode": "frames",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.7006987929344177,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 15,
+ "name": "Action1",
+ "local_transform": {
+ "translation": [
+ -0.0029376449529081583,
+ -0.0367279052734375,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999998807907104
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 18,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv",
+ "sample_time_seconds": 2.1600000858306885,
+ "frame_index": 259,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.41935068368911743,
+ 0.15002314746379852,
+ 0.9472049474716187
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 16,
+ "name": "Exit1",
+ "local_transform": {
+ "translation": [
+ -0.0036697499454021454,
+ -0.021448850631713867,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999997615814209
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 19,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_002__A437.csv",
+ "sample_time_seconds": 2.700000047683716,
+ "frame_index": 324,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.4283851385116577,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 21,
+ "name": "Variation2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 22,
+ "name": "Entry2",
+ "local_transform": {
+ "translation": [
+ -0.0002806121192406863,
+ -3.1954925060272217,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.9999999403953552,
+ 8.89897346496582e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.98980712890625
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 25,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv",
+ "sample_time_seconds": 2.5999999046325684,
+ "frame_index": 312,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.8760449886322021
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 23,
+ "name": "Action2",
+ "local_transform": {
+ "translation": [
+ -0.008173716254532337,
+ -0.040985107421875,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999998807907104
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 26,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv",
+ "sample_time_seconds": 3.25,
+ "frame_index": 390,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 1,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.7384169697761536,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 24,
+ "name": "Exit2",
+ "local_transform": {
+ "translation": [
+ 0.010094057768583298,
+ -0.012274980545043945,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999997615814209
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 27,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_5m_R_001__A415.csv",
+ "sample_time_seconds": 3.869999885559082,
+ "frame_index": 464,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.5244588255882263,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/jump_0_75m.smart_primitive.json b/assets/smart_primitives/unitree_g1/jump_0_75m.smart_primitive.json
new file mode 100644
index 0000000..2491cac
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/jump_0_75m.smart_primitive.json
@@ -0,0 +1,912 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "jump_0_75m",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 24,
+ "camera": {
+ "pos": [
+ 4.7130874928764115,
+ 0.02162317611934983,
+ 1.536546276320962
+ ],
+ "pivot": [
+ -4.3428684169585985,
+ 2.1936712970334096,
+ 1.4424580346789488
+ ],
+ "pitch": -13.300000000000022,
+ "yaw": 166.5125297418001,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 11,
+ "name": "OneHandedJump0",
+ "node_ids": [
+ 4,
+ 5,
+ 6
+ ],
+ "pivot_node_id": 30
+ },
+ {
+ "id": 20,
+ "name": "OneHandedJump1",
+ "node_ids": [
+ 14,
+ 15,
+ 16
+ ],
+ "pivot_node_id": 30
+ },
+ {
+ "id": 28,
+ "name": "NoHandsJump",
+ "node_ids": [
+ 22,
+ 23,
+ 24
+ ],
+ "pivot_node_id": 3
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Box",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.3234234154224396
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 7,
+ "width": 1.570297360420227,
+ "depth": 0.2355446134227357,
+ "height": 0.6438219121564721,
+ "color": [
+ 0.6054707169532776,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 29,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "translation_then_rotation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.5888615101575851,
+ "line_max_offset": 0.5888615101575851,
+ "rotation_axis": "z",
+ "rotation_constraint": "cone",
+ "cone_half_angle_degrees": 60.0,
+ "cone_side": "both",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 21,
+ "name": "Variation3",
+ "local_transform": {
+ "translation": [
+ -1.111121861185893e-09,
+ 0.0027031891513615847,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 22,
+ "name": "Entry3",
+ "local_transform": {
+ "translation": [
+ -0.016362115740776062,
+ -3.0385072231292725,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 8.913874626159668e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.9897918701172
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 26,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv",
+ "sample_time_seconds": 1.4199999570846558,
+ "frame_index": 170,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.785788893699646
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 23,
+ "name": "Action3",
+ "local_transform": {
+ "translation": [
+ 0.007215376943349838,
+ -0.032424211502075195,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 27,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv",
+ "sample_time_seconds": 2.049999952316284,
+ "frame_index": 246,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 2,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.44947439432144165,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 24,
+ "name": "Exit3",
+ "local_transform": {
+ "translation": [
+ -0.008737797848880291,
+ -0.04325723648071289,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 2.86102294921875e-06,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 25,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_no_hand_0_75m_R_103__A416.csv",
+ "sample_time_seconds": 3.109999895095825,
+ "frame_index": 373,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 6,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.7767921686172485,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 30,
+ "name": "Pivot2",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": false,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 31,
+ "motion_direction": [
+ 0.0,
+ 1.0,
+ 0.0
+ ],
+ "operation_order": "translation_then_rotation",
+ "translation_axis": "x",
+ "translation_constraint": "line_projection",
+ "line_min_offset": -0.7066337934696989,
+ "line_max_offset": 0.7066337934696989,
+ "rotation_axis": "z",
+ "rotation_constraint": "cone",
+ "cone_half_angle_degrees": 30.0,
+ "cone_side": "both",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 12,
+ "name": "Variation1",
+ "local_transform": {
+ "translation": [
+ 0.26614877581596375,
+ -0.01962881162762642,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -1.909211277961731e-06,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 4,
+ "name": "Entry1",
+ "local_transform": {
+ "translation": [
+ -0.0029178261756896973,
+ -2.4588727951049805,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.0,
+ 8.907727897167206e-05
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 179.9897918701172
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv",
+ "sample_time_seconds": 1.1833333333333333,
+ "frame_index": 142,
+ "playback_mode": "frames",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.7557507753372192
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 5,
+ "name": "Action1",
+ "local_transform": {
+ "translation": [
+ -0.008723199367523193,
+ -0.03536701202392578,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv",
+ "sample_time_seconds": 2.009999990463257,
+ "frame_index": 241,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 2,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.9447892904281616,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 6,
+ "name": "Exit1",
+ "local_transform": {
+ "translation": [
+ 0.010073423385620117,
+ -0.02449774742126465,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_102__A416.csv",
+ "sample_time_seconds": 2.740000009536743,
+ "frame_index": 329,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 6,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.737289309501648
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": 13,
+ "name": "Variation2",
+ "local_transform": {
+ "translation": [
+ 0.2040756642818451,
+ -0.015702974051237106,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 14,
+ "name": "Entry2",
+ "local_transform": {
+ "translation": [
+ -0.0011776089668273926,
+ -2.7208616733551025,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 8.919835090637207e-05,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.010221377946436405
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 17,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv",
+ "sample_time_seconds": 1.7699999809265137,
+ "frame_index": 212,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 8,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.7006987929344177,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 15,
+ "name": "Action2",
+ "local_transform": {
+ "translation": [
+ 0.012049421668052673,
+ 0.03623390197753906,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -1.7881393432617188e-07,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 18,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv",
+ "sample_time_seconds": 2.4100000858306885,
+ "frame_index": 289,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 2,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.41935068368911743,
+ 0.15002314746379852,
+ 0.9472049474716187
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 16,
+ "name": "Exit2",
+ "local_transform": {
+ "translation": [
+ -0.010956212878227234,
+ 0.0253903865814209,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 1.561640965519473e-05,
+ 1.0000001192092896
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0017895089695230126
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 19,
+ "clip": "../../motions/unitree_g1/jump/jump_over_obstacle_0_75m_R_103__A416.csv",
+ "sample_time_seconds": 3.0199999809265137,
+ "frame_index": 362,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 6,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.4283851385116577,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/locomotion_bs1_linear.smart_primitive.json b/assets/smart_primitives/unitree_g1/locomotion_bs1_linear.smart_primitive.json
new file mode 100644
index 0000000..48a135c
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/locomotion_bs1_linear.smart_primitive.json
@@ -0,0 +1,283 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_bs1_linear",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 1,
+ "camera": {
+ "pos": [
+ 2.092105387617055,
+ 3.0575950398492036,
+ 1.6459016029607894
+ ],
+ "pivot": [
+ -5.484649049047109,
+ -4.243556889127463,
+ -0.21634670639079312
+ ],
+ "pitch": -10.03655632473439,
+ "yaw": -136.0612412724968,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.7017017602920532,
+ 0.7124708294868469
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 3,
+ "clip": "../../motions/unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv",
+ "sample_time_seconds": 0.6200000047683716,
+ "frame_index": 74,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.8336944580078125,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Walk",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.6930667161941528,
+ 0.7208732962608337
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 5,
+ "clip": "../../motions/unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv",
+ "sample_time_seconds": 2.55,
+ "frame_index": 306,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.5838937759399414,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Jog",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.7110520005226135,
+ 0.7031393647193909
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/unitree_g1/locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534.csv",
+ "sample_time_seconds": 1.9083333333333334,
+ "frame_index": 229,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.39405497908592224,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 8,
+ "name": "Run",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.747146487236023,
+ 0.6646592617034912
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A326.csv",
+ "sample_time_seconds": 0.4083333333333333,
+ "frame_index": 49,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.8557117581367493
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/locomotion_bs2_directional.smart_primitive.json b/assets/smart_primitives/unitree_g1/locomotion_bs2_directional.smart_primitive.json
new file mode 100644
index 0000000..37e8e69
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/locomotion_bs2_directional.smart_primitive.json
@@ -0,0 +1,339 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_bs2_directional",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 1,
+ "camera": {
+ "pos": [
+ 3.6425366401672363,
+ -4.171139717102051,
+ 2.9785895347595215
+ ],
+ "pivot": [
+ -3.772688876822216,
+ 9.07386333833163,
+ -3.7524537535790987
+ ],
+ "pitch": -23.913999046412506,
+ "yaw": 119.24231958680377,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.6814023852348328,
+ 0.7319090366363525
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 3,
+ "clip": "../../motions/unitree_g1/locomotion/idle/idle_loop_001__A268.csv",
+ "sample_time_seconds": 0.0,
+ "frame_index": 0,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.7873680591583252,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Forward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.7245281934738159,
+ 0.6892452836036682
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 5,
+ "clip": "../../motions/unitree_g1/locomotion/bs_1d_linear/run_loop_180_R_003__A331.csv",
+ "sample_time_seconds": 0.475,
+ "frame_index": 57,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.6103634238243103
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Backward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.6850272417068481,
+ 0.7285174131393433
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_360_R_very_fast_001__A454.csv",
+ "sample_time_seconds": 0.8916666666666667,
+ "frame_index": 107,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.690045177936554,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 8,
+ "name": "Left",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.9946755170822144,
+ 0.10305613279342651
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455_M.csv",
+ "sample_time_seconds": 0.5083333333333333,
+ "frame_index": 61,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.9389123916625977
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 10,
+ "name": "Right",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.10302495211362839,
+ 0.994678795337677
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 11,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional/jog_ff_loop_270_R_very_fast_002__A455.csv",
+ "sample_time_seconds": 0.5083333333333333,
+ "frame_index": 61,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.37814974784851074
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/locomotion_bs2_directional_crouch.smart_primitive.json b/assets/smart_primitives/unitree_g1/locomotion_bs2_directional_crouch.smart_primitive.json
new file mode 100644
index 0000000..dd3095e
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/locomotion_bs2_directional_crouch.smart_primitive.json
@@ -0,0 +1,339 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_bs2_directional_crouch",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 1,
+ "camera": {
+ "pos": [
+ 4.231281280517578,
+ -0.8333141207695007,
+ 3.113799810409546
+ ],
+ "pivot": [
+ -9.199428457286295,
+ 2.3333025855984717,
+ -3.2719604842863514
+ ],
+ "pitch": -24.82934435391735,
+ "yaw": 166.7108980693576,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7142350077629089,
+ 0.6999059319496155
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 3,
+ "clip": "../../motions/unitree_g1/locomotion/idle/crouch_idle_001__A529.csv",
+ "sample_time_seconds": 0.0,
+ "frame_index": 0,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.6641780138015747,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Forward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.6464789509773254,
+ 0.762931764125824
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 5,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_180_R_001__A196.csv",
+ "sample_time_seconds": 1.55,
+ "frame_index": 186,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.8562536239624023,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Backward",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7927959561347961,
+ 0.6094871163368225
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_360_R_001__A196.csv",
+ "sample_time_seconds": 2.575,
+ "frame_index": 309,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.631855845451355,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 8,
+ "name": "Left",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.005561133846640587,
+ 0.9999845623970032
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 9,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196_M.csv",
+ "sample_time_seconds": 2.1,
+ "frame_index": 252,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.5850575566291809
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 10,
+ "name": "Right",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ -0.0,
+ -0.0,
+ -0.9999844431877136,
+ 0.005578178912401199
+ ]
+ },
+ "euler_degrees": null,
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 11,
+ "clip": "../../motions/unitree_g1/locomotion/bs_2d_directional_crouch/crouch_ff_loop_270_R_002__A196.csv",
+ "sample_time_seconds": 2.1,
+ "frame_index": 252,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": true,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.5451549887657166,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/locomotion_style_variations_bs1_linear.smart_primitive.json b/assets/smart_primitives/unitree_g1/locomotion_style_variations_bs1_linear.smart_primitive.json
new file mode 100644
index 0000000..f1c67b1
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/locomotion_style_variations_bs1_linear.smart_primitive.json
@@ -0,0 +1,483 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "locomotion_style_variations_bs1_linear",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 15,
+ "camera": {
+ "pos": [
+ 4.742900371551514,
+ 5.611968994140625,
+ 2.297426223754883
+ ],
+ "pivot": [
+ -5.484649049047109,
+ -4.243556889127463,
+ -0.21634670639079312
+ ],
+ "pitch": -10.036557461407051,
+ "yaw": -136.0612385254833,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 15,
+ "name": "Idle",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 16,
+ "clip": "../../motions/unitree_g1/locomotion/bs_1d_linear/neutral_walk_ff_180_R_002__A536_M.csv",
+ "sample_time_seconds": 0.6200000047683716,
+ "frame_index": 74,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.6086490750312805,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 2,
+ "name": "Skipping",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 3,
+ "clip": "../../motions/unitree_g1/variations/skipping_R_002__A360.csv",
+ "sample_time_seconds": 5.058333333333334,
+ "frame_index": 607,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.845718264579773,
+ 0.33250001072883606,
+ 0.949999988079071
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 4,
+ "name": "Vogue",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 5,
+ "clip": "../../motions/unitree_g1/variations/dance_vouge_vogue_sequence_180_R_002__A316.csv",
+ "sample_time_seconds": 3.130000114440918,
+ "frame_index": 376,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.919316828250885,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 6,
+ "name": "Injured Torso",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/unitree_g1/variations/injured_torso_grab_walk_ff_180_001__A549.csv",
+ "sample_time_seconds": 2.441666666666667,
+ "frame_index": 293,
+ "playback_mode": "frames",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.3363354802131653,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 9,
+ "name": "Injured Leg",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 10,
+ "clip": "../../motions/unitree_g1/variations/injured_L_leg_grab_walk_ff_180_002__A549.csv",
+ "sample_time_seconds": 5.550000190734863,
+ "frame_index": 666,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.949999988079071,
+ 0.33250001072883606,
+ 0.5150863528251648
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 11,
+ "name": "Zombie",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 12,
+ "clip": "../../motions/unitree_g1/variations/zombie_walk_180_R_003__A330.csv",
+ "sample_time_seconds": 6.039999961853027,
+ "frame_index": 725,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.8349377512931824
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 13,
+ "name": "Combat",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ -0.7071066498756409,
+ 0.7071066498756409
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ -89.99998474121094
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 14,
+ "clip": "../../motions/unitree_g1/variations/combat_quickstep_ff_idle_180_R_002__A365.csv",
+ "sample_time_seconds": 3.6600000858306885,
+ "frame_index": 439,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.9720497131347656,
+ 0.24754062294960022,
+ 0.2745410203933716
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/assets/smart_primitives/unitree_g1/sit.smart_primitive.json b/assets/smart_primitives/unitree_g1/sit.smart_primitive.json
new file mode 100644
index 0000000..448c71b
--- /dev/null
+++ b/assets/smart_primitives/unitree_g1/sit.smart_primitive.json
@@ -0,0 +1,368 @@
+{
+ "format": "motionbricks.smart_primitive.authoring",
+ "schema_version": 1,
+ "name": "sit",
+ "rig": "unitree_g1",
+ "editor": {
+ "selected_node_id": 3,
+ "camera": {
+ "pos": [
+ 1.6919944286346436,
+ 0.11651665717363358,
+ 0.3770078718662262
+ ],
+ "pivot": [
+ -2.0962288111225424,
+ -0.19493040478554935,
+ 0.19111184125104072
+ ],
+ "pitch": -2.799929021090284,
+ "yaw": -175.29992380546045,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0
+ }
+ },
+ "sequences": [
+ {
+ "id": 9,
+ "name": "Sit",
+ "node_ids": [
+ 12,
+ 5
+ ],
+ "pivot_node_id": 3
+ },
+ {
+ "id": 10,
+ "name": "Stand",
+ "node_ids": [
+ 6
+ ],
+ "pivot_node_id": null
+ }
+ ],
+ "root": {
+ "id": 1,
+ "name": "Root",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [],
+ "children": [
+ {
+ "id": 2,
+ "name": "InteractionBox",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.15765346586704254
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "interaction_box",
+ "id": 4,
+ "width": 0.2355446134227357,
+ "depth": 0.2355446134227357,
+ "height": 0.31405947676389623,
+ "color": [
+ 0.8164187073707581,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 3,
+ "name": "Pivot",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 1.0
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "pivot",
+ "id": 11,
+ "motion_direction": [
+ -0.9803921565960564,
+ -0.19705638605468664,
+ 0.0
+ ],
+ "operation_order": "translation_then_rotation",
+ "translation_axis": "none",
+ "translation_constraint": "unconstrained",
+ "line_min_offset": -0.39257434010505676,
+ "line_max_offset": 0.39257434010505676,
+ "rotation_axis": "z",
+ "rotation_constraint": "unconstrained",
+ "cone_half_angle_degrees": 45.0,
+ "cone_side": "forward",
+ "show_motion_direction": true,
+ "show_translation_constraint": true,
+ "show_rotation_constraint": true
+ }
+ ],
+ "children": [
+ {
+ "id": 5,
+ "name": "Sit",
+ "local_transform": {
+ "translation": [
+ 0.0,
+ -7.019776404604272e-08,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.7071067690849304,
+ 0.7071067690849304
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 89.99999237060547
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 7,
+ "clip": "../../motions/unitree_g1/sitting/sit_on_chair_loop.csv",
+ "sample_time_seconds": 0.0,
+ "frame_index": 0,
+ "playback_mode": "time",
+ "hips_constrained": true,
+ "num_poses_to_use": 1,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.5966143608093262,
+ 0.949999988079071,
+ 0.33250001072883606
+ ]
+ }
+ ],
+ "children": [
+ {
+ "id": 6,
+ "name": "ToStand",
+ "local_transform": {
+ "translation": [
+ -0.01179661974310875,
+ -0.002453973749652505,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999999403953552
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 8,
+ "clip": "../../motions/unitree_g1/sitting/sit_on_chair_stop_R_001__A047.csv",
+ "sample_time_seconds": 1.9900000095367432,
+ "frame_index": 239,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 0,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": true,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.33250001072883606,
+ 0.949999988079071,
+ 0.41747766733169556
+ ]
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": 12,
+ "name": "ToSit",
+ "local_transform": {
+ "translation": [
+ 0.01493589673191309,
+ -0.3132540285587311,
+ 0.0
+ ],
+ "rotation_xyzw": [
+ 0.0,
+ 0.0,
+ 0.0,
+ 0.9999999403953552
+ ]
+ },
+ "euler_degrees": [
+ 0.0,
+ 0.0,
+ 0.0
+ ],
+ "visible": true,
+ "translation_locks": [
+ false,
+ false,
+ false
+ ],
+ "rotation_locks": [
+ false,
+ false,
+ false
+ ],
+ "components": [
+ {
+ "type": "target_pose",
+ "id": 13,
+ "clip": "../../motions/unitree_g1/sitting/sit_on_chair_start_R_001__A047.csv",
+ "sample_time_seconds": 1.850000023841858,
+ "frame_index": 222,
+ "playback_mode": "time",
+ "hips_constrained": false,
+ "num_poses_to_use": 4,
+ "transition_early_by_frames": 10,
+ "min_tokens": 6,
+ "max_tokens": 14,
+ "ik_pin_mask": 0,
+ "show_mesh": true,
+ "show_skeletons": false,
+ "show_velocity": false,
+ "show_trajectory": false,
+ "trajectory_scale": 2.0,
+ "color": [
+ 0.9285714030265808,
+ 0.4556344449520111,
+ 0.808134138584137
+ ]
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/docs/examples/_rig.py b/docs/examples/_rig.py
new file mode 100644
index 0000000..7fa708f
--- /dev/null
+++ b/docs/examples/_rig.py
@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared setup for the examples: load a rig's skeleton, engine, and clip without a viewer.
+
+Only the motionbricks package is used here, so the code carries over to an application that
+does not use the demo runtime in app/.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import warp as wp
+
+from motionbricks.io.bvh import load_bvh
+from motionbricks.io.csv import load_csv
+from motionbricks.io.usd import load_skeleton_from_usd
+from motionbricks.io.utils import SOMA_SKELETON_PRIM_PATH, get_asset_file
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE, ModelRig
+from motionbricks.model.soma.contract import SOMA_N1_FP32_ONNX_PATH
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.model.unitree_g1.contract import UNITREE_G1_N1_FP32_ONNX_PATH
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+from motionbricks.utils.space_conversion_utils import FacingDirectionType, SpaceConverter
+
+ASSETS = Path(__file__).resolve().parents[2] / "assets" / "motions"
+WALK = "locomotion/bs_1d_linear/Neutral_walk_forward_002__A057"
+JOG = "locomotion/bs_1d_linear/neutral_jog_ff_180_R_001__A534"
+
+
+@dataclass
+class Rig:
+ """What an example needs from one rig.
+
+ Attributes:
+ engine: The engine. Use it as a context manager.
+ clip: The clip that the example samples poses from.
+ skeleton: The SOMA skeleton, or None for the Unitree G1.
+ reference_pose: A pose with the rig's layout.
+ model_to_runtime: Transform from the clip's source space to world space, which is Z up.
+ """
+
+ engine: MotionBricksSOMAEngine | MotionBricksUnitreeG1Engine
+ clip: object
+ skeleton: object
+ reference_pose: wp.array
+ model_to_runtime: wp.transform
+
+
+def load_rig(model: str, clip_name: str = WALK) -> Rig:
+ """Load a clip of the bundled locomotion set and create the engine for "soma" or "unitree_g1"."""
+ if ModelRig(model) is ModelRig.SOMA:
+ skeleton = load_skeleton_from_usd(
+ get_asset_file("human", "soma_base_skel_minimal_no_root.usd"), SOMA_SKELETON_PRIM_PATH,
+ )
+ clip = load_bvh(str(ASSETS / "soma" / f"{clip_name}.bvh"), skeleton)
+ # SOMA model space and BVH clips are Y up. World space is Z up.
+ to_runtime = SpaceConverter(FacingDirectionType.MUJOCO).convert_transform(wp.transform_identity())
+ engine = MotionBricksSOMAEngine(SOMA_N1_FP32_ONNX_PATH, model_to_runtime=to_runtime)
+ return Rig(engine, clip, skeleton, skeleton.reference_local_transforms, to_runtime)
+ clip = load_csv(ASSETS / "unitree_g1" / f"{clip_name}.csv", device=wp.get_device())
+ # G1 model space and CSV clips are already Z up.
+ engine = MotionBricksUnitreeG1Engine(UNITREE_G1_N1_FP32_ONNX_PATH)
+ reference = wp.zeros(36, dtype=wp.float32)
+ clip.sample(0.0, reference)
+ return Rig(engine, clip, None, reference, wp.transform_identity())
+
+
+def sample_window(rig: Rig, start_time: float, poses: wp.array, root_offset: wp.transform | None = None) -> None:
+ """Sample four clip poses at 30 Hz from start_time into poses, then move their roots by root_offset."""
+ root_offset = wp.mul(root_offset, rig.model_to_runtime) if root_offset is not None else rig.model_to_runtime
+ for index in range(MODEL_POSES_PER_TOKEN):
+ rig.clip.sample(
+ start_time + index / MODEL_SAMPLE_RATE, poses[index], root_offset=root_offset, stream=rig.engine.stream,
+ )
+
+
+def root_positions(poses: wp.array) -> np.ndarray:
+ """Return the root XYZ of each pose of either layout. Both start with the root position."""
+ return poses.numpy().reshape(poses.shape[0], -1)[:, :3]
diff --git a/docs/examples/generate_once.py b/docs/examples/generate_once.py
new file mode 100644
index 0000000..efc6651
--- /dev/null
+++ b/docs/examples/generate_once.py
@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generate motion between clip poses, then chain a second generation. No viewer, no apps.
+
+Each generation takes four context poses and one to four target poses. The first context and both
+targets come from one walk clip. The second generation reads its context from the last four poses
+of the first, which is the loop that makes continuous motion. Run it from the repository root:
+
+ uv run python docs/examples/generate_once.py
+ uv run python docs/examples/generate_once.py --model unitree_g1
+"""
+
+import argparse
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE
+
+from _rig import load_rig, sample_window
+
+# The context ends at this clip time. Each generation targets the clip poses at the next time.
+CONTEXT_END = 1.0
+TARGET_TIMES = (1.8, 3.4)
+
+
+def generate(model: str) -> list[np.ndarray]:
+ """Run both generations for "soma" or "unitree_g1". Return the valid poses of each, as arrays."""
+ wp.init()
+ wp.set_device("cuda:0")
+ rig = load_rig(model)
+ motions = []
+ # The first launch builds a TensorRT plan, which takes a few minutes. Later launches load it.
+ with rig.engine as engine, wp.ScopedStream(engine.stream):
+ skeleton_args = (rig.skeleton,) if rig.skeleton is not None else ()
+ context = engine.create_input(*skeleton_args)
+ target = engine.create_input(*skeleton_args)
+ output = engine.create_output(*skeleton_args)
+ context_poses = wp.empty_like(context.poses)
+ target_poses = wp.empty_like(context.poses)
+
+ # The context is the four poses that end at CONTEXT_END.
+ sample_window(rig, CONTEXT_END - (MODEL_POSES_PER_TOKEN - 1) / MODEL_SAMPLE_RATE, context_poses)
+ for target_time in TARGET_TIMES:
+ sample_window(rig, target_time, target_poses)
+ context.update_from_poses(context_poses, stream=engine.stream)
+ target.update_from_poses(target_poses, stream=engine.stream)
+ engine.generate_animation(context, target, output)
+ engine.synchronize()
+
+ # The output buffer has room for the longest result. Only num_frames frames are valid.
+ frames = output.num_frames
+ motions.append(output.poses[:frames].numpy())
+ root = output.root_transforms()[:frames, :3]
+ print(
+ f"generated {frames} frames ({frames / MODEL_SAMPLE_RATE:.2f} s), "
+ f"root from {root[0].round(2)} to {root[-1].round(2)}"
+ )
+
+ # Play the whole motion, so the last four poses are what the character showed.
+ # An application that moves on early keeps the last four poses it played instead.
+ context_poses = wp.clone(output.poses[frames - MODEL_POSES_PER_TOKEN:frames])
+ return motions
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("--model", choices=("soma", "unitree_g1"), default="soma")
+ generate(parser.parse_args().model)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/examples/locomotion_loop.py b/docs/examples/locomotion_loop.py
new file mode 100644
index 0000000..824abcc
--- /dev/null
+++ b/docs/examples/locomotion_loop.py
@@ -0,0 +1,135 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Move a character along a steered path with a generation loop. No viewer, no apps.
+
+This is the continuous locomotion loop of the Runtime API page, made complete. Each update plays
+the generated motion, records the pose it showed, and decides whether to generate again. The
+target poses are one set of jog poses, placed ahead of the character along the steering direction.
+The steering turns from +X to +Y, so the path bends left. Run it from the repository root:
+
+ uv run python docs/examples/locomotion_loop.py
+ uv run python docs/examples/locomotion_loop.py --model unitree_g1
+"""
+
+import argparse
+import math
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN
+from motionbricks.runtime.motion_player import GeneratedDOFMotionPlayer, GeneratedMotionPlayer
+from motionbricks.runtime.target_pose import (
+ TargetPoseInferenceParams,
+ adjust_target_dof_speed,
+ adjust_target_pose_speed,
+ place_target_dof,
+ place_target_poses,
+)
+
+from _rig import JOG, load_rig, root_positions, sample_window
+
+UPDATE_RATE = 60.0
+DURATION = 9.0
+# The jog poses that serve as the target. Any clip time in the jog works.
+TARGET_TIME = 1.8
+# The ground speed to move at, in m/s. The target poses are scaled to it. Each rig moves at about the
+# speed of its jog clip. A higher G1 speed makes its feet slide.
+DESIRED_SPEED = {"soma": 1.9, "unitree_g1": 1.45}
+# The target sits this many seconds of travel ahead of the character.
+LEAD_SECONDS = 1.0
+# The transition point, in frames before the end of each generation. The next generation takes over there.
+TRANSITION_EARLY_BY = 4
+# Generate again when the steering direction turns by more than this many degrees.
+TURN_THRESHOLD = 15.0
+# The steering direction. It holds +X, turns to +Y between these two times, then holds.
+TURN_START, TURN_END = 2.0, 4.0
+
+
+def steering(time: float) -> np.ndarray:
+ """Return the desired ground direction at a time. An application reads its controls here."""
+ blend = min(max((time - TURN_START) / (TURN_END - TURN_START), 0.0), 1.0)
+ angle = 0.5 * math.pi * blend
+ return np.array([math.cos(angle), math.sin(angle), 0.0], dtype=np.float32)
+
+
+def canonical_target(rig, model: str, poses: wp.array) -> None:
+ """Fill poses with the jog target at the origin, facing +X, at the model's desired speed.
+
+ The clip's own placement and heading are removed, so each generation can place the poses
+ wherever the character is heading.
+ """
+ sample_window(rig, TARGET_TIME, poses)
+ roots = root_positions(poses)
+ offset = roots[-1, :2] - roots[0, :2]
+ heading = math.atan2(offset[1], offset[0])
+ origin = wp.transform(wp.vec3(roots[0, 0], roots[0, 1], 0.0), wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), heading))
+ sample_window(rig, TARGET_TIME, poses, root_offset=wp.transform_inverse(origin))
+ adjust = adjust_target_pose_speed if rig.skeleton is not None else adjust_target_dof_speed
+ adjust(poses, DESIRED_SPEED[model], stream=rig.engine.stream)
+
+
+def run(model: str) -> list[np.ndarray]:
+ """Move "soma" or "unitree_g1" along the steered path. Return the pose shown at each update."""
+ wp.init()
+ wp.set_device("cuda:0")
+ rig = load_rig(model, JOG)
+ shown = []
+ with rig.engine as engine, wp.ScopedStream(engine.stream):
+ if rig.skeleton is not None:
+ player = GeneratedMotionPlayer(engine, rig.skeleton)
+ place = place_target_poses
+ else:
+ player = GeneratedDOFMotionPlayer(engine, rig.reference_pose)
+ place = place_target_dof
+
+ jog_poses = wp.empty((MODEL_POSES_PER_TOKEN, *rig.reference_pose.shape), dtype=rig.reference_pose.dtype)
+ canonical_target(rig, model, jog_poses)
+ target_poses = wp.empty_like(jog_poses)
+ settings = TargetPoseInferenceParams(transition_early_by_frames=TRANSITION_EARLY_BY, num_poses_to_use=4)
+
+ # Start at the origin in the jog pose, as if the character had held it.
+ current_pose = wp.clone(jog_poses[MODEL_POSES_PER_TOKEN - 1])
+ player.seed_history_from_pose(current_pose)
+ foot_contacts = wp.zeros(4, dtype=wp.float32)
+ generated_direction = None
+ generations = 0
+ delta_time = 1.0 / UPDATE_RATE
+
+ for step in range(round(DURATION * UPDATE_RATE)):
+ time = step * delta_time
+ direction = steering(time)
+ position = root_positions(current_pose.reshape((1, -1)))[0] * np.array([1.0, 1.0, 0.0])
+
+ turned = generated_direction is not None and math.degrees(
+ math.acos(min(1.0, float(direction @ generated_direction)))
+ ) > TURN_THRESHOLD
+ if generated_direction is None or turned or player.time_to_transition <= delta_time:
+ ground_position = position + direction * DESIRED_SPEED[model] * LEAD_SECONDS
+ place(wp.vec3(*ground_position), wp.vec3(*direction), jog_poses, target_poses, stream=engine.stream)
+ player.generate(target_poses, settings)
+ generated_direction = direction
+ generations += 1
+
+ player.sample(delta_time, current_pose, foot_contacts)
+ # Apply target pose IK, physics, or other changes to current_pose here.
+ player.record_pose(delta_time, current_pose)
+ shown.append(current_pose.numpy())
+
+ if step % round(UPDATE_RATE) == 0:
+ engine.synchronize()
+ print(f"t = {time:4.1f} s steering {direction[:2].round(2)} root {position[:2].round(2)}")
+ engine.synchronize()
+ print(f"{generations} generations in {DURATION:.0f} s")
+ return shown
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("--model", choices=("soma", "unitree_g1"), default="soma")
+ run(parser.parse_args().model)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/guided_tutorial.md b/docs/guided_tutorial.md
new file mode 100644
index 0000000..f1caba1
--- /dev/null
+++ b/docs/guided_tutorial.md
@@ -0,0 +1,628 @@
+# MotionBricks guided tutorial
+
+This tutorial introduces the core concepts of MotionBricks and applies them to a complete SOMA workflow. The exercises progress from a single generation to a fully interactive scene:
+
+1. **Fundamentals:** use the Inbetweener to rebuild a walking duck-under interaction from target poses.
+2. **Smart Primitive:** turn the same poses into a reusable, pose-based interaction.
+3. **Scene:** assemble several Smart Primitives into an interaction course.
+4. **Scene Preview:** play the result in real time and inspect how it works.
+
+All commands and file paths in this tutorial are relative to the repository root.
+
+![tutorial results](media/tutorial_final_results.gif)
+
+*Final result of the guided tutorial.*
+
+> **Unitree G1:** The same workflow applies to the Unitree G1. Choose **Unitree G1** in the **Character** selector. Use G1 CSV clips and G1 Smart Primitive documents instead of the SOMA ones.
+
+
+## High-level concepts
+
+### Motion generation between poses
+
+MotionBricks generates a transition from the character's recent motion to one or more target poses.
+
+![Four context poses in green, generated poses, and a target pose in blue](media/core_idea.gif)
+
+Each generation uses the following inputs:
+
+- **Four context poses:** the character's most recent motion. Together, they describe the current pose and the velocity with which the character enters the transition.
+- **One to four target poses:** the poses that the character must reach. A single target pose sets the posture, position, and facing where the character stops. A second pose adds velocity at the target. A third and fourth pose add acceleration and momentum, so the character keeps moving through the target.
+
+The model determines the duration of the transition. It generates the root trajectory and the body motion. It also generates the foot placement and the changes in momentum required to reach the target.
+
+The host application remains responsible for deciding **what should happen next**. MotionBricks determines **how the character moves from its current motion to that goal**.
+
+This tutorial uses four example apps. They show how to integrate MotionBricks. They are not a production toolset. The tutorial explains how the model works. It also shows where the model's inputs and outputs fit in an animation system. With that understanding, developers can integrate MotionBricks into their own engines, tools, and pipelines.
+
+### Key poses instead of transition clips
+
+Traditional clip-based systems require authored transitions between many combinations of states. These clips must be selected, synchronized, and blended. With MotionBricks, the state machine selects target poses and places them in the scene instead.
+
+![SOMA locomotion driven by context poses, target poses, and a blend space](media/locomotion_targets_soma.gif)
+*Context poses are shown in purple, current target poses in blue, and the live blend space result in green.*
+
+### Chaining generations
+
+A single generation is intentionally short. Continuous motion comes from a loop. The application generates a transition and plays it up to the transition point. It records each pose it shows. The last four played poses become the context poses of the next generation.
+
+![chaining animation generation](media/target_b_flow.png)
+
+This loop is what we mean by autoregressive. Each generation starts from the motion that the previous generation produced. The model never sees the whole animation at once. It only sees the last four played poses and the next target.
+
+This is the central integration pattern of both the Inbetweener and Scene Preview. Generated motion, locomotion changes, and transitions to or from clips can all contribute to the next context.
+
+## Part 1: Generate an animation in the Inbetweener
+
+The Inbetweener is the smallest complete example of the MotionBricks generation loop. It samples poses from clips and lets you place those poses in the view. It then generates motion through them in order.
+
+In this part, you will create the following sequence of poses:
+
+![target poses for avoidance](media/duck_under_flow.png)
+
+### Launch the Inbetweener
+
+Start the Inbetweener by running:
+
+```sh
+uv run python -m app.inbetweener_demo --model soma
+```
+
+The Newton viewer opens with the Inbetweener.
+
+![Inbetweener opened in the Newton viewer](media/tut_inbetweener_01_open.png)
+
+The interface has two main areas:
+
+- **View:** displays the character, the current poses, and the generated motion.
+- **Inbetweener window:** contains the **Character** selector, the **Target Poses** list, and the generation settings. Confirm that the **Character** selector shows **SOMA**.
+
+To navigate, place the pointer over the view and use the following controls:
+
+- **W**, **A**, **S**, and **D**, or the **arrow keys**, move the camera horizontally.
+- **Q** and **E** move the camera down and up.
+- **Middle mouse drag** orbits around the camera pivot.
+- **Shift + middle mouse drag** pans.
+- **Ctrl + middle mouse drag** moves toward or away from the camera pivot.
+- **Mouse wheel** moves toward or away from the camera pivot. **Ctrl + mouse wheel** changes the camera field of view.
+
+### Create and place the End target
+
+In the **Target Poses** list, click **Target 1** to select it and display its properties:
+
+![Target 1 selected with its properties](media/tut_inbetweener_02_Pose1.png)
+
+Double click **Target 1** and rename it to **End**:
+
+![End pose renamed](media/tut_inbetweener_03_End.png)
+
+In the view, use the move gizmo on the blue pose to move the character along the green (Y) axis:
+
+![move end pose](media/tut_inbetweener_05_EndMove.png)
+
+Move the character slightly further:
+
+![move character](media/tut_inbetweener_04_Move.png)
+
+Click **Generate**:
+
+![Generate button](media/tut_inbetweener_06_generate.png)
+
+This generates your first MotionBricks transition:
+
+![animation generation between two poses](media/tutorial_first_anim.gif)
+
+### Inspect the target and context poses
+
+With the **End** target still selected, turn on **Show Skeleton(s)** and **Show Velocity** under **Visibility**. **Show Mesh** is already on:
+
+![visibility options enabled](media/tut_inbetweener_07_visibility.png)
+
+The view now displays the four poses sampled from the clip for this target. Together, they define the target and its velocity. The red arrow represents the velocity of the target:
+
+![target pose frames](media/tut_inbetweener_08_targetpose.png)
+
+Select **Start** and enable the same options to inspect it:
+
+![context pose frames](media/tut_inbetweener_09_startpose.png)
+
+For **Start**, the view displays the pose at the selected frame and the three poses before it. The poses are sampled at 30 Hz, so in this 120 Hz BVH clip they are every fourth frame. These four poses are the context poses of the generation.
+
+### Add the intermediate targets
+
+Create two new targets by clicking the **+** button below the **Target Poses** list:
+
+![two new targets added](media/tut_inbetweener_10_addposes.png)
+
+Select **Target 2** and **Target 3**, and drag them up in the list:
+
+![new targets moved up in the list](media/tut_inbetweener_11_moveposes.png)
+
+Rename the targets as follows:
+
+- **Entry**
+- **Duck-under**
+
+Select the **Entry** target and use the gizmo to place it between **Start** and **End**, at about one third of the distance:
+
+![move entry pose](media/tut_inbetweener_12_movepose.png)
+
+Select the **Duck-under** target and place it at about two thirds of the distance:
+
+![move avoid pose](media/tut_inbetweener_13_movepose.png)
+
+### Assign the clip and frames
+
+Select the **Entry** target and click the **...** button next to its **Clip** field:
+
+![clip selection button](media/tut_inbetweener_14_clip.png)
+
+Browse to and open the following BVH clip:
+
+```text
+assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh
+```
+
+The view now displays the clip on that target:
+
+![new clip for first pose](media/tut_inbetweener_15_newclippose.png)
+
+Below the **Clip** field, click the **Seconds** button to switch to the **Frames** slider:
+
+![seconds button](media/tut_inbetweener_16_seconds.png)
+
+Select frame **199**:
+
+![switch to frames](media/tut_inbetweener_17_frames.png)
+
+> **Note:** Ctrl + click the slider to type a value directly.
+
+In the view, use the rotate gizmo (the largest circle) to orient the target so that it is consistent with the surrounding targets:
+
+![orient pose](media/tut_inbetweener_18_rotate.png)
+
+Apply the following target settings:
+
+![Entry target settings](media/tut_inbetweener_19_settings.png)
+
+- **Poses to Use:** 4, so the poses that start at the selected frame define the velocity, acceleration, and momentum at the target. See [Set Poses to Use](inbetweener.md#set-poses-to-use).
+- **Transition Early By (frames):** 8. The transition point moves 8 frames earlier, so the next generation starts before the character reaches this target. This target then acts as a guide. It steers the character into the orientation and speed that the next target needs, and the context poses are still in motion, so the model carries that velocity forward. Use a smaller value when the motion must match the target as closely as it can, whether the target is a single pose that stops the character or four poses that describe a velocity and momentum to match. The character then plays all the way to the target. See [Chaining generations](#chaining-generations).
+- **Tokens to Generate:** leave **Min** at 8 and **Max** at 14. This range sets the lengths the model can choose for the transition to this target. Each motion token yields four raw frames, so 8 to 14 motion tokens give 32 to 56 raw frames. The **Raw frames:** readout shows this range. A longer distance between targets needs more tokens to cover the ground. A shorter distance needs fewer tokens, so that the character does not add extra motion to fill the time.
+
+Select the **Duck-under** target and repeat the same steps to assign the BVH clip:
+
+```text
+assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh
+```
+
+Select frame **328** and apply the following settings to this target:
+
+![Duck-under target settings](media/tut_inbetweener_20_settings.png)
+
+Orient the character in the view as shown below:
+
+![duck-under pose](media/tut_inbetweener_21_pose2.png)
+
+### Generate the final animation
+
+The list of targets is now complete. Click **Generate** to view the final animation:
+
+![animation generation in real-time](media/tutorial_end_inbetweener.gif)
+
+You can explore this setup further by changing the following:
+
+- The position and orientation of the character for each target.
+- The clip frame used for each target.
+- The **Poses to Use** and **Transition Early By** values.
+- The **Tokens to Generate** range, which sets how long each generated transition can be. The **Raw frames:** readout below it shows the matching length in frames.
+
+> **Note:** These are the fundamental concepts for integrating MotionBricks into your own application. Your application logic defines the target poses in real time, and MotionBricks generates the motion that reaches them. For the concepts behind the Inbetweener code, see **[Inbetweener](inbetweener.md)** and the **[Runtime API](runtime_api.md)**.
+
+## Part 2: Build a Smart Primitive
+
+The remaining parts of this tutorial show how the example apps work together to build an interactive MotionBricks experience:
+
+- **Smart Primitive Editor:** defines simple pose-based logic around interaction areas.
+- **Scene Editor:** assembles Smart Primitives into an environment.
+- **Scene Preview:** runs the result in real time. It combines locomotion, interaction detection, behaviors, and generated motion.
+
+Together, these apps give developers a practical reference for the MotionBricks workflow. Developers can adapt each part to their own integrations.
+
+### Launch the Smart Primitive Editor
+
+Launch the Smart Primitive Editor:
+
+```sh
+uv run python -m app.smart_primitive_editor
+```
+
+The Newton viewer opens with the Smart Primitive Editor:
+
+![Smart Primitive Editor opened in the Newton viewer](media/tut_smartprim_01_open.png)
+
+Before you begin, confirm that the **Character** selector shows **SOMA**:
+
+![SOMA character](media/tut_smartprim_02_SOMA.png)
+
+> **Note:** The view controls are the same as in the Inbetweener. The Scene Editor uses them too. Scene Preview has its own [controls](#controls). There, **W**, **A**, **S**, and **D**, or the **arrow keys**, move the character. The camera follows the character.
+
+### Create the node hierarchy
+
+A Smart Primitive is built from a hierarchy of nodes, and each node has a defined role. Create the following hierarchy:
+
+- Interaction box
+- Pivot
+ - Entry pose
+ - Duck-under pose
+
+Select the **Root** node and click the **+** button above the hierarchy:
+
+![add node button](media/tut_smartprim_03_addnode.png)
+
+Double click the new node and rename it to **Interaction box**:
+
+![renamed interaction box](media/tut_smartprim_04_interactionbox.png)
+
+To build the rest of the hierarchy, select a node and click **+** to add a child under it:
+
+![Smart Primitive hierarchy](media/tut_smartprim_05_hierarchy.png)
+
+The next steps define the role of each node in the Smart Primitive.
+
+### Configure the Interaction Box
+
+Select the **Interaction box** node and go to the **Properties** window. Right click an empty area of the window to display the available component types, and choose **Add** > **Components** > **Interaction Box**:
+
+![add Interaction Box component](media/tut_smartprim_06_interactionbox.png)
+
+Set **Width** and **Depth** to 1 m and **Height** to 2 m. Set the Z value of **Translation** to 1 m, so that the box stands on the ground:
+
+![interaction box properties](media/tut_smartprim_07_interactionboxset.png)
+
+You can also use the 3D gizmo to move the box up along the Z axis to 1 m:
+
+![move interaction box](media/tut_smartprim_08_interactionboxtransf.png)
+
+### Configure the Pivot
+
+The target poses are authored at fixed positions in the Smart Primitive. They face the direction in which the authored sequence travels. At runtime, however, the character can reach the interaction area from any direction. Without a pivot, a character that arrives from the side first walks to the authored Entry pose. It then turns to follow the sequence, and it leaves the interaction in the authored direction instead of its own.
+
+A pivot solves this problem. When the interaction starts, the pivot turns and slides the whole sequence of target poses to match the direction in which the character enters the interaction area. The character then passes through the interaction without leaving its course:
+
+![A character arrives from the side, without a pivot and with the tutorial Pivot](media/tut_pivot_00_problem.gif)
+
+*A character arrives at 90 degrees to the authored sequence. Without a pivot, on the left, it walks to the authored Entry pose and turns. With the tutorial Pivot, on the right, the target poses turn and slide onto its course. The character's path is an illustration. At runtime, MotionBricks generates the motion.*
+
+To add the pivot, select the **Pivot** node in the hierarchy. Right click an empty area of the **Properties** window and choose **Add** > **Components** > **Pivot**:
+
+![add pivot](media/tut_smartprim_09_addpivot.png)
+
+The **Pivot** properties are added to the node:
+
+![pivot properties](media/tut_smartprim_10_pivotprops.png)
+
+In this tutorial, the character can arrive from any direction. It continues forward and lowers its body to pass under an obstacle in the interaction area. It then resumes its course. Only the poses required inside the interaction area need to be authored. No poses are needed outside of it. When the interaction starts, the pivot first turns the sequence to match the character's direction of approach. It then slides the sequence to the character's point of entry.
+
+To achieve this behavior, set the **Pivot** properties to the following values:
+
+![finished pivot properties](media/tut_smartprim_11_pivotpropsset.png)
+
+| Setting | Value | Purpose |
+| --- | --- | --- |
+| Motion Direction | 0, 1, 0 | The pivot's local +Y axis is the direction in which the authored sequence travels. |
+| Operation Order | Rotation -> Translation | The pivot turns first, and then slides along its turned translation line. |
+| Translation | TranslateX, Line Projection, Min -0.50 m, Max 0.50 m | The pivot can slide sideways by up to 0.5 m in either direction to meet the character's path. |
+| Rotation | RotateZ, Unconstrained | The pivot can turn around the vertical axis to face any direction of approach. |
+
+Each setting offers other options, such as a **Cone** limit on the rotation or the other **Operation Order**. The [Understanding the Pivot](#understanding-the-pivot) section follows the save step. It explains each option in detail and illustrates its effect on the character's motion.
+
+### Configure the target poses
+
+Select the **Entry pose** node in the hierarchy. Right click an empty area of the **Properties** window and choose **Add** > **Components** > **Target Pose**:
+
+![add target pose](media/tut_smartprim_12_addpose.png)
+
+The **Target Pose** properties match the Inbetweener's from Part 1. The Smart Primitive Editor adds **Constrain Root**, **IK Pins**, and **Show Trajectory**. Its **Tokens to Generate** defaults to 6 to 14 instead of 8 to 14. Consecutive steps in a sequence are often placed close together, and the lower minimum lets the model generate a shorter transition between them:
+
+![Target Pose properties](media/tut_smartprim_13_poseprops.png)
+
+Click the **...** button next to **Clip** and open the clip from Part 1:
+
+```text
+assets/motions/soma/avoidance/neutral_avoid_obstacle_bend_down_walk_ff_180_R_001__A543.bvh
+```
+
+Set the target pose values as follows. Enable **Constrain Root**, which moves the clip's root to the node's origin along the ground and keeps its height:
+
+![Entry pose properties set](media/tut_smartprim_14_posepropsset.png)
+
+Use the 3D gizmo to rotate and position the **Entry pose** near the edge of the interaction box. Align the pose with the yellow arrow. This arrow shows the pivot's **Motion Direction**, which is the direction in which the authored sequence travels:
+
+![pose transformations](media/tut_smartprim_15_posetransf.png)
+
+Repeat the previous steps for the **Duck-under pose**. Set the following values, and enable **Constrain Root**:
+
+![Duck-under pose properties set](media/tut_smartprim_16_pose2propsset.png)
+
+Use the 3D gizmo to position and rotate the character so that it stands at the center of the box:
+
+![second pose transformations](media/tut_smartprim_18_pose2transf.png)
+
+### Define the sequence
+
+Next, define the order in which the poses are used.
+
+In the **Sequences** window, click the **+** button to add a new sequence:
+
+![add sequence button](media/tut_smartprim_17_addsequence.png)
+
+Set the sequence **Pivot** field to the **Pivot** node. The sequence then uses this pivot:
+
+![sequence pivot](media/tut_smartprim_19_sequpivot.png)
+
+Add the target poses in the order in which the action takes place. Click **+ Add Target Pose** and choose **Entry pose**. Click it again and choose **Duck-under pose**. You can also drag a node from the **Hierarchy** window onto the sequence header:
+
+![sequence done](media/tut_smartprim_20_sequdone.png)
+
+### Save the Smart Primitive
+
+The Smart Primitive is now complete.
+
+Choose **File** > **Save As...** and save the Smart Primitive document as:
+
+```text
+assets/smart_primitives/soma/SOMA_duck_tutorial.smart_primitive.json
+```
+
+### Understanding the Pivot
+
+This section explains how the **Pivot** configured above adapts the authored poses to each approach. It also explains why the resulting poses continue the character's incoming motion.
+
+The figures use the `SOMA_duck_tutorial` Smart Primitive saved above. They place the poses with the same pivot alignment code that Scene Preview runs, and they show the SOMA mesh used by the editors. The pink and green characters are the actual target poses sent to the model. The blue character stands in for the incoming character. It and the dashed path are illustrations only. At runtime, MotionBricks generates the path.
+
+#### Why a pivot is needed
+
+The target poses of a Smart Primitive are authored at fixed positions relative to the Smart Primitive. At runtime, however, the character can reach the interaction area from many positions, directions, and speeds. If the poses stayed at their authored placement, the first target could lie to one side of the character's path or face a different direction. The generated transition would then need an abrupt turn or sidestep to reach it.
+
+A pivot adapts the placement of the entire sequence to the approach. The **Pivot** node is the parent of the target pose nodes. When the runtime moves and turns the pivot, every target pose follows it as a rigid group. Only the root of each sampled pose is transformed. The joint values stay exactly as sampled from the clip, so the authored body motion is preserved.
+
+#### When the pivot is aligned
+
+In Scene Preview, the pivot is aligned once, at the start of each sequence:
+
+1. The character's probe box extends ahead of the character along its movement. The sequence starts when the probe box overlaps an interaction box of the Smart Primitive.
+2. The behavior selects a sequence. `VelocityMatchingSequenceBehavior` selects the sequence whose first target speed is closest to the character's current speed.
+3. If the sequence references a pivot, the pivot is aligned with the approach. The alignment uses the character's position and its desired velocity. It also uses the line that the probe box covers on the ground.
+4. The target poses in world space are computed from the aligned hierarchy and sent to MotionBricks.
+
+The limits are always measured from the authored placement of the pivot, never from its previous alignment. As a result, the Smart Primitive does not drift over repeated interactions. A sequence without a pivot keeps its current placement.
+
+#### How each setting contributes
+
+The following top view shows the authored layout of the tutorial Smart Primitive. It also shows the visual guides that the Smart Primitive Editor displays for the **Pivot**:
+
+![Authored layout of the tutorial Pivot, top view](media/tut_pivot_01_layout.png)
+
+*Authored layout, top view. The yellow arrow is the Motion Direction, and the red dashed line is the range of the Line Projection.*
+
+| Setting | Role | Editor guide |
+| --- | --- | --- |
+| **Motion Direction** | The direction, in the pivot's local axes, in which the authored sequence travels. Alignment turns the pivot so that this direction matches the character's direction of travel. For this reason, the target poses were oriented along the yellow arrow. | Yellow arrow |
+| **Rotation** | The local axis around which the pivot can turn. **RotateZ** turns it around the vertical axis. **Unconstrained** allows any heading. **Cone** limits the turn to **Half Angle** on each side of the cone center. **Cone Side** sets that center. **Motion Direction** centers the cone on the Motion Direction. **Mirrored** centers it on the opposite direction. **Both** allows either side. | Red arc (Cone only) |
+| **Translation** | The local axis along which the pivot can slide. With **Line Projection**, the pivot moves to the point of the line, between the **Min** and **Max** offsets, that is closest to that line of the probe box. In practice, this is the point where the character's path crosses the line. **Unconstrained** allows any distance along the axis. | Red dashed line |
+| **Operation Order** | **Rotation -> Translation** turns the pivot first. The turn also rotates the translation line around the authored origin. The pivot then slides along the turned line. **Translation -> Rotation** slides along the authored line first, and then turns. | None |
+
+The **Show Motion Direction**, **Show Translation Constraint**, and **Show Rotation Constraint** options of the **Pivot** component show or hide the guides.
+
+#### Effect on different approaches
+
+The figure below compares the placement of the target poses for six approaches, seen from above. In each panel, the blue character is the incoming character at the moment the interaction starts. The pink and green characters are the Entry and Duck-under target poses. The faded dashed arrow marks the authored Motion Direction.
+
+![Pivot alignment for six approaches](media/tut_pivot_02_cases.png)
+
+1. **No pivot:** the poses stay where they were authored. A character that approaches at an angle must turn sharply to reach the Entry pose. It must then turn again to pass under the obstacle.
+2. **Translation only:** the character approaches 0.4 m to the side of the center. The pivot slides 0.4 m along its line, so the poses move onto the character's path.
+3. **Rotation only:** the character approaches at 35 degrees. The pivot turns 35 degrees around Z, so the poses face the character's direction of travel.
+4. **Tutorial settings:** the character approaches at an angle and off center. The pivot turns first. It then slides along the turned line to the point where the character's path crosses it.
+5. **Line Projection** limit: the character approaches 0.85 m to the side. The slide stops at the +0.5 m end of the line, and the generated transition covers the remaining 0.35 m.
+6. **Cone limit:** the cone's **Half Angle** is 30 degrees, and the character approaches at 55 degrees. The turn stops at 30 degrees, and the generated transition covers the remaining 25 degrees.
+
+The following animation uses the tutorial settings. It sweeps the approach across lateral offsets, then across approach angles, and finally across both at once. Each step is shown from above and in perspective, where the duck-under posture is clearly visible. The readout at the bottom reports the resulting turn and slide of the pivot:
+
+![Pivot alignment animated across approach offsets and angles](media/tut_pivot_03_alignment.gif)
+*Live pivot alignment with the tutorial settings. In the first phase, the slide is clamped at ±0.50 m when the offset exceeds the line.*
+
+#### Continuity with the incoming motion
+
+MotionBricks always generates motion from the four context poses toward the next target. These poses carry the character's current velocity. The pivot places the targets so that they are consistent with that context:
+
+- **Position:** after translation, the Entry pose lies on the character's path. The character reaches it by continuing forward, without a sidestep.
+- **Orientation:** after rotation, the four poses of the Entry target, and therefore its velocity, point along the character's direction of travel. The context poses and the target poses describe the same direction of motion. The generated transition is a natural continuation of the incoming walk.
+- **Within the sequence:** all target poses move together. The spacing, orientation, and timing between the Entry and Duck-under poses stay exactly as authored. With **Transition Early By**, the character carries its momentum from one target to the next.
+- **Exit:** the last pose turns by the same rotation as the rest of the sequence. The sequence therefore exits along the aligned Motion Direction. When the interaction ends, the character already moves in its original direction of travel, so locomotion resumes without a corrective turn.
+
+In effect, the pivot re-expresses the authored poses as if the clip had been recorded along the character's actual path. The limits define the range over which this remains valid. In this Smart Primitive, the translation line runs across the direction of travel. The Duck-under pose lies close to the pivot origin. Turning the pivot therefore changes the angle at which the character crosses the interaction area, while the duck-under posture stays near its center. When you author your own Smart Primitives, choose offsets and cone angles that keep every allowed placement valid for the obstacle.
+
+### Explore variations
+
+Change the poses or add more poses to the sequence to make variations. You can also add sequences that respond to different speeds or incoming motions. To learn more about Smart Primitives and their editor, see the **[Smart Primitive Editor](smart_primitive_editor.md)** page.
+
+For comparison, open the following Smart Primitive document in the Smart Primitive Editor. It is similar to the tutorial Smart Primitive and contains several variations of the avoidance:
+
+`assets/smart_primitives/soma/avoidance.smart_primitive.json`
+
+It extends the tutorial Smart Primitive with:
+
+- A second branch, `Variation 1`.
+- A `Jog` sequence sampled from another clip.
+- The same pivot, with the same settings as in this tutorial, shared by the `Walk` and `Jog` sequences.
+- Sequence selection by speed at runtime.
+- A smaller interaction box raised above the ground, from about 1.46 m to 2.46 m. A standing character's probe box is 1.6 m tall, so it reaches the interaction box and starts the avoidance. When the character crouches, its probe box shrinks to about 0.96 m. The character can then move under the obstacle without starting the interaction. This refinement is outside the scope of this tutorial. The tutorial's interaction box extends from the ground to 2 m, so every locomotion mode starts the interaction.
+
+![velocity matching flow](media/velocity_matching_flow.png)
+
+This shows the flexibility of pose-based interactions. A faster approach does not require a new state machine branch or a set of transition clips. It only requires another target sequence. The behavior then selects the sequence that best matches the character's current speed.
+
+## Part 3: Assemble an interaction scene with avoidance, jump, and sit
+
+The scene uses the following Smart Primitives:
+
+- `SOMA_duck_tutorial.smart_primitive.json`, created in Part 2.
+- `jump_0_5m.smart_primitive.json`, bundled with the repository.
+- `sit.smart_primitive.json`, bundled with the repository.
+
+### Launch the Scene Editor
+
+Launch the Scene Editor:
+
+```sh
+uv run python -m app.scene_editor
+```
+
+The Newton viewer opens with the Scene Editor:
+
+![scene editor](media/tut_sceneedit_01_open.png)
+
+Confirm that the **Character** selector shows **SOMA**.
+
+Every Smart Primitive reference in a scene must use the same rig. The `CharacterStart` item defines where the character appears when Scene Preview starts the scene.
+
+### Add the avoidance Smart Primitive
+
+In the Scene Editor, add a new scene item by clicking the **+** button at the top:
+
+![Scene window with the + button](media/tut_sceneedit_02_add.png)
+
+Choose **Smart Primitive**:
+
+![Add menu with Smart Primitive](media/tut_sceneedit_03_addsmartprim.png)
+
+Double click the new item and rename it to **avoid**:
+
+![Renamed Smart Primitive instance](media/tut_sceneedit_04_addsavoid.png)
+
+In the **Properties** window:
+
+- Set **Reference** to the Smart Primitive document created in Part 2.
+- Set the runtime **Behavior** to `VelocityMatchingSequenceBehavior`.
+
+![Smart Primitive instance properties](media/tut_sceneedit_05_primpropsset.png)
+
+Use the 3D gizmo to rotate and position the Smart Primitive instance in the scene:
+
+![Smart Primitive instance layout](media/tut_sceneedit_06_primmove.png)
+
+To show the obstacle, add a **Solid Cube** item to the scene:
+
+![add solid cube](media/tut_sceneedit_07_solidcube.png)
+
+Use the 3D gizmo and the cube's properties to position and scale the cube so that it sits above the **Duck-under pose** of the Smart Primitive:
+
+![adding obstacle cube](media/tut_sceneedit_08_obstacle.png)
+
+### Complete the course
+
+To complete the obstacle course, repeat the previous steps to add the following Smart Primitives:
+
+- `assets/smart_primitives/soma/jump_0_5m.smart_primitive.json`
+- `assets/smart_primitives/soma/sit.smart_primitive.json`
+
+For the **Sit** Smart Primitive, select `SittingBehavior` as the runtime behavior.
+
+Position and rotate the Smart Primitive instances in the scene:
+
+![scene layout](media/tut_sceneedit_09_layout.png)
+
+Add Solid Cubes to show the obstacles for these Smart Primitives:
+
+![obstacles layout](media/tut_sceneedit_10_layoutobstacles.png)
+
+### Save the scene
+
+Choose **File** > **Save As...** and save the scene as:
+
+```text
+assets/scenes/soma_tutorial.scene.json
+```
+
+The scene stores its references relative to the scene file. Several instances can reference the same Smart Primitive document, each with its own placement and behavior. You can experiment further by adding more Smart Primitives and building your own layout.
+
+## Part 4: Play the scene
+
+Scene Preview is a compact real-time character demo. It combines the following parts:
+
+- A state machine.
+- Locomotion blend spaces.
+- Interaction detection.
+- Smart Primitive behaviors.
+- Clip playback.
+- The MotionBricks generation API.
+
+### Launch Scene Preview
+
+Run:
+
+```sh
+uv run python -m app.scene_preview --scene assets/scenes/soma_tutorial.scene.json
+```
+
+The Newton viewer opens with Scene Preview:
+
+![Scene Preview opened with the tutorial scene](media/tut_sceneprev_01_start.png)
+
+If the scene does not load, check three things. Every Smart Primitive reference must resolve. Every referenced Smart Primitive document must use SOMA, the scene's rig. Every instance must have a valid **Behavior**.
+
+The character starts in an idle loop and is ready to explore the scene:
+
+![final result](media/tutorial_end_scenepreview.gif)
+
+### Controls
+
+Use the following controls to move the character and orbit the camera:
+
+| Action | Keyboard and mouse | Controller |
+| --- | --- | --- |
+| Move forward, left, backward, or right | **W**, **A**, **S**, and **D**, or the **arrow keys** | Left stick or D-pad |
+| Run | Hold **Space** while moving | Push the left stick further |
+| Interact manually, or stand up after sitting | **I** | **X** |
+| Switch between the Forward and Strafing modes | **O** | **Y** |
+| Switch between the Crouching and Strafing modes | **P** | **B** |
+| Cycle through the style modes, such as Skipping and Zombie | **[** | **A** |
+| Orbit the camera around the character | Drag with the **middle mouse button** | Right stick |
+
+**Auto Interact** is enabled by default. Scene Preview starts the interaction of the nearest overlapping Smart Primitive instance once per approach. To start each interaction manually with **I** (**X** on a controller), disable **Auto Interact** in the **Scene Preview** window.
+
+When the character is seated, press **I** (**X** on a controller) to run the `Stand` sequence and return to locomotion.
+
+### Inspect the runtime
+
+In the **Scene Preview** window, enable the following options:
+
+- **Show Context Poses** displays the recent poses supplied to the next generation.
+- **Show Target Poses** under **Character** displays the current target poses.
+- **Show Blend Space Poses** displays the blended target pose where locomotion places it. When locomotion needs new motion, it generates toward this target.
+- **Show Probe Box** displays the character's probe box, which reaches ahead along its movement.
+- **Show Interaction Boxes** displays the areas where Smart Primitive behaviors can begin.
+
+Watch **State:** in the **Status** section change from Locomotion to Interaction when the probe box reaches each interaction box. The interaction box turns from red to green while the probe box overlaps it. When the avoidance or jump interaction completes, the character returns to locomotion. Without movement input, it returns to idle. The sit interaction stays in its looping clip until the user requests the `Stand` sequence.
+
+> **Note:** If the feet slide, or if the duck-under starts too early or too late, adjust the Smart Primitive in the Smart Primitive Editor:
+>
+> - **Distance between the target poses:** move the **Entry pose** farther from the **Duck-under pose** to give the character enough lead to lower its body before the obstacle. Move the poses closer together if the character adds extra steps to cover the distance.
+> - **Transition Early By (frames):** adjust the value of the **Entry pose** and the **Duck-under pose**. A larger value moves the transition point earlier, which gives the character more lead into the duck-under. A smaller value lets the character reach each target more closely.
+>
+> Save the Smart Primitive, and then open the scene again in Scene Preview to check the result. Tuning these values is an iterative process. Repeat it until the motion through each interaction box looks right.
+
+## Summary: what this workflow demonstrates
+
+Two target poses from a single clip served first as direct generation goals and then as a reusable interaction. The bundled avoidance Smart Primitive adds a Jog variation without any change to the runtime state machine. The scene combines that interaction with Jump and Sit. Each one uses the same pose-based generation pattern.
+
+This separation of responsibilities is the main integration model:
+
+- The application or state machine selects the next goals.
+- Smart Primitives organize location-specific goals and adapt them to each approach.
+- Behaviors select and play the appropriate target sequence.
+- Scenes place those interactions and their visible geometry.
+- MotionBricks generates continuous motion from the character's current context.
+
+Continue with the [Runtime API](runtime_api.md) to explore the reusable library calls behind the examples. The [Smart Primitive Editor](smart_primitive_editor.md), [Scene Editor](scene_editor.md), and [Scene Preview](scene_preview.md) pages describe each layer in more detail.
diff --git a/docs/inbetweener.md b/docs/inbetweener.md
new file mode 100644
index 0000000..2a18bac
--- /dev/null
+++ b/docs/inbetweener.md
@@ -0,0 +1,342 @@
+# Inbetweener
+
+The [Inbetweener](../app/inbetweener_demo.py) is the smallest complete example of MotionBricks generation in this repository. It prepares context and target poses, generates a transition, and plays it up to its transition point. It then feeds the motion that was played back into the next generation.
+
+<table>
+ <tr>
+ <th>SOMA</th>
+ <th>Unitree G1</th>
+ </tr>
+ <tr>
+ <td><img src="media/inbetweener_soma.gif" alt="The Inbetweener with SOMA" width="100%"></td>
+ <td><img src="media/inbetweener_g1.gif" alt="The Inbetweener with Unitree G1" width="100%"></td>
+ </tr>
+</table>
+
+This page shows how to run the app, then explains its code for developers who integrate MotionBricks into another application. The Newton viewer, its ImGui controls, and its renderers make the data flow visible. The model does not need them.
+
+The [guided tutorial](guided_tutorial.md#part-1-generate-an-animation-in-the-inbetweener) uses this app to build an avoidance sequence from the Start, Entry, Duck-under, and End poses. The sections below connect those authoring actions to the code that prepares the model inputs and runs each generation.
+
+## Run the Inbetweener
+
+```sh
+uv run python -m app.inbetweener_demo
+```
+
+- `--model soma` or `--model unitree_g1` picks the character to start with. SOMA is the default.
+- `--model-precision fp16` uses the mixed FP16 model. FP32 is the default.
+- `--verbose` shows detailed log messages.
+
+The app opens with Start and **Target 1**, sampled from one walk clip at 1 s and 7 s. Target 1 stands 2 m from Start along -Y. Start is green, and targets are blue.
+
+Things to try:
+
+- Switch between SOMA and the Unitree G1 with the **Character** selector. Each switch starts over with Start, one target, and the default view.
+- Move and turn a pose. Height and tilt are locked by default, so a pose stays on the ground.
+- Pick another clip with **...** and drag the time slider to choose a pose from it.
+- Add targets with **+**, drag them in the list to change their order, then press **Generate**.
+- Tune **Poses to Use**, **Transition Early By (frames)**, and **Tokens to Generate** for each target. [How tutorial actions update model inputs](#how-tutorial-actions-update-model-inputs) explains each setting.
+- Turn on **Show Foot Contacts**, beside **Generate**, to outline the foot contacts of generated motion.
+
+### Controls
+
+| Action | Control |
+| --- | --- |
+| Move the camera | **W**, **A**, **S**, and **D**, or the **arrow keys**. **Q** and **E** move it down and up. |
+| Orbit around the camera pivot | Drag with the **middle mouse button** |
+| Look around | Drag with the **left mouse button** |
+| Pan | **Shift** + drag with the **middle mouse button** |
+| Move toward or away from the camera pivot | **Ctrl** + drag with the **middle mouse button**, or the **mouse wheel** |
+| Change the field of view | **Ctrl** + **mouse wheel** |
+| Select a pose | Click its mesh or ground ring in the view, or click it in **Target Poses** |
+| Move or turn the selection | Drag the gizmo, or edit the **Transform** fields |
+| Reset or lock a transform | Right click **Translation** or **Rotation** to reset it. Right click an axis label to lock that axis. |
+
+## Generation flow
+
+The demo uses four essential runtime operations:
+
+```python
+context.update_from_poses(recent_poses)
+target.update_from_poses(target_poses)
+engine.generate_animation(context=context, target=target, output=output)
+output.sample(time, current_pose)
+```
+
+The same pattern applies to SOMA and the G1. Their engine classes and pose layouts differ, but the calls are equivalent.
+
+Each generation produces a short transition. The [Runtime API](runtime_api.md#generation-flow) explains how repeated generations become continuous motion.
+
+## Code map
+
+The model-facing code is concentrated in the following symbols in [`app/inbetweener_demo.py`](../app/inbetweener_demo.py):
+
+| Symbol | Responsibility |
+| --- | --- |
+| `PoseEntry` | Stores one source clip, sample time, world placement, target settings, and four-pose sample window for the demo. |
+| `sample_pose_window()` | Samples four poses at 30 Hz into a caller's array and places their root in world space. |
+| `InbetweenerDemo.use_rig()` | Closes the previous rig's engine, creates one for SOMA or the G1, and resets the app to that rig. |
+| `InbetweenerDemo._prepare_rig()` | Creates the reusable context token, target token, and output buffer, then sets up Start and the first target. |
+| `InbetweenerDemo.refresh_poses()` | Resamples Start and every target, updates their previews and velocities, and returns to Start. |
+| `InbetweenerDemo.reset()` | Loads Start's four poses into the context token. |
+| `InbetweenerDemo.generate_next_segment()` | Loads the next target and calls `engine.generate_animation()` with the target's allowed token counts. |
+| `InbetweenerDemo.step()` | Plays the current segment up to its transition point. There, it copies the last four played poses into the next context and moves to the next target. For each target, the first call runs `generate_next_segment()` instead. |
+| `InbetweenerDemo._draw_foot_contacts()` | Samples the foot contacts of the generated motion and draws them on the character's soles. |
+
+The remaining functions implement the interface, rendering, picking, and file dialogs. They show one authoring environment. An integration can replace them with game state, procedural targets, network input, or another animation tool.
+
+## Initialize the rig and engine
+
+`use_rig()` closes the previous rig's engine before it creates one for the selected rig, so only one engine holds GPU memory:
+
+```python
+if self.engine is not None:
+ self.engine.synchronize()
+ ...
+ self.engine.close()
+ self.engine = None
+self.rig, self.engine = rig, create_engine(self.viewer, rig, self.fp16)
+```
+
+It then calls `_prepare_rig()`. That function uses `load_rig_assets()` to obtain a `RigAssets` with:
+
+- The SOMA character or the G1 robot.
+- A `ClipRegistry` for the rig.
+- A reference pose with the correct buffer layout.
+- The transform from source coordinates to world space.
+
+`_prepare_rig()` creates the context token, target token, and output buffer each time a rig is selected. Every generation with that rig reuses these buffers:
+
+```python
+if rig is ModelRig.SOMA:
+ skeleton = assets.model.skeleton
+ self.context = engine.create_input(skeleton)
+ self.target = engine.create_input(skeleton)
+ self.output = engine.create_output(skeleton)
+else:
+ self.context = engine.create_input()
+ self.target = engine.create_input()
+ self.output = engine.create_output()
+```
+
+For SOMA, each pose holds one local joint transform per skeleton joint. For the G1, each pose holds 36 joint coordinates: the root position, the root's XYZW quaternion, and 29 joint angles. See the [SOMA](soma_model.md) and [Unitree G1](unitree_g1_model.md) model cards for the complete contracts. The Runtime API covers [pose layouts and model space](runtime_api.md#pose-layouts-and-model-space).
+
+## Represent poses in the demo
+
+`PoseEntry` is app state for this demo. The MotionBricks library does not need it. Each `PoseEntry` records:
+
+- A clip and a sample time.
+- A root placement in world space.
+- One four-pose sample window.
+- How many target poses to send to the model, set by **Poses to Use**.
+- How many frames earlier the transition point moves, set by **Transition Early By (frames)**.
+- The smallest and largest token count the model may choose, set by **Tokens to Generate**.
+- Visualization state for the viewer.
+
+The list always starts with Start. The targets follow it.
+
+### Sample the four-pose window
+
+`sample_pose_window()` converts a clip sample into the format that the model expects. It fills the `poses` array that the caller passes. It returns nothing. The keyword-only `anchor` argument picks the pose that sits at the sample time:
+
+```python
+def sample_pose_window(
+ entry: PoseEntry, model_to_runtime: wp.transform, poses: wp.array, *, anchor: int,
+) -> None:
+ ...
+ for frame in range(MODEL_POSES_PER_TOKEN):
+ sample_time = entry.sample_time + (frame - anchor) / MODEL_SAMPLE_RATE
+ entry.clip.sample(sample_time, poses[frame], root_offset=root_offset)
+```
+
+`MODEL_POSES_PER_TOKEN` is four, and `MODEL_SAMPLE_RATE` is 30 Hz.
+
+- For Start, `refresh_poses()` passes `anchor=3`, so the selected sample is the last pose of the window. The three earlier poses describe the motion entering Start.
+- For a target, it passes `anchor=0`, so the selected sample is the first pose of the window. Up to three following poses describe the desired motion after that target.
+
+The [guided tutorial](guided_tutorial.md#inspect-the-target-and-context-poses) shows this difference. With **Show Skeleton(s)** on, the view shows the four poses of Start that end at its sample time. For the End target, it shows the **Poses to Use** poses that begin at its sample time. The `anchor` argument implements that difference.
+
+### Place a pose in the scene
+
+The demo removes the sampled root's ground offset and applies the pose's placement, which the gizmo and the **Transform** fields edit. It also converts source coordinates to world space:
+
+```python
+ground_offset = wp.transform(
+ wp.vec3(-float(root[0]), -float(root[1]), 0.0),
+ wp.quat_identity(),
+)
+root_offset = wp.mul(entry.placement, wp.mul(ground_offset, model_to_runtime))
+```
+
+Only the root placement changes. SOMA local joint transforms and G1 joint angles stay as sampled. For this reason, the [tutorial](guided_tutorial.md#add-the-intermediate-targets) could move and rotate Entry and Duck-under with the gizmo without re-authoring their body poses.
+
+Locked axes keep their value. `apply_transform_locks()` applies the locks to gizmo edits, and the **Transform** fields skip locked axes.
+
+`model_to_runtime` converts SOMA's Y up source coordinates to Z up world space. The G1 conversion is the identity. [Pose layouts and model space](runtime_api.md#pose-layouts-and-model-space) explains why the engine and clip sampling take the same transform.
+
+## How tutorial actions update model inputs
+
+### Select a clip and frame
+
+Choosing a clip and a frame, such as the avoidance BVH clip at frame 199 for Entry in the [tutorial](guided_tutorial.md#assign-the-clip-and-frames), sets `PoseEntry.path`, `PoseEntry.clip`, and `PoseEntry.sample_time` in `_choose_pending_clip()` and `_draw_properties()`. Every change calls `refresh_poses()`:
+
+```python
+for index, entry in enumerate(self.pose_entries):
+ anchor = MODEL_POSES_PER_TOKEN - 1 if index == 0 else 0
+ entry.sampled_poses = wp.empty_like(self.context.poses)
+ sample_pose_window(entry, self.model_to_runtime, entry.sampled_poses, anchor=anchor)
+```
+
+An integration does not need clips. It can load any finite poses with the correct SOMA or G1 layout into the context and target tokens. Clips are only a convenient source of target poses for this demo. For example, [Kimodo](https://github.com/nv-tlabs/kimodo) or [ARDY](https://github.com/nv-tlabs/ardy) could generate them instead.
+
+### Add and order targets
+
+**+** calls `add_target()`, as in the [tutorial](guided_tutorial.md#add-the-intermediate-targets). It copies the clip and sample time of the selection, places the target 1.5 m from the last target along -Y with the same rotation, and names it after its ID, as in **Target 2**. Dragging a target in the list calls `move_target()`.
+
+The list order controls playback. `next_target_index` advances through `pose_entries`. Each target produces one generation. Start stays at index zero because it provides the first context rather than a target.
+
+### Set Poses to Use
+
+**Poses to Use** sets how many of a target's four poses inform the model. It decides whether a target sets only a posture or also describes motion:
+
+```python
+self.target.update_from_poses(entry.sampled_poses[:entry.num_poses_to_use], stream=self.engine.stream)
+```
+
+The accepted range is 1 to 4:
+
+- One pose sets the destination. The model treats it as a stop with no velocity.
+- A second pose adds velocity.
+- A third and fourth pose add acceleration and momentum.
+
+Start always provides all four context poses. No generation ends at Start. For this reason, **Poses to Use**, **Transition Early By (frames)**, and **Tokens to Generate** are disabled for Start.
+
+### Set Transition Early By
+
+**Transition Early By (frames)** lets the sequence move toward the next target before the current segment reaches its last frame, as in the [tutorial](guided_tutorial.md#assign-the-clip-and-frames):
+
+```python
+self.segment_end_frame = max(
+ MODEL_POSES_PER_TOKEN - 1, self.output.num_frames - 1 - entry.transition_early_by_frames,
+)
+```
+
+This setting does not change the target sent to the model. It moves the transition point earlier, so less of the generated motion plays before the next generation. The context for that generation therefore ends at the transition point. At least four frames always play, because the next context is the last four played frames.
+
+This makes a target useful as a guide at runtime. The character heads toward it and moves on before it arrives. Use such a target to steer and place the character before it generates toward a more precise interaction pose, as Entry does before Duck-under in the [tutorial](guided_tutorial.md#assign-the-clip-and-frames).
+
+### Set Tokens to Generate
+
+**Tokens to Generate** sets the smallest and largest token count that the model may choose for the generation toward this target. Each motion token holds four raw frames. The **Raw frames:** readout shows the matching range. `generate_next_segment()` passes the range to the engine as allowed token counts:
+
+```python
+config=MotionBricksInferenceConfig(
+ allowed_token_counts=tuple(range(entry.min_tokens, entry.max_tokens + 1)),
+),
+```
+
+Each target starts with the range in [`DEFAULT_TOKEN_COUNTS`](../motionbricks/model/config.py), 8 to 14 tokens. `MotionBricksInferenceConfig` uses the same default. The model contract allows 6 to 16. Equal **Min** and **Max** values fix the length of the transition. A wide range lets the model choose a duration that suits the distance and the motion.
+
+### Click Generate
+
+The **Generate** button calls `play()`. The button is disabled until the list holds at least one target. `play()` first calls `reset()` and then starts playback:
+
+```python
+def play(self) -> None:
+ self.reset()
+ if len(self.pose_entries) > 1:
+ self.playing = True
+```
+
+Every preview therefore begins from the Start context and moves through the current list of targets in order.
+
+## One generation
+
+`generate_next_segment()` performs one generation:
+
+```python
+entry = self.pose_entries[self.next_target_index]
+self.target.update_from_poses(entry.sampled_poses[:entry.num_poses_to_use], stream=self.engine.stream)
+self.engine.generate_animation(
+ context=self.context, target=self.target, output=self.output,
+ config=MotionBricksInferenceConfig(
+ allowed_token_counts=tuple(range(entry.min_tokens, entry.max_tokens + 1)),
+ ),
+)
+```
+
+Either `reset()` or the previous segment's `step()` loaded the context. The target is the next one in the list. `generate_animation()` fills the reusable output buffer and sets `output.num_frames` to the number of valid frames.
+
+The output buffer is allocated for the largest supported result. Only the first `output.num_frames` frames are valid for the current generation. The demo derives the segment's transition point from that value and the target's **Transition Early By** setting.
+
+All GPU operations are ordered on `engine.stream`. The main loop enters `wp.ScopedStream(self.engine.stream)`, and individual buffer operations also receive `stream=self.engine.stream`. An integration should preserve this ordering. It should also synchronize the engine before it reads GPU results on the CPU.
+
+### Show foot contacts
+
+The **Show Foot Contacts** checkbox next to **Generate** draws the model's foot contacts for the generated motion. The slider beside it sets the threshold. `_draw_foot_contacts()` samples the contacts at the playback time with `output.sample_foot_contacts()`. It then outlines each sole whose contact is above the threshold. [foot_contacts.py](../motionbricks/animation/foot_contacts.py) defines the order and meaning of the four values.
+
+## Playback and chained generation
+
+The complete sequence follows three functions.
+
+### 1. `reset()`: seed the first context
+
+```python
+start = self.pose_entries[0]
+self.context.update_from_poses(start.sampled_poses, stream=self.engine.stream)
+wp.copy(self.current_pose, start.preview_pose, stream=self.engine.stream)
+```
+
+Start's four poses become the context. The current displayed pose returns to the last pose of that window.
+
+### 2. `generate_next_segment()`: generate toward one target
+
+The demo copies the next target's poses to the target token and calls `generate_animation()`. It records the segment's transition point and samples its first pose.
+
+### 3. `step()`: play the segment and preserve continuity
+
+```python
+end_time = self.segment_end_frame / MODEL_SAMPLE_RATE
+self.playback_time = min(self.playback_time + delta_time, end_time)
+self.output.sample(self.playback_time, self.current_pose, stream=self.engine.stream)
+```
+
+`step()` samples the generated motion at the app's update rate until it reaches the transition point. `run()` advances playback by the time since the last frame, capped at 0.1 s. On slower hardware, playback slows down instead of skipping ahead.
+
+Before `step()` advances to the next target, it copies the last four poses that actually played:
+
+```python
+played_frames = self.segment_end_frame + 1
+recent_poses = self.output.poses[played_frames - MODEL_POSES_PER_TOKEN:played_frames]
+self.context.update_from_poses(recent_poses, stream=self.engine.stream)
+```
+
+In the [guided tutorial](guided_tutorial.md#generate-the-final-animation), the generated sequence moved from Start to Entry, Duck-under, and End. After each segment, `step()` made the last four played poses the context for the next target. This feedback loop joins independent generations into continuous motion.
+
+## SOMA and Unitree G1
+
+The **Character** selector shows that the integration flow does not depend on the rig:
+
+| | SOMA | Unitree G1 |
+| --- | --- | --- |
+| Source clips | BVH | CSV |
+| Engine input | `PoseToken` holding local joint transforms | `DOFToken` holding joint coordinates |
+| Generated output | `AnimationBuffer` holding local joint transforms | `DOFAnimationBuffer` holding joint coordinates |
+| Conversion to world space | `model_to_runtime` converts Y up source coordinates to Z up world space | Identity |
+| Rendering in this demo | `SkeletalMeshRenderer` | `DOFMeshRenderer` |
+
+When you select another rig, the demo defers the switch until the start of the next frame. `use_rig()` then closes the current engine and creates an engine for the selected rig. It calls `_prepare_rig()`, which creates the rig's buffers and resets the list to Start and one target.
+
+The TensorRT plan cache keeps a switch back short: it loads the plan instead of building it again. A larger application that keeps several engines should key them by rig, precision, and any other build option that affects the TensorRT plan.
+
+## Use this pattern in an integration
+
+The Inbetweener runs the generation loop by hand, so each call stays visible. The [generation flow](runtime_api.md#generation-flow) in the Runtime API page lists the steps of the loop. For a larger real-time application, use `GeneratedMotionPlayer` or `GeneratedDOFMotionPlayer` from [motion_player.py](../motionbricks/runtime/motion_player.py) as examples. [Chaining generations](runtime_api.md#chaining-generations) describes them.
+
+## Further reference
+
+- [Guided tutorial](guided_tutorial.md): the user-facing workflow that uses this app.
+- [Runtime API](runtime_api.md): engines, pose layouts, clips, generation settings, chaining, TensorRT builds, and logging.
+- [ONNX inference and batching](onnx_inference.md): direct ONNX interfaces, batching, and alternative runtimes.
+- [SOMA model card](soma_model.md): SOMA inputs, outputs, coordinates, and limitations.
+- [Unitree G1 model card](unitree_g1_model.md): G1 joint layout, inputs, outputs, and limitations.
diff --git a/docs/media/core_idea.gif b/docs/media/core_idea.gif
new file mode 100644
index 0000000..538acc3
--- /dev/null
+++ b/docs/media/core_idea.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:30b62b537e2137819c06a7ef321134066816c001d7fdbd9be82823b9d8907482
+size 529695
diff --git a/docs/media/duck_under_flow.png b/docs/media/duck_under_flow.png
new file mode 100644
index 0000000..48f6a2c
--- /dev/null
+++ b/docs/media/duck_under_flow.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9579f9db70c7ac2796982cc4ee650feece9a045a71f83c5bdc59e4101a5f58f8
+size 22798
diff --git a/docs/media/generation_flow.png b/docs/media/generation_flow.png
new file mode 100644
index 0000000..aebd6c0
--- /dev/null
+++ b/docs/media/generation_flow.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e4eaa442dc2fb48cfdcc1f95ba011a1c532c516c89bad72952585d3cdf4a0323
+size 55887
diff --git a/docs/media/inbetweener_g1.gif b/docs/media/inbetweener_g1.gif
new file mode 100644
index 0000000..1b91b6e
--- /dev/null
+++ b/docs/media/inbetweener_g1.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c7af3bc8521f9b6133c86282996d34a82c439d4b331ec969ddecc33eeef0e483
+size 876202
diff --git a/docs/media/inbetweener_soma.gif b/docs/media/inbetweener_soma.gif
new file mode 100644
index 0000000..a308569
--- /dev/null
+++ b/docs/media/inbetweener_soma.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b1ea9155fa6659cc18cdc701237e6d678269cfbbd6dd4638e98c1dcf6a8365b2
+size 789948
diff --git a/docs/media/locomotion_directional_g1.gif b/docs/media/locomotion_directional_g1.gif
new file mode 100644
index 0000000..6355c02
--- /dev/null
+++ b/docs/media/locomotion_directional_g1.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ffaef6f57d18faf60e2f6480d4ba7768053a242405663d5e14ca17bd48c6864a
+size 10455541
diff --git a/docs/media/locomotion_directional_soma.gif b/docs/media/locomotion_directional_soma.gif
new file mode 100644
index 0000000..d80801b
--- /dev/null
+++ b/docs/media/locomotion_directional_soma.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2192edbecc62bbefd31aa676ecc8839ce192ffbea781e99c19f2bb038e547db1
+size 12520213
diff --git a/docs/media/locomotion_styles_g1.gif b/docs/media/locomotion_styles_g1.gif
new file mode 100644
index 0000000..86223ec
--- /dev/null
+++ b/docs/media/locomotion_styles_g1.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b553b158d060fce6cc2ce6244fdfe4d5e79b0ea3d76d91e3357187118c899810
+size 7999228
diff --git a/docs/media/locomotion_styles_soma.gif b/docs/media/locomotion_styles_soma.gif
new file mode 100644
index 0000000..a401360
--- /dev/null
+++ b/docs/media/locomotion_styles_soma.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bca8ca26830dffc577e04c7037b5cb7d6fa92b6554cd2bce0c1e8edc762020eb
+size 7121247
diff --git a/docs/media/locomotion_targets_g1.gif b/docs/media/locomotion_targets_g1.gif
new file mode 100644
index 0000000..9c5bf69
--- /dev/null
+++ b/docs/media/locomotion_targets_g1.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f40e60fca418ebf86d1d48a643f070fd3ea709717841ef2f66c88ad03937930
+size 10812180
diff --git a/docs/media/locomotion_targets_soma.gif b/docs/media/locomotion_targets_soma.gif
new file mode 100644
index 0000000..adda225
--- /dev/null
+++ b/docs/media/locomotion_targets_soma.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b4e1a1b110e9d9e6f448c7771a6189bba84c3dd1427e7696082cd75db4586991
+size 12487412
diff --git a/docs/media/scene_editor.png b/docs/media/scene_editor.png
new file mode 100644
index 0000000..2e8e6d6
--- /dev/null
+++ b/docs/media/scene_editor.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4f479c2c145e0767d879988b47ef49f792f2c0350a46b0dadaa815ba9865c3c7
+size 342466
diff --git a/docs/media/scene_preview_g1.gif b/docs/media/scene_preview_g1.gif
new file mode 100644
index 0000000..369f623
--- /dev/null
+++ b/docs/media/scene_preview_g1.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e8ce800870d3bbab6f45d3f8c2351be462deda3b6fa7526144f1329ac9de016
+size 3059798
diff --git a/docs/media/scene_preview_soma.gif b/docs/media/scene_preview_soma.gif
new file mode 100644
index 0000000..8fd7d09
--- /dev/null
+++ b/docs/media/scene_preview_soma.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4f582b549d39a61e36d67abfa1037faa5df8693ea3f54994a5f5ce26cf92f60b
+size 2388246
diff --git a/docs/media/sit_hold_soma.gif b/docs/media/sit_hold_soma.gif
new file mode 100644
index 0000000..60dffb9
--- /dev/null
+++ b/docs/media/sit_hold_soma.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0a11b611ddec35abbf61e415e9af8bd828bbeaea1496cb2de669232e1d3e2e77
+size 1346829
diff --git a/docs/media/smart_primitive_editor.png b/docs/media/smart_primitive_editor.png
new file mode 100644
index 0000000..5de8761
--- /dev/null
+++ b/docs/media/smart_primitive_editor.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5048cb6670d4b645ca8b3a5a664364d1c44e10e034a2e35e7e40a1496666b22f
+size 376525
diff --git a/docs/media/state_machine.png b/docs/media/state_machine.png
new file mode 100644
index 0000000..ec62ce2
--- /dev/null
+++ b/docs/media/state_machine.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:24e83afad1311ef8f788cb326c72803ea4e5494d0c52a5843a584cf7522b835e
+size 102588
diff --git a/docs/media/target_b_flow.png b/docs/media/target_b_flow.png
new file mode 100644
index 0000000..b92948f
--- /dev/null
+++ b/docs/media/target_b_flow.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:53ce8087f3df34e2ed953be2175911f7850499b40e05b67b388478d08148c1fa
+size 34075
diff --git a/docs/media/teaser.jpg b/docs/media/teaser.jpg
new file mode 100644
index 0000000..6e83461
--- /dev/null
+++ b/docs/media/teaser.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:910023ae13554fa110f82b2be2e534836ee0ccbc613cb6db3ebe451f53c387fc
+size 213636
diff --git a/docs/media/tut_inbetweener_01_open.png b/docs/media/tut_inbetweener_01_open.png
new file mode 100644
index 0000000..0936efb
--- /dev/null
+++ b/docs/media/tut_inbetweener_01_open.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6101ae187e5d8aa040ad32e6da1191e67bdd86aa36614eb94903368e02749dd8
+size 181256
diff --git a/docs/media/tut_inbetweener_02_Pose1.png b/docs/media/tut_inbetweener_02_Pose1.png
new file mode 100644
index 0000000..1ec558b
--- /dev/null
+++ b/docs/media/tut_inbetweener_02_Pose1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08f9ee6324d0b55ac6553d1bbab178ed8c79a8018010feccc5af0e4ad977cbb5
+size 2395
diff --git a/docs/media/tut_inbetweener_03_End.png b/docs/media/tut_inbetweener_03_End.png
new file mode 100644
index 0000000..5f8e535
--- /dev/null
+++ b/docs/media/tut_inbetweener_03_End.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:407e3bc848eae84356eb5c890c4a91fadd3592f2c40b91ef04159a421a264af0
+size 808
diff --git a/docs/media/tut_inbetweener_04_Move.png b/docs/media/tut_inbetweener_04_Move.png
new file mode 100644
index 0000000..3950195
--- /dev/null
+++ b/docs/media/tut_inbetweener_04_Move.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9c030fce998316ced0877651e4a4f6f7a7625497e64e2daa00dac8ba6a010104
+size 167677
diff --git a/docs/media/tut_inbetweener_05_EndMove.png b/docs/media/tut_inbetweener_05_EndMove.png
new file mode 100644
index 0000000..40b4e7e
--- /dev/null
+++ b/docs/media/tut_inbetweener_05_EndMove.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4d517717e9a1afc8082330f6b167d2c2e2f08d1252141d70220219ea5f6443aa
+size 30737
diff --git a/docs/media/tut_inbetweener_06_generate.png b/docs/media/tut_inbetweener_06_generate.png
new file mode 100644
index 0000000..217544f
--- /dev/null
+++ b/docs/media/tut_inbetweener_06_generate.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f920e60ea3a25a7f2d010efe0112b8c5ad3bdf1f60db1df6f4119b4d9652eadc
+size 932
diff --git a/docs/media/tut_inbetweener_07_visibility.png b/docs/media/tut_inbetweener_07_visibility.png
new file mode 100644
index 0000000..492cf01
--- /dev/null
+++ b/docs/media/tut_inbetweener_07_visibility.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f9aec715febcf079b46e36a7e6806c10dbf6984af9939b18c59cef8bf80d59e
+size 2732
diff --git a/docs/media/tut_inbetweener_08_targetpose.png b/docs/media/tut_inbetweener_08_targetpose.png
new file mode 100644
index 0000000..9273b40
--- /dev/null
+++ b/docs/media/tut_inbetweener_08_targetpose.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4d07fc4587d112e78436d6f733164a15c4e20465d2075a265826f8e90cdeef00
+size 93035
diff --git a/docs/media/tut_inbetweener_09_startpose.png b/docs/media/tut_inbetweener_09_startpose.png
new file mode 100644
index 0000000..bb07f22
--- /dev/null
+++ b/docs/media/tut_inbetweener_09_startpose.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:984ace9d7be2054396dd616279b61473e46ff30e92cb61882bdbc4e70b4e1294
+size 95507
diff --git a/docs/media/tut_inbetweener_10_addposes.png b/docs/media/tut_inbetweener_10_addposes.png
new file mode 100644
index 0000000..2ff0c5c
--- /dev/null
+++ b/docs/media/tut_inbetweener_10_addposes.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d14d5113d78380fe708cac98b417612b1b06b4faff8678785a600bea2a7dc9fc
+size 3305
diff --git a/docs/media/tut_inbetweener_11_moveposes.png b/docs/media/tut_inbetweener_11_moveposes.png
new file mode 100644
index 0000000..661d5e1
--- /dev/null
+++ b/docs/media/tut_inbetweener_11_moveposes.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:990678a13b0194ec90978b335dd5de45c31d322ca2ae522e4a7bbffaa6b52d5c
+size 1695
diff --git a/docs/media/tut_inbetweener_12_movepose.png b/docs/media/tut_inbetweener_12_movepose.png
new file mode 100644
index 0000000..51a9909
--- /dev/null
+++ b/docs/media/tut_inbetweener_12_movepose.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3763ca7a415dd2e1fc44b3186bf72f0255684453083f3fe079d4217a54f2864a
+size 201538
diff --git a/docs/media/tut_inbetweener_13_movepose.png b/docs/media/tut_inbetweener_13_movepose.png
new file mode 100644
index 0000000..55527e7
--- /dev/null
+++ b/docs/media/tut_inbetweener_13_movepose.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a049bf7a4b2d3c928ae82d4f9dcf227a7c9446a35230e7ef22353343ebf00a66
+size 164583
diff --git a/docs/media/tut_inbetweener_14_clip.png b/docs/media/tut_inbetweener_14_clip.png
new file mode 100644
index 0000000..51d8958
--- /dev/null
+++ b/docs/media/tut_inbetweener_14_clip.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7aa07428e8c690c9d055120b6622c736950b8e2325f2dc2b2a466d8c735cb67c
+size 1888
diff --git a/docs/media/tut_inbetweener_15_newclippose.png b/docs/media/tut_inbetweener_15_newclippose.png
new file mode 100644
index 0000000..a3c4982
--- /dev/null
+++ b/docs/media/tut_inbetweener_15_newclippose.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0f02eca3189a73b07867ddb8188fd01dc8492de29d9e0955437fa91afe8c8b8d
+size 114485
diff --git a/docs/media/tut_inbetweener_16_seconds.png b/docs/media/tut_inbetweener_16_seconds.png
new file mode 100644
index 0000000..c9791ea
--- /dev/null
+++ b/docs/media/tut_inbetweener_16_seconds.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1e24be64df3bcb8c5172368e751a74fe21051c4a357579a78c6a4e81858d2bd
+size 838
diff --git a/docs/media/tut_inbetweener_17_frames.png b/docs/media/tut_inbetweener_17_frames.png
new file mode 100644
index 0000000..9009fca
--- /dev/null
+++ b/docs/media/tut_inbetweener_17_frames.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2201e15b1b913f33b663f6401c1607edeac97634c0abfb89d1e21e0ee36700bf
+size 640
diff --git a/docs/media/tut_inbetweener_18_rotate.png b/docs/media/tut_inbetweener_18_rotate.png
new file mode 100644
index 0000000..7c42239
--- /dev/null
+++ b/docs/media/tut_inbetweener_18_rotate.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:05cce4adf4561d1c2e038066014795534ead21dc1ed126f675c76d09d3c75bbc
+size 89204
diff --git a/docs/media/tut_inbetweener_19_settings.png b/docs/media/tut_inbetweener_19_settings.png
new file mode 100644
index 0000000..4894764
--- /dev/null
+++ b/docs/media/tut_inbetweener_19_settings.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5b370a6860dc7567fd22f42118a2ebba288d9819c5e38dd966d41c10ccedfb62
+size 2278
diff --git a/docs/media/tut_inbetweener_20_settings.png b/docs/media/tut_inbetweener_20_settings.png
new file mode 100644
index 0000000..a20b9b5
--- /dev/null
+++ b/docs/media/tut_inbetweener_20_settings.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:52fdaa4f8bee4a7ea443068dc0f91c3bd490364fdc181a5ed49dd9c804f13783
+size 3491
diff --git a/docs/media/tut_inbetweener_21_pose2.png b/docs/media/tut_inbetweener_21_pose2.png
new file mode 100644
index 0000000..44a4b88
--- /dev/null
+++ b/docs/media/tut_inbetweener_21_pose2.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5110c201fe30bd806a22ef07aa873929683a21cbcf0069cdaa7efea86f3d2186
+size 68898
diff --git a/docs/media/tut_pivot_00_problem.gif b/docs/media/tut_pivot_00_problem.gif
new file mode 100644
index 0000000..c4b8de7
--- /dev/null
+++ b/docs/media/tut_pivot_00_problem.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15cc0031f78244763416bcb941e2cd90e26993bc65d1feaae0233ef4a1a3c832
+size 560720
diff --git a/docs/media/tut_pivot_01_layout.png b/docs/media/tut_pivot_01_layout.png
new file mode 100644
index 0000000..46b4a47
--- /dev/null
+++ b/docs/media/tut_pivot_01_layout.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:579e1c552c8af8dac3e6b3785c2d167a06577f1c33fe6d2824f472cc7a165c31
+size 200650
diff --git a/docs/media/tut_pivot_02_cases.png b/docs/media/tut_pivot_02_cases.png
new file mode 100644
index 0000000..76b2aa9
--- /dev/null
+++ b/docs/media/tut_pivot_02_cases.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f31d17f89d51bf42eea6e1c39bb29ebc68799e778869b2156fc966b5848f5f0
+size 492481
diff --git a/docs/media/tut_pivot_03_alignment.gif b/docs/media/tut_pivot_03_alignment.gif
new file mode 100644
index 0000000..8cf1e3e
--- /dev/null
+++ b/docs/media/tut_pivot_03_alignment.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba0f8677a2c065d936d68c772682af3c444744c5e31921b7011b65983b88095e
+size 3826752
diff --git a/docs/media/tut_sceneedit_01_open.png b/docs/media/tut_sceneedit_01_open.png
new file mode 100644
index 0000000..06ee715
--- /dev/null
+++ b/docs/media/tut_sceneedit_01_open.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:30020318100d40177253d557e2c4f3302f55aba0d97c12f6db8785a0ca7bdf91
+size 159624
diff --git a/docs/media/tut_sceneedit_02_add.png b/docs/media/tut_sceneedit_02_add.png
new file mode 100644
index 0000000..69d605a
--- /dev/null
+++ b/docs/media/tut_sceneedit_02_add.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7776eb21e2fec8b6ede307e0602169a64ee3e78fd0581b3873e73f3d957fd2ee
+size 1985
diff --git a/docs/media/tut_sceneedit_03_addsmartprim.png b/docs/media/tut_sceneedit_03_addsmartprim.png
new file mode 100644
index 0000000..9bfd067
--- /dev/null
+++ b/docs/media/tut_sceneedit_03_addsmartprim.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:71e9621e06ebcb15c066bf5b8a5ccca07a91d003294494122d9e50ccc22802ef
+size 1396
diff --git a/docs/media/tut_sceneedit_04_addsavoid.png b/docs/media/tut_sceneedit_04_addsavoid.png
new file mode 100644
index 0000000..8031214
--- /dev/null
+++ b/docs/media/tut_sceneedit_04_addsavoid.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:07f29f1ecce09be12c70d1b6e5c8489bb701d37bbbd43f653cc891ae6def5afa
+size 919
diff --git a/docs/media/tut_sceneedit_05_primpropsset.png b/docs/media/tut_sceneedit_05_primpropsset.png
new file mode 100644
index 0000000..cacfa0d
--- /dev/null
+++ b/docs/media/tut_sceneedit_05_primpropsset.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9e063703dc96237e8f7baf050775776f835927bfc555fbe708dcc649366edf39
+size 7592
diff --git a/docs/media/tut_sceneedit_06_primmove.png b/docs/media/tut_sceneedit_06_primmove.png
new file mode 100644
index 0000000..c871b7c
--- /dev/null
+++ b/docs/media/tut_sceneedit_06_primmove.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:be196bec92f4ee8b637cc1f574e4fc9b03e17e7344d51397cc16e10429683e05
+size 92302
diff --git a/docs/media/tut_sceneedit_07_solidcube.png b/docs/media/tut_sceneedit_07_solidcube.png
new file mode 100644
index 0000000..2f93eca
--- /dev/null
+++ b/docs/media/tut_sceneedit_07_solidcube.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ffb6f1e13f97e22d3740507167d530832406c0c4c66bc01a75f974104d5f7c68
+size 1024
diff --git a/docs/media/tut_sceneedit_08_obstacle.png b/docs/media/tut_sceneedit_08_obstacle.png
new file mode 100644
index 0000000..c7770b8
--- /dev/null
+++ b/docs/media/tut_sceneedit_08_obstacle.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cb9f49c8aea4b7016f4ed25c6ba259187f3041d1892bad29a3462d98893ef6cf
+size 74484
diff --git a/docs/media/tut_sceneedit_09_layout.png b/docs/media/tut_sceneedit_09_layout.png
new file mode 100644
index 0000000..7d365cc
--- /dev/null
+++ b/docs/media/tut_sceneedit_09_layout.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fbffe98dcf07b3d74c255c0bcc48cb52dbc47234e91c52d12e818704f0228665
+size 160947
diff --git a/docs/media/tut_sceneedit_10_layoutobstacles.png b/docs/media/tut_sceneedit_10_layoutobstacles.png
new file mode 100644
index 0000000..a1b2ffc
--- /dev/null
+++ b/docs/media/tut_sceneedit_10_layoutobstacles.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0c5f32282e2f2b2135130a6059737fb7b5fe54fc7ec6c8af926972643950989
+size 190564
diff --git a/docs/media/tut_sceneprev_01_start.png b/docs/media/tut_sceneprev_01_start.png
new file mode 100644
index 0000000..9600d93
--- /dev/null
+++ b/docs/media/tut_sceneprev_01_start.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cf7e334aa5c7dadad38f208c1ba3be03ab080620a10549eb2504e6b03fd7e3a4
+size 240968
diff --git a/docs/media/tut_smartprim_01_open.png b/docs/media/tut_smartprim_01_open.png
new file mode 100644
index 0000000..5741a97
--- /dev/null
+++ b/docs/media/tut_smartprim_01_open.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:641d51e5e348d89fa49732247c28d81ea8a7f5a0af4e5a1e38ef129ba254bd79
+size 107967
diff --git a/docs/media/tut_smartprim_02_SOMA.png b/docs/media/tut_smartprim_02_SOMA.png
new file mode 100644
index 0000000..25b874e
--- /dev/null
+++ b/docs/media/tut_smartprim_02_SOMA.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:75474de2e1acdf75045b7308611df48f09274fb3d5a8234a39aa89ac8fc3f95a
+size 1286
diff --git a/docs/media/tut_smartprim_03_addnode.png b/docs/media/tut_smartprim_03_addnode.png
new file mode 100644
index 0000000..4eff3f8
--- /dev/null
+++ b/docs/media/tut_smartprim_03_addnode.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ca433e78c2a9c61e8f4ccbfc589013db768f41c4cda995cb82c35fac76fe3125
+size 1298
diff --git a/docs/media/tut_smartprim_04_interactionbox.png b/docs/media/tut_smartprim_04_interactionbox.png
new file mode 100644
index 0000000..e632ab0
--- /dev/null
+++ b/docs/media/tut_smartprim_04_interactionbox.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3db40d27a5b3ac9b5583a2054f7d30b905ac8e73a38686cbae9f82b007a4fcc0
+size 1688
diff --git a/docs/media/tut_smartprim_05_hierarchy.png b/docs/media/tut_smartprim_05_hierarchy.png
new file mode 100644
index 0000000..6bbcf4e
--- /dev/null
+++ b/docs/media/tut_smartprim_05_hierarchy.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5362dbc1737955b610331498032842456a94a6e0ba8cc9da7a616c7ffd2938d9
+size 3316
diff --git a/docs/media/tut_smartprim_06_interactionbox.png b/docs/media/tut_smartprim_06_interactionbox.png
new file mode 100644
index 0000000..79e5b6e
--- /dev/null
+++ b/docs/media/tut_smartprim_06_interactionbox.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0577a53d194400e700ec18746606b401d4bffe4d01dcfa895f7a48edd7d66f87
+size 5027
diff --git a/docs/media/tut_smartprim_07_interactionboxset.png b/docs/media/tut_smartprim_07_interactionboxset.png
new file mode 100644
index 0000000..02bd05b
--- /dev/null
+++ b/docs/media/tut_smartprim_07_interactionboxset.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8a71f3cd2625cf5ea31b5e41ac0e7112c4c03f786104d07ce76f94122dcce094
+size 4016
diff --git a/docs/media/tut_smartprim_08_interactionboxtransf.png b/docs/media/tut_smartprim_08_interactionboxtransf.png
new file mode 100644
index 0000000..894e43b
--- /dev/null
+++ b/docs/media/tut_smartprim_08_interactionboxtransf.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:944cf22a4ac44937a55560e5c3316a11d696cb8dcef0f28cbba2c2c6de0065a8
+size 45148
diff --git a/docs/media/tut_smartprim_09_addpivot.png b/docs/media/tut_smartprim_09_addpivot.png
new file mode 100644
index 0000000..73f21f9
--- /dev/null
+++ b/docs/media/tut_smartprim_09_addpivot.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8712b157ecb16fe597f73cbb74e47d2a196e868a2d369861df42ed971e460227
+size 1745
diff --git a/docs/media/tut_smartprim_10_pivotprops.png b/docs/media/tut_smartprim_10_pivotprops.png
new file mode 100644
index 0000000..9f3303f
--- /dev/null
+++ b/docs/media/tut_smartprim_10_pivotprops.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b8579c9364363f73f3d5716ff3bf0e210cf2800c56ddfcf52727679a83c5450c
+size 6287
diff --git a/docs/media/tut_smartprim_11_pivotpropsset.png b/docs/media/tut_smartprim_11_pivotpropsset.png
new file mode 100644
index 0000000..f37531d
--- /dev/null
+++ b/docs/media/tut_smartprim_11_pivotpropsset.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e804df49733b46e87b6c18d3232b4748704f103940733eb1eebdcc145041b533
+size 6850
diff --git a/docs/media/tut_smartprim_12_addpose.png b/docs/media/tut_smartprim_12_addpose.png
new file mode 100644
index 0000000..311a0d4
--- /dev/null
+++ b/docs/media/tut_smartprim_12_addpose.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a1671d05e87f9919e0271dd501f166452b7400181f9be3a6b9bbd3aae1b915b
+size 1767
diff --git a/docs/media/tut_smartprim_13_poseprops.png b/docs/media/tut_smartprim_13_poseprops.png
new file mode 100644
index 0000000..47948e0
--- /dev/null
+++ b/docs/media/tut_smartprim_13_poseprops.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3b4cccb2125a8eff81390a252931b5706f93553351b2e6dfd5b4aef0fc9bfe08
+size 2775
diff --git a/docs/media/tut_smartprim_14_posepropsset.png b/docs/media/tut_smartprim_14_posepropsset.png
new file mode 100644
index 0000000..1fa8377
--- /dev/null
+++ b/docs/media/tut_smartprim_14_posepropsset.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c3efa92c53d07da2d7e4e73eedfd4b93fe943e370aa1de838730d35c4fdca9d
+size 3902
diff --git a/docs/media/tut_smartprim_15_posetransf.png b/docs/media/tut_smartprim_15_posetransf.png
new file mode 100644
index 0000000..a5ee21b
--- /dev/null
+++ b/docs/media/tut_smartprim_15_posetransf.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1fbc65fa4c8130838e2be28b5870007b77519efd5c744ca04a9026b6bd7ea642
+size 73356
diff --git a/docs/media/tut_smartprim_16_pose2propsset.png b/docs/media/tut_smartprim_16_pose2propsset.png
new file mode 100644
index 0000000..4b19ebe
--- /dev/null
+++ b/docs/media/tut_smartprim_16_pose2propsset.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f52b87c1c334ca91b2eff0acd414e3d550c782ac9a6940011171b34092f38f70
+size 3889
diff --git a/docs/media/tut_smartprim_17_addsequence.png b/docs/media/tut_smartprim_17_addsequence.png
new file mode 100644
index 0000000..52abac6
--- /dev/null
+++ b/docs/media/tut_smartprim_17_addsequence.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b2b50740d560556436c658f9345a25a9fb959d33b6716633df991f48311e1e92
+size 1412
diff --git a/docs/media/tut_smartprim_18_pose2transf.png b/docs/media/tut_smartprim_18_pose2transf.png
new file mode 100644
index 0000000..bb98f44
--- /dev/null
+++ b/docs/media/tut_smartprim_18_pose2transf.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed3d95f4da79f160dd3e157105ecb54459560b13987eeec11f66ec0373dc0a20
+size 94858
diff --git a/docs/media/tut_smartprim_19_sequpivot.png b/docs/media/tut_smartprim_19_sequpivot.png
new file mode 100644
index 0000000..7cfc73d
--- /dev/null
+++ b/docs/media/tut_smartprim_19_sequpivot.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1af900985d36290e76d3b097889a70c90bf688152078a23ce67eff38b59c3f0f
+size 2428
diff --git a/docs/media/tut_smartprim_20_sequdone.png b/docs/media/tut_smartprim_20_sequdone.png
new file mode 100644
index 0000000..6289fdb
--- /dev/null
+++ b/docs/media/tut_smartprim_20_sequdone.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a464e9171dcd661be81b239e7562e4bb8f72aa7d4e5d051c69da3e55f2c3e9b2
+size 2571
diff --git a/docs/media/tutorial_end_inbetweener.gif b/docs/media/tutorial_end_inbetweener.gif
new file mode 100644
index 0000000..b9bb0c6
--- /dev/null
+++ b/docs/media/tutorial_end_inbetweener.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:164e0b4e9652f637a3a52f50c4a743686e2af691171f1bedc3e7afa6a045dcfb
+size 609982
diff --git a/docs/media/tutorial_end_scenepreview.gif b/docs/media/tutorial_end_scenepreview.gif
new file mode 100644
index 0000000..2e875d1
--- /dev/null
+++ b/docs/media/tutorial_end_scenepreview.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e985f2262936f4029a0ccfcdc07e3d8c04f6ae08f108d71cd4b721059fe9fafc
+size 3718163
diff --git a/docs/media/tutorial_final_results.gif b/docs/media/tutorial_final_results.gif
new file mode 100644
index 0000000..1d2d210
--- /dev/null
+++ b/docs/media/tutorial_final_results.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c4427822f39dc2232712b2e7ec37b3b69c8c8b6a1801b685fa887e335bdfc745
+size 2864037
diff --git a/docs/media/tutorial_first_anim.gif b/docs/media/tutorial_first_anim.gif
new file mode 100644
index 0000000..1903fc7
--- /dev/null
+++ b/docs/media/tutorial_first_anim.gif
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:41e8be6058dad72d487b1394d767ab6e07514fe71cd7ebd65e60f592bf00230c
+size 472262
diff --git a/docs/media/velocity_matching_flow.png b/docs/media/velocity_matching_flow.png
new file mode 100644
index 0000000..5694aca
--- /dev/null
+++ b/docs/media/velocity_matching_flow.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8daa10c0f957384f7c142a40281120d37851c2eabfc456f4659a82a3417576f6
+size 59981
diff --git a/docs/onnx_inference.md b/docs/onnx_inference.md
new file mode 100644
index 0000000..727c03e
--- /dev/null
+++ b/docs/onnx_inference.md
@@ -0,0 +1,121 @@
+# ONNX inference and batching
+
+This page is for running the MotionBricks ONNX models without the bundled engines, such as in another inference library, or for many characters at once in one batch. The [Runtime API](runtime_api.md) engines cover a single character with TensorRT.
+
+MotionBricks includes one ONNX file per model and precision. All four accept a variable number of independent requests, including a batch of one.
+
+| Model | FP32 | Mixed FP16 | Interface |
+| --- | --- | --- | --- |
+| SOMA | [mmm_v6_soma_fp32.onnx](../motionbricks/assets/onnx/soma/mmm_v6_soma_fp32.onnx) | [mmm_v6_soma_fp16.onnx](../motionbricks/assets/onnx/soma/mmm_v6_soma_fp16.onnx) | [SOMA model card](soma_model.md) |
+| Unitree G1 | [mmm_v6_g1_fp32.onnx](../motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp32.onnx) | [mmm_v6_g1_fp16.onnx](../motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp16.onnx) | [Unitree G1 model card](unitree_g1_model.md) |
+
+Each folder also holds a model manifest, [soma_n1.json](../motionbricks/assets/onnx/soma/soma_n1.json) and [unitree_g1_n1.json](../motionbricks/assets/onnx/unitree_g1/unitree_g1_n1.json), with the joint names and the tensor specs for a batch of one.
+
+The files use Git LFS. Run `git lfs pull` after cloning to download them. To recreate them from the checkpoints, use the [exporter](../tools/onnx/README.md). The models are licensed under the NVIDIA Open Model Agreement, as stated in [LICENSE.md](../motionbricks/assets/onnx/LICENSE.md).
+
+## Tensors
+
+`N` is the number of requests in the batch. The model cards explain what each tensor holds and how to prepare it.
+
+| Model | Inputs | Outputs |
+| --- | --- | --- |
+| SOMA | <ul><li><code>global_root_values</code> [N, 8, 5]</li><li><code>local_root_values</code> [N, 8, 4]</li><li><code>local_poses</code> [N, 8, 267]</li><li><code>has_global_root_values</code> [N, 8]</li><li><code>has_local_root_values</code> [N, 8]</li><li><code>has_local_poses</code> [N, 8]</li><li><code>allowed_pred_num_tokens</code> [N, 11]</li></ul> | <ul><li><code>pred_global_motions</code> [N, 64, 366]</li><li><code>pred_num_tokens</code> [N]</li></ul> |
+| Unitree G1 | <ul><li><code>context_qpos</code> [N, 4, 36]</li><li><code>target_qpos</code> [N, 4, 36]</li><li><code>has_global_root_values</code> [N, 8]</li><li><code>has_local_root_values</code> [N, 8]</li><li><code>has_local_poses</code> [N, 8]</li><li><code>allowed_pred_num_tokens</code> [N, 11]</li></ul> | <ul><li><code>pred_qpos</code> [N, 64, 36]</li><li><code>pred_foot_contacts</code> [N, 64, 4]</li><li><code>pred_num_tokens</code> [N]</li></ul> |
+
+Floating point inputs and outputs use FP32 in both precisions. The masks use INT32, with 0 for disabled and 1 for enabled. `allowed_pred_num_tokens` holds one INT32 flag for each token count from 6 to 16. Each request must allow at least one token count.
+
+## Prepare a batch
+
+All inputs to one generation must use the same positive `N`. Their other dimensions are fixed. Each request has its own poses, masks, and allowed token counts. Requests are processed independently.
+
+ONNX Runtime is not a MotionBricks dependency. Add it when you run your script, for example with `uv run --with onnxruntime python my_batch.py`.
+
+With ONNX Runtime, prepare each request with a batch size of one. Then concatenate the requests along axis 0:
+
+```python
+import numpy as np
+import onnxruntime as ort
+
+session = ort.InferenceSession(
+ "motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp32.onnx",
+ providers=["CPUExecutionProvider"],
+)
+
+# requests contains complete input dictionaries, each with a batch size of one.
+inputs = {
+ name: np.concatenate([request[name] for request in requests], axis=0)
+ for name in requests[0]
+}
+outputs = dict(zip(
+ [output.name for output in session.get_outputs()],
+ session.run(None, inputs),
+))
+
+# Read the raw frames for each request.
+motions = [
+ outputs["pred_qpos"][i, :4 * int(count)]
+ for i, count in enumerate(outputs["pred_num_tokens"])
+]
+```
+
+The ONNX interface places no fixed upper limit on `N`. Available memory and the inference library, such as ONNX Runtime or TensorRT, determine practical batch sizes.
+
+## Read the outputs
+
+Request `i` produces `4 * pred_num_tokens[i]` raw frames at 30 Hz, between 24 and 64. The rest of its output space is unused. The first token holds the context poses, and the last token holds the target poses.
+
+The G1 model returns its foot contacts in `pred_foot_contacts`, for the same frames as `pred_qpos`. The SOMA model has no separate foot contact output. Its `pred_global_motions` holds the motion and the foot contacts together, and the SOMA engine decodes both.
+
+The ONNX output includes the [boundary frames](runtime_api.md#generation-length) and has no endpoint correction. The SOMA and G1 engines remove the boundary frames and apply endpoint correction. Their motion therefore starts exactly at the last context pose and ends at the first target pose. In a batch, trim, correct, and place each request separately.
+
+## TensorRT and the demos
+
+The demos build TensorRT plans with a batch size of one. They reuse their device buffers and CUDA graph between generations.
+
+The generic `InferenceEngine` accepts `TensorRTBuildOptions(batch_size=N)` to build a TensorRT plan for another fixed batch size. The plan cache stores a separate plan for each size. The SOMA and G1 engine classes check their plan against a batch size of one. With a larger batch, run `InferenceEngine` directly. Your application then prepares the inputs and reads the outputs of each request.
+
+To change the batch size between generations with one TensorRT plan, create optimization profiles and manage the tensor shapes and buffers in your application.
+
+## Inference performance
+
+The table shows the GPU time of the TensorRT plan alone for one batch, with the requests per second in parentheses. Input preparation, output decoding, and endpoint correction are not included.
+
+| Model | N = 1 | N = 8 | N = 16 | N = 32 |
+| --- | --- | --- | --- | --- |
+| SOMA, FP32 | 2.50 ms (400) | 2.96 ms (2,706) | 3.74 ms (4,280) | 5.28 ms (6,063) |
+| SOMA, mixed FP16 | 1.28 ms (778) | 1.54 ms (5,179) | 1.87 ms (8,535) | 3.93 ms (8,138) |
+| Unitree G1, FP32 | 2.67 ms (375) | 3.78 ms (2,116) | 5.17 ms (3,096) | 7.81 ms (4,097) |
+| Unitree G1, mixed FP16 | 1.63 ms (613) | 1.91 ms (4,194) | 2.36 ms (6,783) | 3.38 ms (9,449) |
+
+The plans were timed with `trtexec` from TensorRT 10.8.0.43, the version the runtime uses, on an NVIDIA GeForce RTX 4090 under Windows. The inputs were already on the GPU, and a CUDA graph replayed each inference, as in the demos. Each batch repeats one real request. The mixed FP16 runs enable FP16 kernels like the demos. Each value comes from the fastest of six plan builds, and every timed plan matched ONNX Runtime on the same request. Timings vary from one build to the next, most for the mixed FP16 models.
+
+The G1 runs disable TF32 like the runtime. Their FP32 convolutions and matrix multiplies then run without Tensor Cores, so G1 FP32 slows down more as the batch grows. For comparison:
+
+| Unitree G1, FP32 | N = 16 | N = 32 |
+| --- | --- | --- |
+| TF32 disabled, as in the runtime | 5.17 ms (3,096) | 7.81 ms (4,097) |
+| TF32 allowed | 4.06 ms (3,936) | 5.78 ms (5,537) |
+
+The [Inference](unitree_g1_model.md#inference) section of the Unitree G1 model card explains why TF32 stays disabled.
+
+To measure your own GPU, run `trtexec` with the batch size in `--shapes`. These commands time the FP32 models with a batch of 8.
+
+SOMA:
+
+```sh
+trtexec --onnx=motionbricks/assets/onnx/soma/mmm_v6_soma_fp32.onnx --shapes=global_root_values:8x8x5,has_global_root_values:8x8,local_root_values:8x8x4,has_local_root_values:8x8,local_poses:8x8x267,has_local_poses:8x8,allowed_pred_num_tokens:8x11 --useCudaGraph --noDataTransfers
+```
+
+Unitree G1, with TF32 disabled like the runtime:
+
+```sh
+trtexec --onnx=motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp32.onnx --shapes=context_qpos:8x4x36,target_qpos:8x4x36,has_global_root_values:8x8,has_local_root_values:8x8,has_local_poses:8x8,allowed_pred_num_tokens:8x11 --useCudaGraph --noDataTransfers --noTF32
+```
+
+For the mixed FP16 models, use the `_fp16.onnx` file and add `--fp16`. `trtexec` fills the inputs with random values unless `--loadInputs` gives it real requests. `trtexec` comes with the TensorRT packages on the [TensorRT download page](https://developer.nvidia.com/tensorrt/download).
+
+## Further reference
+
+- [SOMA model card](soma_model.md) and [Unitree G1 model card](unitree_g1_model.md): what each tensor holds, the joint order, and the model spaces.
+- [Runtime API](runtime_api.md): the engines that prepare these tensors for a batch size of one.
+- [ONNX exporter](../tools/onnx/README.md): recreating the ONNX files from the checkpoints.
diff --git a/docs/runtime_api.md b/docs/runtime_api.md
new file mode 100644
index 0000000..08c3165
--- /dev/null
+++ b/docs/runtime_api.md
@@ -0,0 +1,334 @@
+# Runtime API
+
+This page shows how to use the `motionbricks` library in your own application. The sections follow the order of an integration: set up an engine, prepare poses, generate, and chain generations. The `app` package holds demos built on the library. Two of them show it at work. The [Inbetweener](inbetweener.md) chains generations by hand, so each step stays visible. [Scene Preview](scene_preview.md) uses a motion player and a recorder for continuous locomotion and interactions.
+
+## Overview
+
+### Generation flow
+
+MotionBricks builds continuous motion one generation at a time. Each generation takes four context poses and one to four target poses. Your app plays the generated motion up to the transition point and records every pose it shows. The next generation reads its context from those records and generates toward a new target.
+
+![MotionBricks generation flow: the engine generates from context and target poses, and the last four played poses become the next context](media/generation_flow.png)
+
+| Step | API | Section |
+| --- | --- | --- |
+| Prepare poses | `ClipRegistry`, `sample()` with `root_offset`, or poses from your application | [Place poses in the scene](#place-poses-in-the-scene), [Clips](#clips) |
+| Fill the tokens | `create_input()`, `update_from_poses()`, `update_from_recorder()` | [Engines](#engines), [Record what you show](#record-what-you-show) |
+| Generate | `generate_animation()`, `MotionBricksInferenceConfig`, `TargetPoseInferenceParams` | [Generation settings](#generation-settings) |
+| Play | `sample()`, `output.num_frames`, `sample_foot_contacts()` | [Engines](#engines), [Foot contacts](#foot-contacts) |
+| Record and chain | `MotionRecorder`, `GeneratedMotionPlayer`, `time_to_transition` | [Chaining generations](#chaining-generations) |
+
+The Inbetweener runs this loop once for each target in its list. Scene Preview runs it without end, with targets from locomotion and Smart Primitive behaviors.
+
+### Runnable examples
+
+Two short scripts in [examples](examples) call the library without a viewer or the apps. Run them from the repository root, for either rig:
+
+```sh
+uv run python docs/examples/generate_once.py
+uv run python docs/examples/locomotion_loop.py --model unitree_g1
+```
+
+- [generate_once.py](examples/generate_once.py) generates from clip poses, then chains a second generation from the last four poses it played. It shows the [generation flow](#generation-flow) in its simplest form.
+- [locomotion_loop.py](examples/locomotion_loop.py) runs the [continuous locomotion loop](#a-continuous-locomotion-loop) with a motion player. It steers a jog around a left turn, scales the target poses to the desired speed, and places them ahead of the character.
+
+[_rig.py](examples/_rig.py) holds the setup that both scripts share. It uses only the `motionbricks` package, so you can copy it. The first launch of each model builds a TensorRT plan, which takes a few minutes.
+
+### Packages
+
+| Package | Contents |
+| --- | --- |
+| [motionbricks/model](../motionbricks/model) | Model contracts, engines, context tokens, target tokens, and generation settings |
+| [motionbricks/inference](../motionbricks/inference) | Build, cache, and run TensorRT plans |
+| [motionbricks/animation](../motionbricks/animation), [motionbricks/robotics](../motionbricks/robotics) | `AnimationBuffer`, `DOFAnimationBuffer`, skeletons, and meshes |
+| [motionbricks/io](../motionbricks/io) | BVH, CSV, and USD loading |
+| [motionbricks/runtime](../motionbricks/runtime) | Motion players and recorders, target pose helpers, blend spaces, runtime Smart Primitives, and pivots |
+| [motionbricks/renderers](../motionbricks/renderers) | Newton viewer renderers for meshes, skeletons, and debug shapes |
+| [app/runtime](../app/runtime) | The demo runtime: characters, states, behaviors, documents, and presets |
+
+Each class or function uses its `device` argument, the device of an object it receives, or the current Warp device. For example, `create_input()` uses the engine's device. A recorder uses the device of its reference pose. A renderer uses the device of its skeleton or Newton model.
+
+## Engines
+
+Each engine builds or loads a cached TensorRT plan from a bundled ONNX model, and keeps its buffers and CUDA graph between generations. Engines need a CUDA device and order their work on `engine.stream`. Use an engine as a context manager, or call `close()` when you are done.
+
+```python
+from motionbricks.model.soma.contract import SOMA_N1_FP32_ONNX_PATH
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+
+with MotionBricksSOMAEngine(SOMA_N1_FP32_ONNX_PATH, model_to_runtime=model_to_runtime) as engine:
+ context = engine.create_input(skeleton)
+ target = engine.create_input(skeleton)
+ output = engine.create_output(skeleton)
+
+ context.update_from_poses(context_poses, stream=engine.stream) # four poses
+ target.update_from_poses(target_poses, stream=engine.stream) # one to four poses
+ engine.generate_animation(context, target, output)
+
+ # output.num_frames marks the valid range of the reused buffer.
+ output.sample(time, current_pose, stream=engine.stream)
+ engine.synchronize()
+```
+
+```python
+from motionbricks.model.unitree_g1.contract import UNITREE_G1_N1_FP32_ONNX_PATH
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+
+with MotionBricksUnitreeG1Engine(UNITREE_G1_N1_FP32_ONNX_PATH, model_to_runtime=model_to_runtime) as engine:
+ context = engine.create_input()
+ target = engine.create_input()
+ output = engine.create_output()
+
+ context.update_from_poses(context_joint_q, stream=engine.stream) # four poses
+ target.update_from_poses(target_joint_q, stream=engine.stream) # one to four poses
+ engine.generate_animation(context, target, output)
+
+ # output.num_frames marks the valid range of the reused buffer.
+ output.sample(time, robot_joint_q, stream=engine.stream)
+ engine.synchronize()
+```
+
+| | `MotionBricksSOMAEngine` | `MotionBricksUnitreeG1Engine` |
+| --- | --- | --- |
+| Context and target tokens | `PoseToken`, local joint transforms | `DOFToken`, joint coordinates |
+| Output buffer | `AnimationBuffer`, the same type as loaded BVH clips | `DOFAnimationBuffer`, the same type as loaded CSV clips |
+| Pose | Local joint transforms as `wp.transform`, root first: an XYZ position and an XYZW quaternion per joint | 36 joint coordinates: the root's XYZ position and XYZW quaternion, then 29 joint angles |
+| Model space | Y up, with XZ as the ground plane | Z up, with +X forward |
+| World space | Set by `model_to_runtime` | Set by `model_to_runtime` |
+
+The apps never work with model features directly. They sample poses from clips, move the root to place each pose in the scene, and pass the poses to the engine. Joint values are used as sampled. Clips, Smart Primitive documents, states, and scenes all work with either layout, so the same apps drive both characters. The code that is specific to each rig is small. It lives in [app/runtime/soma](../app/runtime/soma) and [app/runtime/unitree_g1](../app/runtime/unitree_g1). Each folder holds the rig's character, its target pose blender, and its presets.
+
+An engine aligns the context and target for inference, then restores the world placement afterward. It also removes the three [boundary frames](#generation-length) at each end of the generated motion. A SOMA engine finds the model's 30 joints in a skeleton by name. The root must be at index zero. The skeleton can hold more joints, such as the SOMA fingers, which the model does not predict. The model uses the SOMA joint layout and proportions, so a character with another skeleton needs a retargeting step. The G1 engine works directly on the robot's joint coordinates, so you can sample straight into one robot's slice of a Newton `model.joint_q`.
+
+Both engines derive from `MotionBricksEngine` in [motionbricks/model/engine.py](../motionbricks/model/engine.py). It holds the constructor and the generation flow. Each rig engine supplies only the steps that depend on its pose layout: checking the buffers, encoding the context and target, decoding the prediction, and endpoint correction.
+
+The apps create their engines with `create_engine()` in [app/utils/model_loading.py](../app/utils/model_loading.py). It selects the bundled FP32 or mixed FP16 model and reports TensorRT build progress in the viewer. The apps keep one engine at a time. Switching to the other rig closes the current engine before the new one loads, and the TensorRT plan cache keeps the reload short.
+
+### TensorRT builds
+
+The first launch of each model, precision, and batch size builds a TensorRT plan and caches it in `.trt-cache/`. `TensorRTBuildOptions` controls the build:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enable_fp16` | `False` | Lets TensorRT use FP16. The apps enable it with the mixed FP16 model. |
+| `enable_tf32` | `None` | `None` uses the model's default. SOMA permits TF32. G1 disables it, because TF32 changes its motion for little speedup at a batch size of one, as its [model card](unitree_g1_model.md#inference) explains. An explicit value always wins. |
+| `batch_size` | 1 | Builds a TensorRT plan for a fixed batch size |
+
+Pass `force_rebuild=True` to an engine to ignore its cached plan. Each option set has its own cache entry. The mixed FP16 models keep FP32 for normalization, motion geometry, and other sensitive operations. Their inputs and outputs stay FP32. Mixed FP16 and FP32 can choose different motion tokens. Differences can grow when generated motion is fed back as context.
+
+For other batch sizes and inference libraries, see [ONNX inference](onnx_inference.md).
+
+### Logging
+
+The library uses Python's standard `logging` module, with one logger per module. TensorRT messages go to the `motionbricks.inference.tensorrt` logger. Configure logging in your application as usual:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("motionbricks").setLevel(logging.DEBUG)
+```
+
+The apps log info messages by default. Add `--verbose` to any app command for detailed log messages.
+
+## Pose layouts and model space
+
+The apps work in world space, which is Z up. SOMA model space and the BVH clips are Y up. G1 model space and the CSV clips are already Z up.
+
+`model_to_runtime(rig)` in [app/runtime/common/rig.py](../app/runtime/common/rig.py) converts each rig's space to world space. For SOMA, it turns Y up into Z up. It follows the MuJoCo convention, so SOMA faces the same way as G1. For G1, it is the identity.
+
+The apps pass this transform to the engine and to clip sampling, so generated motion and clips land in the same space. Both engines default to the identity, which suits an app that already works in the model space.
+
+### Place poses in the scene
+
+Your app places every context and target pose in world space. To place a pose, move its root by one world transform and keep the other joint values. The root sets where the pose stands and which way it faces. For SOMA, the root is the first local joint transform. For G1, it is the first seven joint coordinates: the root's XYZ position and XYZW quaternion.
+
+When you sample a clip, pass the placement as `root_offset`. A clip in source coordinates also needs `model_to_runtime`, applied first:
+
+```python
+clip.sample(sample_time, pose, root_offset=wp.mul(placement, model_to_runtime), stream=engine.stream)
+```
+
+Pass `root_offset` and `stream` by keyword. For a pose that you already have, multiply its root by the placement. `place_target_poses()` and `place_target_dof()` in [target_pose.py](../motionbricks/runtime/target_pose.py) do this for each pose layout.
+
+The apps place poses in four places:
+
+| Where | What it places | Code | Read more |
+| --- | --- | --- | --- |
+| Inbetweener | Start and each target, from the gizmo and the **Transform** fields | `sample_pose_window()` in [inbetweener_demo.py](../app/inbetweener_demo.py) | [Place a pose in the scene](inbetweener.md#place-a-pose-in-the-scene) |
+| Locomotion | Blended target poses, ahead of the character and turned to its facing | `place_target_poses()` and `place_target_dof()` | [Blend and place the target](scene_preview.md#blend-and-place-the-target) |
+| Smart Primitives | Authored target poses, through the instance's placement and node hierarchy | `get_world_target_poses()` in [smart_primitive.py](../motionbricks/runtime/smart_primitive.py) | [How a scene places the poses](smart_primitive_editor.md#how-a-scene-places-the-poses) |
+| Clips | Idle and interaction clips, ahead of the character or at its current root | `generate_clip_transition()` and `start_clip()` in [character.py](../app/runtime/common/character.py) | [Clips and generated motion](#clips-and-generated-motion) |
+
+Because only the root moves, one set of sampled poses serves every placement. This is why the guided tutorial can move the Entry and Duck-under targets with the gizmo without changing their body poses.
+
+### Clips
+
+[ClipRegistry](../app/runtime/common/clip_registry.py) loads and caches clips for one rig. It reads BVH clips for SOMA and CSV clips for Unitree G1:
+
+```python
+from app.runtime.common.rig import load_rig_assets
+from motionbricks.model.contract import ModelRig
+
+assets = load_rig_assets(ModelRig.SOMA)
+clip = assets.clip_registry.load("assets/motions/soma/locomotion/idle/idle_loop_001__A268.bvh").animation
+```
+
+`load_rig_assets()` returns a `RigAssets` with the rig's skeletal mesh or Newton model, its clip registry, a reference pose that sets the buffer layout, and the `model_to_runtime` transform. Clips are only one source of poses. Any pose with the right layout works as a context or a target.
+
+G1 CSV clips store the root in centimeters and angles in degrees at 120 Hz. The loader converts them to meters, XYZW quaternions, and radians.
+
+## Generate
+
+`generate_animation()` reads the context and target tokens and fills the output buffer with the generated motion and its foot contacts. Two kinds of settings tune it: settings for the whole generation, and settings for each target.
+
+### Generation settings
+
+`generate_animation()` accepts an optional `MotionBricksInferenceConfig`:
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `allowed_token_counts` | 8 to 14 | Lengths the model may choose, from 6 to 16 tokens of four poses |
+| `correct_generated_diff` | `True` | Spreads small corrections over the motion so it starts at the last context pose and ends at the target |
+| `heading_alignment` | (1, 0) | The ground direction in model space that inference turns the last context pose to face: (x, z) for SOMA and (x, y) for G1. (1, 0) faces +X. The [SOMA](soma_model.md) and [Unitree G1](unitree_g1_model.md) model cards describe each model space. |
+
+### Settings for each target
+
+Each target also carries its own settings in `TargetPoseInferenceParams`, from [target_pose.py](../motionbricks/runtime/target_pose.py). They are the settings that you edit for each target in the Inbetweener and the Smart Primitive Editor. The motion players read them in `generate()`.
+
+| Setting | Field | Effect |
+| --- | --- | --- |
+| **Poses to Use** | `num_poses_to_use` | How many of the target's four poses inform the model, from 1 to 4. One pose sets the destination, with the posture and facing at which the character stops. A second pose adds velocity. A third and fourth pose add acceleration and momentum. |
+| **Transition Early By** | `transition_early_by_frames` | Moves the transition point this many frames before the end of the generated motion. A larger value makes this target a guide. The character lines up toward it, then moves on to a more precise next target before arriving. |
+| **Tokens to Generate** | `allowed_token_counts` | Replaces the allowed token counts of the generation settings for this target. `None` keeps them. A single count gives the target exact control over how many frames to generate, as [Generation length](#generation-length) explains. |
+| **IK Pins** | `ik_pin_mask` | SOMA only. As playback of the generated motion nears the target, `TargetPoseIKCorrector` eases the pinned hands and feet onto it with two-bone IK. See [IK Pins](smart_primitive_editor.md#ik-pins). |
+
+### Generation length
+
+The model decides how long each transition takes. Each token holds four poses at 30 Hz. One generation produces 6 to 16 tokens, or 24 to 64 raw frames. The first token holds the context. The last token holds the target. The engine removes three boundary frames at each end. The generated motion then starts at the last context pose and ends at the first target pose. That leaves 18 to 58 valid frames, or about 0.6 to 1.9 s of motion. `output.num_frames` holds the valid frame count of the latest generation.
+
+### Foot contacts
+
+Both models predict foot contacts with the motion. Each frame holds four values. Each value is a confidence from 0 to 1 that a heel or a toe is planted on the ground. The engines clamp the raw model values to this range. The columns are:
+
+| Column | Contact | SOMA joint | G1 point |
+| --- | --- | --- | --- |
+| 0 | Left heel | `LeftFoot` | The left ankle roll joint |
+| 1 | Left toe | `LeftToeBase` | 0.14 m ahead of the left ankle roll joint and 0.035 m below it |
+| 2 | Right heel | `RightFoot` | The right ankle roll joint |
+| 3 | Right toe | `RightToeBase` | 0.14 m ahead of the right ankle roll joint and 0.035 m below it |
+
+The G1 toe points are in the local space of each ankle roll link. `SOMA_N1_FOOT_CONTACT_JOINTS` in [soma/contract.py](../motionbricks/model/soma/contract.py) lists the SOMA joints. `UNITREE_G1_N1_FOOT_CONTACT_BODIES` and `UNITREE_G1_N1_FOOT_CONTACT_OFFSETS` in [unitree_g1/contract.py](../motionbricks/model/unitree_g1/contract.py) list the G1 bodies and points.
+
+Generated motion keeps the foot contacts in `output.foot_contacts`. It is an FP32 array of shape `[capacity, 4]`. Its first `output.num_frames` frames are valid. `generate_animation()` requires this array. `create_output()` allocates it. Clips loaded from files have no foot contacts. Their `foot_contacts` is `None`.
+
+`sample_foot_contacts()` blends the four values at a playback time, the way `sample()` blends poses. The **Show Foot Contacts** option in the Inbetweener and Scene Preview draws the sampled values.
+
+`skeletal_mesh_sole_outlines()` and `body_sole_outlines()` in [foot_contact_renderer.py](../motionbricks/renderers/foot_contact_renderer.py) turn these points into heel and toe outlines. `SkeletonFootContactRenderer` draws the outlines on a SOMA pose, and `DOFFootContactRenderer` on a G1 pose. The apps create each rig's mesh, skeleton, and foot contact renderers with `create_mesh_renderer()`, `create_skeleton_renderer()`, and `create_foot_contact_renderer()` in [rig.py](../app/runtime/common/rig.py).
+
+## Chaining generations
+
+A single generation is short. Continuous motion comes from chaining generations, as the [guided tutorial](guided_tutorial.md#chaining-generations) explains. Each new context must hold the poses that were actually shown. Otherwise the next generation starts from another pose, and the character jumps. The Inbetweener chains by hand, which shows each call.
+
+Two pieces in [motionbricks/runtime](../motionbricks/runtime) implement this pattern for real-time use. `MotionRecorder` keeps the poses that were shown. The motion players generate from those poses and play the result. Scene Preview [builds every state](scene_preview.md#generate-from-recorded-motion) on them. Read them as a reference, then rebuild the same pattern in your own application.
+
+### The Inbetweener's approach
+
+The Inbetweener [chains generations](inbetweener.md#playback-and-chained-generation) without a player. At each transition point, it copies the last four played frames of the generated motion into the context. This works because each segment plays to its transition point, and nothing changes the pose on the way.
+
+### Record what you show
+
+[MotionRecorder](../motionbricks/runtime/motion_recorder.py) keeps a fixed number of recent poses, oldest first. It also keeps the time from each pose to the next. Record one pose at each update of your app. The update rate does not need to match the model's 30 Hz.
+
+```python
+from motionbricks.runtime.motion_recorder import MotionRecorder
+
+history = MotionRecorder(skeleton.reference_local_transforms, capacity=32, stream=engine.stream)
+history.fill(start_pose, stream=engine.stream)
+
+# At each update, after every change to the pose:
+history.record(delta_time, current_pose, stream=engine.stream)
+
+# Before each generation:
+context.update_from_recorder(history, stream=engine.stream)
+```
+
+For G1, pass the robot's reference joint coordinates in place of the skeleton's reference local transforms. `fill()` sets every slot to one pose, as if the character had held it. Call it before the first generation.
+
+`update_from_recorder()` samples four context poses at 30 Hz, ending at the latest recorded pose. It blends the two recorded poses around each sample time. The four poses span 0.1 s. The default 32 poses cover that span at update rates up to about 300 Hz.
+
+Record the pose after every change that your app makes to it. Clip frames, target pose IK, and physics all count. The recorder does not track where a pose came from. That is what lets a generation start from a clip, or from the middle of a segment.
+
+### Play generated motion
+
+[motion_player.py](../motionbricks/runtime/motion_player.py) pairs an engine with a recorder. `GeneratedMotionPlayer` serves SOMA, and `GeneratedDOFMotionPlayer` serves G1. Each player creates its own context token, target token, output buffer, and recorder.
+
+| Member | Use |
+| --- | --- |
+| `seed_history_from_pose(pose)` | Fills the history and the context with one pose. Call it before the first generation. |
+| `generate(target_poses, inference_params)` | Reads the context poses from the history, generates toward the target, and restarts playback. An optional `config` holds the other generation settings. |
+| `sample(delta_time, pose, foot_contacts)` | Advances the playback time, then writes the pose and its foot contacts. |
+| `record_pose(delta_time, pose)` | Records the pose that you showed. |
+| `time_to_transition` | Seconds left until the transition point. |
+
+The player does not decide when to generate. Your code calls `generate()`, usually when `time_to_transition` drops below the time of the next update. Sampling can continue past the transition point. At the end of the valid frames, the pose holds.
+
+### A continuous locomotion loop
+
+This sketch drives a SOMA character with a player. `input_changed()` and `place_target()` stand for your own code.
+
+```python
+import warp as wp
+
+from motionbricks.runtime.motion_player import GeneratedMotionPlayer
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+
+player = GeneratedMotionPlayer(engine, skeleton)
+player.seed_history_from_pose(start_pose)
+current_pose = wp.empty_like(start_pose)
+foot_contacts = wp.zeros(4, dtype=wp.float32, device=engine.device)
+target_poses = wp.empty((4, skeleton.num_joints), dtype=wp.transform, device=engine.device)
+settings = TargetPoseInferenceParams(transition_early_by_frames=10, num_poses_to_use=4)
+
+
+def update(delta_time, desired_velocity):
+ if player.time_to_transition <= delta_time or input_changed(desired_velocity):
+ place_target(target_poses, desired_velocity)
+ player.generate(target_poses, settings)
+ player.sample(delta_time, current_pose, foot_contacts)
+ # Apply target pose IK, physics, or other changes to current_pose here.
+ player.record_pose(delta_time, current_pose)
+```
+
+Each call to `update()` runs one pass of the [generation flow](#generation-flow). [locomotion_loop.py](examples/locomotion_loop.py) runs this loop with `input_changed()` and `place_target()` filled in. Your app makes two decisions in it:
+
+- **When to generate.** Generate when playback reaches the transition point at the latest. Regenerate earlier when the movement input changes enough, so the character responds quickly. Scene Preview's rules are in [When locomotion generates](scene_preview.md#when-locomotion-generates).
+- **Where to place the target.** Sample target poses that match the desired speed. Place them ahead of the character along the desired velocity, and move only the root. Use all four target poses, so the model also matches the velocity at the target. Scene Preview blends its target poses in a blend space, as [Blend and place the target](scene_preview.md#blend-and-place-the-target) shows.
+
+### Clips and generated motion
+
+Clips and generated motion mix freely, because the recorder keeps every pose that was shown. `BaseCharacter` in [character.py](../app/runtime/common/character.py) uses this in both directions:
+
+- **Out of a clip.** `start_clip()` plays a clip, and `step()` keeps recording its frames. The next generation starts from the clip's motion, at any frame.
+- **Into a clip.** `generate_clip_transition()` places the clip ahead of the character. It samples the clip's first four poses as the target and generates toward them with a **Transition Early By** of zero. When the clip transition ends, the state starts the clip.
+
+The idle state uses both. It generates into a looping idle clip, and locomotion later generates out of it.
+
+### Choose an approach
+
+| | Inbetweener | Motion player |
+| --- | --- | --- |
+| Context poses | The last four played frames of the generated motion | Four poses sampled at 30 Hz from the recorded history |
+| When to generate | At each transition point | At any update |
+| Poses from clips, IK, or physics | Never reach the context | Reach the context like any other shown pose |
+
+Start with the Inbetweener to see each call. Move to a recorder as soon as your app regenerates early, plays clips, or changes the pose after sampling.
+
+## Further reference
+
+- [Inbetweener](inbetweener.md): one integration of this API, step by step.
+- [Scene Preview](scene_preview.md): a character runtime built on the motion players, with states, locomotion, and behaviors.
+- [Guided tutorial](guided_tutorial.md): the user-facing workflow that uses this API through the apps.
+- [ONNX inference](onnx_inference.md): direct ONNX interfaces, batching, and other inference libraries.
+- [SOMA model card](soma_model.md): SOMA inputs, outputs, coordinates, and limitations.
+- [Unitree G1 model card](unitree_g1_model.md): G1 joint layout, inputs, outputs, and limitations.
diff --git a/docs/scene_editor.md b/docs/scene_editor.md
new file mode 100644
index 0000000..315b26b
--- /dev/null
+++ b/docs/scene_editor.md
@@ -0,0 +1,132 @@
+# Scene Editor
+
+A scene brings Smart Primitives together into a space the character can play through. It places Smart Primitive instances and Solid Cubes, sets where the character starts, and names the behavior that runs each instance. [Scene Preview](scene_preview.md) opens the saved `.scene.json` document and plays it.
+
+<p align="center">
+ <img src="media/scene_editor.png" alt="Scene Editor with the SOMA gym" width="100%">
+</p>
+
+```sh
+uv run python -m app.scene_editor
+uv run python -m app.scene_editor assets/scenes/soma_gym.scene.json
+```
+
+The optional argument opens a scene at startup. Add `--verbose` for detailed log messages.
+
+> **Note:** The Scene Editor is an example of how to author behaviors and interactions for the model. It is not a production tool. Known limitation: it has no undo or redo, so save your work often.
+
+[Part 3 of the guided tutorial](guided_tutorial.md#part-3-assemble-an-interaction-scene-with-avoidance-jump-and-sit) assembles an interaction course step by step. This page describes what a scene holds and how Scene Preview uses it.
+
+## Controls
+
+Use the **File** menu to create, open, and save scenes. The editor has two panels: **Scene** and **Properties**. Their controls are described with the parts they edit.
+
+| Action | Control |
+| --- | --- |
+| Move the camera | **W**, **A**, **S**, and **D**, or the **arrow keys**. **Q** and **E** move it down and up. |
+| Orbit around the camera pivot | Drag with the **middle mouse button** |
+| Look around | Drag with the **left mouse button** |
+| Pan | **Shift** + drag with the **middle mouse button** |
+| Move toward or away from the camera pivot | **Ctrl** + drag with the **middle mouse button**, or the **mouse wheel** |
+| Change the field of view | **Ctrl** + **mouse wheel** |
+| Select an item | Click it in the view, or click it in the **Scene** tree |
+| Move or turn the selection | Drag the gizmo, or edit the **Transform** fields |
+| Reset or lock a transform | Right click **Translation** or **Rotation** to reset it. Right click an axis label to lock that axis. |
+
+The **Transform** values and the gizmo handles use the parent item's axes.
+
+## What a scene holds
+
+A scene is a `.scene.json` document for one rig, SOMA or Unitree G1. It holds:
+
+- One CharacterStart: where the character appears and which way it faces.
+- Smart Primitive instances: each places one Smart Primitive document in the scene and names the behavior that runs it.
+- Solid Cubes: scenery, such as the box under a jump.
+
+The SOMA gym shows how they fit together:
+
+```text
+CharacterStart
+SmallJumpSP jump_0_5m, VelocityMatchingSequenceBehavior
+└── Box Solid Cube to jump onto
+MidJumpSP jump_0_75m, VelocityMatchingSequenceBehavior
+└── Wall Solid Cube to vault over
+SitSP sit, SittingBehavior
+└── Seat Solid Cube to sit on
+AvoidanceSP avoidance, VelocityMatchingSequenceBehavior
+└── Bar Solid Cube to duck under
+```
+
+The bundled scenes are in [assets/scenes](../assets/scenes):
+
+| Scene | What it shows |
+| --- | --- |
+| `soma_gym` | A small jump, a vault, a box to sit on, and a bar to duck under, for SOMA |
+| `g1_gym` | The same layout for the Unitree G1, scaled to the robot's size |
+
+## Scene tree
+
+The **Scene** panel lists the items. Parents only help editing: moving a Smart Primitive moves the cubes under it. Scene Preview places every item by its world transform.
+
+In **Scene**:
+
+- **+** adds a Smart Primitive or a Solid Cube. **-** deletes the selected item and its children. Right click an item to delete it.
+- Double click an item to rename it. Drag it onto a Smart Primitive or a Solid Cube to make it a child. To move it back to the top level, drop it below the tree or choose **Move to Root** in its right click menu.
+- CharacterStart stays at the top level. It cannot be renamed, deleted, or moved under another item.
+- The **Character** selector sets the scene's rig. While the scene has no references, it switches between SOMA and Unitree G1. To change the rig later, delete the Smart Primitives that hold references, or start a new scene.
+
+## Items
+
+Select an item to edit it in **Properties**.
+
+### CharacterStart
+
+CharacterStart sets where the character appears when Scene Preview opens the scene. Its arrow shows the direction the character faces. Every scene has exactly one.
+
+### Smart Primitive
+
+| Setting | Meaning |
+| --- | --- |
+| Reference | The `.smart_primitive.json` document to place. The first reference sets the scene's rig. Later references must use the same rig. |
+| Show Target Poses | Draws the document's target poses in the scene: all sequences, or the one chosen beside it, in the chosen color |
+| Show Interaction Boxes | Draws the document's interaction boxes |
+| Behavior | Under **Runtime**, the class that runs the instance in Scene Preview, such as `VelocityMatchingSequenceBehavior` or `SittingBehavior`. The list shows every `SmartPrimitiveBehavior` subclass that is imported. |
+
+Several instances can reference the same document. Each instance has its own placement and behavior. A Smart Primitive item starts with no reference and an empty **Behavior**. Scene Preview refuses a scene until every instance has both. [Write a behavior](scene_preview.md#write-a-behavior) in Scene Preview shows how to add a class to the list.
+
+[Add the avoidance Smart Primitive](guided_tutorial.md#add-the-avoidance-smart-primitive) in the tutorial places an instance and chooses its behavior. [Complete the course](guided_tutorial.md#complete-the-course) adds the jump and the sit.
+
+### Solid Cube
+
+**Width**, **Depth**, **Height**, and **Color** set the cube. Cubes are scenery, such as the box under a jump. They are not collision geometry for the model. Put a cube under its Smart Primitive so the two move together.
+
+## How Scene Preview uses a scene
+
+Save the scene with **File** > **Save**, then open it in Scene Preview:
+
+```sh
+uv run python -m app.scene_preview --scene path/to/your.scene.json
+```
+
+Scene Preview flattens the item hierarchy into world transforms and checks every instance before it builds an engine. It then moves the root node of each instance's Smart Primitive to the instance's placement, and starts the character at CharacterStart. [Scenes](scene_preview.md#scenes) in Scene Preview describes the loading.
+
+## Document format
+
+Scene documents are plain JSON:
+
+| Field | Contents |
+| --- | --- |
+| `format`, `schema_version` | `motionbricks.scene` and 1 |
+| `name`, `rig` | The scene name, taken from the file name, and the rig, `soma` or `unitree_g1` |
+| `character_start` | ID 1, its `transform`, and its `euler_degrees` |
+| `smart_primitives` | Each instance has an `id`, a `name`, a `parent_id` or `null`, a `transform`, its `euler_degrees`, a `reference`, its `visibility`, a `target_pose_color`, and a `behavior` class name |
+| `solid_cubes` | Each cube has an `id`, a `name`, a `parent_id` or `null`, a `transform`, its `euler_degrees`, its `dimensions`, and a `color` |
+| `editor` | The selected item and the camera. The editor restores them. |
+
+A `transform` holds a `translation` and a `rotation_xyzw` quaternion. It is relative to the parent item, or to world space at the top level. A `reference` is relative to the scene file, or absolute when the files are on different drives. Another program can write these files. It must use one rig for every referenced Smart Primitive.
+
+## Further reference
+
+- [Guided tutorial](guided_tutorial.md#part-3-assemble-an-interaction-scene-with-avoidance-jump-and-sit): assembling the tutorial scene step by step.
+- [Smart Primitive Editor](smart_primitive_editor.md): authoring the Smart Primitive documents that a scene references.
+- [Scene Preview](scene_preview.md): how a scene loads and how its behaviors run.
diff --git a/docs/scene_preview.md b/docs/scene_preview.md
new file mode 100644
index 0000000..7d9b5f7
--- /dev/null
+++ b/docs/scene_preview.md
@@ -0,0 +1,338 @@
+# Scene Preview
+
+[Scene Preview](../app/scene_preview.py) drives one character through a scene with continuous locomotion and interactions. It is a small character runtime built on MotionBricks. States decide the target poses. The engine generates toward them. The character plays the result and records it for the next generation.
+
+<table>
+ <tr>
+ <th>SOMA</th>
+ <th>Unitree G1</th>
+ </tr>
+ <tr>
+ <td><img src="media/scene_preview_soma.gif" alt="Scene Preview with SOMA" width="100%"></td>
+ <td><img src="media/scene_preview_g1.gif" alt="Scene Preview with the Unitree G1" width="100%"></td>
+ </tr>
+</table>
+
+This page shows how to run the app, then explains its runtime for developers who want a character to move continuously and interact with objects in a scene. Every part is plain Python. The same code runs the SOMA and Unitree G1 characters.
+
+[Part 4 of the guided tutorial](guided_tutorial.md#part-4-play-the-scene) plays the interaction scene that the tutorial builds. The sections below connect what you see there to the code.
+
+## Run Scene Preview
+
+```sh
+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` opens a scene document. Its rig selects SOMA or the Unitree G1. The SOMA gym is the default.
+- `--model-precision fp16` uses the mixed FP16 model. FP32 is the default. [TensorRT builds](runtime_api.md#tensorrt-builds) explains how FP16 and FP32 motion can differ.
+- `--verbose` shows detailed log messages.
+
+The gym scenes place a small jump, a vault, a bar to duck under, and a box to sit on. Every motion comes from the model, except for the idle and sitting loops that play from clips.
+
+Things to try:
+
+- Walk into each object. With **Auto Interact** on, the character jumps, vaults, ducks under the bar, or sits on the box as it arrives.
+- Approach the same object from other angles and at other speeds. Pivots turn and slide each sequence toward the approach. The jumps and the bar pick their variation by speed.
+- While seated, press **I** (**X** on a controller) to stand up.
+- Turn off **Auto Interact** in the **Scene** section, then press **I** (**X** on a controller) near an object to start its interaction by hand.
+- Switch to Crouching with **P** (**B** on a controller) and walk under the bar. Its raised interaction box only catches a standing character, so no interaction starts.
+- Switch to Strafing with **O** (**Y** on a controller), or cycle through the style modes with **[** (**A** on a controller).
+- Turn on the options under **Visibility** to see the poses and boxes behind each generation, such as **Show Context Poses** and **Show Probe Box**.
+- Open the other gym with **...** next to **Scene**. The scene's rig switches the character between SOMA and the Unitree G1.
+
+### Controls
+
+| Action | Keyboard and mouse | Controller |
+| --- | --- | --- |
+| Move forward, left, backward, or right | **W**, **A**, **S**, and **D**, or the **arrow keys** | Left stick or D-pad |
+| Run | Hold **Space** while moving | Push the left stick further |
+| Interact manually, or stand up after sitting | **I** | **X** |
+| Switch between the Forward and Strafing modes | **O** | **Y** |
+| Switch between the Crouching and Strafing modes | **P** | **B** |
+| Cycle through the style modes, such as Skipping and Zombie | **[** | **A** |
+| Orbit the camera around the character | Drag with the **middle mouse button** | Right stick |
+
+## Code map
+
+These symbols carry the runtime's model-facing flow:
+
+| Symbol | Responsibility |
+| --- | --- |
+| `ScenePreview.run()` in [scene_preview.py](../app/scene_preview.py) | Loads a pending scene between frames, then steps and draws each frame on the engine stream. |
+| `ScenePreview.step()` | Reads input, advances the character, moves the camera, then updates interactions. |
+| `ScenePreview.load_scene()` | Reads and checks a scene, loads its rig and Smart Primitives, then creates the character. If a scene opened from the window fails before its engine loads, the current scene keeps running and the window shows the error. |
+| `ScenePreview._update_smart_primitive_interaction()` | Finds the nearest Smart Primitive whose interaction box overlaps the probe box. |
+| `ScenePreview._dispatch_interaction_input()` | Starts an interaction, by hand or with **Auto Interact**, or passes a press to the running behavior. |
+| `BaseCharacter.step()` in [character.py](../app/runtime/common/character.py) | Updates the state machine, plays the current pose, and records it for the next generation. |
+| `BaseCharacter.generate_to_target_poses()` | Generates from the recorded poses toward placed target poses, then restarts playback. |
+| `StateMachine.update()` in [state_machine.py](../app/runtime/common/state_machine.py) | Switches modes, smooths the movement, then updates the current state. |
+| `IdleState`, `LocomotionState`, and `InteractionState` in [states.py](../app/runtime/common/states.py) | Decide when to generate, toward which targets, and when to hand over to another state. |
+| `BaseTargetPoseBlender.evaluate()` in [target_pose_blender.py](../app/runtime/common/target_pose_blender.py) | Blends the locomotion targets for the desired velocity and places them ahead of the character. |
+| `LocomotionMode` and `LocomotionSettings` in [motion.py](../app/runtime/common/motion.py) | Hold each mode's targets and speeds, how quickly movement responds to input, and when locomotion generates again. |
+| `SmartPrimitiveBehavior` in [smart_primitive_behaviors.py](../app/runtime/common/smart_primitive_behaviors.py) | Base class of the behaviors that scenes choose, such as `VelocityMatchingSequenceBehavior` and `SittingBehavior`. |
+| [app/runtime/soma](../app/runtime/soma), [app/runtime/unitree_g1](../app/runtime/unitree_g1) | Each rig's character, target pose blender, and presets. |
+
+The rest of `scene_preview.py` handles the camera, the drawing, and the **Scene Preview** window.
+
+## Main update loop
+
+`ScenePreview.run()` loads a pending scene between frames. Loading can build another engine, so it runs outside the active engine's stream. `run()` then enters the engine stream and calls `step()` and `render()`.
+
+Each `step()`:
+
+1. Measures the time since the last frame.
+2. Reads the keys and the controller, then orbits the camera.
+3. Builds a `LocomotionCommand` from the movement relative to the camera, the run input, and any requested mode.
+4. Calls `BaseCharacter.step()`.
+5. Moves the camera with the character.
+6. Tests the probe box against every interaction box.
+7. Starts an interaction, or passes a press to the running behavior.
+
+The character advances before the interaction test. An interaction that starts in this frame therefore generates its first segment from poses that were already recorded.
+
+### The character update
+
+`BaseCharacter.step()` advances the character by the frame time:
+
+```python
+self.state_machine.update(self, delta_time, command)
+previous_ground_position = self.character_ground_position.copy()
+self._sample_playback(delta_time)
+self._update_character_velocity(previous_ground_position, delta_time)
+self.player.record_pose(delta_time, self.current_pose)
+self._update_probe_box()
+```
+
+1. The state machine updates the movement and the current state. That state may generate new motion or start a clip.
+2. `_sample_playback()` writes the pose to show into `current_pose`. It samples generated motion or a clip.
+3. `_update_character_velocity()` measures how far the character moved.
+4. `record_pose()` stores the pose that was shown.
+5. `_update_probe_box()` moves the probe box ahead of the character.
+
+The character plays from one of three sources:
+
+- `GENERATED`: motion generated toward target poses.
+- `CLIP_TRANSITION`: motion generated toward the first frame of a clip.
+- `CLIP`: the clip itself, played once or in a loop.
+
+### Generate from recorded motion
+
+Every state generates through `generate_to_target_poses()`. The character's motion player samples four context poses at 30 Hz from the recorded history, ending at the latest pose. It then calls the engine and restarts playback. These are the same calls as in the [Inbetweener](inbetweener.md#generation-flow).
+
+The recorded history holds the poses that were actually shown, including clip frames and any [IK Pins](smart_primitive_editor.md#ik-pins) corrections. That is why a generation can start from a clip or from the middle of another generation. A state can start a generation at any time. Otherwise, the current segment plays until its transition point.
+
+## State machine and states
+
+![Scene Preview state machine with Idle, Locomotion, and Interaction states](media/state_machine.png)
+
+`StateMachine` holds five states:
+
+| State | On enter | On each update |
+| --- | --- | --- |
+| Idle, Crouching Idle | Generates a transition into an idle clip | Switches to locomotion when there is movement input. Loops the clip when the transition ends. |
+| Locomotion, Crouching Locomotion | Generates toward the blended target | Switches to idle when the input stops. Generates again when needed. |
+| Interaction | Starts the Smart Primitive's behavior | Generates toward the next target at each transition point, or waits for the clip to end. |
+
+Idle and locomotion come in two pairs, standing and crouching. Standing locomotion has the Forward, Strafing, and style modes. Crouching locomotion has the Crouching mode, and its probe box is 60 percent as tall. When a mode key selects a mode of the other pair, the character moves to that pair's idle or locomotion state, depending on the input.
+
+Each frame, `StateMachine.update()` switches the mode when the command asks for one. It then smooths the movement and updates the current state. Every switch exits the old state before it enters the new one. Movement keeps smoothing in every state, so it carries into the next one.
+
+### Idle
+
+Idle plays looping clips, and the model generates the way in:
+
+1. Choose one of the rig's idle clips at random, other than the current one.
+2. Place the clip one second ahead of the character along its actual velocity. Turn it to the facing of the last movement input.
+3. Sample the clip's first four poses at 30 Hz into the target token. Generate a transition toward these poses.
+4. When the transition ends, play the clip in a loop.
+
+When a scene starts, the character begins directly in an idle loop, and its history is filled with that first pose.
+
+### Interaction
+
+`start_interaction()` enters the interaction state with a Smart Primitive's [behavior](../app/runtime/common/smart_primitive_behaviors.py). The behavior calls `finish()` when it is done. `resume_movement()` then picks locomotion if there is movement input, and idle otherwise. A sequence or clip played without an `on_complete` callback calls `finish()` when it ends.
+
+In the [guided tutorial](guided_tutorial.md#inspect-the-runtime), the avoidance and jump interactions returned to locomotion as soon as their sequences ended. The sit interaction stayed in the interaction state while its clip looped.
+
+## Continuous locomotion
+
+<table>
+ <tr>
+ <th>SOMA</th>
+ <th>Unitree G1</th>
+ </tr>
+ <tr>
+ <td><img src="media/locomotion_targets_soma.gif" alt="SOMA walks, runs, and stops with context, target, and blend space poses shown" width="100%"></td>
+ <td><img src="media/locomotion_targets_g1.gif" alt="Unitree G1 walks, runs, and stops with context, target, and blend space poses shown" width="100%"></td>
+ </tr>
+ <tr>
+ <td><img src="media/locomotion_directional_soma.gif" alt="SOMA strafes in four directions, crouches, then stands back up, with context, target, and blend space poses shown" width="100%"></td>
+ <td><img src="media/locomotion_directional_g1.gif" alt="Unitree G1 strafes in four directions, crouches, then stands back up, with context, target, and blend space poses shown" width="100%"></td>
+ </tr>
+</table>
+
+*Top: in the Forward mode, each character walks to a full run, then stops into idle. Bottom: in the Strafing mode, each character faces one way while it moves forward, right, back, and left. It then switches to Crouching while moving, and back to Strafing before it stops. Context poses are purple, the current targets are blue, and the live blend space pose is green.*
+
+Locomotion keeps generating toward a target placed ahead of the character. Each generation starts from the poses that were just shown, so the motion continues without a break. The movement input is relative to the camera. `MovementControl` smooths it into a desired velocity and a facing direction. In Strafing and Crouching, the character faces the camera direction.
+
+### Locomotion modes
+
+Each rig's `presets.py` defines its locomotion modes. A `LocomotionMode` names a Smart Primitive document of blend targets, the blend value of each target, and the speed limits. The blend targets hold four poses sampled from locomotion clips:
+
+| Mode | Blend space | Targets |
+| --- | --- | --- |
+| Forward | 1D, by speed | Idle, Walk, Jog, Run |
+| Strafing | 2D, by velocity relative to facing | Idle, Forward, Backward, Left, Right |
+| Crouching | 2D, by velocity relative to facing | Idle, Forward, Backward, Left, Right |
+| Styles | 1D, by speed | Idle, then Skipping, Vogue, Injured Torso, Injured Leg, Zombie, or Combat |
+
+The six style modes share one document, `locomotion_style_variations_bs1_linear`. Each blends the Idle target at 0 into its style target at 1. A style mode's default speed is its maximum speed, so the style pose shows in full. Its targets also sit farther ahead, so it walks close to the speed of its clip. Its transition point sits nearer the end of each transition, so the motion gets closer to the style pose. From another mode, **[** (**A** on a controller) returns to the last style mode used. From a style mode, **O** (**Y** on a controller) returns to Forward, and **P** (**B** on a controller) switches to Crouching.
+
+<table>
+ <tr>
+ <th>SOMA</th>
+ <th>Unitree G1</th>
+ </tr>
+ <tr>
+ <td><img src="media/locomotion_styles_soma.gif" alt="SOMA walks in each locomotion style, from Skipping to Combat" width="100%"></td>
+ <td><img src="media/locomotion_styles_g1.gif" alt="Unitree G1 walks in each locomotion style, from Skipping to Combat" width="100%"></td>
+ </tr>
+</table>
+
+*SOMA and the Unitree G1 walk in each of the six style modes, named in the top left*
+
+### Blend and place the target
+
+Each time locomotion generates, it:
+
+1. Evaluates the blend space at the desired velocity. Blends the targets.
+2. Scales the ground speed of the blended target to the desired speed times the mode's `velocity_scale`.
+3. Places the blended target `position_scale` seconds of travel ahead of the character, along the scaled desired velocity. Turns it to the facing direction. Only the root moves.
+4. Generates toward all four target poses, with the mode's **Transition Early By** and token counts.
+
+`BaseTargetPoseBlender.evaluate()` runs the first three steps. Each rig overrides the blend, speed, and placement steps for its pose layout.
+
+These are not classic animation blend spaces. A classic blend space, like the ones in game engines, mixes several clips as they play. The clips must stay in step, so the game engine synchronizes their foot phases and stretches them in time. Here the blend value mixes target poses sampled once from each clip. The model generates the motion toward the blended target, so there is nothing to synchronize or stretch. A rough blend is fine, because the model is robust to imperfect targets and locomotion generates again before each target is reached. Refer to Appendix D of the [paper](https://arxiv.org/abs/2604.24833).
+
+### When locomotion generates
+
+`LocomotionState.update()` decides each frame:
+
+```python
+if character.movement.input_speed <= 0.0:
+ state_machine.transition_to_idle(character)
+ return
+
+if (
+ self._force_regeneration
+ or character.time_to_transition() <= delta_time
+ or self._needs_regeneration(character.movement)
+):
+ self._generate(character)
+```
+
+Without movement input, the character switches to idle. Otherwise, locomotion generates in three cases:
+
+- The mode changed, which sets `_force_regeneration`.
+- Playback reached the transition point of the current segment.
+- The input changed enough. `_needs_regeneration()` checks whether the character started moving, whether the speed changed by more than a fraction of the remaining speed range, or whether the direction turned past a threshold. `LocomotionSettings` in [motion.py](../app/runtime/common/motion.py) holds these thresholds.
+
+These rules are one way to decide when to generate, not the only one. Other rules work too, such as generating on a fixed schedule or only at transition points. Try your own in `LocomotionState` and compare how the motion responds.
+
+### See it in the viewer
+
+Turn on **Show Target Poses**, **Show Context Poses**, and **Show Blend Space Poses** under **Visibility** in the **Scene Preview** window. They show the placed targets of the current generation, the context poses that the next generation would read, and the blend space target for the current frame. The blend space target shows only during locomotion. These are the options that you enabled in [Inspect the runtime](guided_tutorial.md#inspect-the-runtime) in the guided tutorial. **Show Foot Contacts** outlines the model's [foot contacts](runtime_api.md#foot-contacts) on the character's soles.
+
+## Smart Primitive behaviors
+
+### Find an interaction
+
+The character carries a probe box that reaches ahead along the desired velocity. Each frame, Scene Preview tests it against every Smart Primitive interaction box and keeps the nearest overlapping instance. Interaction boxes only trigger behaviors. The model never sees them as collision geometry.
+
+- **Auto Interact** is on by default. It starts an interaction once per approach.
+- **I** (**X** on a controller) starts an interaction by hand. During an interaction, the same press goes to the running behavior, which is how `SittingBehavior` makes the character stand up.
+
+### Run a behavior
+
+`StateMachine.start_interaction()` enters the interaction state, which calls the behavior's `enter()`. The behavior then plays sequences and clips through the interaction state:
+
+- `play_target_pose_sequence()` generates through the targets of a sequence in order. Each step keeps its **Poses to Use**, **Transition Early By**, and **Tokens to Generate** settings. A SOMA step can also pin hands or feet with [IK Pins](smart_primitive_editor.md#ik-pins).
+- `play_clip()` plays a clip once or in a loop. By default, the clip's first root pose is aligned with the character's current root.
+- `finish()` returns control to locomotion or idle.
+
+At each transition point, `InteractionState.update()` generates toward the next target of the sequence. After the last target, it runs the sequence's `on_complete` callback. The **Transition Early By** value of each step sets its transition point.
+
+### Bundled behaviors
+
+Each Smart Primitive instance in a scene names its behavior class. `behavior_types()` in [smart_primitive_behaviors.py](../app/runtime/common/smart_primitive_behaviors.py) finds every `SmartPrimitiveBehavior` subclass by class name:
+
+| Class | What it does |
+| --- | --- |
+| `VelocityMatchingSequenceBehavior` | Picks the sequence whose authored start speed is closest to the character's speed, aligns its pivot, and plays it |
+| `SittingBehavior` | Plays Sit, loops the sitting clip, and plays Stand on the next press |
+
+In [Part 3 of the guided tutorial](guided_tutorial.md#part-3-assemble-an-interaction-scene-with-avoidance-jump-and-sit), you chose `VelocityMatchingSequenceBehavior` for the avoidance and the jump. You chose `SittingBehavior` for the sit.
+
+The bundled avoidance document in the gym scenes has a Walk and a Jog sequence. `VelocityMatchingSequenceBehavior` picks between them by speed:
+
+![VelocityMatchingSequenceBehavior picks the Walk or Jog sequence by speed](media/velocity_matching_flow.png)
+
+`SittingBehavior` plays the Sit sequence, then loops a sitting clip until the next press. The Stand sequence then generates the motion back to standing:
+
+![SOMA sits down, holds, stands up, and walks off](media/sit_hold_soma.gif)
+*SOMA sits down, holds, stands up, and walks off*
+
+### Write a behavior
+
+To add a behavior, subclass `SmartPrimitiveBehavior`, override `enter()` and `interact()`, and declare the sequences and clips it needs:
+
+```python
+class LeaningBehavior(SmartPrimitiveBehavior):
+ """Lean on a wall, stay there, and step away when the user interacts again."""
+
+ required_sequences = ("Lean", "StepAway")
+ clip_paths = (LEAN_LOOP_CLIP,)
+
+ def enter(self) -> None:
+ self.interaction_state.play_target_pose_sequence("Lean", on_complete=self._hold)
+
+ def _hold(self) -> None:
+ self.interaction_state.play_clip(LEAN_LOOP_CLIP, loop=True, align_to_current_pose=True)
+
+ def interact(self) -> None:
+ if self.interaction_state.is_looping:
+ self.interaction_state.play_target_pose_sequence("StepAway")
+```
+
+The class then appears in the Scene Editor's **Behavior** list. Define it in `smart_primitive_behaviors.py`, or import its module before scenes load. The clips a behavior declares load with the scene. Declared sequences are checked when the instance is created. The [Smart Primitive Editor](smart_primitive_editor.md#example-a-sitting-hold) page shows how to author the sequences for a hold.
+
+The bundled behaviors and this example are one setup among many. The model only needs context and target poses, so how a behavior picks and times its targets is up to you. Use them as a starting point and explore your own ideas.
+
+## Scenes
+
+A `.scene.json` document records its rig, the CharacterStart, the Smart Primitive instances, and the Solid Cubes. Each instance references a Smart Primitive document, with its own placement, behavior, and visibility settings. Instances of the same document share one Smart Primitive asset. The [Scene Editor](scene_editor.md) creates scenes, and the files are plain JSON that you can also edit by hand.
+
+`load_scene()` flattens the item hierarchy into world transforms, because parents only help editing. It checks every instance before it builds an engine. A new Smart Primitive item has an empty **Behavior**, so choose one before you save the scene.
+
+## Explore and adapt the runtime
+
+Scene Preview is a reference to learn from, not a framework you have to build on. Change its parts to see how the motion responds, then carry the ideas into your own engine or tools. Each part has its own place:
+
+| Goal | Where to look |
+| --- | --- |
+| Add an interaction | Author a Smart Primitive document, and write a behavior class if the existing ones do not fit. See [Write a behavior](#write-a-behavior). |
+| Change the locomotion poses | The blend target documents that each rig's `presets.py` names, such as `locomotion_bs1_linear`. |
+| Change speeds or the transition point of locomotion | `LocomotionMode` in the rig's `presets.py`. |
+| Change when locomotion generates | `LocomotionSettings` in [motion.py](../app/runtime/common/motion.py), or the rules in `LocomotionState`. |
+| Change how far ahead interactions start | `INTERACTION_PROBE` in each rig's presets, [soma/presets.py](../app/runtime/soma/presets.py) and [unitree_g1/presets.py](../app/runtime/unitree_g1/presets.py). [interaction.py](../app/runtime/common/interaction.py) describes each value. |
+| Build the same pattern in another engine | Record every pose you show, and build each context from the latest four at 30 Hz. Let your own states choose and place the targets. Generate again at each transition point, or whenever your states ask. [Chaining generations](runtime_api.md#chaining-generations) describes the pieces. |
+| Reuse this runtime in another Python app | Create the rig's character, such as `SOMACharacter`, with an engine and a `SmartPrimitiveAssetPool`. Call its `step()` once per frame with a `LocomotionCommand`, then render `current_pose`. Start interactions with `state_machine.start_interaction()`, as `ScenePreview` does. |
+
+## Further reference
+
+- [Guided tutorial](guided_tutorial.md): the user-facing workflow that ends in this app.
+- [Runtime API](runtime_api.md): engines, motion players, generation settings, and chaining.
+- [Smart Primitive Editor](smart_primitive_editor.md): authoring the target poses, sequences, and pivots that behaviors play.
+- [Scene Editor](scene_editor.md): placing Smart Primitive instances and choosing their behaviors.
+- [Inbetweener](inbetweener.md): the same generation flow without a state machine.
diff --git a/docs/smart_primitive_editor.md b/docs/smart_primitive_editor.md
new file mode 100644
index 0000000..7147f7f
--- /dev/null
+++ b/docs/smart_primitive_editor.md
@@ -0,0 +1,237 @@
+# Smart Primitive Editor
+
+A Smart Primitive describes an action as target poses placed around an object. The character does not play the action as a clip. MotionBricks generates motion through the target poses, starting from whatever the character is doing, so one Smart Primitive works from many approaches and speeds. The paper calls these smart objects when they describe interactions, and smart locomotion when they drive navigation.
+
+In this repository, Smart Primitives define the interactions in Scene Preview, such as jumping, ducking, and sitting. They also hold the blend targets of every locomotion mode. The Smart Primitive Editor authors them.
+
+<p align="center">
+ <img src="media/smart_primitive_editor.png" alt="Smart Primitive Editor with the jump_0_5m Smart Primitive" width="100%">
+</p>
+
+```sh
+uv run python -m app.smart_primitive_editor
+```
+
+Add `--verbose` for detailed log messages.
+
+> **Note:** The Smart Primitive Editor is an example of how to author behaviors and interactions for the model. It is not a production tool. Known limitation: it has no undo or redo, so save your work often.
+
+[Part 2 of the guided tutorial](guided_tutorial.md#part-2-build-a-smart-primitive) builds an avoidance Smart Primitive step by step. This page describes what each part of a Smart Primitive holds and how Scene Preview uses it.
+
+## Controls
+
+Use the **File** menu to create, open, and save documents. The editor has three panels: **Hierarchy**, **Sequences**, and **Properties**. Their controls are described with the parts they edit.
+
+| Action | Control |
+| --- | --- |
+| Move the camera | **W**, **A**, **S**, and **D**, or the **arrow keys**. **Q** and **E** move it down and up. |
+| Orbit around the camera pivot | Drag with the **middle mouse button** |
+| Look around | Drag with the **left mouse button** |
+| Pan | **Shift** + drag with the **middle mouse button** |
+| Move toward or away from the camera pivot | **Ctrl** + drag with the **middle mouse button**, or the **mouse wheel** |
+| Change the field of view | **Ctrl** + **mouse wheel** |
+| Select a node | Click its pose or interaction box in the view, or click it in **Hierarchy** |
+| Move or turn the selection | Drag the gizmo, or edit the **Transform** fields |
+| Reset or lock a transform | Right click **Translation** or **Rotation** to reset it. Right click an axis label to lock that axis. |
+
+The **Transform** values and the gizmo handles use the parent node's axes.
+
+## What a Smart Primitive holds
+
+A Smart Primitive is a `.smart_primitive.json` document for one rig, SOMA or Unitree G1. It holds:
+
+- **Nodes** in a transform hierarchy under the root node.
+- **Components** on the nodes: a **Target Pose**, an **Interaction Box**, or a **Pivot**. A node holds at most one of each kind.
+- **Sequences** that list target pose nodes in the order the character reaches them.
+
+The avoidance Smart Primitive from the tutorial shows how they fit together:
+
+```text
+Root
+├── Interaction box Interaction Box: where the interaction can start
+└── Pivot Pivot: turns and slides the sequence toward the approach
+ ├── Entry pose Target Pose: a walking pose before the bar
+ └── Duck-under pose Target Pose: the pose under the bar
+
+Sequences
+ Sequence 1 Entry pose, Duck-under pose Pivot: Pivot
+```
+
+The bundled documents are in [assets/smart_primitives](../assets/smart_primitives):
+
+| Document | What it shows |
+| --- | --- |
+| `jump_0_5m` | A small jump with two variations |
+| `jump_0_75m` | A vault with three variations, two with a hand on the cube |
+| `avoidance` | Ducking under a bar, with walk and jog variations |
+| `sit` | Sitting down, holding, and standing up |
+| `locomotion_bs1_linear` | Idle, Walk, Jog, and Run targets for Forward |
+| `locomotion_bs2_directional` | Idle, Forward, Backward, Left, and Right targets for Strafing |
+| `locomotion_bs2_directional_crouch` | Idle, Forward, Backward, Left, and Right targets for Crouching |
+| `locomotion_style_variations_bs1_linear` | Idle and six style targets, such as Skipping and Zombie, for the style modes |
+
+## Node hierarchy
+
+Each node has a name and a local transform relative to its parent. Moving a node moves everything below it. The root node stands for the Smart Primitive itself. A scene places each instance by moving its root, and the other nodes keep their authored placement relative to it.
+
+The hierarchy also decides what moves together. Put the target poses that a pivot should move under the pivot node. Place interaction boxes and target poses around the object where the action happens.
+
+In **Hierarchy**:
+
+- **+** adds a child to the selected node. **-** deletes the selected node with its children, and the sequences drop their steps. Right click a node for the same actions.
+- Double click a node to rename it. Drag it onto another node to change its parent.
+- The checkbox hides a node and its children in the view.
+- The **Character** selector sets the rig. It is locked once a target pose has a clip.
+
+[Create the node hierarchy](guided_tutorial.md#create-the-node-hierarchy) in the tutorial builds the avoidance hierarchy.
+
+## Components
+
+To add a component, select a node, right click an empty area of **Properties**, and choose **Add** > **Components**. **Referenced by** lists the sequences that use the node.
+
+### Target Pose
+
+A Target Pose samples four poses at 30 Hz from a clip, starting at the chosen time. When a sequence uses the target, only the root of these poses moves to the node's world placement. Joint values stay as sampled, so one sampled target serves every placement.
+
+| Setting | Meaning |
+| --- | --- |
+| Clip | The BVH clip for SOMA or the CSV clip for Unitree G1 |
+| Seconds or Frames | The sample time. |
+| Constrain Root | Moves the clip's root to the node's origin along the ground and keeps its height. Without it, the pose stays where it was in the clip, relative to the clip's origin. |
+| IK Pins | SOMA only. Pulls the chosen hands or feet onto the target pose over the second half of the step. See [IK Pins](#ik-pins). |
+| Poses to Use | How many of the four poses inform the model. See [Set Poses to Use](inbetweener.md#set-poses-to-use). |
+| Transition Early By (frames) | Moves on to the next step this many frames before the generated motion ends. |
+| Tokens to Generate | Limits the length the model can choose for the step. A Target Pose starts at 6 to 14 tokens, and the model allows 6 to 16. Set both values to the same number to request a fixed length. The **Raw frames:** readout shows the matching frame range. |
+
+**Poses to Use**, **Transition Early By**, and **Tokens to Generate** work as they do for [Inbetweener targets](inbetweener.md#set-poses-to-use), except that the default token counts differ. **Speed** shows how fast the sampled poses move. The first target of a sequence sets the sequence's start speed. **Show Mesh**, **Show Skeleton(s)**, **Show Velocity**, and **Show Trajectory** change only the view.
+
+[Configure the target poses](guided_tutorial.md#configure-the-target-poses) in the tutorial sets up the Entry and Duck-under targets.
+
+#### IK Pins
+
+**IK Pins** lists the left and right hands and feet. Pin one when it must land exactly where the target pose puts it. For example, two targets of the SOMA vault, `jump_0_75m`, pin the left hand.
+
+During playback, two-bone IK pulls each pinned hand or foot to where it is in the step's first target pose. The pull starts halfway through the generated step and reaches full strength at its transition point. Each generation replaces the pins, so a step without pins clears them. They also clear when the sequence ends.
+
+The character records the corrected pose, so the next generation starts from where the hand or foot actually was. Only SOMA has target pose IK. `TargetPoseIKCorrector` in [target_pose.py](../motionbricks/runtime/target_pose.py) implements it.
+
+### Interaction Box
+
+**Width**, **Depth**, and **Height** size the box around the node. In Scene Preview, an interaction can start when the character's probe box overlaps any of the Smart Primitive's interaction boxes. The boxes only start interactions. They are not collision geometry for the model.
+
+A Smart Primitive can have several interaction boxes, one on each of several nodes. The probe box of a crouching character is shorter, so a raised interaction box only catches a standing character. The bundled `avoidance` document raises its box for this reason.
+
+[Configure the Interaction Box](guided_tutorial.md#configure-the-interaction-box) in the tutorial sizes and places the avoidance box.
+
+### Pivot
+
+A pivot makes one sequence work from many approaches. When a sequence starts, its pivot node moves and turns toward the character's approach, and every target below it follows. Only the roots of the target poses move.
+
+![A character arrives from the side, without a pivot and with the tutorial Pivot](media/tut_pivot_00_problem.gif)
+
+*A character arrives at 90 degrees to the authored sequence. Without a pivot, on the left, it walks to the authored Entry pose and turns. With the tutorial Pivot, on the right, the target poses turn and slide onto its course.*
+
+| Setting | Meaning |
+| --- | --- |
+| Motion Direction | The pivot's local direction that should line up with the approach |
+| Translation | Slides the pivot along one local axis. **Line Projection** keeps it within the **Offsets**, measured from where it was authored. |
+| Rotation | Turns the pivot around one local axis. **Cone** limits the turn to **Half Angle** on each side of the cone's center. **Cone Side** sets that center: **Motion Direction**, **Mirrored** for the opposite direction, or **Both** for either. |
+| Operation Order | **Translation -> Rotation** slides first. **Rotation -> Translation** turns first, which also turns the line the pivot slides along. |
+
+**Show Motion Direction**, **Show Translation Constraint**, and **Show Rotation Constraint** draw these settings in the view:
+
+![Authored layout of the tutorial Pivot, top view](media/tut_pivot_01_layout.png)
+
+*The tutorial Pivot from above. The yellow arrow is the Motion Direction, and the red dashed line is the range of the Line Projection.*
+
+The pivot aligns once, when the sequence starts. Its limits are measured from the authored placement, never from a previous alignment, so a Smart Primitive does not drift over repeated interactions. A sequence without a pivot keeps its current placement.
+
+[Configure the Pivot](guided_tutorial.md#configure-the-pivot) in the tutorial sets up a pivot. [Understanding the Pivot](guided_tutorial.md#understanding-the-pivot) shows how each setting behaves, compares six approaches, and explains why the aligned poses continue the incoming motion.
+
+## Sequences
+
+A sequence lists target pose nodes in the order the character reaches them. Each step generates toward one target, with that target's settings. A sequence can name a pivot node, which aligns the whole sequence to the approach before it starts.
+
+Several sequences can share nodes. That is how one document holds variations of an action, such as the Walk and Jog sequences of the bundled `avoidance` document. The behavior that a scene chooses for the instance picks the sequence:
+
+- `VelocityMatchingSequenceBehavior` picks the sequence whose start speed is closest to the character's speed.
+- `SittingBehavior` plays the sequences named Sit and Stand.
+
+[Scene Preview](scene_preview.md#smart-primitive-behaviors) describes the behaviors and how to write one.
+
+In **Sequences**:
+
+- **+** adds a sequence and starts renaming it. **-** deletes the selected one. Right click a sequence to rename or delete it.
+- **Pivot** sets the sequence's pivot node, or **None**.
+- **+ Add Target Pose** adds a step. You can also drag a node from **Hierarchy** onto the sequence header. Only nodes with a **Target Pose** become steps.
+- Drag steps to reorder them, and click **x** to remove one.
+
+[Define the sequence](guided_tutorial.md#define-the-sequence) in the tutorial orders the Entry and Duck-under steps. [Explore variations](guided_tutorial.md#explore-variations) adds more sequences to the same document.
+
+## How a scene places the poses
+
+For each step, Scene Preview:
+
+1. Lets the behavior pick a sequence and align its pivot to the character's approach.
+2. Computes each target node's world transform from the instance's placement in the scene and the node hierarchy.
+3. Moves the root of the node's four sampled poses by that transform. Joint values stay as sampled.
+4. Generates from the character's recent motion toward those poses.
+
+Because only the root moves, one set of sampled poses serves every placement. The same document works for any instance in any scene, and for both jump directions of the same cube. The [Scene Editor](scene_editor.md) stores each instance's placement.
+
+## Example: a sitting hold
+
+A hold keeps the character in a pose until something happens. The sitting hold in [sit.smart_primitive.json](../assets/smart_primitives/soma/sit.smart_primitive.json) combines two sequences with a looping clip:
+
+```text
+Root
+├── InteractionBox Interaction Box
+└── Pivot Pivot, turns around Z to face the approach
+ └── Sit Target Pose: sit_on_chair_loop, frame 0, 1 pose, Constrain Root
+ ├── ToStand Target Pose: sit_on_chair_stop at 1.99 s, 4 poses
+ └── ToSit Target Pose: sit_on_chair_start at 1.85 s, 4 poses
+
+Sequences
+ Sit ToSit, Sit Pivot: Pivot
+ Stand ToStand Pivot: None
+```
+
+1. **Sit** first reaches ToSit, a pose from the sitting clip just before the character sits. Then it reaches Sit, which is the first frame of the looping clip. The pivot turns both targets toward the approach, so the character turns around and sits from any side.
+2. When Sit completes, `SittingBehavior` plays [sit_on_chair_loop](../assets/motions/soma/sitting/sit_on_chair_loop.bvh) as a loop, aligned to the reached pose. Because the Sit target is the loop's first frame, the handoff from generated motion to the clip is smooth.
+3. When you press **I** (**X** on a controller), the behavior plays **Stand**, which generates toward a standing pose from the stand-up clip. Stand has no pivot, so it keeps the placement chosen by Sit.
+4. When Stand completes, the character returns to locomotion or idle.
+
+<p align="center">
+ <img src="media/sit_hold_soma.gif" alt="SOMA sits down, holds, stands up, and walks off" width="80%">
+</p>
+
+To build another hold, such as leaning on a wall:
+
+1. Prepare a looping clip of the held pose.
+2. Author an entry sequence that ends on the looping clip's first frame with **Constrain Root**, and an exit sequence that returns to a standing pose.
+3. Add a pivot to the entry sequence so the hold adapts to the approach.
+4. Write a behavior class like `SittingBehavior`. [Write a behavior](scene_preview.md#write-a-behavior) in Scene Preview shows an example.
+5. Choose that class as the scene instance's **Behavior** in the [Scene Editor](scene_editor.md).
+
+## Document format
+
+Documents are plain JSON:
+
+| Field | Contents |
+| --- | --- |
+| `format`, `schema_version` | `motionbricks.smart_primitive.authoring` and 1 |
+| `name`, `rig` | The document name and `soma` or `unitree_g1` |
+| `root` | The node tree. Each node has an `id`, a `name`, a `local_transform`, its `components`, and its `children`. |
+| `sequences` | Each sequence has an `id`, a `name`, its `node_ids` in order, and a `pivot_node_id` or `null` |
+| `editor` | The selected node and the camera. The editor restores them. |
+
+Clip paths are relative to the document. Opening a document checks its rig against the clips. Scene Preview reads the same files, so there is no export step.
+
+**File** > **Save** and **Save As...** write the document. Each component is saved with its `type`, such as `target_pose`, `interaction_box`, or `pivot`, and its settings. A Target Pose saves its clip and sample time, not the sampled poses. Loading samples the poses again from the clip.
+
+## Further reference
+
+- [Guided tutorial](guided_tutorial.md#part-2-build-a-smart-primitive): building the avoidance Smart Primitive step by step.
+- [Scene Editor](scene_editor.md): placing Smart Primitive instances in a scene.
+- [Scene Preview](scene_preview.md): the behaviors and states that play Smart Primitive sequences.
+- [Runtime API](runtime_api.md): target settings, motion players, and chaining.
diff --git a/docs/soma_model.md b/docs/soma_model.md
new file mode 100644
index 0000000..58ada3d
--- /dev/null
+++ b/docs/soma_model.md
@@ -0,0 +1,280 @@
+# MotionBricks SOMA Model Card
+
+## Model Description
+
+MotionBricks SOMA generates 3D human motion from recent motion and target poses. It predicts short transitions that an application joins into continuous animation, updating the targets as the character moves through a scene.
+
+The [MotionBricks](https://nvlabs.github.io/motionbricks/) model is trained on Bones RigPlay 1 (RP1) motion prepared for the 30-joint [SOMA](https://github.com/NVlabs/SOMA-X) skeleton.
+
+This card covers the SOMA ONNX models in MotionBricks v0.2.0. Each ONNX model combines the pose tokenizer and decoder, pose predictor, and root predictor from `MotionBricks-SOMA-RP-v1`. The FP32 and mixed FP16 variants share the same tensor interface. FP32 uses 32-bit floating-point precision. Mixed FP16 uses 16-bit precision for selected operations.
+
+The SafeTensors checkpoint has its own model card and component interfaces. [Unitree G1 models](unitree_g1_model.md) are documented separately. A training pipeline is not included.
+
+This model is intended for commercial and non-commercial motion-generation applications.
+
+### Where to Start
+
+- To run the demo, follow [Setup](../README.md#setup), then the commands under [Inference](#inference).
+- To add generation to an application, use the [runtime API](runtime_api.md#engines).
+- To export ONNX models from the SafeTensors checkpoint, follow the [exporter guide](../tools/onnx/README.md).
+
+| Property | Value |
+| --- | --- |
+| Model family | MotionBricks |
+| Task | Motion generation and inbetweening conditioned on poses |
+| Skeleton | SOMA, 30 joints |
+| Parameters | About 200 million in the checkpoint |
+| Public pose representation | Root motion, joint positions, and 6D rotations |
+| Model format | ONNX, opset 17 |
+| Precisions | FP32 and mixed FP16 |
+| Batch size | Variable `N`. The demos use `N=1`. |
+| FPS | 30 |
+| Context | Four recent poses |
+| Targets | Up to four placed poses |
+| Output length | 24 to 64 raw frames, or 18 to 58 after the engine removes the boundary frames |
+
+## License and Terms of Use
+
+Use of this model is governed by the [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). It permits commercial use and redistribution of modified models, subject to the agreement's terms.
+
+- The accompanying software uses [Apache 2.0](../LICENSE).
+- The listed Bones-derived human BVH and G1 CSV samples use the [NVIDIA Sample Data Evaluation License](../assets/motions/LICENSE.txt). They are for internal evaluation and testing of NVIDIA technologies. See the [sample notice](../assets/motions/README.md) for the exact files covered.
+- Robot assets and third-party dependencies retain their [respective licenses](../licenses).
+
+## Deployment Geography
+
+Global.
+
+## Intended Uses
+
+**Use Case:** Generate pose-conditioned human motion for animation, robotics simulation, and interactive character applications.
+
+- Generate transitions between authored or sampled human poses.
+- Drive interactive locomotion by placing targets from the application.
+- Animate approaches to objects and interactions described by target poses.
+- Prototype character animation in games, media tools, and simulation scenes.
+
+The application supplies target positions and orientations in the scene. Generated motion can become the context for the next generation.
+
+This model is intended for developers and researchers building animation, robotics, and simulation workflows, both commercial and non-commercial. Generated motion is not validated for physical robot control.
+
+## References
+
+T. Wang, O. Dionne, M. De Ruyter, D. Minor, D. Rempe, K. Zhao, M. Petrovich, Y. Yuan, C. Li, Z. Luo, B. Robison, X. Blackwell, B. Antoniazzi, X. B. Peng, Y. Zhu, and S. Yuen. **MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives**. ACM Transactions on Graphics 45(4), 2026. [DOI 10.1145/3811334](https://doi.org/10.1145/3811334), [arXiv:2604.24833](https://arxiv.org/abs/2604.24833).
+
+## Model Architecture
+
+**Architecture Type:** Modular latent generative model.
+
+**Network Architecture:** Transformers that predict the root motion and the motion tokens, with a learned motion decoder.
+
+| Component | Role | Parameters |
+| --- | --- | --- |
+| Pose VQ-VAE (vector-quantized variational autoencoder) | Encodes tokens of four poses and decodes motion. Its codebook has 5 heads of 16 codes. | 23.4 million |
+| Pose model | Masked transformer that predicts motion tokens, with 16 layers of width 1024 | 136.5 million |
+| Root model | Predicts the duration and the root path | 40.4 million |
+
+The method is described in the [MotionBricks paper](https://arxiv.org/abs/2604.24833).
+
+**Base Model:** The SOMA components were trained from scratch on RP1 motion. The ONNX export combines those trained components into a deployment graph and converts precision where requested. Exporting does not retrain them or introduce a new training dataset.
+
+## Inputs
+
+**Input modality:** Poses as joint positions and 6D rotations, root motion constraints, and allowed token counts. The eight conditioning slots hold four context poses followed by four target poses, sampled at 30 Hz.
+
+**Input format:** Numeric ONNX tensors. Motion values use FP32, and masks and token counts use INT32. The input tensor table defines each parameter's name, shape, and meaning.
+
+`N` is the number of independent requests, and all inputs must use the same `N`. The model manifest `soma_n1.json` describes the tensors for `N=1`.
+
+### Pose Representation
+
+Poses describe joint positions and 6D rotations on the SOMA skeleton. The root joint is `Hips`. Root features provide position, heading, velocity, and height constraints. SOMA model space is Y up, with XZ as the ground plane. Positions use meters. Each 6D rotation holds the first two columns of a joint's rotation matrix in SOMA model space. Context and target poses share the same space. The model manifest [soma_n1.json](../motionbricks/assets/onnx/soma/soma_n1.json) records the joint order and each tensor's name, shape, and dtype.
+
+### Input Tensors
+
+| Input | Shape | Type | Meaning |
+| --- | --- | --- | --- |
+| `global_root_values` | `[N,8,5]` | FP32 | Root position (XYZ), then the cosine and sine of the heading |
+| `has_global_root_values` | `[N,8]` | INT32 | Mask for the root position and heading |
+| `local_root_values` | `[N,8,4]` | FP32 | Heading rate in rad/s, root ground velocity along X and Z in m/s, and root height |
+| `has_local_root_values` | `[N,8]` | INT32 | Mask for the root velocity and height |
+| `local_poses` | `[N,8,267]` | FP32 | Positions of the 29 non-root joints relative to the root's ground position (87 values), then a 6D rotation for each of the 30 joints (180 values) |
+| `has_local_poses` | `[N,8]` | INT32 | Mask for the body pose |
+| `allowed_pred_num_tokens` | `[N,11]` | INT32 | Allowed token counts, 6 to 16 |
+
+All seven inputs are required. Masks contain 0 or 1, with context slots first, then target slots. At least one token count must be allowed. Entry `i` of `allowed_pred_num_tokens` allows a token count of `6 + i`. Each motion token represents four poses.
+
+## Outputs
+
+**Output modality:** Skeletal motion features with predicted foot contacts, and the chosen token count.
+
+**Output format:** Numeric ONNX tensors. Motion features use FP32, and the token count uses INT32. The output tensor table defines each parameter's name, shape, and meaning.
+
+| Output | Shape | Type | Meaning |
+| --- | --- | --- | --- |
+| `pred_global_motions` | `[N,64,366]` | FP32 | Per frame: root position and heading (5), joint positions (87), 6D rotations (180), joint velocities (90), and foot contacts (4), in SOMA model space |
+| `pred_num_tokens` | `[N]` | INT32 | Token count the model chose |
+
+The leading `4 * pred_num_tokens` frames contain generated motion. The raw output contains 24 to 64 frames. Removing three boundary frames at each end leaves 18 to 58 valid frames at 30 Hz. The engine decodes these features into the root position and joint rotations.
+
+The last four features of each frame are foot contacts for the left heel, left toe, right heel, and right toe. Their joints are `LeftFoot`, `LeftToeBase`, `RightFoot`, and `RightToeBase`. See [foot_contacts.py](../motionbricks/animation/foot_contacts.py) for their meaning.
+
+## Software Integration
+
+| Component | Integration |
+| --- | --- |
+| Tested inference runtime | NVIDIA TensorRT 10.8 |
+| Application framework | Python and NVIDIA Warp |
+| Demo environment | Newton |
+| Tested operating system | Windows |
+| Documented deployment hardware | NVIDIA Ada Lovelace GeForce RTX 4090 |
+
+The application supplies placed context and target poses. The engine handles coordinate conversion and returns generated motion in world space.
+
+The table identifies the tested setup, not a complete compatibility matrix. Timings are reported only for the GeForce RTX 4090 under Windows. The checkpoint-to-ONNX exporter runs on CPU and is separate from this GPU inference path. A CPU-versus-GPU inference comparison is not provided.
+
+The integration of foundation and fine-tuned models into AI systems requires additional testing using use-case-specific data to ensure safe and effective deployment. Following the V-model methodology, iterative testing and validation at both unit and system levels are essential to mitigate risks, meet technical and functional requirements, and ensure compliance with safety and ethical standards before deployment.
+
+### Runtime Generation
+
+`MotionBricksSOMAEngine` runs the generation calls in [Engines](runtime_api.md#engines). Its `PoseToken` context and target hold local joint transforms. It generates into the same `AnimationBuffer` type that loaded BVH clips use.
+
+The skeleton passed to `create_input()` and `create_output()` must contain the model's joint names, with the root at index zero. The engine maps model joints to this skeleton. Pass `model_to_runtime` when world space differs from SOMA model space.
+
+Before inference, the engine removes the ground position and heading of the last context pose. It keeps the root height. After inference, it restores the world placement and removes three boundary frames at each end. By default, inference turns the last context pose to face +X in SOMA model space.
+
+## Model Versions
+
+**Model version:** `MotionBricks-SOMA-RP-v1`. The accompanying software release is v0.2.0.
+
+| Precision | ONNX file |
+| --- | --- |
+| FP32 | `mmm_v6_soma_fp32.onnx` |
+| Mixed FP16 | `mmm_v6_soma_fp16.onnx` |
+
+Files are stored in [motionbricks/assets/onnx/soma](../motionbricks/assets/onnx/soma).
+
+Motion inputs and outputs use FP32 in both variants. Masks and token counts use INT32. The [SOMA checkpoint on Hugging Face](https://huggingface.co/nvidia/MotionBricks/tree/main/soma) contains the SafeTensors weights used by the [exporter](../tools/onnx/README.md).
+
+## Training, Testing and Evaluation Datasets
+
+### Training Dataset
+
+**Name/Identifier:** Bones RigPlay 1 (RP1).
+
+**Data Modality:** Other: human skeletal motion capture processed into the uniform 30-joint SOMA representation at 30 Hz. The training inputs are motion features, not text, images, audio, or video.
+
+**Training Data Size:** 313,526 human-motion clips in the selected training subset. The source corpus contains approximately 350,000 clips and 700 hours of motion. The source-corpus duration is not the selected training-subset duration.
+
+**Data Collection Method:** Automatic/Sensors. Bones recorded human performances in a motion-capture studio and supplied skeletal motion. NVIDIA processed that motion into a uniform SOMA representation. The source performances were not captured directly on the SOMA skeleton.
+
+**Labeling Method:** Automatic/Sensors for captured skeletal motion, followed by automated preparation into uniform motion features. Pose and motion values are the learning data. The recorded runs do not consume text embeddings or text annotations.
+
+**Properties:** Training uses uniform SOMA motion features, random first headings, and random crops of up to 15 seconds. Root motion and joint features provide the motion representation. Text embeddings and text augmentation are disabled. All three checkpoint components were trained in FP32. The training corpus is not distributed with these exports.
+
+**Linguistic Characteristics:** Not applicable to the motion-feature inputs. Associated text descriptions are dataset metadata, not model conditioning inputs.
+
+### Testing Dataset
+
+**Name, Size and Role:** We used 313,526 clips for training and a separate, selected set of 4,881 clips for validation and evaluation during training. No clips are shared between these sets. The 4,881 clips are a selection from the held-out pool, not the entire pool. A separate untouched final-test set, a performer-disjoint split, and the selected subset's duration are not documented.
+
+**Data Collection Method:** Automatic/Sensors, from the same Bones studio motion-capture source and processed uniform SOMA representation as the training set.
+
+**Labeling Method:** Automatic/Sensors for the skeletal motion, followed by automated preparation into the same motion features. Text annotations are not consumed by the recorded validation path.
+
+**Properties:** The validation inputs are 30 Hz skeletal-motion features in the same uniform SOMA representation as the training inputs. Linguistic characteristics are not applicable to these motion-only inputs. Disjoint clips alone do not rule out other forms of data leakage.
+
+### Evaluation Dataset and Results
+
+**Name/Size:** Evaluation uses the same 4,881-clip RP1 subset described under [Testing Dataset](#testing-dataset). It is not an additional independent test set.
+
+**Benchmark Score:** A complete end-to-end benchmark of these SOMA ONNX models is not provided.
+
+**Data Collection Method:** Automatic/Sensors. Bones captured the source motion in a studio.
+
+**Labeling Method:** Automatic/Sensors for captured skeletal motion, followed by automated preparation into uniform SOMA motion features.
+
+**Properties:** SOMA skeletal-motion features at 30 Hz, without text-conditioned labels. Linguistic characteristics are not applicable to these inputs. The subset's duration is not documented.
+
+**Recorded Results:** Training measured tokenizer reconstruction and foot skating, root-predictor validation, and pose-predictor training loss. A complete pose-predictor validation result is not provided. These measurements do not evaluate the exported ONNX models.
+
+The ONNX models were tested in the setup listed under [Software Integration](#software-integration). The GPU time and throughput of the TensorRT plans at several batch sizes are in [Inference performance](onnx_inference.md#inference-performance). Quantitative motion quality and an FP32-versus-mixed-FP16 quality comparison are not reported. The [MotionBricks paper](https://arxiv.org/abs/2604.24833) describes method-level experiments on its own models and datasets, not a benchmark of these SOMA ONNX models.
+
+## Inference
+
+FP32 is the default. Run the demo with either precision:
+
+```sh
+uv run python -m app.scene_preview --model-precision fp32
+uv run python -m app.scene_preview --model-precision fp16
+```
+
+The SOMA TensorRT configuration permits TF32 for eligible FP32 operations.
+
+The mixed FP16 ONNX model uses FP16 for the neural predictors and the motion decoder. It keeps FP32 for feature normalization, motion geometry, LayerNormalization, Softmax, and Resize. The demos build a TensorRT plan for `N=1`.
+
+Mixed FP16 and FP32 can produce different motion, because rounding affects the choice of motion tokens.
+
+**Acceleration Engine:** NVIDIA TensorRT 10.8.
+
+**Test Hardware Set-Up:** NVIDIA Ada Lovelace GeForce RTX 4090 on Windows.
+
+The exporter checks checkpoint integrity, ONNX graph validity, and the expected tensor interface. Those structural checks do not establish complete security coverage, safe physical behavior, or equivalent motion quality across precisions and backends.
+
+## Limitations
+
+- The demos run one request at a time with the same batched ONNX model available to users. Context and target tokens hold at most four poses each, so longer motion requires repeated generation. See [batching](onnx_inference.md).
+- The model uses the SOMA joint layout and proportions. Other skeletons require an appropriate representation or a retargeting step.
+- Conditioning comes from poses and motion constraints. Text prompts and scene geometry are outside this model's input interface. The application places targets and handles obstacles.
+- The model works best with target poses within its training distribution. Poses outside it can produce lower quality motion.
+- Generated motion can vary with precision and inference runtime. Differences can accumulate when generated motion is fed back as context.
+- Kinematic motion generation does not establish dynamic feasibility, physical robot tracking, collision avoidance, or safe contact. Physical execution requires a separate controller and application-specific validation.
+
+## Ethical Considerations
+
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. Developers should work with their internal model team to ensure this model meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+For more detailed information, see the [Bias](#bias-subcard), [Explainability](#explainability-subcard), [Privacy](#privacy-subcard) and [Safety and Security](#safety-and-security-subcard) subcards below.
+
+Please report model quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
+
+## Bias Subcard
+
+| Field | Response |
+| --- | --- |
+| Participation considerations from adversely impacted groups in model design and testing | Not reported. |
+| Measures taken to mitigate unwanted bias | Specific measured mitigation is not reported. Applications should evaluate motion quality for their users and motion conditions. |
+| Bias Metric, if measured | Comparisons of demographic, body, and motion coverage are not reported. |
+
+The fixed SOMA representation does not establish equivalent quality across body proportions or motion categories. Precision conversion does not establish new subgroup-performance evidence.
+
+## Explainability Subcard
+
+| Field | Response |
+| --- | --- |
+| Intended Task/Domain | Pose-conditioned human skeletal motion generation and inbetweening. |
+| Model Type | Modular latent generative model, with transformer predictors and learned pose tokenizer and decoder. |
+| Intended Users | Developers and researchers building animation, robotics, and simulation workflows. |
+| Output | Batched skeletal-motion features and selected token count through the two-output ONNX interface. The engine decodes features into the root position and joint rotations. |
+| Describe how the model works | Recent motion and target constraints condition root and pose predictors. A tokenizer represents motion as discrete codes, and a decoder reconstructs skeletal motion. The combined graph includes the inference feature transformations. Applications can reuse output as context. |
+| Groups tested to produce comparable outcomes | Demographic subgroup comparisons are not reported. |
+| Technical Limitations and Mitigation | Fixed skeleton, short context, no scene-geometry input, and variation across backends and precisions. Validate application-specific motion, target placement, and any physical execution separately. |
+| Verified to have met prescribed NVIDIA quality standards | Yes |
+| Performance Metrics | See [Evaluation Dataset and Results](#evaluation-dataset-and-results) for the available measurements and their limits. |
+| Potential Known Risks | Pose/contact artifacts, unwanted motion under out-of-distribution constraints, and unsafe physical interpretation if generated poses are treated as validated robot commands. |
+| Licensing | Use of this model is governed by the [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). See [License and Terms of Use](#license-and-terms-of-use) for separate software and sample-data terms. |
+
+## Privacy Subcard
+
+The datasets used to train this model were reviewed before release. Please review [NVIDIA’s Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/) for more information.
+
+## Safety and Security Subcard
+
+| Field | Response |
+| --- | --- |
+| Model Application Fields | Industrial/Machinery and Robotics, Media & Entertainment. Generated motion is not validated for physical robot control. |
+| Life-critical impact | Generated skeletal motion is not a validated physical controller. Misuse as robot commands can create physical risk. |
+| Use Case Restrictions | Use of this model is governed by the [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). See [License and Terms of Use](#license-and-terms-of-use) for separate software and sample-data terms. |
+| Model and dataset restrictions | These ONNX files do not distribute the RP1 training corpus. Access to the dataset is governed separately from the model weights. |
+
+Evaluate generated motion in the intended application. Physical execution requires a separate tracking and safety system. Artifact-integrity and graph checks do not establish complete security or safe downstream behavior.
diff --git a/docs/unitree_g1_model.md b/docs/unitree_g1_model.md
new file mode 100644
index 0000000..9668b83
--- /dev/null
+++ b/docs/unitree_g1_model.md
@@ -0,0 +1,300 @@
+# MotionBricks Unitree G1 Model Card
+
+## Model Description
+
+MotionBricks Unitree G1 generates robot motion from recent poses and placed target poses. It produces short transitions that an application can join into continuous reference motion.
+
+The [MotionBricks](https://nvlabs.github.io/motionbricks/) model is trained on motion capture retargeted to a 34-joint Unitree G1 skeleton. It reuses the original weights released in [GR00T Whole-Body Control](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/main/motionbricks).
+
+This card covers the G1 ONNX models in MotionBricks v0.2.0. Each ONNX model combines the pose tokenizer and decoder, pose predictor, and root predictor from `MotionBricks-G1-RP-v1`. It accepts and returns G1 joint coordinates, handling the conversion to skeletal features within the model. The FP32 and mixed FP16 variants share the same tensor interface. FP32 uses 32-bit floating-point precision. Mixed FP16 uses 16-bit precision for selected operations.
+
+The SafeTensors checkpoint has its own model card and component interfaces. [SOMA models](soma_model.md) are documented separately. A training pipeline is not included.
+
+This model is intended for commercial and non-commercial motion-generation applications.
+
+### Where to Start
+
+- To run the G1 demo, follow [Setup](../README.md#setup), then the commands under [Inference](#inference).
+- To add generation to an application, use the [runtime API](runtime_api.md#engines).
+- To export ONNX models from the SafeTensors checkpoint, follow the [exporter guide](../tools/onnx/README.md).
+
+| Property | Value |
+| --- | --- |
+| Model family | MotionBricks |
+| Task | Robot motion generation and inbetweening conditioned on poses |
+| Robot | Unitree G1, 29 joint angles and a floating root |
+| Skeleton | Unitree G1, 34 model joints |
+| Parameters | About 195 million in the checkpoint |
+| Public pose representation | Root XYZ, XYZW quaternion, and 29 joint angles |
+| Model format | ONNX, opset 17 |
+| Precisions | FP32 and mixed FP16 |
+| Batch size | Variable `N`. The demos use `N=1`. |
+| FPS | 30 |
+| Context | Four recent poses |
+| Targets | Up to four placed poses |
+| Output length | 24 to 64 raw frames, or 18 to 58 after the engine removes the boundary frames |
+
+## License and Terms of Use
+
+Use of this model is governed by the [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). It permits commercial use and redistribution of modified models, subject to the agreement's terms.
+
+- The accompanying software uses [Apache 2.0](../LICENSE).
+- The listed Bones-derived human BVH and G1 CSV samples use the [NVIDIA Sample Data Evaluation License](../assets/motions/LICENSE.txt). They are for internal evaluation and testing of NVIDIA technologies. See the [sample notice](../assets/motions/README.md) for the exact files covered.
+- Robot assets and third-party dependencies retain their [respective licenses](../licenses).
+
+## Deployment Geography
+
+Global.
+
+## Intended Uses
+
+**Use Case:** Generate pose-conditioned G1 reference motion for animation, robotics simulation, and downstream control experiments.
+
+- Generate transitions between G1 poses or poses sampled from motion clips.
+- Preview locomotion and steering in Newton by placing target poses.
+- Produce kinematic reference motion for robot control experiments.
+- Explore repeated generation that uses the previous output as the next context.
+
+The output describes desired poses. A controller downstream is responsible for tracking those poses under robot dynamics and physical constraints.
+
+This model is intended for developers and researchers building animation, robotics, and simulation workflows, both commercial and non-commercial. Generated motion is not validated for physical robot control.
+
+## References
+
+T. Wang, O. Dionne, M. De Ruyter, D. Minor, D. Rempe, K. Zhao, M. Petrovich, Y. Yuan, C. Li, Z. Luo, B. Robison, X. Blackwell, B. Antoniazzi, X. B. Peng, Y. Zhu, and S. Yuen. **MotionBricks: Scalable Real-Time Motions with Modular Latent Generative Model and Smart Primitives**. ACM Transactions on Graphics 45(4), 2026. [DOI 10.1145/3811334](https://doi.org/10.1145/3811334), [arXiv:2604.24833](https://arxiv.org/abs/2604.24833).
+
+## Model Architecture
+
+**Architecture Type:** Modular latent generative model.
+
+**Network Architecture:** Transformers that predict the root motion and the motion tokens, with a learned motion decoder.
+
+| Component | Role | Parameters |
+| --- | --- | --- |
+| Pose VQ-VAE (vector-quantized variational autoencoder) | Encodes tokens of four poses and decodes motion. Its codebook has 8 heads of 10 codes. | 23.8 million |
+| Pose model | Masked transformer that predicts motion tokens, with 16 layers of width 1024 | 136.6 million |
+| Root model | Predicts the duration and the root path | 34.1 million |
+
+The ONNX model converts between G1 joint coordinates and the transforms of its 34-joint skeleton. The method is described in the [MotionBricks paper](https://arxiv.org/abs/2604.24833).
+
+**Base Model:** The original G1 components were trained from scratch on RP1 motion retargeted to G1. This release reuses those weights without retraining. The ONNX export combines the components and adds the joint-coordinate interface.
+
+## Inputs
+
+**Input modality:** G1 joint coordinates, conditioning masks, and allowed token counts. Context and target poses are in G1 model space and sampled at 30 Hz.
+
+**Input format:** Numeric ONNX tensors. Joint coordinates use FP32, and masks and token counts use INT32. The input tensor table defines each parameter's name, shape, and meaning.
+
+`N` is the number of independent requests, and all inputs must use the same `N`. The model manifest `unitree_g1_n1.json` describes the tensors for `N=1`.
+
+### Pose Representation
+
+Every pose contains 36 FP32 joint coordinates:
+
+```text
+[root_x, root_y, root_z, root_qx, root_qy, root_qz, root_qw, 29 joint angles]
+```
+
+G1 model space is Z up, with +X forward. Positions use meters, and joint angles use radians. The root joint is the pelvis. Quaternion components use XYZW order. Joint angle order is defined by `joint_names` in [unitree_g1_n1.json](../motionbricks/assets/onnx/unitree_g1/unitree_g1_n1.json).
+
+### Input Tensors
+
+| Input | Shape | Type | Meaning |
+| --- | --- | --- | --- |
+| `context_qpos` | `[N,4,36]` | FP32 | Four recent context poses at 30 Hz |
+| `target_qpos` | `[N,4,36]` | FP32 | Four placed target poses |
+| `has_global_root_values` | `[N,8]` | INT32 | Mask for the root position and heading |
+| `has_local_root_values` | `[N,8]` | INT32 | Mask for the root velocity and height |
+| `has_local_poses` | `[N,8]` | INT32 | Mask for the body pose |
+| `allowed_pred_num_tokens` | `[N,11]` | INT32 | Allowed token counts, 6 to 16 |
+
+All six inputs are required. Masks contain 0 or 1, with context slots first, then target slots. At least one token count must be allowed. Entry `i` of `allowed_pred_num_tokens` allows a token count of `6 + i`. Each motion token represents four poses.
+
+Pose values must be finite and root quaternions non-zero, including masked slots.
+
+## Outputs
+
+**Output modality:** G1 joint coordinates, predicted foot contacts, and the chosen token count.
+
+**Output format:** Numeric ONNX tensors. Joint coordinates and foot contacts use FP32. The token count uses INT32. The output tensor table defines each parameter's name, shape, and meaning.
+
+| Output | Shape | Type | Meaning |
+| --- | --- | --- | --- |
+| `pred_qpos` | `[N,64,36]` | FP32 | Decoded joint coordinates in the same space as the inputs |
+| `pred_num_tokens` | `[N]` | INT32 | Token count the model chose |
+| `pred_foot_contacts` | `[N,64,4]` | FP32 | Predicted foot contacts for each frame of `pred_qpos` |
+
+The leading `4 * pred_num_tokens` frames contain generated motion. The raw output contains 24 to 64 frames. Removing three boundary frames at each end leaves 18 to 58 valid frames at 30 Hz.
+
+Each frame of `pred_foot_contacts` holds four foot contacts for the left heel, left toe, right heel, and right toe. The heel contact points are at the ankle roll joints. Each toe contact point sits 0.14 m ahead of its ankle roll joint and 0.035 m below it, in the ankle roll link's local space. See [foot_contacts.py](../motionbricks/animation/foot_contacts.py) for their meaning.
+
+The foot contacts are model predictions. They are not contact sensor readings and do not guarantee stable contact on a physical robot.
+
+## Software Integration
+
+| Component | Integration |
+| --- | --- |
+| Tested inference runtime | NVIDIA TensorRT 10.8 |
+| Application framework | Python and NVIDIA Warp |
+| Demo environment | Newton |
+| Tested operating system | Windows |
+| Documented deployment hardware | NVIDIA Ada Lovelace GeForce RTX 4090 |
+
+The application supplies placed context and target poses. The engine aligns them for inference and returns generated motion in world space.
+
+The table identifies the tested setup, not a complete compatibility matrix. Timings are reported only for the GeForce RTX 4090 under Windows. The checkpoint-to-ONNX exporter runs on CPU and is separate from this GPU inference path. A CPU-versus-GPU inference comparison is not provided.
+
+The integration of foundation and fine-tuned models into AI systems requires additional testing using use-case-specific data to ensure safe and effective deployment. Following the V-model methodology, iterative testing and validation at both unit and system levels are essential to mitigate risks, meet technical and functional requirements, and ensure compliance with safety and ethical standards before deployment.
+
+### Runtime Generation
+
+`MotionBricksUnitreeG1Engine` runs the generation calls in [Engines](runtime_api.md#engines). Its `DOFToken` context and target hold joint coordinates as Warp FP32 arrays. It generates into the same `DOFAnimationBuffer` type that loaded CSV clips use.
+
+The caller can sample directly into one robot's view of Newton `model.joint_q`, then call `newton.eval_fk` for playback. No joint names are remapped. Pass `model_to_runtime` when world space differs from G1 model space.
+
+Before inference, the engine removes the ground position and heading of the last context pose. It keeps the root height and joint angles. After inference, it restores the world placement and removes three boundary frames at each end. By default, inference turns the last context pose to face +X in G1 model space.
+
+The engine smooths the decoded root position over neighboring frames. This removes frame-to-frame jitter in the model's output and keeps the gait.
+
+## Model Versions
+
+**Model version:** `MotionBricks-G1-RP-v1`. The accompanying software release is v0.2.0.
+
+| Precision | ONNX file |
+| --- | --- |
+| FP32 | `mmm_v6_g1_fp32.onnx` |
+| Mixed FP16 | `mmm_v6_g1_fp16.onnx` |
+
+Files are stored in [motionbricks/assets/onnx/unitree_g1](../motionbricks/assets/onnx/unitree_g1).
+
+Motion inputs and outputs use FP32 in both variants. Masks and token counts use INT32. The [G1 checkpoint on Hugging Face](https://huggingface.co/nvidia/MotionBricks/tree/main/g1) contains the SafeTensors weights used by the [exporter](../tools/onnx/README.md).
+
+## Training, Testing and Evaluation Datasets
+
+### Training Dataset
+
+**Name/Identifier:** Bones RigPlay 1 (RP1).
+
+**Data Modality:** Other: human motion capture retargeted to a 34-joint Unitree G1 representation at 30 Hz. The model uses skeletal motion features rather than text descriptions for conditioning.
+
+**Training Data Size:** 313,526 selected training clips. The source corpus contains approximately 350,000 RP1 clips and 700 hours of motion. The 700 hours describe the source corpus, not the selected training subset.
+
+**Data Collection Method:** Automatic/Sensors. Bones captured human performances in a studio and supplied skeletal motion. NVIDIA used [SOMA Retargeter](https://github.com/NVIDIA/soma-retargeter) to retarget that motion to G1, then converted it into model features. This preparation is not direct robot recording.
+
+**Labeling Method:** Automatic/Sensors for captured skeletal motion, followed by automated retargeting and feature preparation. Text annotations are not conditioning inputs for this motion-only model.
+
+**Properties:** Time-varying retargeted skeletal motion for pose-conditioned robot generation.
+
+**Linguistic Characteristics:** Not applicable to the motion-feature inputs. Associated text descriptions are dataset metadata, not model conditioning inputs.
+
+The ONNX conversion does not retrain the original G1 weights or introduce a new training dataset.
+
+### Testing Dataset
+
+**Name, Size and Role:** We used 313,526 clips for training and a separate, selected set of 4,881 clips for validation and evaluation during training. No clips are shared between these sets. The 4,881 clips are a selection from the held-out pool, not the entire pool. A separate untouched final-test set, a performer-disjoint split, and the selected subset's duration are not documented.
+
+**Data Collection Method:** Automatic/Sensors, from the same Bones studio motion-capture source as the training set. NVIDIA retargeted the human motion to the G1 representation.
+
+**Labeling Method:** Automatic/Sensors for captured skeletal motion, followed by automated retargeting and feature preparation.
+
+**Properties:** The validation inputs are 30 Hz skeletal-motion features on the 34-joint G1 representation. Text descriptions are selection metadata, not conditioning inputs. Linguistic characteristics are not applicable to these motion-only inputs. Disjoint clips alone do not rule out other forms of data leakage.
+
+### Evaluation Dataset and Results
+
+**Name/Size:** Evaluation uses the same 4,881-clip RP1 subset described under [Testing Dataset](#testing-dataset). It is not an additional independent test set.
+
+**Benchmark Score:** A complete quantitative evaluation of these G1 ONNX models is not provided.
+
+**Data Collection Method:** Automatic/Sensors, using the same studio-captured human motion retargeted to G1.
+
+**Labeling Method:** Automatic/Sensors for captured skeletal motion, followed by automated retargeting and feature preparation.
+
+**Properties:** Evaluation uses the same 30 Hz G1 skeletal-motion representation as training. Text descriptions are selection metadata, not conditioning inputs. Linguistic characteristics are not applicable to the motion-only inputs. The subset's duration is unspecified.
+
+**Recorded Results:** Training measurements for the original G1 components are not reported.
+
+The ONNX models were tested in the setup listed under [Software Integration](#software-integration). The GPU time and throughput of the TensorRT plans at several batch sizes are in [Inference performance](onnx_inference.md#inference-performance). Memory usage and demographic comparisons are not reported. A quality comparison between FP32 and mixed FP16 is also not reported.
+
+The [MotionBricks paper](https://arxiv.org/abs/2604.24833) describes method-level experiments on its own models and datasets. This Newton integration has not been evaluated for tracking on a physical robot.
+
+## Inference
+
+FP32 is the default. Run the G1 gym in Scene Preview with either precision:
+
+```sh
+uv run python -m app.scene_preview --scene assets/scenes/g1_gym.scene.json --model-precision fp32
+uv run python -m app.scene_preview --scene assets/scenes/g1_gym.scene.json --model-precision fp16
+```
+
+The G1 TensorRT configuration disables TensorFloat-32 (TF32) in both precisions. With TF32 enabled, a batch of one runs only about 2 percent faster, but joint angles can differ by several degrees on identical inputs. The differences grow across chained generations. Larger batches gain more, as [Inference performance](onnx_inference.md#inference-performance) shows. Pass `TensorRTBuildOptions(enable_tf32=True)` to allow it.
+
+The mixed FP16 ONNX model uses FP16 for the neural predictors and the motion decoder. It keeps FP32 for feature normalization, motion geometry, LayerNormalization, Softmax, and Resize. The G1 forward kinematics, motion integration, and conversion between quaternions and joint angles also stay FP32. The demos build a TensorRT plan for `N=1`.
+
+Mixed FP16 and FP32 can produce different motion, because rounding affects the choice of motion tokens.
+
+**Acceleration Engine:** NVIDIA TensorRT 10.8.
+
+**Test Hardware Set-Up:** NVIDIA Ada Lovelace GeForce RTX 4090 on Windows.
+
+The exporter checks checkpoint integrity, ONNX graph validity, and the expected tensor interface. Those structural checks do not establish complete security coverage, safe physical behavior, or equivalent motion quality across precisions and backends.
+
+## Limitations
+
+- The demos run one request at a time with the same batched ONNX model available to users. Context and target tokens hold at most four poses each, so longer motion requires repeated generation. See [batching](onnx_inference.md).
+- The joint coordinate interface is specific to the bundled G1 kinematics and joint order. Another robot or joint layout requires a matching conversion and model.
+- Conditioning comes from poses and motion constraints. Text prompts and scene geometry are outside this model's input interface. The application places targets and handles obstacles.
+- The model works best with target poses within its training distribution. Poses outside it can produce lower quality motion.
+- The model generates kinematic poses. Dynamic balance, actuator limits, collision avoidance, and contact tracking require a controller downstream.
+- Generated motion can vary with precision and inference runtime. Differences can accumulate when generated motion is fed back as context.
+- This Newton integration has not been evaluated for tracking on a physical robot.
+
+## Ethical Considerations
+
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. Developers should work with their internal model team to ensure this model meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+For more detail, see the [Bias](#bias-subcard), [Explainability](#explainability-subcard), [Privacy](#privacy-subcard) and [Safety and Security](#safety-and-security-subcard) subcards below.
+
+Please report model quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
+
+## Bias Subcard
+
+| Field | Response |
+| --- | --- |
+| Participation considerations from adversely impacted groups in model design and testing | Specific participation measures are not reported for the original G1 checkpoints or these exports. |
+| Measures taken to mitigate unwanted bias | A measured bias-mitigation procedure is not reported. Evaluate motion behavior across the intended application's users, targets and motion conditions. |
+| Bias Metric, if measured | No demographic subgroup or motion-coverage bias metric is reported for these exports. |
+
+Retargeting motion to one robot skeleton does not establish equal quality across the human behaviors represented in the source data or across motion categories.
+
+## Explainability Subcard
+
+| Field | Response |
+| --- | --- |
+| Intended Task/Domain | Pose-conditioned Unitree G1 motion generation and inbetweening. |
+| Model Type | Modular latent generative model with transformer predictors and a learned tokenizer and decoder. |
+| Intended Users | Developers and researchers building robot-motion previews, interactive pose transitions and reference-motion workflows. |
+| Output | Joint coordinates (root position, XYZW quaternion, and 29 joint angles), four foot contacts per frame, and the token count. These are kinematic references. |
+| Describe how the model works | The ONNX model converts joint coordinates into skeletal features. Root and pose predictors generate motion codes and root motion conditioned on recent and target poses. A decoder reconstructs motion, and the ONNX model converts it back to joint coordinates. |
+| Groups tested to produce comparable outcomes | Demographic subgroup comparisons are not reported. |
+| Technical Limitations and Mitigation | Fixed G1 kinematics, short context, no scene geometry, and variation across backends and precisions. Validate targets, motion quality, physical limits, and downstream tracking for the intended application. |
+| Verified to have met prescribed NVIDIA quality standards | Yes |
+| Performance Metrics | See [Evaluation Dataset and Results](#evaluation-dataset-and-results) for the available measurements and their limits. |
+| Potential Known Risks | Pose/contact artifacts, unsuitable motion from out-of-distribution constraints, and physical risk if a generated reference is treated as a safe control command. |
+| Licensing | Use of this model is governed by the [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). See [License and Terms of Use](#license-and-terms-of-use) for separate software and sample-data terms. |
+
+## Privacy Subcard
+
+The datasets used to train this model were reviewed before release. Please review [NVIDIA’s Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/) for more information.
+
+## Safety and Security Subcard
+
+| Field | Response |
+| --- | --- |
+| Model Application Fields | Industrial/Machinery and Robotics, Media & Entertainment. Generated motion is not validated for physical robot control. |
+| Life-critical impact | Generated reference motion is not a validated physical controller. Directly executing unsuitable motion on a robot can create physical risk. |
+| Use Case Restrictions | Use of this model is governed by the [NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/). See [License and Terms of Use](#license-and-terms-of-use) for separate software and sample-data terms. |
+| Model and dataset restrictions | The ONNX files do not redistribute the full training corpus. Dataset access and motion-sample use are governed separately from the model weights. |
+
+The exporter checks artifact integrity and graph structure. Those checks are not security approval or assurance of safe behavior. Evaluate the model and its downstream control system together under the intended operating conditions before physical use.
+
+Physical execution requires a downstream tracking controller, limit enforcement, and safety validation.
diff --git a/licenses/Daniel-Holden-MIT-LICENSE.txt b/licenses/Daniel-Holden-MIT-LICENSE.txt
new file mode 100644
index 0000000..8a05421
--- /dev/null
+++ b/licenses/Daniel-Holden-MIT-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Daniel Holden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/licenses/imgui_bundle-LICENSE.txt b/licenses/imgui_bundle-LICENSE.txt
new file mode 100644
index 0000000..b4aa09c
--- /dev/null
+++ b/licenses/imgui_bundle-LICENSE.txt
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021-2023 Pascal Thomet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file
diff --git a/licenses/imgui_bundle-components-LICENSE.txt b/licenses/imgui_bundle-components-LICENSE.txt
new file mode 100644
index 0000000..89f535d
--- /dev/null
+++ b/licenses/imgui_bundle-components-LICENSE.txt
@@ -0,0 +1,861 @@
+imgui-bundle 1.92.4 component notices
+
+MotionBricks installs imgui-bundle as a dependency. These notices apply to the
+identified components of that dependency, not to MotionBricks code or models.
+The imgui-bundle root license is in imgui_bundle-LICENSE.txt.
+
+======================================================================
+external/imspinner/imspinner/LICENSE.txt
+Source: https://raw.githubusercontent.com/pthom/imgui_bundle/v1.92.4/external/imspinner/imspinner/LICENSE.txt
+======================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2021-2022 Dalerank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui/imgui
+Source: https://raw.githubusercontent.com/pthom/imgui/8618a3c2da1abfe6aab17f27a32e42c602d2291e/LICENSE.txt
+======================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2014-2025 Omar Cornut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/glfw/glfw
+Source: https://raw.githubusercontent.com/glfw/glfw/7482de6071d21db77a7236155da44c172a7f6c9e/LICENSE.md
+======================================================================
+
+Copyright (c) 2002-2006 Marcus Geelnard
+
+Copyright (c) 2006-2019 Camilla Löwy
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would
+ be appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not
+ be misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source
+ distribution.
+
+======================================================================
+external/hello_imgui/hello_imgui
+Source: https://raw.githubusercontent.com/pthom/hello_imgui/8e8fd2c3333cf1b1fbac8ab0db3c09a07125f973/LICENSE
+======================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2019-2020 Pascal Thomet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/ImFileDialog/ImFileDialog
+Source: https://raw.githubusercontent.com/pthom/ImFileDialog/7d9ae5183770b9f73de62958840d5bff12ad194b/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2021 dfranx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui-knobs/imgui-knobs
+Source: https://raw.githubusercontent.com/pthom/imgui-knobs/ee9db0b014d6b2260d1c91beb5f0ae5c9fc520a5/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2022 Simon Altschuler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui-node-editor/imgui-node-editor
+Source: https://raw.githubusercontent.com/pthom/imgui-node-editor/bb59cc7478c8762401ef60537e83060cd320901d/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2019 Michał Cichoń
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui_md/imgui_md
+Source: https://raw.githubusercontent.com/pthom/imgui_md/acb65f6bb57c493fcac40bc04f9c9eaa04c3f64d/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2021 Dmitry Mekhontsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui_tex_inspect/imgui_tex_inspect
+Source: https://raw.githubusercontent.com/pthom/imgui_tex_inspect/77dd3e10218b6c8e0efbcd3221847ba2fb329e38/LICENSE.txt
+======================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2014-2021 Omar Cornut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui_toggle/imgui_toggle
+Source: https://raw.githubusercontent.com/pthom/imgui_toggle/74c4100476572073db87ceb418e52e444a46e564/LICENSE
+======================================================================
+
+Copyright © 2022 nitz — chris marc dailey https://cmd.wtf
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+======================================================================
+external/imgui_md/md4c
+Source: https://raw.githubusercontent.com/mity/md4c/e9ff661ff818ee94a4a231958d9b6768dc6882c9/LICENSE.md
+======================================================================
+
+
+# The MIT License (MIT)
+
+Copyright © 2016-2020 Martin Mitáš
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the “Software”),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+======================================================================
+external/ImGuiColorTextEdit/ImGuiColorTextEdit
+Source: https://raw.githubusercontent.com/pthom/ImGuiColorTextEdit/e3f369f2afed51087fe43c4ad97c33e5b440ed47/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2017 BalazsJako
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/ImGuizmo/ImGuizmo
+Source: https://raw.githubusercontent.com/pthom/ImGuizmo/5f775c3f95a2954a55bf83c6af8343e7a3ac8f40/LICENSE
+======================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2016 Cedric Guillemet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/immvision/cvnp
+Source: https://raw.githubusercontent.com/pthom/cvnp/7a79541431671030a817c4fa2a3c511d8b6af904/LICENSE
+======================================================================
+
+ The MIT License (MIT)
+
+Copyright © 2022 <Pascal Thomet>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+======================================================================
+external/implot/implot
+Source: https://raw.githubusercontent.com/pthom/implot/61af48ee1369083a3da391a849867af6d1b811a6/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2020 Evan Pezent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/imgui-command-palette/imgui-command-palette
+Source: https://raw.githubusercontent.com/pthom/imgui-command-palette/ce7ec18876726c12c9d829a68f99ef57372352cb/LICENSE
+======================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2021 hnOsmium0001
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/ImCoolBar/ImCoolBar
+Source: https://raw.githubusercontent.com/pthom/ImCoolBar/4b4f6c546153ff0f0f822859235eebc003d7bfee/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2023 Aiekick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+external/nanovg/nanovg
+Source: https://raw.githubusercontent.com/pthom/nanovg/6f970a9e85027f510d3443624982ad6ba1a1dc3d/LICENSE.txt
+======================================================================
+
+Copyright (c) 2013 Mikko Mononen [email protected]
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+claim that you wrote the original software. If you use this software
+in a product, an acknowledgment in the product documentation would be
+appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.
+
+======================================================================
+external/implot3d/implot3d
+Source: https://raw.githubusercontent.com/pthom/implot3d/5312d6f92883f2c5eedbdd410d2fdf6256ee68ea/LICENSE
+======================================================================
+
+MIT License
+
+Copyright (c) 2024-2025 Breno Cunha Queiroz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+======================================================================
+python_backends/LICENSE_pyimgui.txt
+Source: https://raw.githubusercontent.com/pthom/imgui_bundle/v1.92.4/bindings/imgui_bundle/python_backends/LICENSE_pyimgui.txt
+======================================================================
+
+Copyright (c) 2016, Michał Jaworski
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+* Neither the name of pyimgui nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+======================================================================
+assets/fonts/Roboto/LICENSE.txt
+Source: https://raw.githubusercontent.com/pthom/imgui_bundle/v1.92.4/bindings/imgui_bundle/assets/fonts/Roboto/LICENSE.txt
+======================================================================
+
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+======================================================================
+demos_assets/fonts/Playbox/Playbox-license.txt
+Source: https://raw.githubusercontent.com/pthom/imgui_bundle/v1.92.4/bindings/imgui_bundle/demos_assets/fonts/Playbox/Playbox-license.txt
+======================================================================
+
+Love them or hate them but font licenses can clear your mind when it comes to using fonts.
+
+This license details what you are allowed - and not allowed - to do with the color font that was provided to you for free, thanks to the generosity of its designer: Matt Lyon www.c8six.com
+
+
+
+** End-User License Agreement **
+
+By downloading and/or installing this font delivered by Fontself during the #ColorFontWeek, you agree to this license. Please take 3 minutes to read it entirely, as it will help you get the best out of this awesome font for your next projects.
+
+In case of any doubt, please contact Fontself at [email protected]
+
+
+** What is allowed **
+
+- Use for personal and commercial work
+- Use for yourself and on behalf of a client
+- Use for desktop, print, web, ebook, video and film projects (this will practically be limited due to the novelty of color fonts, see recommendations below)
+- Use for physical/digital products/services, distributed for free or a fee, only if the font file or the original typeface design are not the main elements of the product (ie. T-shirts, posters, cards, etc.)
+- Embed in a PDF document
+- Embed in a web page, only if you credit its designer
+- It is ok to temporarily handle the font file to your local printer if needed
+- But you cannot give the font to your clients for their logos or communications. You should embed the font in PDFs or flatten the designs if you want to share it with third-parties.
+
+
+** What is NOT allowed **
+(Unless you get an explicit & written permission from its designer)
+
+- Modify the font
+- Sell or share it (even for free)
+- All other forms of distribution: resell, sublicense, transfer, redistribute, repackage with any other product or service
+- Upload, host or include in any online or offline archive, website or collection
+- Install, deliver or provide access to use the font in any app, website or service allowing other people to use or share the font (i.e. online design editors, print on demand services, etc.)
+
+
+** What is recommended **
+
+- Credit the font designer whenever you can (we all appreciate some recognition, don't we ;)
+- Test & validate your production & distribution chains to ensure color fonts will properly be displayed in your projects. Since color font technologies are pretty new, many apps, operating systems, browsers and printers will not display or render the colored glyphs, instead showing black vector shapes or even nothing at all. Color fonts may contain fallback vector glyphs for backward compatibility, so if you want to use color fonts for production projects, do your homework first.
+- Show what you have created with this font: designers love to see what other creatives make with their fonts, so feel free to ping the font designer or even tag your projects with a #ColorFontWeek hashtag so we can all enjoy your cool designs.
+- And if you are a project commissionner, contact the designer, your business will really benefit from extra creativity & talent!
+
+
+** One more thing(s) **
+
+- Except for your right to use this font, all other rights are owned and retained by the font designer
+- Neither the designer nor Fontself guarantee that the font is compatible or fully functional under any production workflow
+- Neither the designer nor Fontself are liable for any damages resulting from the installation or use of the font
+- For more informations on color fonts, their technologies and support across apps, visit www.colorfonts.com
+- To learn about the font creation tool used to craft this font, check Fontself Maker on www.fontself.com
+- And to discover more about the #ColorFontWeek initiative from Adobe and Fontself, read http://blogs.adobe.com/creativecloud/color-font-week-design-in-color/ and visit https://colorfontweek.fontself.com
+
+
+That's about it, if anything is not clear enough or you have any questions please contact Fontself via [email protected]
+
+Enjoy!
+
+======================================================================
+imgui_test_engine
+Source: https://raw.githubusercontent.com/pthom/imgui_test_engine/75a70367f4ed098a112f6b96a78c9c2f15a2c0e6/imgui_test_engine/LICENSE.txt
+======================================================================
+
+Dear ImGui Test Engine License (v1.04)
+Copyright (c) 2018-2025 Omar Cornut
+
+This document is a legal agreement ("License") between you ("Licensee") and
+DISCO HELLO ("Licensor") that governs your use of Dear ImGui Test Engine ("Software").
+
+1. LICENSE MODELS
+
+1.1. Free license
+
+The Licensor grants you a free license ("Free License") if you meet ANY of the following
+criterion:
+
+- You are a natural person;
+- You are not a legal entity, or you are a not-for-profit legal entity;
+- You are using this Software for educational purposes;
+- You are using this Software to create Derivative Software released publicly and under
+ an Open Source license, as defined by the Open Source Initiative;
+- You are a legal entity with a turnover inferior to 2 million USD (or equivalent) during
+ your last fiscal year.
+
+1.2. Paid license
+
+If you do not meet any criterion of Article 1.1, Licensor grants you a trial period of a
+maximum of 45 days, at no charge. Following this trial period, you must subscribe to a paid
+license ("Paid License") with the Licensor to continue using the Software.
+Paid Licenses are exclusively sold by DISCO HELLO. Paid Licenses and the associated
+information are available at the following URL: http://www.dearimgui.com/licenses
+
+2. GRANT OF LICENSE
+
+2.1. License scope
+
+A limited and non-exclusive worldwide license is hereby granted, to the Licensee,
+to reproduce, execute, publicly perform, and display, use, copy, modify, merge,
+distribute, or create derivative works based on and/or derived from the Software
+("Derivative Software").
+
+2.2. Right of distribution
+
+License holders may also publish and/or distribute the Software or any Derivative
+Software. The above copyright notice and this license shall be included in all copies
+or substantial portions of the Software and/or Derivative Software.
+
+License holders may add their own attribution notices within the Derivative Software
+that they distribute. Such attribution notices must not directly or indirectly imply a
+modification of the License. License holders may provide to their modifications their
+own copyright and/or additional or different terms and conditions, providing such
+conditions complies with this License.
+
+3. DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/licenses/newton-LICENSE.txt b/licenses/newton-LICENSE.txt
new file mode 100644
index 0000000..2bb9ad2
--- /dev/null
+++ b/licenses/newton-LICENSE.txt
@@ -0,0 +1,176 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
\ No newline at end of file
diff --git a/licenses/numpy-LICENSE.txt b/licenses/numpy-LICENSE.txt
new file mode 100644
index 0000000..74b2da5
--- /dev/null
+++ b/licenses/numpy-LICENSE.txt
@@ -0,0 +1,30 @@
+Copyright (c) 2005-2025, NumPy Developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.
+
+ * Neither the name of the NumPy Developers nor the names of any
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file
diff --git a/licenses/pyglet-LICENSE.txt b/licenses/pyglet-LICENSE.txt
new file mode 100644
index 0000000..dc94a1a
--- /dev/null
+++ b/licenses/pyglet-LICENSE.txt
@@ -0,0 +1,30 @@
+Copyright (c) 2006-2008 Alex Holkner
+Copyright (c) 2008-2023 pyglet contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of pyglet nor the names of its
+ contributors may be used to endorse or promote products
+ derived from this software without specific prior written
+ permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file
diff --git a/licenses/scipy-LICENSE.txt b/licenses/scipy-LICENSE.txt
new file mode 100644
index 0000000..521b005
--- /dev/null
+++ b/licenses/scipy-LICENSE.txt
@@ -0,0 +1,30 @@
+Copyright (c) 2001-2002 Enthought, Inc. 2003, SciPy Developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file
diff --git a/licenses/tensorrt-LICENSE.txt b/licenses/tensorrt-LICENSE.txt
new file mode 100644
index 0000000..3eed0fc
--- /dev/null
+++ b/licenses/tensorrt-LICENSE.txt
@@ -0,0 +1,479 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ Copyright 2021 NVIDIA Corporation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+
+ PORTIONS LICENSED AS FOLLOWS
+
+ > tools/pytorch-quantization/examples/torchvision/models/classification/resnet.py
+
+ BSD 3-Clause License
+
+ Copyright (c) Soumith Chintala 2016,
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+ * Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ > samples/common/windows/getopt.c
+
+ Copyright (c) 2002 Todd C. Miller <[email protected]>
+
+ Permission to use, copy, modify, and distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+ Sponsored in part by the Defense Advanced Research Projects
+ Agency (DARPA) and Air Force Research Laboratory, Air Force
+ Materiel Command, USAF, under agreement number F39502-99-1-0512.
+
+
+ Copyright (c) 2000 The NetBSD Foundation, Inc.
+ All rights reserved.
+
+ This code is derived from software contributed to The NetBSD Foundation
+ by Dieter Baron and Thomas Klausner.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+ ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+ - Copyright (c) 2002 Todd C. Miller <[email protected]>
+ - Copyright (c) 2000 The NetBSD Foundation, Inc.
+
+
+ > parsers/common/ieee_half.h
+ > samples/common/half.h
+ > third_party/ieee/half.h
+
+ The MIT License
+
+ Copyright (c) 2012-2017 Christian Rau <[email protected]>
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+
+ > plugin/multiscaleDeformableAttnPlugin/multiscaleDeformableAttn.cu
+ > plugin/multiscaleDeformableAttnPlugin/multiscaleDeformableAttn.h
+ > plugin/multiscaleDeformableAttnPlugin/multiscaleDeformableIm2ColCuda.cuh
+
+ Copyright 2020 SenseTime
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ DETR
+
+ Copyright 2020 - present, Facebook, Inc
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ > demo/Diffusion/utilities.py
+ > demo/Diffusion/stable_video_diffusion_pipeline.py
+
+ HuggingFace diffusers library.
+
+ Copyright 2024 The HuggingFace Team.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ > demo/Diffusion/utils_sd3/sd3_impls.py
+ > demo/Diffusion/utils_sd3/other_impls.py
+ > demo/Diffusion/utils_sd3/mmdit.py
+ > demo/Diffusion/stable_diffusion_3_pipeline.py
+
+ MIT License
+
+ Copyright (c) 2024 Stability AI
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+
+ > demo/Diffusion/utilities.py
+
+ ModelScope library.
+
+ Copyright (c) Alibaba, Inc. and its affiliates.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ > plugin/scatterElementsPlugin/atomics.cuh
+ > plugin/scatterElementsPlugin/reducer.cuh
+ > plugin/scatterElementsPlugin/scatterElementsPluginKernel.cu
+ > plugin/scatterElementsPlugin/scatterElementsPluginKernel.h
+ > plugin/scatterElementsPlugin/TensorInfo.cuh
+
+ Copyright (c) 2020 Matthias Fey <[email protected]>
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.
+
+ > plugin/roiAlignPlugin/roiAlignKernel.cu
+
+ MIT License
+
+ Copyright (c) Microsoft Corporation
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+
+ > samples/common/sampleTuning.cpp
+ > samples/common/sampleUtils.cpp
+ > samples/trtexec/trtexec.cpp
+
+ nlohmann/json library.
+
+ MIT License
+
+ Copyright (c) 2013-2022 Niels Lohmann
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
\ No newline at end of file
diff --git a/licenses/trimesh-LICENSE.txt b/licenses/trimesh-LICENSE.txt
new file mode 100644
index 0000000..43f10d9
--- /dev/null
+++ b/licenses/trimesh-LICENSE.txt
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Michael Dawson-Haggerty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file
diff --git a/licenses/unitree-LICENSE.txt b/licenses/unitree-LICENSE.txt
new file mode 100644
index 0000000..6dfdada
--- /dev/null
+++ b/licenses/unitree-LICENSE.txt
@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2016-2022 HangZhou YuShu TECHNOLOGY CO.,LTD. ("Unitree Robotics")
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\ No newline at end of file
diff --git a/licenses/usd-core-LICENSE.txt b/licenses/usd-core-LICENSE.txt
new file mode 100644
index 0000000..e53e682
--- /dev/null
+++ b/licenses/usd-core-LICENSE.txt
@@ -0,0 +1,895 @@
+============================================================
+OpenUSD
+============================================================
+
+Note: The Tomorrow Open Source Technology License 1.0 differs from the
+original Apache License 2.0 in the following manner. Section 6 ("Trademarks")
+is different.
+
+TOMORROW OPEN SOURCE TECHNOLOGY LICENSE 1.0
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor
+ and its affiliates, except as required to comply with Section 4(c) of
+ the License and to reproduce the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+============================================================
+RapidJSON
+============================================================
+
+Tencent is pleased to support the open source community by making RapidJSON available.
+
+Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All rights reserved.
+
+If you have downloaded a copy of the RapidJSON binary from Tencent, please note that the RapidJSON binary is licensed under the MIT License.
+If you have downloaded a copy of the RapidJSON source code from Tencent, please note that RapidJSON source code is licensed under the MIT License, except for the third-party components listed below which are subject to different license terms. Your integration of RapidJSON into your own projects may require compliance with the MIT License, as well as the other licenses applicable to the third-party components included within RapidJSON. To avoid the problematic JSON license in your own projects, it's sufficient to exclude the bin/jsonchecker/ directory, as it's the only code under the JSON license.
+A copy of the MIT License is included in this file.
+
+Other dependencies and licenses:
+
+Open Source Software Licensed Under the BSD License:
+--------------------------------------------------------------------
+
+The msinttypes r29
+Copyright (c) 2006-2013 Alexander Chemeris
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name of copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Open Source Software Licensed Under the JSON License:
+--------------------------------------------------------------------
+
+json.org
+Copyright (c) 2002 JSON.org
+All Rights Reserved.
+
+JSON_checker
+Copyright (c) 2002 JSON.org
+All Rights Reserved.
+
+
+Terms of the JSON License:
+---------------------------------------------------
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+The Software shall be used for Good, not Evil.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+Terms of the MIT License:
+--------------------------------------------------------------------
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+============================================================
+double-conversion
+============================================================
+
+Copyright 2006-2011, the V8 project authors. All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.
+ * Neither the name of Google Inc. nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+============================================================
+OpenEXR/IlmBase/Half
+============================================================
+
+///////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2002, Industrial Light & Magic, a division of Lucas
+// Digital Ltd. LLC
+//
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+// * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+// * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+// * Neither the name of Industrial Light & Magic nor the names of
+// its contributors may be used to endorse or promote products derived
+// from this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+///////////////////////////////////////////////////////////////////////////
+
+============================================================
+libdeflate
+============================================================
+
+Copyright 2016 Eric Biggers
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation files
+(the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+============================================================
+Apple Technical Q&A QA1361 - Detecting the Debugger
+https://developer.apple.com/library/content/qa/qa1361/_index.html
+============================================================
+
+Sample code project: Detecting the Debugger
+Version: 1.0
+
+Abstract: Shows how to determine if code is being run under the debugger.
+
+IMPORTANT: This Apple software is supplied to you by Apple
+Inc. ("Apple") in consideration of your agreement to the following
+terms, and your use, installation, modification or redistribution of
+this Apple software constitutes acceptance of these terms. If you do
+not agree with these terms, please do not use, install, modify or
+redistribute this Apple software.
+
+In consideration of your agreement to abide by the following terms, and
+subject to these terms, Apple grants you a personal, non-exclusive
+license, under Apple's copyrights in this original Apple software (the
+"Apple Software"), to use, reproduce, modify and redistribute the Apple
+Software, with or without modifications, in source and/or binary forms;
+provided that if you redistribute the Apple Software in its entirety and
+without modifications, you must retain this notice and the following
+text and disclaimers in all such redistributions of the Apple Software.
+Neither the name, trademarks, service marks or logos of Apple Inc. may
+be used to endorse or promote products derived from the Apple Software
+without specific prior written permission from Apple. Except as
+expressly stated in this notice, no other rights or licenses, express or
+implied, are granted by Apple herein, including but not limited to any
+patent rights that may be infringed by your derivative works or by other
+works in which the Apple Software may be incorporated.
+
+The Apple Software is provided by Apple on an "AS IS" basis. APPLE
+MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
+THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND
+OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS.
+
+IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION,
+MODIFICATION AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED
+AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE),
+STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+============================================================
+LZ4
+============================================================
+
+LZ4 - Fast LZ compression algorithm
+Copyright (C) 2011-present, Yann Collet.
+
+BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+You can contact the author at :
+ - LZ4 homepage : http://www.lz4.org
+ - LZ4 source repository : https://github.com/lz4/lz4
+
+============================================================
+stb
+============================================================
+
+stb_image - v2.19 - public domain image loader - http://nothings.org/stb
+ no warranty implied; use at your own risk
+
+stb_image_resize - v0.95 - public domain image resizing
+ by Jorge L Rodriguez (@VinoBS) - 2014
+ http://github.com/nothings/stb
+
+stb_image_write - v1.09 - public domain - http://nothings.org/stb/stb_image_write.h
+ writes out PNG/BMP/TGA/JPEG/HDR images to C stdio - Sean Barrett 2010-2015
+ no warranty implied; use at your own risk
+
+ALTERNATIVE B - Public Domain (www.unlicense.org)
+This is free and unencumbered software released into the public domain.
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
+software, either in source code form or as a compiled binary, for any purpose,
+commercial or non-commercial, and by any means.
+In jurisdictions that recognize copyright laws, the author or authors of this
+software dedicate any and all copyright interest in the software to the public
+domain. We make this dedication for the benefit of the public at large and to
+the detriment of our heirs and successors. We intend this dedication to be an
+overt act of relinquishment in perpetuity of all present and future rights to
+this software under copyright law.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+============================================================
+pugixml
+============================================================
+
+MIT License
+
+Copyright (c) 2006-2019 Arseny Kapoulkine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+============================================================
+Vulkan C++ examples and demos (dome light texture filtering)
+============================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2016 Sascha Willems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+============================================================
+pbrt (Hammersley Low-Discrepancy Sampling Sequence)
+============================================================
+
+Copyright (c) 1998-2015, Matt Pharr, Greg Humphreys, and Wenzel Jakob.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+============================================================
+Draco
+============================================================
+USD bundles Draco, which is available under the Apache 2.0 license. For details,
+see https://github.com/google/draco/blob/master/README.md.
+
+
+============================================================
+Roboto Fonts
+============================================================
+USD bundles Roboto fonts, which is available under the Apache 2.0 license.
+For details, see https://fonts.google.com/specimen/Roboto#license
+
+
+============================================================
+Roboto Mono Fonts
+============================================================
+USD bundles Roboto Mono fonts, which is available under the Apache 2.0 license.
+For details, see https://fonts.google.com/specimen/Roboto+Mono#license
+
+
+============================================================
+Vulkan Memory Allocator
+============================================================
+Copyright (c) 2017-2020 Advanced Micro Devices, Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+============================================================
+PBRT (Sampling functions)
+============================================================
+USD includes code derived from the pbrt-v4 library, retrieved from
+https://github.com/mmp/pbrt-v4/tree/8c19f304558fd7681e2fef2c395a689d0106fb05, which was
+provided subject to the unmodified Apache 2.0 license. For details, see
+https://github.com/mmp/pbrt-v4/blob/8c19f304558fd7681e2fef2c395a689d0106fb05/LICENSE.txt
+
+============================================================
+Cycles (IES reader)
+============================================================
+USD includes classes from the Blender Foundation's Cycles project, retrieved from
+https://projects.blender.org/blender/cycles/src/commit/0be21d452506ec90259b9063c28b5a6fc1cac6a1,
+which was provided subject to the unmodified Apache 2.0 license. For details, see
+https://projects.blender.org/blender/cycles/src/commit/0be21d452506ec90259b9063c28b5a6fc1cac6a1/LICENSE
+
+============================================================
+Spirv Reflect
+============================================================
+Copyright 2017-2018 Google Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+============================================================
+khrplatform.h
+============================================================
+Copyright (c) 2008-2018 The Khronos Group Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and/or associated documentation files (the
+"Materials"), to deal in the Materials without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Materials, and to
+permit persons to whom the Materials are furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Materials.
+
+THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
+
+
+============================================================
+surfgrad-bump-standalone-demo
+============================================================
+MIT License
+
+Copyright (c) 2020 mmikk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+================================================================
+Tessil robin-map
+================================================================
+MIT License
+
+Copyright (c) 2017 Thibaut Goetghebuer-Planchon <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+=====
+CLI11
+=====
+
+CLI11 2.3.1 Copyright (c) 2017-2022 University of Cincinnati, developed by Henry
+Schreiner under NSF AWARD 1414736. All rights reserved.
+
+Redistribution and use in source and binary forms of CLI11, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+ may be used to endorse or promote products derived from this software without
+ specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+================================================================
+The Art of C++ : PEGTL (Parsing Expression Grammar Template Library)
+================================================================
+
+The MIT License (MIT)
+
+Copyright (c) 2007-2022 Dr. Colin Hirsch and Daniel Frey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================
+Doxygen Awesome
+================================================================
+
+MIT License
+
+Copyright (c) 2021 - 2023 jothepro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================
+LibAvif v1.0.4
+================================================================
+
+Copyright 2019 Joe Drago. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================
+AVIF/src/obu.c, renamed in this repository as AVIF/src/avif_obu.c
+================================================================
+
+Copyright © 2018-2019, VideoLAN and dav1d authors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================
+AVIF/third_party/libyuv/*
+================================================================
+
+Copyright 2011 The LibYuv Project Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+
+ * Neither the name of Google nor the names of its contributors may
+ be used to endorse or promote products derived from this software
+ without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================
+libaom
+================================================================
+
+Copyright (c) 2016, Alliance for Open Media. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+================================================================
+boost
+================================================================
+
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
\ No newline at end of file
diff --git a/licenses/warp-LICENSE.txt b/licenses/warp-LICENSE.txt
new file mode 100644
index 0000000..2bb9ad2
--- /dev/null
+++ b/licenses/warp-LICENSE.txt
@@ -0,0 +1,176 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
\ No newline at end of file
diff --git a/motionbricks/__init__.py b/motionbricks/__init__.py
new file mode 100644
index 0000000..84e68ff
--- /dev/null
+++ b/motionbricks/__init__.py
@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from ._version import __version__ # noqa: F401
diff --git a/motionbricks/_version.py b/motionbricks/_version.py
new file mode 100644
index 0000000..9f090f7
--- /dev/null
+++ b/motionbricks/_version.py
@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+__version__ = "0.2.0"
diff --git a/motionbricks/animation/__init__.py b/motionbricks/animation/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/motionbricks/animation/animation_buffer.py b/motionbricks/animation/animation_buffer.py
new file mode 100644
index 0000000..a4f10c7
--- /dev/null
+++ b/motionbricks/animation/animation_buffer.py
@@ -0,0 +1,259 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Store animations as local joint transforms, and loop or remap them."""
+
+from __future__ import annotations
+
+import numpy as np
+import warp as wp
+
+import motionbricks.utils.pose_utils as pose_utils
+import motionbricks.utils.time_utils as time_utils
+from motionbricks.animation.foot_contacts import sample_foot_contacts, validate_foot_contacts
+
+
+def _remap_animation_kernel(
+ source_local_poses: wp.array2d(dtype=wp.transform),
+ joint_mapping: wp.array(dtype=wp.int32),
+ destination_local_poses: wp.array2d(dtype=wp.transform),
+):
+ frame, source_joint = wp.tid()
+ destination_joint = joint_mapping[source_joint]
+ if destination_joint >= 0:
+ destination_local_poses[frame, destination_joint] = source_local_poses[
+ frame, source_joint
+ ]
+
+
+def _loop_delta_kernel(
+ local_poses: wp.array2d(dtype=wp.transform),
+ last: wp.int32,
+ deltas: wp.array(dtype=wp.transform),
+):
+ joint = wp.tid()
+ # Joint 0 is the root.
+ if joint == 0:
+ deltas[0] = pose_utils.compute_root_endpoint_delta(local_poses[last, 0], local_poses[0, 0])
+ else:
+ deltas[joint] = pose_utils.compute_delta_transform(local_poses[last, joint], local_poses[0, joint])
+
+
+def _make_loopable_kernel(
+ deltas: wp.array(dtype=wp.transform),
+ last: wp.int32,
+ local_poses: wp.array2d(dtype=wp.transform),
+):
+ frame, joint = wp.tid()
+ weight = wp.float32(frame) / wp.float32(last)
+ if joint == 0:
+ # A loop has only an end correction.
+ local_poses[frame, 0] = pose_utils.apply_root_endpoint_correction(
+ local_poses[frame, 0], wp.transform_identity(), deltas[0], weight,
+ )
+ else:
+ local_poses[frame, joint] = pose_utils.apply_delta_transform(local_poses[frame, joint], deltas[joint], weight)
+
+
+class AnimationBuffer:
+ """Store animation frames as local joint transforms at a fixed sample rate.
+
+ num_frames counts the frames in use, which can be fewer than the storage holds.
+ foot_contacts is a [capacity, 4] array of predicted foot contacts for generated
+ motion. It is None for clips.
+ """
+
+ def __init__(
+ self,
+ skeleton,
+ sample_rate: float,
+ poses: wp.array,
+ *,
+ num_frames: int | None = None,
+ foot_contacts: wp.array | None = None,
+ ) -> None:
+ """Create an animation whose frames live in poses.
+
+ Args:
+ skeleton: Skeleton of the animation.
+ sample_rate: Sample rate in Hz. It must be positive.
+ poses: Warp array of [capacity, num_joints] local joint transforms. It is
+ used as is.
+ num_frames: Number of frames in use. None uses the whole capacity.
+ foot_contacts: Predicted foot contacts as a float32 [capacity, 4] array on
+ the same device, or None for clips.
+ """
+ self.skeleton = skeleton
+ self.sample_rate = float(sample_rate)
+ if self.sample_rate <= 0.0:
+ raise ValueError("sample_rate must be positive.")
+ self.poses = poses
+ if (
+ self.poses.dtype != wp.transform
+ or self.poses.ndim != 2
+ or self.poses.shape[1] != self.skeleton.num_joints
+ ):
+ raise ValueError("poses must have shape [capacity, num_joints].")
+ validate_foot_contacts(foot_contacts, self.capacity, self.device)
+ self.foot_contacts = foot_contacts
+ self.num_frames = self.capacity if num_frames is None else num_frames
+
+ @property
+ def device(self):
+ """Device of the frame storage."""
+ return self.poses.device
+
+ @property
+ def capacity(self) -> int:
+ """Number of frames the storage holds."""
+ return self.poses.shape[0]
+
+ @property
+ def num_frames(self) -> int:
+ """Number of frames in use, from 0 to capacity."""
+ return self._num_frames
+
+ @num_frames.setter
+ def num_frames(self, frame_count: int) -> None:
+ if not 0 <= frame_count <= self.capacity:
+ raise ValueError(f"num_frames must be in [0, {self.capacity}].")
+ self._num_frames = int(frame_count)
+
+ @property
+ def duration(self) -> float:
+ """Time from the first to the last frame in use, in seconds."""
+ return max(0, self.num_frames - 1) / self.sample_rate
+
+ def root_transforms(self) -> np.ndarray:
+ """Return the root of each frame in use on the host, shaped [num_frames, 7].
+
+ Each row holds the position (XYZ), then the rotation (XYZW).
+ """
+ # Joint 0 is the root.
+ return self.poses[: self.num_frames, 0].numpy().copy()
+
+ def sample(
+ self,
+ time: float,
+ output_pose: wp.array,
+ *,
+ root_offset: wp.transform = wp.transform_identity(),
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Write the pose sampled at time into output_pose.
+
+ The two nearest frames are blended. Times outside the animation are clamped.
+
+ Args:
+ time: Sample time in seconds.
+ output_pose: Array that receives one local joint transform per joint.
+ root_offset: World transform applied to the root. The default leaves the
+ root unchanged.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if self.num_frames == 0:
+ raise ValueError("Cannot sample an empty animation buffer.")
+ if (
+ output_pose.dtype != wp.transform
+ or output_pose.ndim != 1
+ or output_pose.shape[0] != self.skeleton.num_joints
+ ):
+ raise ValueError("output_pose must contain one transform per joint.")
+
+ frame, next_frame, blend = time_utils.frame_index_from_time(time, self.sample_rate, self.num_frames)
+ wp.launch(
+ pose_utils.blend_pose_joints_with_root_offset_kernel,
+ dim=output_pose.shape[0],
+ inputs=[self.poses, frame, next_frame, blend, root_offset],
+ outputs=[output_pose],
+ device=self.device,
+ stream=stream,
+ )
+
+ def sample_foot_contacts(self, time: float, output: wp.array, stream: wp.Stream | None = None) -> None:
+ """Write the four foot contacts sampled at time into output.
+
+ The two nearest frames are blended.
+
+ Args:
+ time: Sample time in seconds.
+ output: Float32 array that receives the four foot contacts.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ sample_foot_contacts(self, time, output, stream)
+
+ def copy(self) -> AnimationBuffer:
+ """Return a new animation with copies of the frames in use and their foot contacts."""
+ foot_contacts = None if self.foot_contacts is None else wp.clone(self.foot_contacts[: self.num_frames])
+ return AnimationBuffer(
+ self.skeleton,
+ self.sample_rate,
+ wp.clone(self.poses[: self.num_frames]),
+ foot_contacts=foot_contacts,
+ )
+
+ def make_loopable(self, stream: wp.Stream | None = None) -> None:
+ """Adjust the frames in use so the first and last poses match.
+
+ Each correction grows from zero at the first frame to the full difference at the
+ last frame in use. The root position correction blends linearly, as in endpoint
+ correction.
+
+ Args:
+ stream: Stream for the work. None uses the current stream.
+ """
+ if self.num_frames < 2:
+ return
+ last = self.num_frames - 1
+ deltas = wp.empty(self.skeleton.num_joints, dtype=wp.transform, device=self.device)
+ wp.launch(
+ _loop_delta_kernel, dim=self.skeleton.num_joints,
+ inputs=[self.poses, last], outputs=[deltas],
+ device=self.device, stream=stream,
+ )
+ wp.launch(
+ _make_loopable_kernel, dim=(self.num_frames, self.skeleton.num_joints),
+ inputs=[deltas, last], outputs=[self.poses],
+ device=self.device, stream=stream,
+ )
+
+
+def create_animation_buffer_for_skeleton(animation_buffer, new_skeleton):
+ """Remap an animation to a new skeleton by joint name.
+
+ Joints missing from the source keep the new skeleton's reference pose. Foot
+ contacts are not copied. The same buffer comes back when it already uses
+ new_skeleton.
+
+ Args:
+ animation_buffer: Animation to remap.
+ new_skeleton: Skeleton of the new buffer.
+ """
+
+ if animation_buffer.skeleton is new_skeleton:
+ return animation_buffer
+ source_skeleton = animation_buffer.skeleton
+ joint_mapping = wp.array(
+ [new_skeleton.joint_index(name) for name in source_skeleton.joint_names],
+ dtype=wp.int32,
+ )
+ output = AnimationBuffer(
+ new_skeleton,
+ animation_buffer.sample_rate,
+ wp.empty((animation_buffer.num_frames, new_skeleton.num_joints), dtype=wp.transform),
+ )
+ if animation_buffer.num_frames == 0:
+ return output
+ pose_utils.fill_poses(new_skeleton.reference_local_transforms, output.poses)
+ wp.launch(
+ _remap_animation_kernel,
+ dim=(animation_buffer.num_frames, source_skeleton.num_joints),
+ inputs=[animation_buffer.poses, joint_mapping],
+ outputs=[output.poses],
+ )
+ return output
diff --git a/motionbricks/animation/foot_contacts.py b/motionbricks/animation/foot_contacts.py
new file mode 100644
index 0000000..63f373d
--- /dev/null
+++ b/motionbricks/animation/foot_contacts.py
@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Predicted foot contacts stored with generated motion.
+
+Each frame holds four foot contacts, in the order left heel, left toe,
+right heel, right toe. Each value is a confidence from 0 to 1 that the heel
+or toe is planted. Raw model values can fall outside this range.
+The engines clamp them to this range.
+"""
+
+import warp as wp
+
+from motionbricks.utils.time_utils import frame_index_from_time
+
+FOOT_CONTACT_COUNT = 4
+
+
+def _blend_foot_contacts_kernel(
+ foot_contacts: wp.array2d(dtype=wp.float32),
+ frame: wp.int32,
+ next_frame: wp.int32,
+ blend: wp.float32,
+ output: wp.array(dtype=wp.float32),
+):
+ contact = wp.tid()
+ output[contact] = wp.lerp(foot_contacts[frame, contact], foot_contacts[next_frame, contact], blend)
+
+
+def validate_foot_contacts(foot_contacts: wp.array | None, capacity: int, device) -> None:
+ """Check that foot_contacts is None or a float32 [capacity, 4] array on device.
+
+ Anything else raises ValueError.
+
+ Args:
+ foot_contacts: Array to check, or None.
+ capacity: Number of frames the array must hold.
+ device: Device the array must be on.
+ """
+ if foot_contacts is None:
+ return
+ if foot_contacts.dtype != wp.float32 or foot_contacts.shape != (capacity, FOOT_CONTACT_COUNT):
+ raise ValueError(f"foot_contacts must be float32 with shape [{capacity}, {FOOT_CONTACT_COUNT}].")
+ if foot_contacts.device != device:
+ raise ValueError("foot_contacts must be on the same device as the poses.")
+
+
+def sample_foot_contacts(buffer, time: float, output: wp.array, stream: wp.Stream | None = None) -> None:
+ """Write a buffer's foot contacts sampled at time into output.
+
+ The two nearest frames are blended.
+
+ Args:
+ buffer: Animation buffer that has foot contacts.
+ time: Sample time in seconds.
+ output: Float32 array that receives the four foot contacts, on the buffer's
+ device.
+ stream: Stream for the work. None uses the current stream.
+ """
+ if buffer.foot_contacts is None:
+ raise ValueError("Cannot sample foot contacts from an animation buffer that has none.")
+ if buffer.num_frames == 0:
+ raise ValueError("Cannot sample an empty animation buffer.")
+ if output.dtype != wp.float32 or output.shape != (FOOT_CONTACT_COUNT,):
+ raise ValueError(f"output must be a float32 array of {FOOT_CONTACT_COUNT} foot contacts.")
+ if output.device != buffer.foot_contacts.device:
+ raise ValueError("output must be on the same device as the foot contacts.")
+ frame, next_frame, blend = frame_index_from_time(time, buffer.sample_rate, buffer.num_frames)
+ wp.launch(
+ _blend_foot_contacts_kernel,
+ dim=FOOT_CONTACT_COUNT,
+ inputs=[buffer.foot_contacts, frame, next_frame, blend],
+ outputs=[output],
+ device=output.device,
+ stream=stream,
+ )
diff --git a/motionbricks/animation/ik.py b/motionbricks/animation/ik.py
new file mode 100644
index 0000000..d56c7f3
--- /dev/null
+++ b/motionbricks/animation/ik.py
@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Solve two-bone IK chains in Warp kernels."""
+
+import warp as wp
+
+# Derived from Daniel Holden's ik_two_bone implementation in controller.cpp.
+# https://github.com/orangeduck/Motion-Matching
+# The accompanying article describes the two-joint IK method.
+# https://theorangeduck.com/page/simple-two-joint
+# See licenses/Daniel-Holden-MIT-LICENSE.txt for its copyright and MIT notice.
+# NVIDIA additions retain the copyright and Apache-2.0 terms above.
+
+_EPSILON = wp.constant(1e-3)
+
+
+class TwoBoneIKChain:
+ """IK chain with two bones.
+
+ pin is the IKPin flag the chain serves. The joint indices name the chain start, the
+ middle joint, and the tip. hint_offset_local is the point in the middle joint's
+ local space that the chain bends toward.
+ """
+
+ pin: wp.int32
+ root_index: wp.int32
+ mid_index: wp.int32
+ tip_index: wp.int32
+ hint_offset_local: wp.vec3
+
+
+def solve_two_bone_ik(
+ in_weight: wp.float32,
+ in_a_parent_world_tx: wp.transform,
+ in_a_world_tx: wp.transform,
+ in_b_world_tx: wp.transform,
+ in_c_world_tx: wp.transform,
+ in_t_world_tx: wp.transform,
+ in_use_hint: wp.bool,
+ in_hint_world: wp.vec3,
+) -> tuple[wp.transform, wp.transform, wp.transform]:
+ """Solve a two-bone IK chain so its tip reaches the pinned transform in_t_world_tx.
+
+ It returns the solved world transforms of the chain start, the middle joint, and the
+ tip. in_weight blends from the input pose at 0 to the solved pose at 1. With
+ in_use_hint, the chain bends toward in_hint_world.
+ """
+ in_weight = wp.clamp(in_weight, 0.0, 1.0)
+ a = in_a_world_tx.p
+ b = in_b_world_tx.p
+ c = in_c_world_tx.p
+ t = wp.lerp(c, in_t_world_tx.p, in_weight)
+
+ l_ab = wp.length(b - a)
+ l_cb = wp.length(b - c)
+ l_at = wp.clamp(wp.length(t - a), _EPSILON, l_ab + l_cb - _EPSILON)
+
+ rot_axis = wp.normalize(wp.where(in_use_hint, wp.cross(c - a, in_hint_world - a), wp.cross(c - a, b - a)))
+ ac_ab_0 = wp.atan2(wp.dot(rot_axis, wp.cross(c - a, b - a)), wp.dot(c - a, b - a))
+ ba_bc_0 = wp.atan2(wp.dot(rot_axis, wp.cross(a - b, c - b)), wp.dot(a - b, c - b))
+ ac_ab_1 = wp.acos(wp.clamp(((l_ab * l_ab) + (l_at * l_at) - (l_cb * l_cb)) / (2.0 * l_ab * l_at), -1.0, 1.0))
+ ba_bc_1 = wp.acos(wp.clamp(((l_ab * l_ab) + (l_cb * l_cb) - (l_at * l_at)) / (2.0 * l_ab * l_cb), -1.0, 1.0))
+
+ rot_a_local = wp.quat_from_axis_angle(wp.quat_rotate_inv(in_a_world_tx.q, rot_axis), ac_ab_1 - ac_ab_0)
+ rot_b_local = wp.quat_from_axis_angle(wp.quat_rotate_inv(in_b_world_tx.q, rot_axis), ba_bc_1 - ba_bc_0)
+
+ a_local_tx = wp.mul(
+ wp.mul(wp.transform_inverse(in_a_parent_world_tx), in_a_world_tx),
+ wp.transform(wp.vec3(0.0, 0.0, 0.0), rot_a_local),
+ )
+ a_world_tx = wp.mul(in_a_parent_world_tx, a_local_tx)
+
+ ac_local = wp.quat_rotate_inv(a_world_tx.q, c - a)
+ at_local = wp.quat_rotate_inv(a_world_tx.q, t - a)
+ a_local_tx = wp.mul(a_local_tx, wp.transform(wp.vec3(0.0, 0.0, 0.0), wp.quat_between_vectors(ac_local, at_local)))
+ a_world_tx = wp.mul(in_a_parent_world_tx, a_local_tx)
+
+ b_local_tx = wp.mul(
+ wp.mul(wp.transform_inverse(in_a_world_tx), in_b_world_tx),
+ wp.transform(wp.vec3(0.0, 0.0, 0.0), rot_b_local),
+ )
+ b_world_tx = wp.mul(a_world_tx, b_local_tx)
+ c_world_tx = wp.mul(b_world_tx, wp.mul(wp.transform_inverse(in_b_world_tx), in_c_world_tx))
+
+ # wp.quat_inverse returns the conjugate, so renormalize the quaternions
+ # to keep errors from building up.
+ return (
+ wp.transform(a_world_tx.p, wp.normalize(a_world_tx.q)),
+ wp.transform(b_world_tx.p, wp.normalize(b_world_tx.q)),
+ wp.transform(c_world_tx.p, wp.normalize(wp.quat_slerp(c_world_tx.q, in_t_world_tx.q, in_weight))),
+ )
+
+
+def apply_two_bone_ik_chains_kernel(
+ weight: wp.float32,
+ pin_mask: wp.int32,
+ chains: wp.array(dtype=TwoBoneIKChain),
+ pinned_transforms: wp.array(dtype=wp.transform),
+ parent_indices: wp.array(dtype=wp.int32),
+ input_world_transforms: wp.array(dtype=wp.transform),
+ output_local_transforms: wp.array(dtype=wp.transform),
+):
+ """Apply weighted IK corrections to one local pose.
+
+ One thread runs per chain. Chains whose pin is not in pin_mask stay as they are.
+ """
+
+ chain_index = wp.tid()
+ chain = chains[chain_index]
+ if (pin_mask & chain.pin) == 0:
+ return
+
+ root_index = chain.root_index
+ mid_index = chain.mid_index
+ tip_index = chain.tip_index
+ root_parent_index = parent_indices[root_index]
+
+ root_parent_world = wp.transform_identity()
+ if root_parent_index >= 0:
+ root_parent_world = input_world_transforms[root_parent_index]
+
+ root_world = input_world_transforms[root_index]
+ mid_world = input_world_transforms[mid_index]
+ tip_world = input_world_transforms[tip_index]
+ hint_world = wp.transform_point(mid_world, chain.hint_offset_local)
+ solved_root, solved_mid, solved_tip = solve_two_bone_ik(
+ weight,
+ root_parent_world,
+ root_world,
+ mid_world,
+ tip_world,
+ pinned_transforms[chain_index],
+ True,
+ hint_world,
+ )
+
+ output_local_transforms[root_index] = wp.mul(wp.transform_inverse(root_parent_world), solved_root)
+ output_local_transforms[mid_index] = wp.mul(wp.transform_inverse(solved_root), solved_mid)
+ output_local_transforms[tip_index] = wp.mul(wp.transform_inverse(solved_mid), solved_tip)
diff --git a/motionbricks/animation/mesh.py b/motionbricks/animation/mesh.py
new file mode 100644
index 0000000..d960a13
--- /dev/null
+++ b/motionbricks/animation/mesh.py
@@ -0,0 +1,159 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Triangle meshes, skinned meshes, and skeletal meshes."""
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+
+
+class Mesh:
+ """Triangle mesh with vertex positions and triangle indices."""
+
+ def __init__(self, points: np.ndarray, indices: np.ndarray) -> None:
+ """Create a mesh from host vertex positions and triangle indices.
+
+ Args:
+ points: Vertex positions with shape (N, 3).
+ indices: Triangle indices as a flat array, three per triangle.
+ """
+ self._points = wp.array(points, dtype=wp.vec3)
+ self._indices = wp.array(indices, dtype=wp.int32)
+
+ @property
+ def points(self) -> wp.array:
+ """Vertex positions, one vec3 per vertex."""
+ return self._points
+
+ @property
+ def indices(self) -> wp.array:
+ """Triangle indices as a flat int32 array, three per triangle."""
+ return self._indices
+
+ @property
+ def num_points(self) -> int:
+ """Number of vertices in the mesh."""
+ return self._points.size
+
+ @property
+ def num_indices(self) -> int:
+ """Number of triangle indices in the mesh."""
+ return self._indices.size
+
+
+class SkinnedMesh(Mesh):
+ """Triangle mesh for linear blend skinning, with K influences per vertex.
+
+ Joint indices and weights are flat arrays ordered by vertex. For N vertices
+ and K influences per vertex, both arrays contain N * K elements.
+ """
+
+ def __init__(
+ self,
+ points: np.ndarray,
+ indices: np.ndarray,
+ joint_indices: np.ndarray,
+ joint_weights: np.ndarray,
+ ) -> None:
+ """Create a skinned mesh from host geometry and skinning data.
+
+ Args:
+ points: Vertex positions with shape (N, 3).
+ indices: Triangle indices as a flat array, three per triangle.
+ joint_indices: Joint index of every vertex influence.
+ joint_weights: Weight of every vertex influence.
+ """
+ super().__init__(points, indices)
+ self._joint_indices = wp.array(joint_indices, dtype=wp.int32)
+ self._joint_weights = wp.array(joint_weights, dtype=wp.float32)
+ self._num_influences = (
+ self._joint_indices.size // self._points.size
+ if self._points.size > 0
+ else 0
+ )
+
+ @property
+ def num_influences(self) -> int:
+ """Number of joint influences stored for each vertex."""
+ return self._num_influences
+
+ @property
+ def joint_indices(self) -> wp.array:
+ """Joint index of every vertex influence, as a flat int32 array."""
+ return self._joint_indices
+
+ @property
+ def joint_weights(self) -> wp.array:
+ """Weight of every vertex influence, as a flat float32 array."""
+ return self._joint_weights
+
+
+class SkeletalMesh:
+ """Skinned meshes driven by one skeleton, ready to render.
+
+ Each inverse bind transform maps vertices from skeleton space into the
+ joint's bind space. Skinning composes it with the joint's current world
+ transform to move vertices into the current pose.
+
+ Override poses and masks change how the mesh is drawn, such as relaxing
+ the fingers. An override pose holds one local transform per joint. A mask
+ holds one weight per joint from 0 to 1. Renderers pick one of each by name.
+ """
+
+ def __init__(
+ self,
+ skinned_meshes: list[SkinnedMesh],
+ skeleton: Skeleton,
+ inverse_bind_transforms: list[wp.transform],
+ override_poses: dict[str, wp.array] | None = None,
+ override_pose_masks: dict[str, wp.array] | None = None,
+ ) -> None:
+ """Create a skeletal mesh from mesh parts and the skeleton that drives them.
+
+ Args:
+ skinned_meshes: Mesh parts deformed by the skeleton.
+ skeleton: Skeleton that drives every mesh part.
+ inverse_bind_transforms: One inverse bind transform per skeleton joint.
+ override_poses: Override poses by name. None means none.
+ override_pose_masks: Override pose masks by name. None means none.
+ """
+ if len(inverse_bind_transforms) != skeleton.num_joints:
+ raise ValueError(
+ "inverse_bind_transforms must contain one transform per joint."
+ )
+
+ self._skinned_meshes = skinned_meshes
+ self._skeleton = skeleton
+ self._inverse_bind_transforms = wp.array(
+ inverse_bind_transforms,
+ dtype=wp.transform,
+ )
+ self._override_poses = dict(override_poses or {})
+ self._override_pose_masks = dict(override_pose_masks or {})
+
+ @property
+ def skinned_meshes(self) -> list[SkinnedMesh]:
+ """Skinned mesh parts driven by :attr:`skeleton`."""
+ return self._skinned_meshes
+
+ @property
+ def skeleton(self) -> Skeleton:
+ """Skeleton that drives the mesh parts."""
+ return self._skeleton
+
+ @property
+ def inverse_bind_transforms(self) -> wp.array:
+ """One inverse bind transform per joint, as a Warp array."""
+ return self._inverse_bind_transforms
+
+ @property
+ def override_poses(self) -> dict[str, wp.array]:
+ """Override poses by name. Each holds one local transform per joint."""
+ return self._override_poses
+
+ @property
+ def override_pose_masks(self) -> dict[str, wp.array]:
+ """Override pose masks by name. Each holds one weight per joint from 0 to 1."""
+ return self._override_pose_masks
diff --git a/motionbricks/animation/skeleton.py b/motionbricks/animation/skeleton.py
new file mode 100644
index 0000000..7595c9e
--- /dev/null
+++ b/motionbricks/animation/skeleton.py
@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Describe a joint hierarchy and its reference pose."""
+
+import numpy as np
+import warp as wp
+
+import motionbricks.utils.pose_utils as pose_utils
+
+
+class Skeleton:
+ """Joint hierarchy and reference pose."""
+
+ def __init__(
+ self,
+ joint_names,
+ parent_indices,
+ local_transforms,
+ ) -> None:
+ """Create a skeleton from its hierarchy and reference pose.
+
+ Args:
+ joint_names: Name of each joint. There must be at least one.
+ parent_indices: Parent index of each joint, or -1 for the root.
+ local_transforms: Reference pose, as one local transform per joint.
+ """
+ self.joint_names = list(joint_names)
+ self._num_joints = len(self.joint_names)
+ if self._num_joints == 0:
+ raise ValueError("A skeleton needs at least one joint.")
+ self._np_parent_indices = np.asarray(parent_indices, dtype=np.int32)
+
+ if self._np_parent_indices.shape != (self._num_joints,):
+ raise ValueError(
+ f"Expected {self._num_joints} parent indices, "
+ f"got {self._np_parent_indices.size}."
+ )
+ if len(local_transforms) != self._num_joints:
+ raise ValueError(
+ f"Expected {self._num_joints} local transforms, "
+ f"got {len(local_transforms)}."
+ )
+
+ self.parent_indices = wp.array(
+ self._np_parent_indices,
+ dtype=wp.int32,
+ )
+ self._reference_local_transforms = wp.array(
+ local_transforms,
+ dtype=wp.transform,
+ )
+
+ self.up_axis = wp.vec3(0.0, 0.0, 1.0)
+ self.forward_axis = wp.vec3(0.0, -1.0, 0.0)
+
+ @property
+ def num_joints(self) -> int:
+ """Number of joints in the hierarchy."""
+ return self._num_joints
+
+ @property
+ def device(self):
+ """Device of the skeleton's arrays."""
+ return self.parent_indices.device
+
+ @property
+ def reference_local_transforms(self) -> wp.array:
+ """Reference pose, as one local joint transform per joint."""
+ return self._reference_local_transforms
+
+ def joint_index(self, joint_name: str) -> int:
+ """Return the index of a joint, or -1 when no joint has that name.
+
+ Args:
+ joint_name: Name of the joint.
+ """
+ try:
+ return self.joint_names.index(joint_name)
+ except ValueError:
+ return -1
+
+ def joint_name(self, index: int) -> str:
+ """Return the name of a joint.
+
+ Args:
+ index: Joint index. An index out of range raises ValueError.
+ """
+ if not 0 <= index < self._num_joints:
+ raise ValueError(f"Joint index {index} must be in [0, {self._num_joints}).")
+ return self.joint_names[index]
+
+ def joint_parent(self, index: int) -> int:
+ """Return the parent index of a joint, or -1 for the root.
+
+ Args:
+ index: Joint index. An index out of range raises ValueError.
+ """
+ if not 0 <= index < self._num_joints:
+ raise ValueError(f"Joint index {index} must be in [0, {self._num_joints}).")
+ return int(self._np_parent_indices[index])
+
+ def joint_mask(self, joint_names, weight: float = 1.0) -> wp.array:
+ """Return one weight per joint: weight on the named joints, zero elsewhere.
+
+ Args:
+ joint_names: Joints that get the weight. Names the skeleton lacks are skipped.
+ weight: Weight of the named joints, clamped to 0 to 1.
+ """
+ weight = wp.clamp(float(weight), 0.0, 1.0)
+ weights = np.zeros(self._num_joints, dtype=np.float32)
+ for joint_name in joint_names:
+ index = self.joint_index(joint_name)
+ if index >= 0:
+ weights[index] = weight
+ return wp.array(weights, dtype=wp.float32, device=self.device)
+
+ def compute_world_transforms(
+ self,
+ local_transforms: wp.array,
+ world_transforms: wp.array,
+ root_tx=wp.transform_identity(),
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Compute the world transforms of a pose into world_transforms.
+
+ Args:
+ local_transforms: Local joint transforms of one pose.
+ world_transforms: Array that receives one world transform per joint.
+ root_tx: Transform applied to the root. The default leaves the root
+ unchanged.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ pose_utils.compute_world_poses(
+ local_transforms,
+ self.parent_indices,
+ world_transforms,
+ root_tx,
+ stream=stream,
+ )
diff --git a/motionbricks/assets/human/soma_base_skel_minimal_no_root.usd b/motionbricks/assets/human/soma_base_skel_minimal_no_root.usd
new file mode 100644
index 0000000..1f25330
--- /dev/null
+++ b/motionbricks/assets/human/soma_base_skel_minimal_no_root.usd
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ab93d78a0f1c06d3bcbedee5ceebb5d9d5b002fd0a88638e9399ed80b61871d
+size 2036435
diff --git a/motionbricks/assets/onnx/LICENSE.md b/motionbricks/assets/onnx/LICENSE.md
new file mode 100644
index 0000000..6b4344c
--- /dev/null
+++ b/motionbricks/assets/onnx/LICENSE.md
@@ -0,0 +1,10 @@
+# Model license
+
+The MotionBricks ONNX models in this folder are licensed under the
+[NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/).
+This covers the SOMA models in [soma](soma) and the Unitree G1 models in [unitree_g1](unitree_g1).
+
+Licensed by NVIDIA Corporation under the NVIDIA Open Model Agreement.
+
+This file identifies the applicable license. The linked agreement contains its terms. The source
+code in this repository and other bundled assets have their own licenses.
diff --git a/motionbricks/assets/onnx/soma/mmm_v6_soma_fp16.onnx b/motionbricks/assets/onnx/soma/mmm_v6_soma_fp16.onnx
new file mode 100644
index 0000000..3d087b2
--- /dev/null
+++ b/motionbricks/assets/onnx/soma/mmm_v6_soma_fp16.onnx
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6c9f78e23decbda8e1cfd1b0cc96980ea4b24b3ca2c808d03b058f48f82fc9ef
+size 380327058
diff --git a/motionbricks/assets/onnx/soma/mmm_v6_soma_fp32.onnx b/motionbricks/assets/onnx/soma/mmm_v6_soma_fp32.onnx
new file mode 100644
index 0000000..404b764
--- /dev/null
+++ b/motionbricks/assets/onnx/soma/mmm_v6_soma_fp32.onnx
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:856419dc72aeb14e591eebf4dd0ea05734a2506ddb00bcd39dd6dac2ad60f4fb
+size 757864273
diff --git a/motionbricks/assets/onnx/soma/soma_n1.json b/motionbricks/assets/onnx/soma/soma_n1.json
new file mode 100644
index 0000000..0c3273d
--- /dev/null
+++ b/motionbricks/assets/onnx/soma/soma_n1.json
@@ -0,0 +1,107 @@
+{
+ "schema_version": 1,
+ "name": "mmm_v6_soma_fp32",
+ "onnx_filename": "mmm_v6_soma_fp32.onnx",
+ "precision_variants": {
+ "fp16": {
+ "name": "mmm_v6_soma_fp16",
+ "onnx_filename": "mmm_v6_soma_fp16.onnx"
+ }
+ },
+ "onnx_opset": 17,
+ "batch_size": 1,
+ "sample_rate": 30.0,
+ "frames_per_token": 4,
+ "min_pred_tokens": 6,
+ "max_pred_tokens": 16,
+ "context_frames": 4,
+ "target_capacity": 4,
+ "joint_names": [
+ "Hips",
+ "Spine1",
+ "Spine2",
+ "Chest",
+ "Neck1",
+ "Neck2",
+ "Head",
+ "Jaw",
+ "LeftEye",
+ "RightEye",
+ "LeftShoulder",
+ "LeftArm",
+ "LeftForeArm",
+ "LeftHand",
+ "LeftHandThumbEnd",
+ "LeftHandMiddleEnd",
+ "RightShoulder",
+ "RightArm",
+ "RightForeArm",
+ "RightHand",
+ "RightHandThumbEnd",
+ "RightHandMiddleEnd",
+ "LeftLeg",
+ "LeftShin",
+ "LeftFoot",
+ "LeftToeBase",
+ "RightLeg",
+ "RightShin",
+ "RightFoot",
+ "RightToeBase"
+ ],
+ "tensor_specs": [
+ {
+ "name": "global_root_values",
+ "mode": "input",
+ "shape": [1, 8, 5],
+ "dtype": "float32"
+ },
+ {
+ "name": "has_global_root_values",
+ "mode": "input",
+ "shape": [1, 8],
+ "dtype": "int32"
+ },
+ {
+ "name": "local_root_values",
+ "mode": "input",
+ "shape": [1, 8, 4],
+ "dtype": "float32"
+ },
+ {
+ "name": "has_local_root_values",
+ "mode": "input",
+ "shape": [1, 8],
+ "dtype": "int32"
+ },
+ {
+ "name": "local_poses",
+ "mode": "input",
+ "shape": [1, 8, 267],
+ "dtype": "float32"
+ },
+ {
+ "name": "has_local_poses",
+ "mode": "input",
+ "shape": [1, 8],
+ "dtype": "int32"
+ },
+ {
+ "name": "allowed_pred_num_tokens",
+ "mode": "input",
+ "shape": [1, 11],
+ "dtype": "int32"
+ },
+ {
+ "name": "pred_global_motions",
+ "mode": "output",
+ "shape": [1, 64, 366],
+ "dtype": "float32"
+ },
+ {
+ "name": "pred_num_tokens",
+ "mode": "output",
+ "shape": [1],
+ "dtype": "int32"
+ }
+ ]
+}
diff --git a/motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp16.onnx b/motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp16.onnx
new file mode 100644
index 0000000..4f84279
--- /dev/null
+++ b/motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp16.onnx
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3ddfc4d7305b805005d782d3db0bd95941f0d3111118865821c6800785a0aa5a
+size 368832561
diff --git a/motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp32.onnx b/motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp32.onnx
new file mode 100644
index 0000000..b6e5d85
--- /dev/null
+++ b/motionbricks/assets/onnx/unitree_g1/mmm_v6_g1_fp32.onnx
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:79258d3613988b74ab84a530352ea600bbe78a1048584f059e231e44641cea16
+size 734253102
diff --git a/motionbricks/assets/onnx/unitree_g1/unitree_g1_n1.json b/motionbricks/assets/onnx/unitree_g1/unitree_g1_n1.json
new file mode 100644
index 0000000..dc2bf84
--- /dev/null
+++ b/motionbricks/assets/onnx/unitree_g1/unitree_g1_n1.json
@@ -0,0 +1,106 @@
+{
+ "schema_version": 1,
+ "name": "mmm_v6_g1_fp32",
+ "onnx_filename": "mmm_v6_g1_fp32.onnx",
+ "precision_variants": {
+ "fp16": {
+ "name": "mmm_v6_g1_fp16",
+ "onnx_filename": "mmm_v6_g1_fp16.onnx"
+ }
+ },
+ "onnx_opset": 17,
+ "batch_size": 1,
+ "sample_rate": 30.0,
+ "frames_per_token": 4,
+ "min_pred_tokens": 6,
+ "max_pred_tokens": 16,
+ "context_frames": 4,
+ "target_capacity": 4,
+ "joint_names": [
+ "left_hip_pitch_joint",
+ "left_hip_roll_joint",
+ "left_hip_yaw_joint",
+ "left_knee_joint",
+ "left_ankle_pitch_joint",
+ "left_ankle_roll_joint",
+ "right_hip_pitch_joint",
+ "right_hip_roll_joint",
+ "right_hip_yaw_joint",
+ "right_knee_joint",
+ "right_ankle_pitch_joint",
+ "right_ankle_roll_joint",
+ "waist_yaw_joint",
+ "waist_roll_joint",
+ "waist_pitch_joint",
+ "left_shoulder_pitch_joint",
+ "left_shoulder_roll_joint",
+ "left_shoulder_yaw_joint",
+ "left_elbow_joint",
+ "left_wrist_roll_joint",
+ "left_wrist_pitch_joint",
+ "left_wrist_yaw_joint",
+ "right_shoulder_pitch_joint",
+ "right_shoulder_roll_joint",
+ "right_shoulder_yaw_joint",
+ "right_elbow_joint",
+ "right_wrist_roll_joint",
+ "right_wrist_pitch_joint",
+ "right_wrist_yaw_joint"
+ ],
+ "tensor_specs": [
+ {
+ "name": "context_qpos",
+ "mode": "input",
+ "shape": [1, 4, 36],
+ "dtype": "float32"
+ },
+ {
+ "name": "target_qpos",
+ "mode": "input",
+ "shape": [1, 4, 36],
+ "dtype": "float32"
+ },
+ {
+ "name": "has_global_root_values",
+ "mode": "input",
+ "shape": [1, 8],
+ "dtype": "int32"
+ },
+ {
+ "name": "has_local_root_values",
+ "mode": "input",
+ "shape": [1, 8],
+ "dtype": "int32"
+ },
+ {
+ "name": "has_local_poses",
+ "mode": "input",
+ "shape": [1, 8],
+ "dtype": "int32"
+ },
+ {
+ "name": "allowed_pred_num_tokens",
+ "mode": "input",
+ "shape": [1, 11],
+ "dtype": "int32"
+ },
+ {
+ "name": "pred_qpos",
+ "mode": "output",
+ "shape": [1, 64, 36],
+ "dtype": "float32"
+ },
+ {
+ "name": "pred_num_tokens",
+ "mode": "output",
+ "shape": [1],
+ "dtype": "int32"
+ },
+ {
+ "name": "pred_foot_contacts",
+ "mode": "output",
+ "shape": [1, 64, 4],
+ "dtype": "float32"
+ }
+ ]
+}
diff --git a/motionbricks/assets/robots/unitree_g1/g1_29dof_rev_1_0.xml b/motionbricks/assets/robots/unitree_g1/g1_29dof_rev_1_0.xml
new file mode 100644
index 0000000..dc9d6ec
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/g1_29dof_rev_1_0.xml
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f9118483faf22d64ddefb7445dda33f2261cd5cd0901849017d65f02496b8ca
+size 25500
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/head_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/head_link.STL
new file mode 100644
index 0000000..401f822
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/head_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:005fb67fbd3eff94aa8bf4a6e83238174e9f91b6721f7111594322f223724411
+size 932784
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_ankle_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_ankle_pitch_link.STL
new file mode 100644
index 0000000..7cd7052
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_ankle_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d49e3abc6f5b12e532062cd575b87b5ef40cd2a3fc18f54a1ca5bba4f773d51d
+size 71184
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_ankle_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_ankle_roll_link.STL
new file mode 100644
index 0000000..cb69f65
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_ankle_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c4092af943141d4d9f74232f3cfa345afc6565f46a077793b8ae0e68b39dc33f
+size 653384
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_elbow_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_elbow_link.STL
new file mode 100644
index 0000000..7fa0527
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_elbow_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fa752198accd104d5c4c3a01382e45165b944fbbc5acce085059223324e5bed3
+size 88784
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_hip_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_hip_pitch_link.STL
new file mode 100644
index 0000000..4cf7475
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_hip_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4725168105ee768ee31638ef22b53f6be2d7641bfd7cfefe803488d884776fa4
+size 181684
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_hip_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_hip_roll_link.STL
new file mode 100644
index 0000000..585f604
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_hip_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:91f25922ee8a7c3152790051bebad17b4d9cd243569c38fe340285ff93a97acf
+size 192184
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_hip_yaw_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_hip_yaw_link.STL
new file mode 100644
index 0000000..b46a741
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_hip_yaw_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a16d88aa6ddac8083aa7ad55ed317bea44b1fa003d314fba88965b7ed0f3b55b
+size 296284
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_knee_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_knee_link.STL
new file mode 100644
index 0000000..2dcf84e
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_knee_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d92b9e3d3a636761150bb8025e32514c4602b91c7028d523ee42b3e632de477
+size 854884
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_rubber_hand.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_rubber_hand.STL
new file mode 100644
index 0000000..04a2fa2
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_rubber_hand.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cff2221a690fa69303f61fce68f2d155c1517b52efb6ca9262dd56e0bc6e70fe
+size 2287484
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_pitch_link.STL
new file mode 100644
index 0000000..926d980
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f0d1cfd02fcf0d42f95e678eeca33da3afbcc366ffba5c052847773ec4f31d52
+size 176784
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_roll_link.STL
new file mode 100644
index 0000000..4c6840b
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fb9df21687773522598dc384f1a2945c7519f11cbc8bd372a49170316d6eee88
+size 400284
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_yaw_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_yaw_link.STL
new file mode 100644
index 0000000..89b0e06
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_shoulder_yaw_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1aa97e9748e924336567992181f78c7cd0652fd52a4afcca3df6b2ef6f9e712e
+size 249184
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_pitch_link.STL
new file mode 100644
index 0000000..f9c9e4f
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b251d8e05047f695d0f536cd78c11973cfa4e78d08cfe82759336cc3471de3a9
+size 85984
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_roll_link.STL
new file mode 100644
index 0000000..2097ca3
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:edc387c9a0ba8c2237e9b296d32531426fabeb6f53e58df45c76106bca74148c
+size 356184
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_yaw_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_yaw_link.STL
new file mode 100644
index 0000000..692f4b0
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/left_wrist_yaw_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:83f8fb3a726bf9613d65dd14f0f447cb918c3c95b3938042a0c9c09749267d3b
+size 318684
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/pelvis.STL b/motionbricks/assets/robots/unitree_g1/meshes/pelvis.STL
new file mode 100644
index 0000000..f98a88d
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/pelvis.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ba6bbc888e630550140d3c26763f10206da8c8bd30ed886b8ede41c61f57a31
+size 1060884
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/pelvis_contour_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/pelvis_contour_link.STL
new file mode 100644
index 0000000..8025bc0
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/pelvis_contour_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5cc5c2c7a312329e3feeb2b03d3fc09fc29705bd01864f6767e51be959662420
+size 1805184
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_ankle_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_ankle_pitch_link.STL
new file mode 100644
index 0000000..94a586a
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_ankle_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15be426539ec1be70246d4d82a168806db64a41301af8b35c197a33348c787a9
+size 71184
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_ankle_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_ankle_roll_link.STL
new file mode 100644
index 0000000..3c38507
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_ankle_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4b66222ea56653e627711b56d0a8949b4920da5df091da0ceb343f54e884e3a5
+size 653784
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_elbow_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_elbow_link.STL
new file mode 100644
index 0000000..52aa0eb
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_elbow_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1be925d7aa268bb8fddf5362b9173066890c7d32092c05638608126e59d1e2ab
+size 88784
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_hip_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_hip_pitch_link.STL
new file mode 100644
index 0000000..064085f
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_hip_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e4f3c99d7f4a7d34eadbef9461fc66e3486cb5442db1ec50c86317d459f1a9c6
+size 181284
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_hip_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_hip_roll_link.STL
new file mode 100644
index 0000000..6544025
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_hip_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4c254ef66a356f492947f360dd931965477b631e3fcc841f91ccc46d945d54f6
+size 192684
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_hip_yaw_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_hip_yaw_link.STL
new file mode 100644
index 0000000..0ad7bee
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_hip_yaw_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e479c2936ca2057e9eb2f7dff6c189b7419d7b8484dea0b298cbb36a2a6aa668
+size 296284
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_knee_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_knee_link.STL
new file mode 100644
index 0000000..65e8a70
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_knee_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:63c4008449c9bbe701a6e2b557b7a252e90cf3a5abcf54cee46862b9a69f8ec8
+size 852284
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_rubber_hand.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_rubber_hand.STL
new file mode 100644
index 0000000..58148fb
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_rubber_hand.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:99533b778bca6246144fa511bb9d4e555e075c641f2a0251e04372869cd99d67
+size 2192684
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_pitch_link.STL
new file mode 100644
index 0000000..48a1c46
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:24cdb387e0128dfe602770a81c56cdce3a0181d34d039a11d1aaf8819b7b8c02
+size 176784
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_roll_link.STL
new file mode 100644
index 0000000..2a5d22f
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:962b97c48f9ce9e8399f45dd9522e0865d19aa9fd299406b2d475a8fc4a53e81
+size 401884
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_yaw_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_yaw_link.STL
new file mode 100644
index 0000000..0882a56
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_shoulder_yaw_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a0b76489271da0c72461a344c9ffb0f0c6e64f019ea5014c1624886c442a2fe5
+size 249984
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_pitch_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_pitch_link.STL
new file mode 100644
index 0000000..2efd25c
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_pitch_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d22f8f3b3127f15a63e5be1ee273cd5075786c3142f1c3d9f76cbf43d2a26477
+size 79584
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_roll_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_roll_link.STL
new file mode 100644
index 0000000..77d23a7
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_roll_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a7ee9212ff5b94d6cb7f52bb1bbf3f352194d5b598acff74f4c77d340c5b344f
+size 356084
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_yaw_link.STL b/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_yaw_link.STL
new file mode 100644
index 0000000..77edbb4
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/right_wrist_yaw_link.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc9dece2d12509707e0057ba2e48df8f3d56db0c79410212963a25e8a50f61a6
+size 341484
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/torso_link_rev_1_0.STL b/motionbricks/assets/robots/unitree_g1/meshes/torso_link_rev_1_0.STL
new file mode 100644
index 0000000..836b992
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/torso_link_rev_1_0.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:11ddb46f2098efbbd8816b1d65893632d8e78be936376c7cdcd6771899ccc723
+size 2570584
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/waist_roll_link_rev_1_0.STL b/motionbricks/assets/robots/unitree_g1/meshes/waist_roll_link_rev_1_0.STL
new file mode 100644
index 0000000..36a5a70
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/waist_roll_link_rev_1_0.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b67c347a05abc3e8ddae600d98a082bee273bb39f8e651647708b0a7140a8a97
+size 85884
diff --git a/motionbricks/assets/robots/unitree_g1/meshes/waist_yaw_link_rev_1_0.STL b/motionbricks/assets/robots/unitree_g1/meshes/waist_yaw_link_rev_1_0.STL
new file mode 100644
index 0000000..dc628fb
--- /dev/null
+++ b/motionbricks/assets/robots/unitree_g1/meshes/waist_yaw_link_rev_1_0.STL
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec6db442b11f25eed898b5add07940c85d804f300de24dcbd264ccd8be7d554c
+size 619984
diff --git a/motionbricks/inference/__init__.py b/motionbricks/inference/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/motionbricks/inference/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/motionbricks/inference/builder.py b/motionbricks/inference/builder.py
new file mode 100644
index 0000000..256c83d
--- /dev/null
+++ b/motionbricks/inference/builder.py
@@ -0,0 +1,319 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Build and cache TensorRT plans for a chosen batch size."""
+
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+import logging
+from pathlib import Path
+from typing import Any
+
+import tensorrt as trt
+
+from .cache import (
+ TensorRTEngineCache,
+ cache_key_for,
+ make_cache_identity,
+ sha256_file,
+)
+from .errors import EngineBuildError
+
+
+@dataclass(frozen=True, slots=True)
+class TensorRTBuildOptions:
+ """Settings that affect the generated TensorRT plan.
+
+ Invalid values raise ValueError.
+
+ Attributes:
+ workspace_size_bytes: Memory TensorRT may use while building, in bytes. None
+ keeps TensorRT's default limit.
+ builder_optimization_level: Optimization level from 0 to 5. Higher levels spend
+ more build time searching for faster kernels.
+ enable_fp16: Allow TensorRT to use FP16 kernels.
+ enable_tf32: Allow TensorRT to use TF32 kernels. None uses the engine's default
+ for its model, or TensorRT's default when building without an engine.
+ TensorRT's default permits TF32.
+ batch_size: Batch size used to build the plan. It replaces a dynamic leading
+ batch dimension in the ONNX model.
+ """
+
+ workspace_size_bytes: int | None = None
+ builder_optimization_level: int = 3
+ enable_fp16: bool = False
+ enable_tf32: bool | None = None
+ batch_size: int = 1
+
+ def __post_init__(self) -> None:
+ if self.batch_size < 1:
+ raise ValueError("batch_size must be positive.")
+ if self.workspace_size_bytes is not None and self.workspace_size_bytes <= 0:
+ raise ValueError("workspace_size_bytes must be positive when specified.")
+ if not 0 <= self.builder_optimization_level <= 5:
+ raise ValueError("builder_optimization_level must be 0 to 5.")
+
+ def cache_payload(self) -> dict[str, Any]:
+ """Return the build options that go into the plan's cache key."""
+ payload = asdict(self)
+ # Omit default precision settings from the cache key. Include the batch
+ # size so each size gets its own cached plan.
+ if not self.enable_fp16:
+ payload.pop("enable_fp16")
+ if self.enable_tf32 is not False:
+ payload.pop("enable_tf32")
+ return payload
+
+
+@dataclass(frozen=True, slots=True)
+class SerializedEnginePlan:
+ """TensorRT plan bytes with the source model and the key of its cache entry."""
+
+ data: bytes = field(repr=False)
+ onnx_path: Path
+ cache_key: str
+ loaded_from_cache: bool
+
+
+def load_or_build_serialized_engine(
+ onnx_path: str | Path,
+ *,
+ options: TensorRTBuildOptions,
+ device_fingerprint: Mapping[str, Any],
+ cache_dir: str | Path,
+ force_rebuild: bool,
+ logger: Any,
+ progress_monitor: Any | None = None,
+) -> SerializedEnginePlan:
+ """Load a compatible cached plan, or build one from ONNX and cache it.
+
+ make_cache_identity() lists the values a cached plan must match.
+
+ Args:
+ onnx_path: ONNX model to build from.
+ options: Build options for the plan.
+ device_fingerprint: Values that identify the GPU, such as its name and
+ architecture.
+ cache_dir: Directory that holds the cached plans.
+ force_rebuild: Build a new plan even when a cached one matches.
+ logger: TensorRT logger for the build, as create_logger() returns.
+ progress_monitor: TensorRT progress monitor for the build. None reports no
+ progress.
+ """
+
+ model_path = Path(onnx_path).expanduser().resolve()
+ if not model_path.is_file():
+ raise FileNotFoundError(f"Could not find ONNX file: {model_path}.")
+
+ onnx_sha256 = sha256_file(model_path)
+ cache_identity = make_cache_identity(
+ onnx_sha256=onnx_sha256,
+ tensorrt_version=str(trt.__version__),
+ build_options=options.cache_payload(),
+ device_fingerprint=device_fingerprint,
+ )
+ cache_key = cache_key_for(cache_identity)
+ cache_metadata = dict(cache_identity)
+ cache_metadata["onnx_filename"] = model_path.name
+ cache = TensorRTEngineCache(cache_dir)
+
+ if not force_rebuild:
+ data = cache.load(model_path.stem, cache_key)
+ if data is not None:
+ return SerializedEnginePlan(
+ data=data,
+ onnx_path=model_path,
+ cache_key=cache_key,
+ loaded_from_cache=True,
+ )
+
+ data = build_serialized_engine(
+ model_path,
+ options,
+ logger,
+ progress_monitor=progress_monitor,
+ )
+ cache.store(
+ model_path.stem,
+ cache_key,
+ data,
+ metadata=cache_metadata,
+ )
+ return SerializedEnginePlan(
+ data=data,
+ onnx_path=model_path,
+ cache_key=cache_key,
+ loaded_from_cache=False,
+ )
+
+
+def build_serialized_engine(
+ onnx_path: Path,
+ options: TensorRTBuildOptions,
+ logger: Any,
+ *,
+ progress_monitor: Any | None = None,
+) -> bytes:
+ """Build a TensorRT plan with a fixed batch size from an ONNX model.
+
+ The plan is not cached. Every failure raises EngineBuildError.
+
+ Args:
+ onnx_path: ONNX model to build from.
+ options: Build options for the plan.
+ logger: TensorRT logger for the build, as create_logger() returns.
+ progress_monitor: TensorRT progress monitor for the build. None reports no
+ progress.
+ """
+
+ try:
+ builder = trt.Builder(logger)
+
+ # TensorRT 10 and newer always use explicit batch.
+ network = builder.create_network(0)
+ if network is None:
+ raise EngineBuildError("TensorRT could not create a network definition.")
+ parser = trt.OnnxParser(network, logger)
+ if not parser.parse_from_file(str(onnx_path)):
+ diagnostics = [str(parser.get_error(index)) for index in range(parser.num_errors)]
+ detail = "\n".join(diagnostics) if diagnostics else "No parser diagnostics were reported."
+ raise EngineBuildError(f"TensorRT failed to parse {onnx_path}:\n{detail}")
+
+ _specialize_batch_dimension(network, options.batch_size)
+ _require_static_network(network)
+ config = builder.create_builder_config()
+ if config is None:
+ raise EngineBuildError("TensorRT could not create a builder configuration.")
+ if options.workspace_size_bytes is not None:
+ config.set_memory_pool_limit(
+ trt.MemoryPoolType.WORKSPACE,
+ options.workspace_size_bytes,
+ )
+ config.builder_optimization_level = options.builder_optimization_level
+ if options.enable_tf32 is False:
+ config.clear_flag(trt.BuilderFlag.TF32)
+ if options.enable_fp16:
+ config.set_flag(trt.BuilderFlag.FP16)
+ if progress_monitor is not None:
+ config.progress_monitor = progress_monitor
+
+ serialized = builder.build_serialized_network(network, config)
+ if serialized is None:
+ raise EngineBuildError(
+ "TensorRT failed to build the plan. Retry with VERBOSE logging for "
+ "detailed tactic diagnostics."
+ )
+ plan = bytes(serialized)
+ if not plan:
+ raise EngineBuildError("TensorRT returned an empty plan.")
+ return plan
+ except EngineBuildError:
+ raise
+ except Exception as exc:
+ raise EngineBuildError(f"TensorRT failed while building {onnx_path}: {exc}") from exc
+
+
+_TENSORRT_SEVERITIES = {
+ "INTERNAL_ERROR": trt.Logger.INTERNAL_ERROR,
+ "ERROR": trt.Logger.ERROR,
+ "WARNING": trt.Logger.WARNING,
+ "INFO": trt.Logger.INFO,
+ "VERBOSE": trt.Logger.VERBOSE,
+}
+# TensorRT's info and verbose messages are details, so they log at debug level.
+_TENSORRT_LOG_LEVELS = {
+ trt.Logger.INTERNAL_ERROR: logging.CRITICAL,
+ trt.Logger.ERROR: logging.ERROR,
+ trt.Logger.WARNING: logging.WARNING,
+ trt.Logger.INFO: logging.DEBUG,
+ trt.Logger.VERBOSE: logging.DEBUG,
+}
+_TENSORRT_LOG = logging.getLogger("motionbricks.inference.tensorrt")
+
+
+class _TensorRTLogger(trt.ILogger):
+ """Forward TensorRT messages down to a minimum severity to Python logging."""
+
+ def __init__(self, min_severity: trt.ILogger.Severity) -> None:
+ trt.ILogger.__init__(self)
+ self._levels = {
+ severity: level
+ for severity, level in _TENSORRT_LOG_LEVELS.items()
+ if int(severity) <= int(min_severity)
+ }
+
+ def log(self, severity: trt.ILogger.Severity, msg: str) -> None:
+ level = self._levels.get(severity)
+ if level is not None:
+ _TENSORRT_LOG.log(level, msg)
+
+
+def create_logger(severity: str) -> trt.ILogger:
+ """Create a TensorRT logger that forwards messages to Python logging.
+
+ Args:
+ severity: Least severe TensorRT message to forward: INTERNAL_ERROR, ERROR,
+ WARNING, INFO, or VERBOSE. Case does not matter.
+ """
+
+ min_severity = _TENSORRT_SEVERITIES.get(severity.upper())
+ if min_severity is None:
+ raise ValueError(
+ f"Unknown TensorRT log severity {severity!r}. Expected one of {tuple(_TENSORRT_SEVERITIES)}."
+ )
+ return _TensorRTLogger(min_severity)
+
+
+def require_supported_tensorrt() -> None:
+ """Check that TensorRT 10 or newer is installed.
+
+ InferenceEngine uses its named tensor API.
+ """
+
+ version = str(trt.__version__)
+ try:
+ major_version = int(version.split(".", maxsplit=1)[0])
+ except ValueError as exc:
+ raise RuntimeError(f"Cannot interpret TensorRT version {version!r}.") from exc
+ if major_version < 10:
+ raise RuntimeError(
+ f"TensorRT {version} is not supported. MotionBricks requires TensorRT 10 or newer."
+ )
+
+
+def _specialize_batch_dimension(network: Any, batch_size: int) -> None:
+ """Set the batch size in TensorRT before building the plan.
+
+ A fixed batch size lets inference reuse its buffers and CUDA graph.
+ The ONNX file stays unchanged. It can be used to build plans for other
+ batch sizes.
+ """
+ for index in range(int(network.num_inputs)):
+ tensor = network.get_input(index)
+ shape = tuple(int(dimension) for dimension in tensor.shape)
+ if not any(dimension < 0 for dimension in shape):
+ continue
+ if not shape or shape[0] != -1 or any(dimension <= 0 for dimension in shape[1:]):
+ raise EngineBuildError(
+ f"Only the leading batch dimension may be dynamic: {tensor.name!r}: {shape}."
+ )
+ tensor.shape = (batch_size, *shape[1:])
+
+
+def _require_static_network(network: Any) -> None:
+ dynamic_tensors: list[str] = []
+ for tensor_kind, count, getter in (
+ ("input", network.num_inputs, network.get_input),
+ ("output", network.num_outputs, network.get_output),
+ ):
+ for index in range(int(count)):
+ tensor = getter(index)
+ shape = tuple(int(dimension) for dimension in tensor.shape)
+ if any(dimension < 0 for dimension in shape):
+ dynamic_tensors.append(f"{tensor_kind} {tensor.name!r}: {shape}")
+ if dynamic_tensors:
+ raise EngineBuildError(
+ "InferenceEngine requires static shapes after batch specialization. Dynamic tensors: "
+ + ", ".join(dynamic_tensors)
+ + "."
+ )
diff --git a/motionbricks/inference/cache.py b/motionbricks/inference/cache.py
new file mode 100644
index 0000000..da66193
--- /dev/null
+++ b/motionbricks/inference/cache.py
@@ -0,0 +1,213 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Cache TensorRT plans by a hash of the model, TensorRT version, and GPU."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import re
+from typing import Any, Mapping
+import uuid
+
+from .errors import EngineCacheError
+
+
+_CACHE_SCHEMA_VERSION = 1
+_HASH_CHUNK_BYTES = 8 * 1024 * 1024
+
+
+def sha256_file(path: str | Path) -> str:
+ """Return the SHA-256 digest of a file in lowercase hexadecimal.
+
+ The file is read in chunks, so a large ONNX model never loads into memory at once.
+
+ Args:
+ path: File to hash.
+ """
+
+ digest = hashlib.sha256()
+ with Path(path).open("rb") as stream:
+ while chunk := stream.read(_HASH_CHUNK_BYTES):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+def make_cache_identity(
+ *,
+ onnx_sha256: str,
+ tensorrt_version: str,
+ build_options: Mapping[str, Any],
+ device_fingerprint: Mapping[str, Any],
+) -> dict[str, Any]:
+ """Return the values that determine TensorRT plan compatibility.
+
+ The identity also records the operating system and CPU architecture.
+
+ Args:
+ onnx_sha256: SHA-256 digest of the ONNX file, as sha256_file() returns it.
+ tensorrt_version: TensorRT version string.
+ build_options: Build options that change the plan, as
+ TensorRTBuildOptions.cache_payload() returns them.
+ device_fingerprint: Values that identify the GPU, such as its name and
+ architecture.
+ """
+
+ return {
+ "schema_version": _CACHE_SCHEMA_VERSION,
+ "onnx_sha256": onnx_sha256,
+ "tensorrt_version": tensorrt_version,
+ "build_options": dict(build_options),
+ "device": dict(device_fingerprint),
+ "platform": {
+ "system": platform.system(),
+ "machine": platform.machine(),
+ },
+ }
+
+
+def cache_key_for(identity: Mapping[str, Any]) -> str:
+ """Hash a cache identity into the key in its plan's file name, a SHA-256 digest.
+
+ Args:
+ identity: Values from make_cache_identity().
+ """
+
+ encoded = json.dumps(identity, sort_keys=True, separators=(",", ":")).encode("utf-8")
+ return hashlib.sha256(encoded).hexdigest()
+
+
+class TensorRTEngineCache:
+ """A directory of atomically written TensorRT plan files.
+
+ A JSON file next to each plan describes how it was built. Failed reads and
+ writes raise EngineCacheError.
+ """
+
+ def __init__(self, directory: str | Path) -> None:
+ """Store plans in directory.
+
+ Args:
+ directory: Directory for the cache. The first write creates it.
+ """
+ self.directory = Path(directory).expanduser().resolve()
+
+ def path_for(self, model_name: str, key: str) -> Path:
+ """Return the path of the plan file.
+
+ Characters that are unsafe in file names become dashes.
+
+ Args:
+ model_name: Name of the model, usually the ONNX file's stem.
+ key: Cache key of the plan.
+ """
+ safe_name = re.sub(r"[^A-Za-z0-9_.-]+", "-", model_name).strip(".-") or "model"
+ return self.directory / f"{safe_name}-{key}.plan"
+
+ def metadata_path_for(self, model_name: str, key: str) -> Path:
+ """Return the path of the JSON file that describes the plan.
+
+ Args:
+ model_name: Name of the model, usually the ONNX file's stem.
+ key: Cache key of the plan.
+ """
+ return self.path_for(model_name, key).with_suffix(".json")
+
+ def load(self, model_name: str, key: str) -> bytes | None:
+ """Return the cached plan, or None when the cache has no entry.
+
+ An empty plan file counts as no entry, and the cache removes it.
+
+ Args:
+ model_name: Name of the model, usually the ONNX file's stem.
+ key: Cache key of the plan.
+ """
+ path = self.path_for(model_name, key)
+ if not path.is_file() or not self.metadata_path_for(model_name, key).is_file():
+ return None
+ try:
+ data = path.read_bytes()
+ except OSError as exc:
+ raise EngineCacheError(f"Could not read plan cache entry {path}: {exc}") from exc
+ if not data:
+ self.invalidate(model_name, key)
+ return None
+ return data
+
+ def store(
+ self,
+ model_name: str,
+ key: str,
+ plan: bytes,
+ *,
+ metadata: Mapping[str, Any],
+ ) -> None:
+ """Write the plan and its JSON file. Both files are written atomically.
+
+ Args:
+ model_name: Name of the model, usually the ONNX file's stem.
+ key: Cache key of the plan.
+ plan: Serialized TensorRT plan. It must not be empty.
+ metadata: JSON values saved next to the plan.
+ """
+ if not plan:
+ raise EngineCacheError("Cannot cache an empty TensorRT plan.")
+
+ path = self.path_for(model_name, key)
+ try:
+ _write_atomic(path, plan)
+ self._store_metadata(model_name, key, metadata)
+ except OSError as exc:
+ raise EngineCacheError(f"Could not write plan cache entry {path}: {exc}") from exc
+
+ def _store_metadata(
+ self,
+ model_name: str,
+ key: str,
+ metadata: Mapping[str, Any],
+ ) -> None:
+ """Write a readable file next to the plan that describes how it was built."""
+
+ plan_path = self.path_for(model_name, key)
+ path = self.metadata_path_for(model_name, key)
+ record = dict(metadata)
+ record["cache_key"] = key
+ record["plan_file"] = plan_path.name
+
+ try:
+ data = (json.dumps(record, indent=2, sort_keys=True) + "\n").encode("utf-8")
+ _write_atomic(path, data)
+ except (OSError, TypeError, ValueError) as exc:
+ raise EngineCacheError(f"Could not write plan cache metadata {path}: {exc}") from exc
+
+ def invalidate(self, model_name: str, key: str) -> None:
+ """Remove the plan and its JSON file, if they exist.
+
+ Args:
+ model_name: Name of the model, usually the ONNX file's stem.
+ key: Cache key of the plan.
+ """
+ for path in (
+ self.path_for(model_name, key),
+ self.metadata_path_for(model_name, key),
+ ):
+ try:
+ path.unlink(missing_ok=True)
+ except OSError as exc:
+ raise EngineCacheError(
+ f"Could not remove invalid plan cache entry {path}: {exc}"
+ ) from exc
+
+
+def _write_atomic(path: Path, data: bytes) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ temporary_path = path.parent / f".{path.name}.{uuid.uuid4().hex}.tmp"
+ try:
+ with temporary_path.open("xb") as stream:
+ stream.write(data)
+ stream.flush()
+ os.replace(temporary_path, path)
+ finally:
+ temporary_path.unlink(missing_ok=True)
diff --git a/motionbricks/inference/engine.py b/motionbricks/inference/engine.py
new file mode 100644
index 0000000..066fedd
--- /dev/null
+++ b/motionbricks/inference/engine.py
@@ -0,0 +1,319 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""An inference engine that runs a TensorRT plan with reusable device buffers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+import tensorrt as trt
+import warp as wp
+
+from .builder import (
+ SerializedEnginePlan,
+ TensorRTBuildOptions,
+ create_logger,
+ load_or_build_serialized_engine,
+ require_supported_tensorrt,
+)
+from .cache import TensorRTEngineCache
+from .errors import (
+ EngineBuildError,
+ EngineClosedError,
+ EngineDeserializationError,
+ EngineExecutionError,
+ TensorContractError,
+)
+from .types import TensorSpec, inspect_engine_tensors
+
+
+class InferenceEngine:
+ """Run an ONNX model asynchronously in TensorRT with a fixed batch size.
+
+ TensorRT runs on the current device, which must be a CUDA device. The engine
+ reuses the same device buffers for each inference.
+
+ TensorRT messages go to the ``motionbricks.inference.tensorrt`` logger. Info and
+ verbose messages log at debug level.
+ """
+
+ # Build options that leave enable_tf32 unset use this value.
+ default_enable_tf32 = True
+
+ def __init__(
+ self,
+ onnx_path: str | Path,
+ *,
+ build_options: TensorRTBuildOptions | None = None,
+ stream: wp.Stream | None = None,
+ cache_dir: str | Path = ".trt-cache",
+ force_rebuild: bool = False,
+ logger_severity: str = "INFO",
+ build_progress_monitor: Any | None = None,
+ ) -> None:
+ """Load the cached plan or build a new one, then allocate the device buffers.
+
+ Args:
+ onnx_path: ONNX model to run.
+ build_options: Build options for the plan. None uses the defaults. When
+ enable_tf32 is None, default_enable_tf32 decides.
+ stream: Stream for inference. None creates a new stream.
+ cache_dir: Directory that holds the cached plans. A relative path starts
+ at the working directory.
+ force_rebuild: Build a new plan even when a cached one matches.
+ logger_severity: Least severe TensorRT message to forward:
+ INTERNAL_ERROR, ERROR, WARNING, INFO, or VERBOSE.
+ build_progress_monitor: TensorRT progress monitor for the build. None
+ reports no progress.
+ """
+ require_supported_tensorrt()
+ wp.init()
+
+ self._closed = False
+ device = wp.get_device()
+ if not device.is_cuda:
+ raise ValueError(f"TensorRT requires a CUDA device, got {device.alias!r}.")
+ self._stream = stream or wp.Stream()
+ if self._stream.device != device:
+ raise ValueError(
+ f"The stream uses {self._stream.device.alias}, but the current device is "
+ f"{device.alias}."
+ )
+
+ self._logger = create_logger(logger_severity)
+ self._runtime: Any | None = None
+ self._engine: Any | None = None
+ self._context: Any | None = None
+ self._cuda_graph: Any | None = None
+ self._buffers: dict[str, Any] = {}
+ self._tensor_specs: Mapping[str, TensorSpec] = MappingProxyType({})
+
+ self._onnx_path = Path(onnx_path)
+
+ options = build_options or TensorRTBuildOptions()
+ if options.enable_tf32 is None:
+ options = replace(options, enable_tf32=self.default_enable_tf32)
+ try:
+ self._initialize(
+ options,
+ cache_dir=cache_dir,
+ force_rebuild=force_rebuild,
+ progress_monitor=build_progress_monitor,
+ )
+ except Exception:
+ self._discard_resources(synchronize=False)
+ self._closed = True
+ raise
+
+ @property
+ def device(self) -> wp.context.Device:
+ """Warp CUDA device that runs inference."""
+ return self._stream.device
+
+ @property
+ def stream(self) -> wp.Stream:
+ """Stream that runs inference, including the baked CUDA graph."""
+
+ return self._stream
+
+ @property
+ def tensor_specs(self) -> Mapping[str, TensorSpec]:
+ """Metadata of every engine tensor, keyed by tensor name."""
+ return self._tensor_specs
+
+ @property
+ def cuda_graph_baked(self) -> bool:
+ """Whether bake_cuda_graph() has captured inference."""
+ return self._cuda_graph is not None
+
+ def device_tensor(self, name: str) -> Any:
+ """Return the persistent Warp CUDA array bound to a TensorRT tensor.
+
+ Args:
+ name: Tensor name, as a key of tensor_specs. An unknown name raises
+ KeyError.
+ """
+
+ self._ensure_open()
+ try:
+ return self._buffers[name]
+ except KeyError as exc:
+ raise KeyError(f"Unknown engine tensor {name!r}.") from exc
+
+ def enqueue_async(self) -> None:
+ """Enqueue one TensorRT inference, or launch its baked CUDA graph."""
+
+ self._ensure_open()
+ if self._cuda_graph is None:
+ self._enqueue_tensorrt()
+ return
+ try:
+ wp.capture_launch(self._cuda_graph, stream=self._stream)
+ except Exception as exc:
+ raise EngineExecutionError(f"CUDA graph launch failed: {exc}") from exc
+
+ def synchronize(self) -> None:
+ """Wait for all work on the engine's stream to finish."""
+ self._ensure_open()
+ wp.synchronize_stream(self._stream)
+
+ def bake_cuda_graph(self) -> None:
+ """Warm up and capture only the TensorRT enqueue into a CUDA graph.
+
+ Other CUDA work for the model can run before and after inference on the
+ same stream.
+ """
+
+ self._ensure_open()
+ if self._cuda_graph is not None:
+ return
+
+ # TensorRT must finish its first-enqueue setup before capture.
+ self._enqueue_tensorrt()
+ wp.synchronize_stream(self._stream)
+
+ capture_started = False
+ try:
+ wp.capture_begin(stream=self._stream)
+ capture_started = True
+ self._enqueue_tensorrt()
+ graph = wp.capture_end(stream=self._stream)
+ capture_started = False
+ except Exception as exc:
+ if capture_started:
+ try:
+ wp.capture_end(stream=self._stream)
+ except Exception:
+ pass
+ raise EngineExecutionError(f"CUDA graph capture failed: {exc}") from exc
+
+ if graph is None:
+ raise EngineExecutionError("CUDA graph capture returned no graph.")
+ self._cuda_graph = graph
+
+ def close(self) -> None:
+ """Wait for outstanding work and release owned resources."""
+
+ if self._closed:
+ return
+ self._discard_resources(synchronize=True)
+ self._closed = True
+
+ def _initialize(
+ self,
+ build_options: TensorRTBuildOptions,
+ *,
+ cache_dir: str | Path,
+ force_rebuild: bool,
+ progress_monitor: Any | None,
+ ) -> None:
+ trt.init_libnvinfer_plugins(self._logger, "")
+
+ def load_or_build(rebuild: bool) -> SerializedEnginePlan:
+ return load_or_build_serialized_engine(
+ self._onnx_path,
+ options=build_options,
+ device_fingerprint={"name": self.device.name, "architecture": self.device.arch},
+ cache_dir=cache_dir,
+ force_rebuild=rebuild,
+ logger=self._logger,
+ progress_monitor=progress_monitor,
+ )
+
+ plan = load_or_build(force_rebuild)
+ try:
+ self._deserialize(plan.data)
+ except EngineDeserializationError as exc:
+ TensorRTEngineCache(cache_dir).invalidate(plan.onnx_path.stem, plan.cache_key)
+ if not plan.loaded_from_cache:
+ raise EngineBuildError(
+ "TensorRT built a plan that the current runtime could not deserialize."
+ ) from exc
+ # A cached plan that fails to load, such as one from another TensorRT build, is rebuilt once.
+ plan = load_or_build(True)
+ try:
+ self._deserialize(plan.data)
+ except EngineDeserializationError as rebuild_exc:
+ TensorRTEngineCache(cache_dir).invalidate(plan.onnx_path.stem, plan.cache_key)
+ raise EngineBuildError(
+ "TensorRT rebuilt a plan that the current runtime could not deserialize."
+ ) from rebuild_exc
+
+ self._allocate_and_bind_buffers()
+
+ def _deserialize(self, serialized_engine: bytes) -> None:
+ if not serialized_engine:
+ raise EngineDeserializationError("Cannot deserialize an empty TensorRT plan.")
+
+ self._context = None
+ self._engine = None
+ self._runtime = None
+ try:
+ self._runtime = trt.Runtime(self._logger)
+ self._engine = self._runtime.deserialize_cuda_engine(serialized_engine)
+ if self._engine is None:
+ raise EngineDeserializationError("TensorRT rejected the serialized plan.")
+ self._context = self._engine.create_execution_context()
+ if self._context is None:
+ raise EngineDeserializationError(
+ "TensorRT could not create an execution context."
+ )
+ specs = inspect_engine_tensors(self._engine)
+ except EngineDeserializationError:
+ raise
+ except Exception as exc:
+ raise EngineDeserializationError(
+ f"TensorRT could not load the serialized plan: {exc}"
+ ) from exc
+
+ self._tensor_specs = MappingProxyType({spec.name: spec for spec in specs})
+
+ def _allocate_and_bind_buffers(self) -> None:
+ buffers: dict[str, Any] = {}
+ for spec in self._tensor_specs.values():
+ warp_dtype = wp.dtype_from_numpy(spec.dtype)
+ buffer = wp.zeros(spec.shape, dtype=warp_dtype)
+ accepted = self._context.set_tensor_address(spec.name, int(buffer.ptr))
+ if accepted is False:
+ raise TensorContractError(
+ f"TensorRT rejected the buffer address for {spec.name!r}."
+ )
+ buffers[spec.name] = buffer
+ self._buffers = buffers
+
+ def _enqueue_tensorrt(self) -> None:
+ try:
+ submitted = self._context.execute_async_v3(self._stream.cuda_stream)
+ except Exception as exc:
+ raise EngineExecutionError(f"TensorRT inference submission failed: {exc}") from exc
+ if submitted is False:
+ raise EngineExecutionError("TensorRT failed to enqueue inference.")
+
+ def _ensure_open(self) -> None:
+ if self._closed:
+ raise EngineClosedError("Cannot use a closed inference engine.")
+
+ def _discard_resources(self, *, synchronize: bool) -> None:
+ if synchronize:
+ try:
+ wp.synchronize_stream(self._stream)
+ except Exception:
+ pass
+ self._cuda_graph = None
+ self._buffers.clear()
+ self._context = None
+ self._engine = None
+ self._runtime = None
+ self._logger = None
+
+ def __enter__(self) -> "InferenceEngine":
+ self._ensure_open()
+ return self
+
+ def __exit__(self, exc_type, exc_value, traceback) -> None:
+ self.close()
diff --git a/motionbricks/inference/errors.py b/motionbricks/inference/errors.py
new file mode 100644
index 0000000..5880d01
--- /dev/null
+++ b/motionbricks/inference/errors.py
@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Errors raised by TensorRT inference and model contracts."""
+
+
+class InferenceError(RuntimeError):
+ """Base class for MotionBricks inference failures."""
+
+
+class EngineClosedError(InferenceError):
+ """Raised when an operation is attempted on a closed engine."""
+
+
+class TensorContractError(InferenceError):
+ """Raised when an engine or model does not satisfy a tensor contract."""
+
+
+class EngineBuildError(InferenceError):
+ """Raised when a TensorRT plan cannot be built."""
+
+
+class EngineDeserializationError(InferenceError):
+ """Raised when a TensorRT plan cannot be loaded."""
+
+
+class EngineExecutionError(InferenceError):
+ """Raised when an inference launch fails."""
+
+
+class EngineCacheError(InferenceError):
+ """Raised when a TensorRT plan cache operation fails."""
diff --git a/motionbricks/inference/progress.py b/motionbricks/inference/progress.py
new file mode 100644
index 0000000..bcc9191
--- /dev/null
+++ b/motionbricks/inference/progress.py
@@ -0,0 +1,120 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Track TensorRT build progress safely across threads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import Lock
+
+import tensorrt as trt
+
+
+@dataclass(frozen=True, slots=True)
+class TensorRTBuildProgress:
+ """Progress through the TensorRT optimizer's current phase."""
+
+ phase_name: str | None = None
+ completed_steps: int = 0
+ total_steps: int = 0
+
+ @property
+ def fraction(self) -> float:
+ """Completed share of the phase, from 0 to 1."""
+ if self.total_steps == 0:
+ return 0.0
+ return min(1.0, self.completed_steps / self.total_steps)
+
+
+class TensorRTBuildProgressMonitor(trt.IProgressMonitor):
+ """Collect TensorRT optimizer callbacks for polling from another thread."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self._lock = Lock()
+ self._phases: dict[str, tuple[int, int]] = {}
+ self._active_phase: str | None = None
+ self._cancel_requested = False
+
+ def phase_start(
+ self,
+ phase_name: str,
+ _parent_phase: str | None,
+ num_steps: int,
+ ) -> None:
+ """Record the start of an optimizer phase. TensorRT calls it.
+
+ Args:
+ phase_name: Name of the phase.
+ _parent_phase: Name of the enclosing phase, or None. It is ignored.
+ num_steps: Number of steps in the phase.
+ """
+ with self._lock:
+ self._phases[phase_name] = (0, num_steps)
+ self._active_phase = phase_name
+
+ def step_complete(self, phase_name: str, step: int) -> bool:
+ """Record a finished step, and return False once a cancel is requested.
+
+ TensorRT calls it. A False return stops the build.
+
+ Args:
+ phase_name: Name of the phase.
+ step: Index of the finished step, from zero.
+ """
+ with self._lock:
+ phase = self._phases.get(phase_name)
+ if phase is not None:
+ _, total_steps = phase
+ completed_steps = min(step + 1, total_steps)
+ self._phases[phase_name] = (completed_steps, total_steps)
+ self._active_phase = phase_name
+ return not self._cancel_requested
+
+ def phase_finish(self, phase_name: str) -> None:
+ """Mark every step of the phase as done. TensorRT calls it.
+
+ Args:
+ phase_name: Name of the phase.
+ """
+ with self._lock:
+ phase = self._phases.get(phase_name)
+ if phase is None:
+ return
+ _, total_steps = phase
+ self._phases[phase_name] = (total_steps, total_steps)
+ self._active_phase = phase_name
+
+ def snapshot(self) -> TensorRTBuildProgress:
+ """Return the progress of the unfinished phase with the most steps.
+
+ When every phase is done, it returns the last active phase.
+ """
+ with self._lock:
+ if self._active_phase is None:
+ return TensorRTBuildProgress()
+
+ active_phases = [
+ (name, completed_steps, total_steps)
+ for name, (completed_steps, total_steps) in self._phases.items()
+ if completed_steps < total_steps
+ ]
+ if active_phases:
+ phase_name, completed_steps, total_steps = max(
+ active_phases,
+ key=lambda phase: phase[2],
+ )
+ else:
+ phase_name = self._active_phase
+ completed_steps, total_steps = self._phases[phase_name]
+ return TensorRTBuildProgress(
+ phase_name,
+ completed_steps,
+ total_steps,
+ )
+
+ def request_cancel(self) -> None:
+ """Ask TensorRT to stop the build after its current step."""
+ with self._lock:
+ self._cancel_requested = True
diff --git a/motionbricks/inference/types.py b/motionbricks/inference/types.py
new file mode 100644
index 0000000..a0986ce
--- /dev/null
+++ b/motionbricks/inference/types.py
@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tensor metadata shared by the inference engine and model contracts."""
+
+from dataclasses import dataclass
+from enum import Enum
+from math import prod
+from typing import Any
+
+import numpy as np
+
+from .errors import EngineDeserializationError
+
+
+class TensorMode(str, Enum):
+ """Whether an engine tensor is consumed or produced by inference."""
+
+ INPUT = "input"
+ OUTPUT = "output"
+
+
+@dataclass(frozen=True, slots=True)
+class TensorSpec:
+ """Metadata for one named static inference tensor.
+
+ Invalid metadata raises ValueError.
+
+ Attributes:
+ name: Tensor name in the TensorRT plan.
+ mode: Whether inference consumes or produces the tensor.
+ shape: Static shape. Every dimension must be positive.
+ dtype: Element type. Object types are rejected.
+ """
+
+ name: str
+ mode: TensorMode
+ shape: tuple[int, ...]
+ dtype: np.dtype[Any]
+
+ def __post_init__(self) -> None:
+ if not self.name:
+ raise ValueError("Tensor name cannot be empty.")
+ if any(dimension <= 0 for dimension in self.shape):
+ raise ValueError(f"Tensor {self.name!r} has invalid static shape {self.shape}.")
+ if self.dtype.hasobject:
+ raise ValueError(f"Tensor {self.name!r} cannot use object dtype.")
+
+ @property
+ def element_count(self) -> int:
+ """Number of elements in the tensor."""
+ return prod(self.shape)
+
+ @property
+ def nbytes(self) -> int:
+ """Size of the tensor in bytes."""
+ return self.element_count * self.dtype.itemsize
+
+
+def inspect_engine_tensors(engine: Any) -> tuple[TensorSpec, ...]:
+ """Read and validate the static device tensors exposed by a loaded TensorRT plan.
+
+ An unsupported tensor raises EngineDeserializationError.
+
+ Args:
+ engine: Deserialized TensorRT engine.
+ """
+
+ import tensorrt as trt
+
+ specs: list[TensorSpec] = []
+ for index in range(int(engine.num_io_tensors)):
+ name = str(engine.get_tensor_name(index))
+ trt_mode = engine.get_tensor_mode(name)
+ if trt_mode == trt.TensorIOMode.INPUT:
+ mode = TensorMode.INPUT
+ elif trt_mode == trt.TensorIOMode.OUTPUT:
+ mode = TensorMode.OUTPUT
+ else:
+ raise EngineDeserializationError(
+ f"TensorRT tensor {name!r} has unknown I/O mode {trt_mode}."
+ )
+
+ if engine.get_tensor_location(name) != trt.TensorLocation.DEVICE:
+ raise EngineDeserializationError(
+ f"TensorRT tensor {name!r} is not device-resident."
+ )
+ shape = tuple(int(dimension) for dimension in engine.get_tensor_shape(name))
+ if any(dimension < 0 for dimension in shape):
+ raise EngineDeserializationError(
+ f"TensorRT tensor {name!r} has unsupported dynamic shape {shape}."
+ )
+ try:
+ dtype = np.dtype(trt.nptype(engine.get_tensor_dtype(name)))
+ except Exception as exc:
+ raise EngineDeserializationError(
+ f"TensorRT tensor {name!r} has an unsupported dtype: {exc}"
+ ) from exc
+ specs.append(TensorSpec(name, mode, shape, dtype))
+
+ if not specs:
+ raise EngineDeserializationError("The TensorRT plan exposes no input or output tensors.")
+ return tuple(specs)
diff --git a/motionbricks/io/__init__.py b/motionbricks/io/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/motionbricks/io/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/motionbricks/io/bvh.py b/motionbricks/io/bvh.py
new file mode 100644
index 0000000..daa0817
--- /dev/null
+++ b/motionbricks/io/bvh.py
@@ -0,0 +1,253 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Load skeletons and animation clips from BVH files."""
+
+import logging
+import time
+from pathlib import Path
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.animation.animation_buffer import AnimationBuffer, create_animation_buffer_for_skeleton
+
+logger = logging.getLogger(__name__)
+
+
+def _euler_to_quaternion(
+ euler_angles: wp.array(dtype=wp.float32),
+ rotation_order: wp.array(dtype=wp.int32),
+):
+ """Convert angles in degrees to a quaternion using the file's channel order.
+
+ Each entry in rotation_order identifies an axis: 0 for X, 1 for Y, 2 for Z.
+ The result is a unit XYZW quaternion.
+ """
+
+ quaternion = wp.quat_identity()
+ # BVH can list the rotation axes in any order, but quat_rpy uses a fixed order.
+ for i in range(rotation_order.shape[0]):
+ axis = wp.vec3(0.0)
+ axis[rotation_order[i]] = 1.0
+ rotation = wp.quat_from_axis_angle(axis, wp.radians(euler_angles[i]))
+ # Keep unit quaternions throughout the ordered axis composition.
+ quaternion *= wp.normalize(rotation)
+
+ return wp.normalize(quaternion)
+
+
+def _convert_frame_animation_kernel(
+ reference_local_transforms: wp.array(dtype=wp.transform),
+ has_positions: wp.array(dtype=wp.bool),
+ has_rotations: wp.array(dtype=wp.bool),
+ animation_data_positions: wp.array3d(dtype=wp.float32),
+ animation_data_rotations: wp.array3d(dtype=wp.float32),
+ rotate_order: wp.array2d(dtype=wp.int32),
+ frame_data: wp.array2d(dtype=wp.transform),
+):
+ """Build a local transform for each joint in each frame.
+
+ Convert positions from centimeters to meters and angles to quaternions.
+ Use the reference position or rotation when the joint has no such channels.
+ """
+
+ frame, joint_index = wp.tid()
+
+ if has_positions[joint_index]:
+ positions = wp.vec3(
+ animation_data_positions[frame, joint_index, 0],
+ animation_data_positions[frame, joint_index, 1],
+ animation_data_positions[frame, joint_index, 2],
+ ) * 0.01
+ else:
+ positions = reference_local_transforms[joint_index].p
+
+ if has_rotations[joint_index]:
+ rotation = _euler_to_quaternion(
+ animation_data_rotations[frame, joint_index], rotate_order[joint_index]
+ )
+ else:
+ rotation = reference_local_transforms[joint_index].q
+
+ frame_data[frame, joint_index] = wp.transform(positions, rotation)
+
+
+def _open_bvh(bvh_file):
+ path = Path(bvh_file)
+ if not path.exists():
+ raise ValueError(f"Could not find BVH file: {bvh_file}.")
+ if path.suffix.lower() != ".bvh":
+ raise ValueError(f"Expected a BVH file: {bvh_file}.")
+ return path.open(encoding="utf-8")
+
+
+def _read_bvh_hierarchy(source, remove_namespace):
+ """Read joints and channel labels, stopping at the MOTION section."""
+ names, parents, offsets, joint_channels = [], [], [], []
+ joint_stack = []
+ in_end_site = False
+
+ for line in source:
+ tokens = line.split()
+ if not tokens:
+ continue
+ if tokens[0] == "MOTION":
+ break
+ if tokens[0] in ("ROOT", "JOINT"):
+ name = tokens[1]
+ names.append(name.rsplit(":", 1)[-1] if remove_namespace else name)
+ parents.append(joint_stack[-1] if joint_stack else -1)
+ joint_stack.append(len(names) - 1)
+ offsets.append([0.0, 0.0, 0.0])
+ joint_channels.append([])
+ elif tokens[:2] == ["End", "Site"]:
+ # End Site marks the end of a joint chain, not another animated joint.
+ in_end_site = True
+ elif tokens[0] == "OFFSET" and not in_end_site:
+ offsets[joint_stack[-1]] = [float(value) for value in tokens[1:4]]
+ elif tokens[0] == "CHANNELS":
+ channels = tokens[2:]
+ channel_count = int(tokens[1])
+ if channel_count != len(channels):
+ raise ValueError(
+ f"BVH joint {names[joint_stack[-1]]!r} declares {channel_count} channels "
+ f"but lists {len(channels)}."
+ )
+ joint_channels[joint_stack[-1]] = channels
+ elif tokens[0] == "}":
+ if in_end_site:
+ in_end_site = False
+ else:
+ joint_stack.pop()
+
+ reference_pose = np.zeros((len(names), 7), dtype=np.float32)
+ reference_pose[:, :3] = np.asarray(offsets, dtype=np.float32) * 0.01
+ reference_pose[:, 6] = 1.0
+ skeleton = Skeleton(names, parents, reference_pose)
+ return skeleton, joint_channels
+
+
+def _read_bvh(path, remove_namespace):
+ """Read the skeleton, then load all motion values into a float32 array."""
+ frame_count = 0
+
+ with _open_bvh(path) as source:
+ skeleton, joint_channels = _read_bvh_hierarchy(source, remove_namespace)
+ for line in source:
+ tokens = line.split()
+ if not tokens:
+ continue
+ if tokens[0] == "Frames:":
+ frame_count = int(tokens[1])
+ elif tokens[:2] == ["Frame", "Time:"]:
+ sample_rate = round(1.0 / float(tokens[2]), 2)
+ break
+ else:
+ raise ValueError(f"BVH frame time is missing: {path}.")
+
+ samples = np.loadtxt(source, dtype=np.float32, ndmin=2)
+
+ channel_count = sum(len(channels) for channels in joint_channels)
+ if samples.shape != (frame_count, channel_count):
+ raise ValueError(
+ f"BVH motion has shape {samples.shape}. "
+ f"Expected {frame_count} frames and {channel_count} channels."
+ )
+
+ return skeleton, samples, joint_channels, sample_rate
+
+
+def _create_animation(skeleton, samples, joint_channels, sample_rate):
+ """Copy each channel's values for all frames at once, then build poses in Warp.
+
+ Position channels go into X, Y, Z slots. Rotation channels keep the order
+ listed in the file, since changing that order changes the resulting pose.
+ """
+ frame_count, joint_count = samples.shape[0], skeleton.num_joints
+ positions = np.zeros((frame_count, joint_count, 3), dtype=np.float32)
+ rotations = np.zeros_like(positions)
+ has_positions = np.zeros(joint_count, dtype=bool)
+ has_rotations = np.zeros(joint_count, dtype=bool)
+ rotation_orders = np.zeros((joint_count, 3), dtype=np.int32)
+
+ column = 0
+ for joint, channels in enumerate(joint_channels):
+ rotation_index = 0
+ for channel in channels:
+ channel = channel.lower()
+ if channel.endswith("position"):
+ axis = "xyz".index(channel[0])
+ positions[:, joint, axis] = samples[:, column]
+ has_positions[joint] = True
+ elif channel.endswith("rotation"):
+ rotations[:, joint, rotation_index] = samples[:, column]
+ rotation_orders[joint, rotation_index] = "xyz".index(channel[0])
+ has_rotations[joint] = True
+ rotation_index += 1
+ column += 1
+
+ local_transforms = wp.empty((frame_count, joint_count), dtype=wp.transform)
+ wp.launch(
+ _convert_frame_animation_kernel,
+ dim=(frame_count, joint_count),
+ inputs=[
+ skeleton.reference_local_transforms,
+ wp.array(has_positions, dtype=wp.bool),
+ wp.array(has_rotations, dtype=wp.bool),
+ wp.array(positions, dtype=wp.float32),
+ wp.array(rotations, dtype=wp.float32),
+ wp.array(rotation_orders, dtype=wp.int32),
+ ],
+ outputs=[local_transforms],
+ )
+ return AnimationBuffer(skeleton, sample_rate, local_transforms)
+
+
+def load_skeleton_from_bvh(file_path, *, remove_namespace=True):
+ """Read a BVH skeleton without loading its motion data.
+
+ Args:
+ file_path: Path to an existing .bvh file.
+ remove_namespace: If True (the default), shorten names such as
+ "actor:rig:Hips" to "Hips". Set False to keep the full names.
+ """
+ with _open_bvh(file_path) as source:
+ skeleton, _ = _read_bvh_hierarchy(source, remove_namespace)
+ return skeleton
+
+
+def load_bvh(file_path, skeleton=None, *, remove_namespace=True):
+ """Load an animation clip from a BVH file.
+
+ Positions are converted from centimeters to meters. Rotation angles are
+ read in degrees and applied in the order listed for each joint.
+
+ Every motion row must have one value per listed channel, and the number of
+ frames must match Frames: in the header.
+
+ Args:
+ file_path: Path to an existing .bvh file.
+ skeleton: Skeleton to match by exact joint name. Its joints missing from the
+ file keep their reference transforms. None keeps the file's skeleton.
+ remove_namespace: If True (the default), shorten names such as
+ "actor:rig:Hips" to "Hips". Set False to keep the full names.
+
+ Returns:
+ The clip. Its skeleton is the given skeleton, or the file's skeleton when
+ skeleton is None.
+ """
+ start = time.perf_counter()
+ file_skeleton, samples, joint_channels, sample_rate = _read_bvh(file_path, remove_namespace)
+ animation = _create_animation(file_skeleton, samples, joint_channels, sample_rate)
+ if skeleton is not None:
+ animation = create_animation_buffer_for_skeleton(animation, skeleton)
+
+ logger.debug(
+ "Loaded %s: %d frames at a sample rate of %g Hz in %.2f s.",
+ file_path, animation.num_frames, animation.sample_rate, time.perf_counter() - start,
+ )
+ return animation
diff --git a/motionbricks/io/csv.py b/motionbricks/io/csv.py
new file mode 100644
index 0000000..5fe699a
--- /dev/null
+++ b/motionbricks/io/csv.py
@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Read and write robot motion CSV files."""
+
+import csv
+from itertools import chain
+from pathlib import Path
+
+import numpy as np
+import warp as wp
+
+from scipy.spatial.transform import Rotation as R
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT
+
+# Sample rate of the robot motion CSV clips. The files do not store it.
+CSV_SAMPLE_RATE = 120.0
+_CSV_EXPORT_ROOT_TITLE = [
+ "Frame", "root_translateX", "root_translateY", "root_translateZ", "root_rotateX", "root_rotateY", "root_rotateZ",
+]
+# The joint angle columns follow the frame number and the root columns.
+_CSV_ROOT_COLUMN_COUNT = len(_CSV_EXPORT_ROOT_TITLE)
+
+
+def load_csv(
+ file_path: str | Path,
+ sample_rate: float = CSV_SAMPLE_RATE,
+ *,
+ device=None,
+) -> DOFAnimationBuffer:
+ """Load a robot motion CSV as joint coordinates.
+
+ The file stores root translations in centimeters, root Euler rotations
+ in extrinsic XYZ order, and all angles in degrees. The returned buffer
+ uses meters, XYZW quaternions, and radians. Joint columns keep their file
+ order, which must match the robot's joint_q.
+
+ Args:
+ file_path: CSV file to read.
+ sample_rate: Sample rate of the motion in Hz. The file does not store it.
+ device: Device for new arrays. None uses the current device.
+ """
+ path = Path(file_path)
+ with path.open("r", encoding="utf-8-sig", newline="") as source:
+ header = next(csv.reader(source), None)
+ if (
+ header is None
+ or header[:_CSV_ROOT_COLUMN_COUNT] != _CSV_EXPORT_ROOT_TITLE
+ or len(header) <= _CSV_ROOT_COLUMN_COUNT
+ ):
+ raise ValueError(
+ f"{path}: expected the columns Frame and root_translateX to root_rotateZ, "
+ "then one named column per joint angle."
+ )
+ names = tuple(header[_CSV_ROOT_COLUMN_COUNT:])
+ rows = (line for line in source if line.strip())
+ first_row = next(rows, None)
+ if first_row is None:
+ raise ValueError(f"{path}: CSV contains no motion frames.")
+ data = np.loadtxt(chain((first_row,), rows), delimiter=",", ndmin=2)
+
+ if data.shape[1] != len(header):
+ raise ValueError(f"{path}: row width does not match the CSV header.")
+
+ joint_q = np.empty((len(data), ROOT_COORDINATE_COUNT + len(names)), dtype=np.float32)
+ joint_q[:, :3] = data[:, 1:4] * 0.01
+ joint_q[:, 3:ROOT_COORDINATE_COUNT] = R.from_euler("xyz", data[:, 4:7], degrees=True).as_quat()
+ joint_q[:, ROOT_COORDINATE_COUNT:] = np.deg2rad(data[:, _CSV_ROOT_COLUMN_COUNT:])
+ if not np.isfinite(joint_q).all():
+ raise ValueError(f"{path}: motion coordinates must be finite.")
+ return DOFAnimationBuffer(names, sample_rate, wp.array(joint_q, dtype=wp.float32, device=device))
+
+
+def save_csv(file_path: str | Path, buffer: DOFAnimationBuffer) -> None:
+ """Save the frames in use of buffer as a robot motion CSV.
+
+ Translations are written in centimeters, root rotations as extrinsic XYZ
+ Euler angles, and all angles in degrees. The joint angle columns take the
+ buffer's joint names.
+
+ Args:
+ file_path: CSV file to write. An existing file is replaced.
+ buffer: Joint coordinate animation with at least one frame in use.
+ """
+ if buffer.num_frames == 0:
+ raise ValueError("buffer must contain at least one frame in use.")
+
+ frames = buffer.poses[:buffer.num_frames].numpy()
+ with open(file_path, "w", newline="", encoding="utf-8") as destination:
+ writer = csv.writer(destination)
+ writer.writerow(_CSV_EXPORT_ROOT_TITLE + list(buffer.joint_names))
+
+ for frame_index, pose in enumerate(frames):
+ position_cm = wp.vec3(*pose[:3]) * 100.0
+ rotation = wp.quat(*pose[3:ROOT_COORDINATE_COUNT])
+ euler_degrees = R.from_quat(rotation).as_euler("xyz", degrees=True)
+
+ row = [frame_index, *position_cm, *euler_degrees]
+ row.extend(np.rad2deg(pose[ROOT_COORDINATE_COUNT:]))
+ writer.writerow(row)
diff --git a/motionbricks/io/usd.py b/motionbricks/io/usd.py
new file mode 100644
index 0000000..3849cb7
--- /dev/null
+++ b/motionbricks/io/usd.py
@@ -0,0 +1,406 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Load skeletons and skinned meshes from USD.
+
+The USD rest pose becomes the skeleton's reference pose.
+"""
+
+import logging
+
+import numpy as np
+import warp as wp
+from pxr import Tf, Usd, UsdGeom, UsdSkel
+
+from motionbricks.animation.mesh import SkeletalMesh, SkinnedMesh
+from motionbricks.animation.skeleton import Skeleton
+
+logger = logging.getLogger(__name__)
+
+_EPSILON = 1e-6
+
+###############################################################################
+# USD Stage Metadata Helpers
+###############################################################################
+
+
+def _resolve_time_code(stage):
+ """Return the time code for evaluating transforms and attributes.
+
+ A stage with a time range uses its start time. Exporters often animate
+ xformOps without a meaningful default value, and bind pose loading expects
+ the first frame.
+ """
+ start = stage.GetStartTimeCode()
+ if start < stage.GetEndTimeCode():
+ return Usd.TimeCode(start)
+ return Usd.TimeCode.Default()
+
+
+def _open_stage(usd_file_path):
+ """Open a USD stage. Every failure raises ValueError."""
+ try:
+ stage = Usd.Stage.Open(str(usd_file_path))
+ except Tf.ErrorException as exc:
+ raise ValueError(f"Could not open USD stage: {usd_file_path}.") from exc
+ if stage is None:
+ raise ValueError(f"Could not open USD stage: {usd_file_path}.")
+ return stage
+
+
+def get_stage_meters_per_unit(stage):
+ """Return the stage's meters per unit, such as 0.01 for centimeters.
+
+ Args:
+ stage: Open USD stage.
+ """
+ return UsdGeom.GetStageMetersPerUnit(stage)
+
+
+def get_stage_up_axis(stage):
+ """Return the stage's up axis, 'Y' or 'Z'.
+
+ Args:
+ stage: Open USD stage.
+ """
+ up_axis = UsdGeom.GetStageUpAxis(stage)
+ return "Y" if up_axis == UsdGeom.Tokens.y else "Z"
+
+
+###############################################################################
+# Matrix Decomposition Helpers
+###############################################################################
+
+
+def decompose_matrix(mat, translation_scale=1.0):
+ """Split a row major 4x4 matrix into a position, a rotation, and a scale.
+
+ Returns (wp.vec3, wp.quat, np.ndarray).
+
+ Args:
+ mat: Row major 4x4 matrix, as USD stores it.
+ translation_scale: Factor applied to the position, such as 0.01 to convert
+ centimeters to meters.
+ """
+ # USD matrices are row major, so the translation is in row 3.
+ pos = mat[3, :3] * translation_scale
+
+ # The upper 3x3 block holds rotation and scale.
+ rot_matrix = mat[:3, :3].copy()
+
+ # Each column's length is the scale along that axis.
+ scale = np.array(
+ [
+ np.linalg.norm(rot_matrix[:, 0]),
+ np.linalg.norm(rot_matrix[:, 1]),
+ np.linalg.norm(rot_matrix[:, 2]),
+ ]
+ )
+
+ for i in range(3):
+ if scale[i] > _EPSILON:
+ rot_matrix[:, i] /= scale[i]
+
+ # Transpose to the layout Warp expects before converting to a quaternion.
+ rot = wp.quat_from_matrix(wp.mat33(rot_matrix.T.flatten()))
+
+ return wp.vec3(pos[0], pos[1], pos[2]), rot, scale
+
+
+def get_prim_world_scale(prim, time_code):
+ """Return a prim's world scale [sx, sy, sz] from its world transform.
+
+ Args:
+ prim: USD prim.
+ time_code: Time at which to evaluate the transform.
+ """
+ xform_cache = UsdGeom.XformCache(time_code)
+ mat = np.array(xform_cache.GetLocalToWorldTransform(prim), dtype=np.float32)
+
+ # Each column's length is the scale along that axis.
+ scale = np.array(
+ [
+ np.linalg.norm(mat[:3, 0]),
+ np.linalg.norm(mat[:3, 1]),
+ np.linalg.norm(mat[:3, 2]),
+ ]
+ )
+
+ return scale
+
+
+def get_prim_meters_scale(stage, prim):
+ """Return the factor that converts a prim's data to meters.
+
+ It combines the stage's meters per unit with the prim's world scale. The
+ scale is assumed uniform, so only its X component is used.
+
+ Args:
+ stage: Stage that holds the prim.
+ prim: Prim whose data to convert.
+ """
+ meters_per_unit = get_stage_meters_per_unit(stage)
+ prim_scale = get_prim_world_scale(prim, _resolve_time_code(stage))
+
+ combined_scale = meters_per_unit * prim_scale[0]
+
+ return combined_scale
+
+
+###############################################################################
+# USD Loading Functions
+###############################################################################
+
+
+def get_bind_transform_as_warp_transform(bind_matrix, scale=1.0):
+ """Convert a row major 4x4 bind matrix to a transform, scaling its translation.
+
+ Args:
+ bind_matrix: Row major 4x4 bind matrix.
+ scale: Factor applied to the translation.
+ """
+ # USD multiplies row vectors, so its matrix is the transpose of Warp's.
+ transform = wp.transform_from_matrix(wp.transpose(wp.mat44(*bind_matrix.flatten())))
+ return wp.transform(transform.p * scale, transform.q)
+
+
+def _load_skeleton(stage, skeleton_prim_path):
+ skeleton_prim = stage.GetPrimAtPath(skeleton_prim_path)
+ if not skeleton_prim.IsValid():
+ raise ValueError(f"Skeleton prim not found at path {skeleton_prim_path}.")
+
+ usd_skeleton = UsdSkel.Skeleton(skeleton_prim)
+ joint_paths = usd_skeleton.GetJointsAttr().Get()
+ rest_transforms = usd_skeleton.GetRestTransformsAttr().Get()
+ if not joint_paths or not rest_transforms:
+ raise ValueError(
+ f"Skeleton {skeleton_prim_path} has no joints or rest transforms."
+ )
+ if len(joint_paths) != len(rest_transforms):
+ raise ValueError(
+ f"Skeleton {skeleton_prim_path} has {len(joint_paths)} joints but "
+ f"{len(rest_transforms)} rest transforms."
+ )
+
+ translation_scale = get_prim_meters_scale(stage, skeleton_prim)
+
+ joint_path_strings = [str(path) for path in joint_paths]
+ path_to_index = {path: index for index, path in enumerate(joint_path_strings)}
+ joint_names = [path.rsplit("/", 1)[-1] for path in joint_path_strings]
+ if len(set(joint_names)) != len(joint_names):
+ raise ValueError(f"Skeleton {skeleton_prim_path} has duplicate joint names.")
+
+ parent_indices = []
+ for path in joint_path_strings:
+ parent_path = path.rsplit("/", 1)[0] if "/" in path else None
+ parent_indices.append(-1 if parent_path is None else path_to_index[parent_path])
+
+ local_transforms = []
+ for matrix in rest_transforms:
+ position, rotation, _ = decompose_matrix(
+ np.asarray(matrix, dtype=np.float32),
+ translation_scale=translation_scale,
+ )
+ local_transforms.append(wp.transform(position, rotation))
+
+ skeleton = Skeleton(joint_names, parent_indices, local_transforms)
+ if get_stage_up_axis(stage) == "Y":
+ skeleton.up_axis = wp.vec3(0.0, 1.0, 0.0)
+ skeleton.forward_axis = wp.vec3(0.0, 0.0, 1.0)
+ return skeleton
+
+
+def _get_value_or_first_sample(attribute, time_code):
+ """Return the attribute's value at time_code, or else its first time sample."""
+ value = attribute.Get(time_code)
+ return attribute.Get(Usd.TimeCode.EarliestTime()) if value is None else value
+
+
+def _load_override_poses(stage, skeleton_prim, skeleton, translation_scale):
+ """Return each SkelAnimation under the skeleton prim as local joint transforms for every joint, by prim name.
+
+ Joints missing from the animation use their reference transforms.
+ If the animation only has time samples, use its first sample.
+ """
+ time_code = _resolve_time_code(stage)
+ rest = skeleton.reference_local_transforms.numpy()
+ poses = {}
+ for prim in skeleton_prim.GetChildren():
+ if not prim.IsA(UsdSkel.Animation):
+ continue
+ animation = UsdSkel.Animation(prim)
+ joint_paths = animation.GetJointsAttr().Get() or []
+ translations = _get_value_or_first_sample(animation.GetTranslationsAttr(), time_code) or []
+ rotations = _get_value_or_first_sample(animation.GetRotationsAttr(), time_code) or []
+ if not len(joint_paths) == len(translations) == len(rotations):
+ raise ValueError(f"SkelAnimation {prim.GetPath()} needs a translation and a rotation per joint.")
+
+ pose = rest.copy()
+ for path, translation, rotation in zip(joint_paths, translations, rotations):
+ name = str(path).rsplit("/", 1)[-1]
+ joint = skeleton.joint_index(name)
+ if joint < 0:
+ raise ValueError(f"SkelAnimation {prim.GetPath()} names unknown joint {name}.")
+ pose[joint, :3] = np.asarray(translation) * translation_scale
+ pose[joint, 3:6] = rotation.GetImaginary()
+ pose[joint, 6] = rotation.GetReal()
+ poses[prim.GetName()] = wp.array(pose, dtype=wp.transform, device=skeleton.reference_local_transforms.device)
+ return poses
+
+
+def load_skeleton_from_usd(usd_file_path, skeleton_prim_path):
+ """Load a Skeleton with its reference pose from USD.
+
+ A stage that fails to open, or a missing skeleton, raises ValueError.
+
+ Args:
+ usd_file_path: USD file to open.
+ skeleton_prim_path: Path of the UsdSkel.Skeleton prim.
+ """
+
+ stage = _open_stage(usd_file_path)
+ return _load_skeleton(stage, skeleton_prim_path)
+
+
+def _load_skinned_meshes(stage, mesh_prim, skeleton, skeleton_world_transform, scale):
+ """Load every skinned mesh at or below mesh_prim, with its points in skeleton space.
+
+ Meshes without a skinning binding are skipped with a warning. A mesh without a joints
+ relationship uses the skeleton's joints. Quads are split into two triangles, and
+ larger polygons are skipped. A binding without joint indices or weights raises
+ ValueError.
+
+ Args:
+ stage: Stage that holds the meshes.
+ mesh_prim: Mesh prim, or a prim whose descendants hold meshes.
+ skeleton: Skeleton whose joint indices the meshes use.
+ skeleton_world_transform: World transform of the skeleton. It moves the mesh
+ points into skeleton space.
+ scale: Factor that converts the mesh's data to meters.
+ """
+ time_code = _resolve_time_code(stage)
+ # XformCache handles every xformOp, reset, and pivot in the world transform.
+ xform_cache = UsdGeom.XformCache(time_code)
+ inv_skel_rot = wp.quat_inverse(skeleton_world_transform.q)
+ meshes = []
+ for prim in Usd.PrimRange(mesh_prim):
+ if not prim.IsA(UsdGeom.Mesh):
+ continue
+ binding_api = UsdSkel.BindingAPI(prim)
+ if not binding_api:
+ logger.warning("Mesh %s has no skinning binding and is skipped.", prim.GetPath())
+ continue
+ joint_indices = binding_api.GetJointIndicesAttr().Get()
+ joint_weights = binding_api.GetJointWeightsAttr().Get()
+ if joint_indices is None or joint_weights is None:
+ raise ValueError(f"Mesh {prim.GetPath()} needs jointIndices and jointWeights.")
+
+ # The geom bind transform moves mesh points into skeleton space, where the bind
+ # transforms are. An authored geomBindTransform, USD's standard mapping, wins.
+ geom_bind_value = binding_api.GetGeomBindTransformAttr().Get(time_code)
+ if geom_bind_value is not None:
+ position, rotation, _ = decompose_matrix(
+ np.array(geom_bind_value, dtype=np.float32).reshape(4, 4), translation_scale=scale,
+ )
+ geom_bind = wp.transform(position, rotation)
+ else:
+ # inv(skeleton_world) * mesh_world, keeping position and rotation. Scale is
+ # applied to the points separately.
+ mesh_position, mesh_rotation, _ = decompose_matrix(
+ np.array(xform_cache.GetLocalToWorldTransform(prim), dtype=np.float32), translation_scale=scale,
+ )
+ # Subtract the skeleton position, then rotate into skeleton space.
+ geom_bind = wp.transform(
+ wp.quat_rotate(inv_skel_rot, mesh_position - skeleton_world_transform.p),
+ wp.mul(inv_skel_rot, mesh_rotation),
+ )
+
+ mesh = UsdGeom.Mesh(prim)
+ points = np.array(mesh.GetPointsAttr().Get(), dtype=np.float32) * scale
+ for i in range(len(points)):
+ points[i] = wp.transform_point(geom_bind, wp.vec3(points[i]))
+ indices = np.array(mesh.GetFaceVertexIndicesAttr().Get(), dtype=np.int32)
+ faces = []
+ face_id = 0
+ for count in mesh.GetFaceVertexCountsAttr().Get():
+ if count == 3:
+ faces.append(indices[face_id : face_id + 3])
+ elif count == 4:
+ faces.append(indices[face_id : face_id + 3])
+ faces.append(indices[[face_id, face_id + 2, face_id + 3]])
+ face_id += count
+
+ # Joint indices refer to the mesh's own joint list. Map each one to the skeleton
+ # by name. A joint the skeleton lacks gets -1.
+ joints = binding_api.GetJointsAttr().Get()
+ names = skeleton.joint_names if joints is None else [str(joint).rsplit("/", 1)[-1] for joint in joints]
+ skeleton_joints = np.array([skeleton.joint_index(name) for name in names], dtype=int)
+ meshes.append(SkinnedMesh(
+ points,
+ np.array(faces, dtype=np.int32).flatten(),
+ skeleton_joints[np.array(joint_indices, dtype=np.int32)],
+ np.array(joint_weights, dtype=np.float32),
+ ))
+ return meshes
+
+
+def load_skeletal_mesh_with_skeleton_from_usd(
+ usd_file_path,
+ mesh_prim_path,
+ skeleton_prim_path,
+):
+ """Load a skeletal mesh and construct its Skeleton from the same USD stage.
+
+ Every SkelAnimation under the skeleton prim becomes an override pose named
+ after its prim. Failures raise ValueError.
+
+ Args:
+ usd_file_path: USD file to open.
+ mesh_prim_path: Path of the mesh prim, or of a prim whose descendants hold the
+ meshes.
+ skeleton_prim_path: Path of the UsdSkel.Skeleton prim.
+ """
+
+ stage = _open_stage(usd_file_path)
+ skeleton = _load_skeleton(stage, skeleton_prim_path)
+ mesh_prim = stage.GetPrimAtPath(mesh_prim_path)
+ if not mesh_prim.IsValid():
+ raise ValueError(f"Mesh prim not found at path {mesh_prim_path}.")
+
+ # The mesh and skeleton prims can be scaled differently, so each uses its own scale.
+ skeleton_prim = stage.GetPrimAtPath(skeleton_prim_path)
+ skeleton_scale = get_prim_meters_scale(stage, skeleton_prim)
+ skeleton_position, skeleton_rotation, _ = decompose_matrix(
+ np.array(
+ UsdGeom.XformCache(_resolve_time_code(stage)).GetLocalToWorldTransform(skeleton_prim),
+ dtype=np.float32,
+ ),
+ translation_scale=skeleton_scale,
+ )
+ skinned_meshes = _load_skinned_meshes(
+ stage,
+ mesh_prim,
+ skeleton,
+ wp.transform(skeleton_position, skeleton_rotation),
+ get_prim_meters_scale(stage, mesh_prim),
+ )
+ if not skinned_meshes:
+ raise ValueError(f"No skinned meshes found under {mesh_prim_path}.")
+
+ # The skeleton was built from the same joints attribute, so the binds come in joint
+ # order. They use the skeleton prim's scale, not the mesh prim's.
+ bind_matrices = UsdSkel.Skeleton(skeleton_prim).GetBindTransformsAttr().Get()
+ if bind_matrices is None or len(bind_matrices) != skeleton.num_joints:
+ raise ValueError(f"Skeleton {skeleton_prim_path} needs one bind transform per joint.")
+ inverse_bind_transforms = [
+ wp.transform_inverse(get_bind_transform_as_warp_transform(
+ np.array(matrix, dtype=np.float32).reshape(4, 4), scale=skeleton_scale,
+ ))
+ for matrix in bind_matrices
+ ]
+ return SkeletalMesh(
+ skinned_meshes,
+ skeleton,
+ inverse_bind_transforms,
+ override_poses=_load_override_poses(stage, skeleton_prim, skeleton, skeleton_scale),
+ )
diff --git a/motionbricks/io/utils.py b/motionbricks/io/utils.py
new file mode 100644
index 0000000..cd4f916
--- /dev/null
+++ b/motionbricks/io/utils.py
@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Find bundled assets, and load the SOMA skeletal mesh or the Unitree G1 Newton model."""
+
+import re
+from pathlib import Path
+
+import motionbricks.io.usd as usd_utils
+
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+
+# The skeleton prim inside the bundled SOMA character file.
+SOMA_SKELETON_PRIM_PATH = "/OUTPUT/c_skeleton_grp/Hips"
+_SOMA_FINGER_JOINT = re.compile(r"(Left|Right)Hand(Thumb|Index|Middle|Ring|Pinky)")
+
+
+def get_package_root() -> Path:
+ """Return the filesystem path to the package root."""
+ return _PACKAGE_ROOT
+
+
+def get_assets_dir() -> Path:
+ """Return the assets directory path."""
+ return get_package_root() / 'assets'
+
+
+def get_asset_file(*relative_parts: str) -> Path:
+ """Return a path to a specific file under assets/.
+
+ Args:
+ *relative_parts: Path parts under assets/, such as "human" and the file name.
+ """
+ return get_assets_dir().joinpath(*relative_parts)
+
+
+def get_soma_human_model():
+ """Return the SOMA mesh with its skeleton in the reference pose.
+
+ The mesh holds the file's RelaxedHands override pose and a Fingers mask.
+ A renderer can select them to draw relaxed fingers.
+ """
+
+ mesh = usd_utils.load_skeletal_mesh_with_skeleton_from_usd(
+ get_asset_file('human', 'soma_base_skel_minimal_no_root.usd'),
+ '/OUTPUT/c_geometry_grp',
+ SOMA_SKELETON_PRIM_PATH,
+ )
+ skeleton = mesh.skeleton
+ fingers = [name for name in skeleton.joint_names if _SOMA_FINGER_JOINT.match(name)]
+ mesh.override_pose_masks['Fingers'] = skeleton.joint_mask(fingers)
+ return mesh
+
+
+def get_unitree_g1_model(*, device=None, load_visuals: bool = True):
+ """Load the bundled Unitree G1 robot as a Newton model.
+
+ Args:
+ device: Device for new arrays.
+ load_visuals: Load the visual meshes. False skips them.
+ """
+ import newton
+
+ builder = newton.ModelBuilder(up_axis=newton.Axis.Z)
+ builder.add_mjcf(
+ str(get_asset_file("robots", "unitree_g1", "g1_29dof_rev_1_0.xml")),
+ parse_meshes=load_visuals,
+ parse_visuals=load_visuals,
+ parse_sites=False,
+ collapse_fixed_joints=False,
+ enable_self_collisions=False,
+ )
+ return builder.finalize(device=device)
diff --git a/motionbricks/model/__init__.py b/motionbricks/model/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/motionbricks/model/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/motionbricks/model/config.py b/motionbricks/model/config.py
new file mode 100644
index 0000000..c59cf61
--- /dev/null
+++ b/motionbricks/model/config.py
@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generation options for MotionBricks models."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from motionbricks.model.contract import MODEL_MAX_TOKEN_COUNT, MODEL_MIN_TOKEN_COUNT
+
+DEFAULT_TOKEN_COUNTS = tuple(range(8, 15))
+
+
+@dataclass(frozen=True, slots=True)
+class MotionBricksInferenceConfig:
+ """Generation settings for output length, heading alignment, and endpoint correction.
+
+ Invalid values raise ValueError.
+
+ Attributes:
+ allowed_token_counts: Token counts the model may choose from, each from 6 to 16.
+ The default allows 8 to 14.
+ correct_generated_diff: Apply endpoint correction, so the motion starts at the
+ last context pose and ends at the first target pose. False keeps the
+ predicted endpoint poses.
+ heading_alignment: Ground direction that inference turns the last context pose to
+ face, in model space: (x, z) for SOMA and (x, y) for G1. The default (1, 0)
+ faces +X.
+ """
+
+ allowed_token_counts: tuple[int, ...] = DEFAULT_TOKEN_COUNTS
+ correct_generated_diff: bool = True
+ heading_alignment: tuple[float, float] = (1.0, 0.0)
+
+ def __post_init__(self) -> None:
+ if not self.allowed_token_counts:
+ raise ValueError("allowed_token_counts cannot be empty.")
+ if not all(MODEL_MIN_TOKEN_COUNT <= count <= MODEL_MAX_TOKEN_COUNT for count in self.allowed_token_counts):
+ raise ValueError(
+ f"allowed_token_counts values must be {MODEL_MIN_TOKEN_COUNT} to {MODEL_MAX_TOKEN_COUNT}."
+ )
+ if len(self.heading_alignment) != 2:
+ raise ValueError("heading_alignment must contain two values.")
+ if not np.isfinite(self.heading_alignment).all() or np.linalg.norm(self.heading_alignment) <= 1.0e-6:
+ raise ValueError("heading_alignment must be a finite, non-zero direction.")
+
+ def allowed_token_bits(self) -> int:
+ """Return the allowed token counts as a bit mask, with bit 0 for 6 tokens."""
+ bits = 0
+ for value in self.allowed_token_counts:
+ bits |= 1 << (value - MODEL_MIN_TOKEN_COUNT)
+ return bits
diff --git a/motionbricks/model/contract.py b/motionbricks/model/contract.py
new file mode 100644
index 0000000..137c696
--- /dev/null
+++ b/motionbricks/model/contract.py
@@ -0,0 +1,183 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""MotionBricks rigs, timing, and the tensor contract of each model."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+import json
+from pathlib import Path
+
+import numpy as np
+
+from motionbricks.inference.errors import TensorContractError
+from motionbricks.inference.types import TensorMode, TensorSpec
+
+
+# Core model timing shared by the SOMA and G1 representations.
+MODEL_SAMPLE_RATE = 30.0
+MODEL_POSES_PER_TOKEN = 4
+# The model reads four context poses, then a target token of up to four target poses.
+MODEL_CONTEXT_AND_TARGET_POSES = 2 * MODEL_POSES_PER_TOKEN
+# Fewest and most motion tokens either model can generate.
+MODEL_MIN_TOKEN_COUNT = 6
+MODEL_MAX_TOKEN_COUNT = 16
+# Frames removed from each end of the generated motion.
+MODEL_BOUNDARY_FRAMES = MODEL_POSES_PER_TOKEN - 1
+
+
+def valid_frame_count(token_count: int) -> int:
+ """Return the number of valid frames left after removing the boundary frames.
+
+ Args:
+ token_count: Token count, from 6 to 16. Other values raise ValueError.
+ """
+ if not MODEL_MIN_TOKEN_COUNT <= token_count <= MODEL_MAX_TOKEN_COUNT:
+ raise ValueError(
+ f"token_count must be {MODEL_MIN_TOKEN_COUNT} to {MODEL_MAX_TOKEN_COUNT}, got {token_count}."
+ )
+ return token_count * MODEL_POSES_PER_TOKEN - 2 * MODEL_BOUNDARY_FRAMES
+
+
+# The longest generated motion, which sets the capacity of every output buffer.
+MODEL_MAX_VALID_FRAMES = valid_frame_count(MODEL_MAX_TOKEN_COUNT)
+
+
+class ModelRig(StrEnum):
+ """MotionBricks rig types.
+
+ SOMA poses hold one local joint transform per skeleton joint. Unitree G1 poses
+ are joint coordinates: a root position and rotation, then the joint angles.
+ """
+
+ SOMA = "soma"
+ UNITREE_G1 = "unitree_g1"
+
+
+@dataclass(frozen=True, slots=True)
+class MotionBricksModelContract:
+ """The tensors and joints of one exported model graph.
+
+ load_model_manifest() reads it from the model manifest. The FP32 and mixed FP16
+ models share it, because their tensors match. The timing that every model shares
+ lives in the MODEL_ constants above. Invalid values raise ValueError.
+
+ Attributes:
+ name: Model name from the manifest.
+ onnx_filename: File name of the ONNX model, without a directory.
+ joint_names: Joint names in model order. For G1, they name the 29 joint
+ angles.
+ tensor_specs: Metadata of every input and output tensor.
+ """
+
+ name: str
+ onnx_filename: str
+ joint_names: tuple[str, ...]
+ tensor_specs: tuple[TensorSpec, ...]
+
+ def __post_init__(self) -> None:
+ if not self.name:
+ raise ValueError("Model contract name cannot be empty.")
+ if not self.onnx_filename or Path(self.onnx_filename).name != self.onnx_filename:
+ raise ValueError("onnx_filename must be a filename without directory components.")
+ if not self.joint_names or len(set(self.joint_names)) != len(self.joint_names):
+ raise ValueError("joint_names must be non-empty and unique.")
+ tensor_names = tuple(spec.name for spec in self.tensor_specs)
+ if not tensor_names or len(set(tensor_names)) != len(tensor_names):
+ raise ValueError("tensor_specs must be non-empty with unique names.")
+
+ def validate_tensor_specs(self, actual_specs: Mapping[str, TensorSpec]) -> None:
+ """Check tensor metadata against the contract's names, modes, shapes, and dtypes.
+
+ A mismatch raises TensorContractError, which lists every difference.
+
+ Args:
+ actual_specs: Tensor metadata keyed by tensor name, such as
+ InferenceEngine.tensor_specs.
+ """
+ expected_specs = {spec.name: spec for spec in self.tensor_specs}
+ errors: list[str] = []
+
+ missing = sorted(expected_specs.keys() - actual_specs.keys())
+ unexpected = sorted(actual_specs.keys() - expected_specs.keys())
+ if missing:
+ errors.append("missing tensors: " + ", ".join(missing))
+ if unexpected:
+ errors.append("unexpected tensors: " + ", ".join(unexpected))
+
+ for name in expected_specs.keys() & actual_specs.keys():
+ expected = expected_specs[name]
+ actual = actual_specs[name]
+ if actual.mode is not expected.mode:
+ errors.append(
+ f"{name}: expected mode {expected.mode.value}, got {actual.mode.value}"
+ )
+ if actual.shape != expected.shape:
+ errors.append(f"{name}: expected shape {expected.shape}, got {actual.shape}")
+ if actual.dtype != expected.dtype:
+ errors.append(f"{name}: expected dtype {expected.dtype}, got {actual.dtype}")
+
+ if errors:
+ detail = ". ".join(errors)
+ raise TensorContractError(f"Engine does not match {self.name!r}: {detail}.")
+
+
+# The manifest repeats the shared timing, so a model exported with other timing fails to load.
+_MANIFEST_TIMING = (
+ ("sample_rate", MODEL_SAMPLE_RATE),
+ ("frames_per_token", MODEL_POSES_PER_TOKEN),
+ ("context_frames", MODEL_POSES_PER_TOKEN),
+ ("target_capacity", MODEL_POSES_PER_TOKEN),
+ ("min_pred_tokens", MODEL_MIN_TOKEN_COUNT),
+ ("max_pred_tokens", MODEL_MAX_TOKEN_COUNT),
+)
+
+
+def load_model_manifest(path: Path) -> tuple[MotionBricksModelContract, Path, Path]:
+ """Load a model manifest and return its contract, FP32 ONNX path, and mixed FP16 ONNX path.
+
+ The ONNX files sit next to the manifest. A manifest whose timing differs from the
+ MODEL_ constants raises ValueError.
+
+ Args:
+ path: Model manifest JSON file.
+ """
+
+ manifest_path = Path(path)
+ try:
+ manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ValueError(f"Could not load model manifest {manifest_path}: {exc}") from exc
+
+ try:
+ if manifest["schema_version"] != 1:
+ raise ValueError(f"unsupported schema_version {manifest['schema_version']!r}")
+ for field, value in _MANIFEST_TIMING:
+ if manifest[field] != value:
+ raise ValueError(f"{field} must be {value:g}")
+ tensor_specs = tuple(
+ TensorSpec(
+ tensor["name"],
+ TensorMode(tensor["mode"]),
+ tuple(tensor["shape"]),
+ np.dtype(tensor["dtype"]),
+ )
+ for tensor in manifest["tensor_specs"]
+ )
+ contract = MotionBricksModelContract(
+ name=manifest["name"],
+ onnx_filename=manifest["onnx_filename"],
+ joint_names=tuple(manifest["joint_names"]),
+ tensor_specs=tensor_specs,
+ )
+ fp16_onnx_filename = manifest["precision_variants"]["fp16"]["onnx_filename"]
+ except (KeyError, TypeError, ValueError) as exc:
+ raise ValueError(f"Invalid model manifest {manifest_path}: {exc}") from exc
+ return (
+ contract,
+ manifest_path.with_name(contract.onnx_filename),
+ manifest_path.with_name(fp16_onnx_filename),
+ )
diff --git a/motionbricks/model/engine.py b/motionbricks/model/engine.py
new file mode 100644
index 0000000..50d262b
--- /dev/null
+++ b/motionbricks/model/engine.py
@@ -0,0 +1,158 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""The engine setup and generation flow that the SOMA and Unitree G1 engines share."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import warp as wp
+
+from motionbricks.inference.builder import TensorRTBuildOptions
+from motionbricks.inference.engine import InferenceEngine
+
+from .config import MotionBricksInferenceConfig
+from .contract import valid_frame_count
+from .generation import GenerationTimer, read_token_count
+
+if TYPE_CHECKING:
+ from motionbricks.animation.animation_buffer import AnimationBuffer
+ from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+ from .soma.buffers import PoseToken
+ from .unitree_g1.buffers import DOFToken
+
+
+class MotionBricksEngine(InferenceEngine, ABC):
+ """Generate motion from recent motion and target poses with a MotionBricks model.
+
+ Each rig engine sets contract, creates its tokens and output buffer, and supplies
+ the steps that depend on its pose layout: _initialize_pose_layout(),
+ _prepare_generation(), _encode_guide_poses(), _decode_generated_poses(), and
+ _post_process_generated_poses().
+ """
+
+ def __init__(
+ self,
+ onnx_path: str | Path,
+ *,
+ model_to_runtime: wp.transform = wp.transform_identity(),
+ build_options: TensorRTBuildOptions | None = None,
+ stream: wp.Stream | None = None,
+ cache_dir: str | Path = ".trt-cache",
+ force_rebuild: bool = False,
+ bake_cuda_graph: bool = True,
+ logger_severity: str = "INFO",
+ build_progress_monitor: Any | None = None,
+ ) -> None:
+ """Load or build the TensorRT plan, then check it against the model's contract.
+
+ Args:
+ onnx_path: ONNX model to run.
+ model_to_runtime: Transform from model space to world space. The default is
+ the identity.
+ build_options: Build options for the plan. None uses the defaults.
+ stream: Stream for inference. None creates a new stream.
+ cache_dir: Directory that holds the cached plans. A relative path starts
+ at the working directory.
+ force_rebuild: Build a new plan even when a cached one matches.
+ bake_cuda_graph: Capture inference into a CUDA graph on the first
+ generation.
+ logger_severity: Least severe TensorRT message to forward:
+ INTERNAL_ERROR, ERROR, WARNING, INFO, or VERBOSE.
+ build_progress_monitor: TensorRT progress monitor for the build. None
+ reports no progress.
+ """
+ super().__init__(
+ onnx_path,
+ build_options=build_options,
+ stream=stream,
+ cache_dir=cache_dir,
+ force_rebuild=force_rebuild,
+ logger_severity=logger_severity,
+ build_progress_monitor=build_progress_monitor,
+ )
+ try:
+ self.contract.validate_tensor_specs(self.tensor_specs)
+ except Exception:
+ self.close()
+ raise
+
+ self._use_cuda_graph = bake_cuda_graph
+ self._model_to_runtime = wp.transform(model_to_runtime)
+ self._runtime_to_model = wp.transform_inverse(self._model_to_runtime)
+ self.timer = GenerationTimer(self.stream)
+ self._alignment = wp.empty(1, dtype=wp.transform, device=self.device)
+ self._generated_frame_count = wp.empty(1, dtype=wp.int32, device=self.device)
+ self._initialize_pose_layout()
+
+ def generate_animation(
+ self,
+ context: PoseToken | DOFToken,
+ target: PoseToken | DOFToken,
+ output: AnimationBuffer | DOFAnimationBuffer,
+ *,
+ config: MotionBricksInferenceConfig | None = None,
+ ) -> AnimationBuffer | DOFAnimationBuffer:
+ """Generate motion at a sample rate of 30 Hz into output, and return output.
+
+ Update the context and target tokens on self.stream before calling. It waits
+ for the generation to finish. timer.milliseconds then holds the time of each
+ stage.
+
+ Args:
+ context: Context token with four poses, their root in world space.
+ target: Target token with one to four poses, their root in world space.
+ output: Animation buffer from create_output(). Its num_frames gives the number
+ of valid frames. Its foot_contacts holds the predicted foot contacts.
+ config: Generation settings for the allowed token counts, heading
+ alignment, and endpoint correction. None uses the defaults.
+ """
+ self._ensure_open()
+ config = config or MotionBricksInferenceConfig()
+ self._prepare_generation(context, target, output)
+ output.num_frames = 0
+
+ with self.timer.stage("encode"):
+ self._encode_guide_poses(context, target, config)
+ if self._use_cuda_graph and not self.cuda_graph_baked:
+ self.bake_cuda_graph()
+ with self.timer.stage("inference"):
+ self.enqueue_async()
+ with self.timer.stage("decode"):
+ self._decode_generated_poses(output)
+ if config.correct_generated_diff:
+ with self.timer.stage("post_process"):
+ self._post_process_generated_poses(context, target, output)
+ self.synchronize()
+ self.timer.read()
+
+ token_count = read_token_count(self, config)
+ output.num_frames = valid_frame_count(token_count)
+ return output
+
+ @abstractmethod
+ def _initialize_pose_layout(self) -> None:
+ """Allocate what the rig's pose layout needs. The constructor calls it last."""
+
+ @abstractmethod
+ def _prepare_generation(self, context, target, output) -> None:
+ """Check the tokens and output against the pose layout, and prepare for them."""
+
+ @abstractmethod
+ def _encode_guide_poses(self, context, target, config: MotionBricksInferenceConfig) -> None:
+ """Align the context and target poses, and write them and the conditions into the inputs."""
+
+ @abstractmethod
+ def _decode_generated_poses(self, output) -> None:
+ """Decode the prediction into output, and write the valid frame count."""
+
+ @abstractmethod
+ def _post_process_generated_poses(self, context, target, output) -> None:
+ """Match the generated motion's endpoints to the last context pose and first target pose."""
+
+
+__all__ = ["MotionBricksEngine"]
diff --git a/motionbricks/model/generation.py b/motionbricks/model/generation.py
new file mode 100644
index 0000000..b0039bd
--- /dev/null
+++ b/motionbricks/model/generation.py
@@ -0,0 +1,183 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generation steps that the SOMA and Unitree G1 engines share."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+import warp as wp
+
+from motionbricks.inference.errors import TensorContractError
+
+from .config import MotionBricksInferenceConfig
+from .contract import (
+ MODEL_MAX_TOKEN_COUNT,
+ MODEL_MAX_VALID_FRAMES,
+ MODEL_MIN_TOKEN_COUNT,
+ MODEL_POSES_PER_TOKEN,
+ MODEL_SAMPLE_RATE,
+)
+from .kernels import pad_token_poses_kernel, write_motionbricks_conditions_kernel
+
+if TYPE_CHECKING:
+ from motionbricks.animation.animation_buffer import AnimationBuffer
+ from motionbricks.inference.engine import InferenceEngine
+ from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+ from .soma.buffers import PoseToken
+ from .unitree_g1.buffers import DOFToken
+
+
+GENERATION_STAGES = ("encode", "inference", "decode", "post_process")
+
+
+def write_token_poses(poses: wp.array, token_poses: wp.array, stream: wp.Stream | None) -> int:
+ """Copy one to four poses into a token, and pad the unused rows with the last pose.
+
+ Args:
+ poses: One to four poses laid out as [pose, value], or one pose as [value]. A
+ value is a local joint transform for SOMA and a joint coordinate for G1.
+ token_poses: The token's storage for four poses, with the same dtype and the same
+ number of values per pose.
+ stream: Stream for the work. None uses the current stream.
+
+ Returns:
+ The number of poses supplied.
+ """
+ if poses.dtype != token_poses.dtype or poses.ndim not in (1, 2):
+ raise ValueError("Token poses must be a vector or matrix with the token's dtype.")
+ if poses.ndim == 1:
+ poses = poses.reshape((1, poses.shape[0]))
+ num_poses, num_values = poses.shape
+ if not 1 <= num_poses <= MODEL_POSES_PER_TOKEN:
+ raise ValueError(f"A context or target token requires 1 to {MODEL_POSES_PER_TOKEN} poses.")
+ if num_values != token_poses.shape[1]:
+ raise ValueError(f"Each token pose holds {token_poses.shape[1]} values, got {num_values}.")
+ wp.launch(
+ pad_token_poses_kernel,
+ dim=token_poses.shape,
+ inputs=[poses, num_poses],
+ outputs=[token_poses],
+ device=token_poses.device,
+ stream=stream,
+ )
+ return num_poses
+
+
+def check_generation_buffers(
+ context: PoseToken | DOFToken,
+ target: PoseToken | DOFToken,
+ output: AnimationBuffer | DOFAnimationBuffer,
+) -> None:
+ """Check the pose counts and the output buffer that every model needs.
+
+ Each engine also checks the joints of its rig. A mismatch raises ValueError.
+
+ Args:
+ context: Context token.
+ target: Target token.
+ output: Animation buffer that receives the generated motion.
+ """
+ if context.num_poses != MODEL_POSES_PER_TOKEN:
+ raise ValueError(f"Context token must contain {MODEL_POSES_PER_TOKEN} poses.")
+ if not 1 <= target.num_poses <= MODEL_POSES_PER_TOKEN:
+ raise ValueError(f"Target token must contain 1 to {MODEL_POSES_PER_TOKEN} poses.")
+ if output.sample_rate != MODEL_SAMPLE_RATE:
+ raise ValueError(f"Output must use a sample rate of {MODEL_SAMPLE_RATE:g} Hz.")
+ if output.capacity < MODEL_MAX_VALID_FRAMES:
+ raise ValueError(f"Output capacity must be at least {MODEL_MAX_VALID_FRAMES} frames.")
+ if output.foot_contacts is None:
+ raise ValueError("Output must have foot_contacts. create_output() allocates them.")
+
+
+def write_conditions(
+ engine: InferenceEngine,
+ num_target_poses: int,
+ config: MotionBricksInferenceConfig,
+) -> None:
+ """Tell the model which context and target poses are given, and which token counts it may choose.
+
+ Args:
+ engine: Engine whose conditioning tensors are written.
+ num_target_poses: Number of given target poses, from 1 to 4.
+ config: Generation settings with the allowed token counts.
+ """
+ wp.launch(
+ write_motionbricks_conditions_kernel,
+ dim=MODEL_MAX_TOKEN_COUNT - MODEL_MIN_TOKEN_COUNT + 1,
+ inputs=[num_target_poses, config.allowed_token_bits()],
+ outputs=[
+ engine.device_tensor("has_global_root_values"),
+ engine.device_tensor("has_local_root_values"),
+ engine.device_tensor("has_local_poses"),
+ engine.device_tensor("allowed_pred_num_tokens"),
+ ],
+ stream=engine.stream,
+ )
+
+
+def read_token_count(engine: InferenceEngine, config: MotionBricksInferenceConfig) -> int:
+ """Return the token count the model chose. Call it after the engine's stream finishes.
+
+ A count outside config.allowed_token_counts raises TensorContractError.
+
+ Args:
+ engine: Engine that ran the generation.
+ config: Generation settings with the allowed token counts.
+ """
+ with wp.ScopedStream(engine.stream):
+ token_count = int(engine.device_tensor("pred_num_tokens").numpy()[0])
+ if token_count not in config.allowed_token_counts:
+ raise TensorContractError(
+ f"Model selected {token_count} tokens, outside the allowed set {config.allowed_token_counts}."
+ )
+ return token_count
+
+
+class GenerationTimer:
+ """Time each stage of a generation with CUDA events on the engine's stream.
+
+ milliseconds holds the times of the last generation, keyed by the names in
+ GENERATION_STAGES. A skipped stage reads 0.
+ """
+
+ def __init__(self, stream: wp.Stream) -> None:
+ """Create the start and end events of each stage on the stream's device.
+
+ Args:
+ stream: Stream whose work is timed.
+ """
+ self._stream = stream
+ self._events = {
+ stage: (
+ wp.Event(device=stream.device, enable_timing=True),
+ wp.Event(device=stream.device, enable_timing=True),
+ )
+ for stage in GENERATION_STAGES
+ }
+ self._timed: set[str] = set()
+ self.milliseconds = dict.fromkeys(GENERATION_STAGES, 0.0)
+
+ @contextmanager
+ def stage(self, name: str) -> Generator[None]:
+ """Time the work that the with block enqueues on the stream.
+
+ Args:
+ name: Stage name from GENERATION_STAGES.
+ """
+ start, end = self._events[name]
+ self._stream.record_event(start)
+ yield
+ self._stream.record_event(end)
+ self._timed.add(name)
+
+ def read(self) -> None:
+ """Read the stage times into milliseconds. Call it after the stream finishes."""
+ for name, (start, end) in self._events.items():
+ timed = name in self._timed
+ self.milliseconds[name] = wp.get_event_elapsed_time(start, end, synchronize=False) if timed else 0.0
+ self._timed.clear()
diff --git a/motionbricks/model/kernels.py b/motionbricks/model/kernels.py
new file mode 100644
index 0000000..4bb4f10
--- /dev/null
+++ b/motionbricks/model/kernels.py
@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Conditioning masks and token padding that the SOMA and Unitree G1 engines share."""
+
+from typing import Any
+
+import warp as wp
+
+from .contract import MODEL_CONTEXT_AND_TARGET_POSES, MODEL_POSES_PER_TOKEN
+
+
+def pad_token_poses_kernel(
+ poses: wp.array2d(dtype=Any),
+ num_poses: wp.int32,
+ token_poses: wp.array2d(dtype=Any),
+):
+ """Copy the supplied poses into a token, repeating the last one in the unused rows."""
+ pose, value = wp.tid()
+ token_poses[pose, value] = poses[wp.min(pose, num_poses - 1), value]
+
+
+def write_motionbricks_conditions_kernel(
+ num_target_poses: wp.int32,
+ allowed_token_bits: wp.int32,
+ has_global_root_values: wp.array2d(dtype=wp.int32),
+ has_local_root_values: wp.array2d(dtype=wp.int32),
+ has_local_poses: wp.array2d(dtype=wp.int32),
+ allowed_pred_num_tokens: wp.array2d(dtype=wp.int32),
+):
+ """Mark the conditioning slots in use, and write the allowed token counts as a mask.
+
+ One thread runs per token count, from 6 to 16. The first eight threads also mark the
+ four context pose slots and the four target pose slots. The context poses and the
+ first num_target_poses target poses count as given. Local root values stay unmarked
+ at the last context pose and the last target pose, because their derivatives are
+ unknown there.
+ """
+ index = wp.tid()
+ if index < MODEL_CONTEXT_AND_TARGET_POSES:
+ value = wp.where(index < MODEL_POSES_PER_TOKEN + num_target_poses, wp.int32(1), wp.int32(0))
+ has_global_root_values[0, index] = value
+ has_local_poses[0, index] = value
+ has_local_root_values[0, index] = wp.where(
+ index == MODEL_POSES_PER_TOKEN - 1 or index == MODEL_POSES_PER_TOKEN + num_target_poses - 1,
+ wp.int32(0),
+ value,
+ )
+ allowed_pred_num_tokens[0, index] = (allowed_token_bits >> index) & 1
diff --git a/motionbricks/model/soma/__init__.py b/motionbricks/model/soma/__init__.py
new file mode 100644
index 0000000..a4d6362
--- /dev/null
+++ b/motionbricks/model/soma/__init__.py
@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/motionbricks/model/soma/buffers.py b/motionbricks/model/soma/buffers.py
new file mode 100644
index 0000000..b55e758
--- /dev/null
+++ b/motionbricks/model/soma/buffers.py
@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Context and target tokens for the SOMA model."""
+
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE
+from motionbricks.model.generation import write_token_poses
+from motionbricks.runtime.motion_recorder import MotionRecorder
+import motionbricks.utils.pose_utils as pose_utils
+from motionbricks.utils.time_utils import history_sample_indices
+
+
+def _sample_recorder_kernel(
+ recorded_poses: wp.array2d(dtype=wp.transform),
+ lower_frames: wp.vec4i,
+ upper_frames: wp.vec4i,
+ blends: wp.vec4,
+ token_poses: wp.array2d(dtype=wp.transform),
+):
+ pose, joint = wp.tid()
+ token_poses[pose, joint] = pose_utils.blend_transform(
+ recorded_poses[lower_frames[pose], joint],
+ recorded_poses[upper_frames[pose], joint],
+ blends[pose],
+ )
+
+
+class PoseToken:
+ """Hold up to four poses for model context or a target.
+
+ poses holds the local joint transforms of all four poses, laid out as [pose, joint].
+ num_poses counts the supplied poses. Padding repeats the last pose in the unused
+ space.
+ """
+
+ def __init__(self, num_joints: int, *, device=None) -> None:
+ """Allocate room for four poses.
+
+ Args:
+ num_joints: Joints per pose. It must be positive.
+ device: Device for new arrays. None uses the current device.
+ """
+ if num_joints <= 0:
+ raise ValueError("num_joints must be positive.")
+ self.num_joints = num_joints
+ self.poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, self.num_joints),
+ dtype=wp.transform,
+ device=device,
+ )
+ self._num_poses = 0
+
+ @property
+ def num_poses(self) -> int:
+ """Number of supplied poses, from 1 to 4, or 0 before the first update."""
+ return self._num_poses
+
+ def update_from_poses(
+ self,
+ local_poses: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Copy one to four poses and pad the unused space with the last pose.
+
+ The poses are in time order at the model's sample rate of 30 Hz. A context
+ token ends at the current pose. A target token starts at the pose to reach.
+
+ Args:
+ local_poses: Local joint transforms of one to four poses, as a transform
+ array of [pose, joint] or [joint].
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._num_poses = write_token_poses(local_poses, self.poses, stream)
+
+ def update_from_recorder(
+ self,
+ motion_history: MotionRecorder,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Sample four poses at 30 Hz, ending at the latest recorded pose.
+
+ Args:
+ motion_history: Recorder of played poses, with the token's joint count.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if motion_history.poses.shape[1] != self.num_joints:
+ raise ValueError("History and token joint counts do not match.")
+ lower_frames, upper_frames, blends = history_sample_indices(
+ motion_history.delta_times, MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE,
+ )
+
+ wp.launch(
+ _sample_recorder_kernel,
+ dim=self.poses.shape,
+ inputs=[
+ motion_history.poses,
+ wp.vec4i(*lower_frames),
+ wp.vec4i(*upper_frames),
+ wp.vec4(*blends),
+ ],
+ outputs=[self.poses],
+ device=self.poses.device,
+ stream=stream,
+ )
+ self._num_poses = MODEL_POSES_PER_TOKEN
diff --git a/motionbricks/model/soma/contract.py b/motionbricks/model/soma/contract.py
new file mode 100644
index 0000000..7254932
--- /dev/null
+++ b/motionbricks/model/soma/contract.py
@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""The SOMA model's contract, ONNX paths, foot contact joints, and heading joints.
+
+The contract comes from the model's manifest and describes a batch size of one.
+"""
+
+from pathlib import Path
+
+from ..contract import load_model_manifest
+
+SOMA_N1_MANIFEST_PATH = Path(__file__).resolve().parents[2] / "assets/onnx/soma/soma_n1.json"
+SOMA_N1_CONTRACT, SOMA_N1_FP32_ONNX_PATH, SOMA_N1_FP16_ONNX_PATH = load_model_manifest(SOMA_N1_MANIFEST_PATH)
+SOMA_N1_FOOT_CONTACT_JOINTS = ("LeftFoot", "LeftToeBase", "RightFoot", "RightToeBase")
+# The right and left leg joints whose positions give a pose's heading, as in training.
+SOMA_N1_HEADING_JOINTS = ("RightLeg", "LeftLeg")
diff --git a/motionbricks/model/soma/engine.py b/motionbricks/model/soma/engine.py
new file mode 100644
index 0000000..fbf502b
--- /dev/null
+++ b/motionbricks/model/soma/engine.py
@@ -0,0 +1,221 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generate SOMA motion with TensorRT."""
+
+from __future__ import annotations
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.utils.pose_utils import compute_world_poses
+
+from ..config import MotionBricksInferenceConfig
+from ..contract import (
+ MODEL_CONTEXT_AND_TARGET_POSES,
+ MODEL_MAX_VALID_FRAMES,
+ MODEL_POSES_PER_TOKEN,
+ MODEL_SAMPLE_RATE,
+)
+from ..engine import MotionBricksEngine
+from ..generation import check_generation_buffers, write_conditions
+from . import kernels
+from .buffers import PoseToken
+from .contract import SOMA_N1_CONTRACT, SOMA_N1_HEADING_JOINTS
+
+
+class MotionBricksSOMAEngine(MotionBricksEngine):
+ """Generate SOMA motion from recent motion and target poses.
+
+ Each pose holds one local transform per skeleton joint. The root joint is
+ Hips.
+ """
+
+ contract = SOMA_N1_CONTRACT
+
+ def _initialize_pose_layout(self) -> None:
+ # _bind_pose_skeleton() fills these for the skeleton of the tokens and output.
+ self._pose_skeleton = None
+ self._model_to_pose = None
+ self._pose_to_model = None
+ self._guide_world = None
+ self._start_deltas = None
+ self._end_deltas = None
+ self._right_leg_index = -1
+ self._left_leg_index = -1
+
+ def create_input(self, skeleton) -> PoseToken:
+ """Create a context or target token with room for four poses.
+
+ Args:
+ skeleton: Skeleton of the poses. It must contain the model's joint names.
+ Missing joints raise ValueError.
+ """
+ self._ensure_open()
+ self._bind_pose_skeleton(skeleton)
+ return PoseToken(skeleton.num_joints, device=self.device)
+
+ def create_output(self, skeleton) -> AnimationBuffer:
+ """Create an empty animation buffer with room for the longest generated motion.
+
+ Args:
+ skeleton: Skeleton of the generated motion. It must contain the model's joint
+ names. Missing joints raise ValueError.
+ """
+ self._ensure_open()
+ self._bind_pose_skeleton(skeleton)
+ return AnimationBuffer(
+ skeleton,
+ MODEL_SAMPLE_RATE,
+ wp.empty((MODEL_MAX_VALID_FRAMES, skeleton.num_joints), dtype=wp.transform, device=self.device),
+ num_frames=0,
+ foot_contacts=wp.zeros((MODEL_MAX_VALID_FRAMES, FOOT_CONTACT_COUNT), dtype=wp.float32, device=self.device),
+ )
+
+ def _prepare_generation(
+ self,
+ context: PoseToken,
+ target: PoseToken,
+ output: AnimationBuffer,
+ ) -> None:
+ self._bind_pose_skeleton(output.skeleton)
+ num_joints = output.skeleton.num_joints
+ for name, token in (("Context", context), ("Target", target)):
+ if token.num_joints != num_joints:
+ raise ValueError(f"{name} token must contain {num_joints} joints per pose.")
+ check_generation_buffers(context, target, output)
+
+ def _bind_pose_skeleton(self, skeleton) -> None:
+ if skeleton is self._pose_skeleton:
+ return
+
+ model_to_pose = [
+ skeleton.joint_index(name) for name in self.contract.joint_names
+ ]
+ if -1 in model_to_pose:
+ raise ValueError(
+ "The skeleton is missing model joints: "
+ + ", ".join(
+ name
+ for name, index in zip(self.contract.joint_names, model_to_pose)
+ if index == -1
+ )
+ )
+ assert model_to_pose[0] == 0, "The skeleton must store the root at index zero."
+
+ pose_to_model = np.full(skeleton.num_joints, -1, dtype=np.int32)
+ for model_joint, pose_joint in enumerate(model_to_pose):
+ parent = skeleton.joint_parent(pose_joint)
+ # Model joints outside the connected skeleton hierarchy keep their
+ # local transforms from the reference pose during decoding.
+ if parent == -1 or pose_to_model[parent] >= 0:
+ pose_to_model[pose_joint] = model_joint
+
+ self._pose_skeleton = None
+ right_leg, left_leg = SOMA_N1_HEADING_JOINTS
+ self._right_leg_index = skeleton.joint_index(right_leg)
+ self._left_leg_index = skeleton.joint_index(left_leg)
+ self._model_to_pose = wp.array(model_to_pose, dtype=wp.int32, device=self.device)
+ self._pose_to_model = wp.array(pose_to_model, dtype=wp.int32, device=self.device)
+ self._guide_world = wp.empty(
+ (MODEL_CONTEXT_AND_TARGET_POSES, skeleton.num_joints), dtype=wp.transform, device=self.device,
+ )
+ self._start_deltas = wp.empty(skeleton.num_joints, dtype=wp.transform, device=self.device)
+ self._end_deltas = wp.empty(skeleton.num_joints, dtype=wp.transform, device=self.device)
+ self._pose_skeleton = skeleton
+
+ def _encode_guide_poses(
+ self,
+ context: PoseToken,
+ target: PoseToken,
+ config: MotionBricksInferenceConfig,
+ ) -> None:
+ # runtime_to_model composes each pose into SOMA model space.
+ for token, rows in (
+ (context, self._guide_world[:MODEL_POSES_PER_TOKEN]),
+ (target, self._guide_world[MODEL_POSES_PER_TOKEN:]),
+ ):
+ compute_world_poses(
+ token.poses, self._pose_skeleton.parent_indices, rows, self._runtime_to_model, stream=self.stream,
+ )
+ wp.launch(
+ kernels.compute_guide_alignment_kernel,
+ dim=1,
+ inputs=[
+ self._right_leg_index,
+ self._left_leg_index,
+ wp.vec2(*config.heading_alignment),
+ self._guide_world,
+ ],
+ outputs=[self._alignment],
+ stream=self.stream,
+ )
+ wp.launch(
+ kernels.encode_motionbricks_inputs_kernel,
+ dim=MODEL_CONTEXT_AND_TARGET_POSES,
+ inputs=[
+ len(self.contract.joint_names),
+ self._right_leg_index,
+ self._left_leg_index,
+ self._model_to_pose,
+ self._guide_world,
+ self._alignment,
+ ],
+ outputs=[
+ self.device_tensor("global_root_values"),
+ self.device_tensor("local_root_values"),
+ self.device_tensor("local_poses"),
+ ],
+ stream=self.stream,
+ )
+ write_conditions(self, target.num_poses, config)
+
+ def _decode_generated_poses(self, output: AnimationBuffer) -> None:
+ wp.launch(
+ kernels.decode_motionbricks_output_kernel,
+ dim=MODEL_MAX_VALID_FRAMES,
+ inputs=[
+ len(self.contract.joint_names),
+ self._pose_skeleton.num_joints,
+ self._pose_skeleton.parent_indices,
+ self._pose_to_model,
+ self._pose_skeleton.reference_local_transforms,
+ self._alignment,
+ self._model_to_runtime,
+ self.device_tensor("pred_global_motions"),
+ self.device_tensor("pred_num_tokens"),
+ ],
+ outputs=[
+ output.poses,
+ output.foot_contacts,
+ self._generated_frame_count,
+ ],
+ stream=self.stream,
+ )
+
+ def _post_process_generated_poses(
+ self,
+ context: PoseToken,
+ target: PoseToken,
+ output: AnimationBuffer,
+ ) -> None:
+ """Match the generated motion's endpoints to the last context pose and first target pose.
+
+ The corrections span the generated motion.
+ """
+ wp.launch(
+ kernels.compute_endpoint_deltas_kernel,
+ dim=self._pose_skeleton.num_joints,
+ inputs=[self._generated_frame_count, context.poses, target.poses, output.poses],
+ outputs=[self._start_deltas, self._end_deltas],
+ stream=self.stream,
+ )
+ wp.launch(
+ kernels.apply_endpoint_deltas_kernel,
+ dim=(MODEL_MAX_VALID_FRAMES, self._pose_skeleton.num_joints),
+ inputs=[self._generated_frame_count, self._start_deltas, self._end_deltas],
+ outputs=[output.poses],
+ stream=self.stream,
+ )
diff --git a/motionbricks/model/soma/kernels.py b/motionbricks/model/soma/kernels.py
new file mode 100644
index 0000000..6527432
--- /dev/null
+++ b/motionbricks/model/soma/kernels.py
@@ -0,0 +1,317 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Warp kernels for the SOMA MotionBricks pose contract."""
+
+import warp as wp
+
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.model.contract import MODEL_BOUNDARY_FRAMES, MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE
+import motionbricks.utils.pose_utils as pose_utils
+
+
+# Mirrors the training representation's compute_heading_method="hips_pos".
+def _heading_from_hip_positions(
+ right_hip: wp.vec3,
+ left_hip: wp.vec3,
+) -> wp.float32:
+ across = wp.vec3(right_hip[0] - left_hip[0], 0.0, right_hip[2] - left_hip[2])
+ length = wp.length(across)
+ if length <= 1.0e-6:
+ return 0.0
+ across = across / length
+ forward = wp.cross(wp.vec3(0.0, 1.0, 0.0), across)
+ return wp.atan2(forward[0], forward[2])
+
+
+def _rotation_from_6d(x_raw: wp.vec3, y_raw: wp.vec3) -> wp.quat:
+ x_axis = wp.normalize(x_raw)
+ z_axis = wp.normalize(wp.cross(x_axis, y_raw))
+ y_axis = wp.cross(z_axis, x_axis)
+ return wp.quat_from_matrix(wp.matrix_from_cols(x_axis, y_axis, z_axis))
+
+
+def _read_rotation(
+ features: wp.array3d(dtype=wp.float32),
+ frame: wp.int32,
+ offset: wp.int32,
+) -> wp.quat:
+ x_axis = wp.vec3(
+ features[0, frame, offset],
+ features[0, frame, offset + 1],
+ features[0, frame, offset + 2],
+ )
+ y_axis = wp.vec3(
+ features[0, frame, offset + 3],
+ features[0, frame, offset + 4],
+ features[0, frame, offset + 5],
+ )
+ return _rotation_from_6d(x_axis, y_axis)
+
+
+def compute_guide_alignment_kernel(
+ right_leg_index: wp.int32,
+ left_leg_index: wp.int32,
+ desired_heading: wp.vec2,
+ world_poses: wp.array2d(dtype=wp.transform),
+ alignment: wp.array(dtype=wp.transform),
+):
+ """Compute the heading alignment of the last context pose to desired_heading.
+
+ The heading comes from the positions of the leg joints. The result maps aligned
+ poses back to SOMA model space and keeps the root height.
+ """
+ last_context_frame = MODEL_POSES_PER_TOKEN - 1
+ hips_position = world_poses[last_context_frame, 0].p
+ current_angle = _heading_from_hip_positions(
+ world_poses[last_context_frame, right_leg_index].p,
+ world_poses[last_context_frame, left_leg_index].p,
+ )
+ desired_angle = wp.atan2(desired_heading[0], desired_heading[1])
+ alignment[0] = wp.transform(
+ wp.vec3(hips_position[0], 0.0, hips_position[2]),
+ wp.quat_from_axis_angle(wp.vec3(0.0, 1.0, 0.0), current_angle - desired_angle),
+ )
+
+
+def _aligned_position(alignment: wp.transform, position: wp.vec3) -> wp.vec3:
+ # Subtract before rotating to retain precision far from the origin.
+ return wp.quat_rotate_inv(alignment.q, position - alignment.p)
+
+
+def encode_motionbricks_inputs_kernel(
+ num_model_joints: wp.int32,
+ right_leg_index: wp.int32,
+ left_leg_index: wp.int32,
+ model_to_pose: wp.array(dtype=wp.int32),
+ world_poses: wp.array2d(dtype=wp.transform),
+ alignment: wp.array(dtype=wp.transform),
+ global_root_values: wp.array3d(dtype=wp.float32),
+ local_root_values: wp.array3d(dtype=wp.float32),
+ local_poses: wp.array3d(dtype=wp.float32),
+):
+ """Encode each context and target pose into the model's root and pose input tensors.
+
+ Positions and headings are measured after the alignment. Root velocities use the
+ next pose, so they are zero at the last context pose and the last target pose.
+ """
+ frame = wp.tid()
+ final_frame = 2 * MODEL_POSES_PER_TOKEN - 1
+ next_frame = wp.where(
+ frame == MODEL_POSES_PER_TOKEN - 1,
+ frame,
+ wp.min(frame + 1, final_frame),
+ )
+
+ align = alignment[0]
+ current_hips = _aligned_position(align, world_poses[frame, 0].p)
+ next_hips = _aligned_position(align, world_poses[next_frame, 0].p)
+
+ current_right = _aligned_position(align, world_poses[frame, right_leg_index].p)
+ current_left = _aligned_position(align, world_poses[frame, left_leg_index].p)
+ next_right = _aligned_position(align, world_poses[next_frame, right_leg_index].p)
+ next_left = _aligned_position(align, world_poses[next_frame, left_leg_index].p)
+
+ current_heading = _heading_from_hip_positions(current_right, current_left)
+ next_heading = _heading_from_hip_positions(next_right, next_left)
+ heading_delta = wp.atan2(
+ wp.sin(next_heading - current_heading),
+ wp.cos(next_heading - current_heading),
+ )
+
+ global_root_values[0, frame, 0] = current_hips[0]
+ global_root_values[0, frame, 1] = current_hips[1]
+ global_root_values[0, frame, 2] = current_hips[2]
+ global_root_values[0, frame, 3] = wp.cos(current_heading)
+ global_root_values[0, frame, 4] = wp.sin(current_heading)
+
+ local_root_values[0, frame, 0] = heading_delta * MODEL_SAMPLE_RATE
+ local_root_values[0, frame, 1] = (next_hips[0] - current_hips[0]) * MODEL_SAMPLE_RATE
+ local_root_values[0, frame, 2] = (next_hips[2] - current_hips[2]) * MODEL_SAMPLE_RATE
+ local_root_values[0, frame, 3] = current_hips[1]
+
+ root_position = wp.vec3(current_hips[0], 0.0, current_hips[2])
+ for model_joint in range(num_model_joints):
+ pose_joint = model_to_pose[model_joint]
+ joint_position = _aligned_position(align, world_poses[frame, pose_joint].p)
+ joint_rotation = wp.mul(wp.quat_inverse(align.q), world_poses[frame, pose_joint].q)
+
+ if model_joint > 0:
+ position_offset = (model_joint - 1) * 3
+ centered_position = joint_position - root_position
+ local_poses[0, frame, position_offset] = centered_position[0]
+ local_poses[0, frame, position_offset + 1] = centered_position[1]
+ local_poses[0, frame, position_offset + 2] = centered_position[2]
+
+ rotation_offset = (num_model_joints - 1) * 3 + model_joint * 6
+ x_axis = wp.quat_rotate(joint_rotation, wp.vec3(1.0, 0.0, 0.0))
+ y_axis = wp.quat_rotate(joint_rotation, wp.vec3(0.0, 1.0, 0.0))
+ local_poses[0, frame, rotation_offset] = x_axis[0]
+ local_poses[0, frame, rotation_offset + 1] = x_axis[1]
+ local_poses[0, frame, rotation_offset + 2] = x_axis[2]
+ local_poses[0, frame, rotation_offset + 3] = y_axis[0]
+ local_poses[0, frame, rotation_offset + 4] = y_axis[1]
+ local_poses[0, frame, rotation_offset + 5] = y_axis[2]
+
+
+def decode_motionbricks_output_kernel(
+ num_model_joints: wp.int32,
+ num_pose_joints: wp.int32,
+ parent_indices: wp.array(dtype=wp.int32),
+ pose_to_model: wp.array(dtype=wp.int32),
+ reference_local_poses: wp.array(dtype=wp.transform),
+ alignment: wp.array(dtype=wp.transform),
+ model_to_runtime: wp.transform,
+ pred_global_motions: wp.array3d(dtype=wp.float32),
+ pred_num_tokens: wp.array(dtype=wp.int32),
+ output_local_poses: wp.array2d(dtype=wp.transform),
+ output_foot_contacts: wp.array2d(dtype=wp.float32),
+ output_frame_count: wp.array(dtype=wp.int32),
+):
+ """Decode the predicted motion into local joint transforms and foot contacts.
+
+ It drops the boundary frames and writes the valid frame count. Foot contacts are
+ clamped to 0 to 1. The alignment and model_to_runtime place the root in world space.
+ """
+ frame = wp.tid()
+ # Keep reads inside the prediction buffer. The engine checks the token count.
+ raw_count = wp.clamp(pred_num_tokens[0] * MODEL_POSES_PER_TOKEN, 0, pred_global_motions.shape[1])
+ frame_count = wp.max(0, raw_count - 2 * MODEL_BOUNDARY_FRAMES)
+ if frame == 0:
+ output_frame_count[0] = frame_count
+ if frame >= frame_count:
+ return
+
+ raw_frame = MODEL_BOUNDARY_FRAMES + frame
+ first_contact = pred_global_motions.shape[2] - FOOT_CONTACT_COUNT
+ for contact in range(FOOT_CONTACT_COUNT):
+ output_foot_contacts[frame, contact] = wp.clamp(
+ pred_global_motions[0, raw_frame, first_contact + contact], 0.0, 1.0,
+ )
+
+ # Layout: global root [5], child joint positions [3*(J-1)], global 6D
+ # rotations [6*J], local velocities [3*J], and foot contacts [4].
+ # Reconstruction uses the root position and global rotations.
+ position_offset = 5
+ rotation_offset = position_offset + (num_model_joints - 1) * 3
+
+ hips_position = wp.vec3(
+ pred_global_motions[0, raw_frame, 0],
+ pred_global_motions[0, raw_frame, 1],
+ pred_global_motions[0, raw_frame, 2],
+ )
+ hips_rotation = _read_rotation(pred_global_motions, raw_frame, rotation_offset)
+ # This also restores the ground offset removed when encoding the context and target poses.
+ hips_transform = wp.mul(
+ alignment[0],
+ wp.transform(hips_position, hips_rotation),
+ )
+
+ output_local_poses[frame, 0] = wp.mul(model_to_runtime, hips_transform)
+
+ for joint in range(1, num_pose_joints):
+ model_joint = pose_to_model[joint]
+ if model_joint < 0:
+ output_local_poses[frame, joint] = reference_local_poses[joint]
+ continue
+
+ predicted_rotation = _read_rotation(
+ pred_global_motions,
+ raw_frame,
+ rotation_offset + model_joint * 6,
+ )
+ parent_model_joint = pose_to_model[parent_indices[joint]]
+ parent_rotation = _read_rotation(
+ pred_global_motions,
+ raw_frame,
+ rotation_offset + parent_model_joint * 6,
+ )
+ # The common alignment cancels in parent-to-child space.
+ local_rotation = wp.mul(wp.quat_inverse(parent_rotation), predicted_rotation)
+ output_local_poses[frame, joint] = wp.transform(
+ reference_local_poses[joint].p,
+ wp.normalize(local_rotation),
+ )
+
+
+def compute_endpoint_deltas_kernel(
+ output_frame_count: wp.array(dtype=wp.int32),
+ context_poses: wp.array2d(dtype=wp.transform),
+ target_poses: wp.array2d(dtype=wp.transform),
+ output_local_poses: wp.array2d(dtype=wp.transform),
+ start_deltas: wp.array(dtype=wp.transform),
+ end_deltas: wp.array(dtype=wp.transform),
+):
+ """Compute the endpoint correction of each joint.
+
+ Start deltas move the first generated pose to the last context pose. End deltas move
+ the last generated pose to the first target pose. The root moves in world space, so
+ its deltas come from pose_utils.compute_root_endpoint_delta().
+ """
+ joint = wp.tid()
+ frame_count = output_frame_count[0]
+ if frame_count < 2:
+ return
+ last_frame = frame_count - 1
+ last_context_pose = context_poses.shape[0] - 1
+ if joint == 0:
+ start_deltas[0] = pose_utils.compute_root_endpoint_delta(
+ output_local_poses[0, 0], context_poses[last_context_pose, 0],
+ )
+ end_deltas[0] = pose_utils.compute_root_endpoint_delta(
+ output_local_poses[last_frame, 0], target_poses[0, 0],
+ )
+ return
+
+ start_deltas[joint] = pose_utils.compute_delta_transform(
+ output_local_poses[0, joint],
+ context_poses[last_context_pose, joint],
+ )
+ end_deltas[joint] = pose_utils.compute_delta_transform(
+ output_local_poses[last_frame, joint],
+ target_poses[0, joint],
+ )
+
+
+def apply_endpoint_deltas_kernel(
+ output_frame_count: wp.array(dtype=wp.int32),
+ start_deltas: wp.array(dtype=wp.transform),
+ end_deltas: wp.array(dtype=wp.transform),
+ output_local_poses: wp.array2d(dtype=wp.transform),
+):
+ """Apply the endpoint correction across the generated motion in place.
+
+ The start correction fades out over the motion as the end correction fades in.
+ """
+ frame, joint = wp.tid()
+ frame_count = output_frame_count[0]
+ if frame_count < 2 or frame >= frame_count:
+ return
+
+ end_weight = wp.float32(frame) / wp.float32(frame_count - 1)
+ start_weight = 1.0 - end_weight
+ if joint == 0:
+ output_local_poses[frame, 0] = pose_utils.apply_root_endpoint_correction(
+ output_local_poses[frame, 0], start_deltas[0], end_deltas[0], end_weight,
+ )
+ return
+
+ corrected_pose = pose_utils.apply_delta_transform(
+ output_local_poses[frame, joint],
+ start_deltas[joint],
+ start_weight,
+ )
+ output_local_poses[frame, joint] = pose_utils.apply_delta_transform(
+ corrected_pose,
+ end_deltas[joint],
+ end_weight,
+ )
diff --git a/motionbricks/model/unitree_g1/__init__.py b/motionbricks/model/unitree_g1/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/motionbricks/model/unitree_g1/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/motionbricks/model/unitree_g1/buffers.py b/motionbricks/model/unitree_g1/buffers.py
new file mode 100644
index 0000000..8ac2248
--- /dev/null
+++ b/motionbricks/model/unitree_g1/buffers.py
@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Context and target tokens for the Unitree G1 model."""
+
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE
+from motionbricks.model.generation import write_token_poses
+from motionbricks.runtime.motion_recorder import MotionRecorder
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT, read_root_transform, write_root_transform
+from motionbricks.utils.pose_utils import blend_transform
+from motionbricks.utils.time_utils import history_sample_indices
+
+
+def _sample_dof_recorder_kernel(
+ joint_q: wp.array2d(dtype=wp.float32),
+ lower_frames: wp.vec4i,
+ upper_frames: wp.vec4i,
+ blends: wp.vec4,
+ output: wp.array2d(dtype=wp.float32),
+):
+ frame, coordinate = wp.tid()
+ lower, upper, blend = lower_frames[frame], upper_frames[frame], blends[frame]
+ if coordinate == 0:
+ root = blend_transform(read_root_transform(joint_q, lower), read_root_transform(joint_q, upper), blend)
+ write_root_transform(root, output, frame)
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ output[frame, coordinate] = wp.lerp(joint_q[lower, coordinate], joint_q[upper, coordinate], blend)
+
+
+class DOFToken:
+ """Hold up to four poses for model context or a target.
+
+ poses holds the joint coordinates of all four poses, laid out as [pose, coordinate].
+ Each pose holds the root position (XYZ, meters), its rotation (XYZW quaternion), and
+ the joint angles (radians). num_poses counts the supplied poses. Padding repeats the
+ last pose in the unused space.
+ """
+
+ def __init__(self, num_dofs: int, *, device=None) -> None:
+ """Allocate room for four poses.
+
+ Args:
+ num_dofs: Number of joint angles per pose, 29 for G1. It must be positive.
+ device: Device for new arrays. None uses the current device.
+ """
+ if num_dofs <= 0:
+ raise ValueError("num_dofs must be positive.")
+ self.num_dofs = num_dofs
+ self.num_coordinates = ROOT_COORDINATE_COUNT + self.num_dofs
+ self.poses = wp.empty(
+ (MODEL_POSES_PER_TOKEN, self.num_coordinates), dtype=wp.float32, device=device,
+ )
+ self._num_poses = 0
+
+ @property
+ def num_poses(self) -> int:
+ """Number of supplied poses, from 1 to 4, or 0 before the first update."""
+ return self._num_poses
+
+ def update_from_poses(
+ self,
+ joint_q: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Copy one to four poses and pad the unused space with the last pose.
+
+ The poses are in time order at the model's sample rate of 30 Hz. A context
+ token ends at the current pose. A target token starts at the pose to reach.
+
+ Args:
+ joint_q: Joint coordinates of one to four poses, as a float32 array of
+ [pose, coordinate] or [coordinate].
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._num_poses = write_token_poses(joint_q, self.poses, stream)
+
+ def update_from_recorder(self, motion_history: MotionRecorder, stream: wp.Stream | None = None) -> None:
+ """Sample four poses at 30 Hz, ending at the latest recorded pose.
+
+ Args:
+ motion_history: Recorder of played poses, with the token's coordinate
+ count.
+ stream: Stream for the work. None uses the current stream.
+ """
+ if motion_history.poses.shape[1] != self.num_coordinates:
+ raise ValueError("History and token coordinate counts do not match.")
+ lower, upper, blends = history_sample_indices(
+ motion_history.delta_times, MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE,
+ )
+ wp.launch(
+ _sample_dof_recorder_kernel,
+ dim=self.poses.shape,
+ inputs=[motion_history.poses, wp.vec4i(*lower), wp.vec4i(*upper), wp.vec4(*blends)],
+ outputs=[self.poses],
+ device=self.poses.device,
+ stream=stream,
+ )
+ self._num_poses = MODEL_POSES_PER_TOKEN
diff --git a/motionbricks/model/unitree_g1/contract.py b/motionbricks/model/unitree_g1/contract.py
new file mode 100644
index 0000000..cc7d00b
--- /dev/null
+++ b/motionbricks/model/unitree_g1/contract.py
@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""The Unitree G1 model's contract, ONNX paths, and foot contact points.
+
+The contract comes from the model's manifest and describes a batch size of one.
+"""
+
+from pathlib import Path
+
+from ..contract import load_model_manifest
+
+
+UNITREE_G1_N1_MANIFEST_PATH = (
+ Path(__file__).resolve().parents[2] / "assets/onnx/unitree_g1/unitree_g1_n1.json"
+)
+UNITREE_G1_N1_CONTRACT, UNITREE_G1_N1_FP32_ONNX_PATH, UNITREE_G1_N1_FP16_ONNX_PATH = load_model_manifest(
+ UNITREE_G1_N1_MANIFEST_PATH,
+)
+UNITREE_G1_N1_FOOT_CONTACT_BODIES = ("left_ankle_roll_link",) * 2 + ("right_ankle_roll_link",) * 2
+UNITREE_G1_N1_FOOT_CONTACT_OFFSETS = ((0.0, 0.0, 0.0), (0.14, 0.0, -0.035)) * 2
diff --git a/motionbricks/model/unitree_g1/engine.py b/motionbricks/model/unitree_g1/engine.py
new file mode 100644
index 0000000..f0d9651
--- /dev/null
+++ b/motionbricks/model/unitree_g1/engine.py
@@ -0,0 +1,139 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generate Unitree G1 motion with TensorRT."""
+
+from __future__ import annotations
+
+import warp as wp
+
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT
+
+from ..config import MotionBricksInferenceConfig
+from ..contract import MODEL_MAX_VALID_FRAMES, MODEL_POSES_PER_TOKEN, MODEL_SAMPLE_RATE
+from ..engine import MotionBricksEngine
+from ..generation import check_generation_buffers, write_conditions
+from . import kernels
+from .buffers import DOFToken
+from .contract import UNITREE_G1_N1_CONTRACT
+
+
+class MotionBricksUnitreeG1Engine(MotionBricksEngine):
+ """Generate G1 motion from recent motion and target poses.
+
+ Each pose contains 36 joint coordinates: root position, an XYZW quaternion,
+ and 29 joint angles. The root joint is the pelvis. Positions are in meters.
+ Joint angles are in radians. TF32 stays off unless the build options enable it,
+ because it moves joint angles by several degrees for under 2 percent faster
+ inference.
+ """
+
+ contract = UNITREE_G1_N1_CONTRACT
+ default_enable_tf32 = False
+
+ def _initialize_pose_layout(self) -> None:
+ self._root_position_filter = wp.array(kernels.ROOT_POSITION_FILTER, dtype=wp.float32, device=self.device)
+ self._num_coordinates = ROOT_COORDINATE_COUNT + len(self.contract.joint_names)
+ # Row 0 corrects toward the last context pose, and row 1 toward the first target pose.
+ self._endpoint_deltas = wp.empty((2, self._num_coordinates), dtype=wp.float32, device=self.device)
+
+ def create_input(self) -> DOFToken:
+ """Create a context or target token with room for four poses."""
+ self._ensure_open()
+ return DOFToken(len(self.contract.joint_names), device=self.device)
+
+ def create_output(self) -> DOFAnimationBuffer:
+ """Create an empty animation buffer with room for the longest generated motion."""
+ self._ensure_open()
+ return DOFAnimationBuffer(
+ self.contract.joint_names,
+ MODEL_SAMPLE_RATE,
+ wp.empty((MODEL_MAX_VALID_FRAMES, self._num_coordinates), dtype=wp.float32, device=self.device),
+ num_frames=0,
+ foot_contacts=wp.zeros((MODEL_MAX_VALID_FRAMES, FOOT_CONTACT_COUNT), dtype=wp.float32, device=self.device),
+ )
+
+ def _prepare_generation(
+ self,
+ context: DOFToken,
+ target: DOFToken,
+ output: DOFAnimationBuffer,
+ ) -> None:
+ num_dofs = len(self.contract.joint_names)
+ for name, token in (("Context", context), ("Target", target)):
+ if token.num_dofs != num_dofs:
+ raise ValueError(f"{name} token must contain {num_dofs} joint angles per pose.")
+ if output.num_dofs != num_dofs:
+ raise ValueError(f"Output must contain {num_dofs} joint angles per frame.")
+ check_generation_buffers(context, target, output)
+
+ def _encode_guide_poses(
+ self,
+ context: DOFToken,
+ target: DOFToken,
+ config: MotionBricksInferenceConfig,
+ ) -> None:
+ wp.launch(
+ kernels.compute_guide_alignment_kernel,
+ dim=1,
+ inputs=[wp.vec2(*config.heading_alignment), self._runtime_to_model, context.poses],
+ outputs=[self._alignment],
+ stream=self.stream,
+ )
+ for token, tensor_name in ((context, "context_qpos"), (target, "target_qpos")):
+ wp.launch(
+ kernels.encode_motionbricks_inputs_kernel,
+ dim=MODEL_POSES_PER_TOKEN,
+ inputs=[self._runtime_to_model, token.poses, self._alignment],
+ outputs=[self.device_tensor(tensor_name)[0]],
+ stream=self.stream,
+ )
+ write_conditions(self, target.num_poses, config)
+
+ def _decode_generated_poses(self, output: DOFAnimationBuffer) -> None:
+ wp.launch(
+ kernels.decode_motionbricks_output_kernel,
+ dim=MODEL_MAX_VALID_FRAMES,
+ inputs=[
+ self._alignment,
+ self._model_to_runtime,
+ self.device_tensor("pred_qpos")[0],
+ self.device_tensor("pred_foot_contacts")[0],
+ self.device_tensor("pred_num_tokens"),
+ self._root_position_filter,
+ ],
+ outputs=[output.poses, output.foot_contacts, self._generated_frame_count],
+ stream=self.stream,
+ )
+
+ def _post_process_generated_poses(
+ self,
+ context: DOFToken,
+ target: DOFToken,
+ output: DOFAnimationBuffer,
+ ) -> None:
+ """Match the generated motion's endpoints to the last context pose and first target pose.
+
+ Root corrections span the generated motion. Joint angle corrections fade over
+ JOINT_ANGLE_FADE_SECONDS at each end with a quadratic ease in and out.
+ """
+ wp.launch(
+ kernels.compute_endpoint_deltas_kernel,
+ dim=2,
+ inputs=[self._generated_frame_count, context.poses, target.poses, output.poses],
+ outputs=[self._endpoint_deltas],
+ stream=self.stream,
+ )
+ wp.launch(
+ kernels.apply_endpoint_deltas_kernel,
+ dim=MODEL_MAX_VALID_FRAMES,
+ inputs=[
+ self._generated_frame_count,
+ self._endpoint_deltas,
+ kernels.JOINT_ANGLE_FADE_SECONDS * MODEL_SAMPLE_RATE,
+ ],
+ outputs=[output.poses],
+ stream=self.stream,
+ )
diff --git a/motionbricks/model/unitree_g1/kernels.py b/motionbricks/model/unitree_g1/kernels.py
new file mode 100644
index 0000000..2ca92c8
--- /dev/null
+++ b/motionbricks/model/unitree_g1/kernels.py
@@ -0,0 +1,169 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Root alignment, decoding, and endpoint correction of G1 joint coordinates."""
+
+import warp as wp
+
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.model.contract import MODEL_BOUNDARY_FRAMES, MODEL_POSES_PER_TOKEN
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT, read_root_transform, write_root_transform
+from motionbricks.utils.math_utils import quadratic_fade_weight
+from motionbricks.utils.pose_utils import apply_root_endpoint_correction, compute_root_endpoint_delta
+
+# Filter taps for the root position at a sample rate of 30 Hz. They keep the gait below 4 Hz
+# and remove frame to frame jitter above 8 Hz.
+ROOT_POSITION_FILTER = (-0.0465, 0.0639, 0.2827, 0.3998, 0.2827, 0.0639, -0.0465)
+
+# Endpoint correction of the joint angles fades in and out over this time at each end.
+JOINT_ANGLE_FADE_SECONDS = 0.3
+
+
+def compute_guide_alignment_kernel(
+ desired_heading: wp.vec2,
+ runtime_to_model: wp.transform,
+ context_joint_q: wp.array2d(dtype=wp.float32),
+ alignment: wp.array(dtype=wp.transform),
+):
+ """Compute the heading alignment of the last context pose to desired_heading.
+
+ runtime_to_model brings the root into G1 model space first. The result maps
+ aligned poses back to G1 model space and keeps the root height.
+ """
+ root = wp.mul(runtime_to_model, read_root_transform(context_joint_q, MODEL_POSES_PER_TOKEN - 1))
+ forward = wp.transform_vector(root, wp.vec3(1.0, 0.0, 0.0))
+ current_angle = wp.atan2(forward[1], forward[0])
+ desired_angle = wp.atan2(desired_heading[1], desired_heading[0])
+ alignment[0] = wp.transform(
+ wp.vec3(root.p[0], root.p[1], 0.0),
+ wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), current_angle - desired_angle),
+ )
+
+
+def encode_motionbricks_inputs_kernel(
+ runtime_to_model: wp.transform,
+ joint_q: wp.array2d(dtype=wp.float32),
+ alignment: wp.array(dtype=wp.transform),
+ qpos: wp.array2d(dtype=wp.float32),
+):
+ """Encode a token's joint coordinates relative to the alignment into context_qpos or target_qpos.
+
+ runtime_to_model brings each root into G1 model space first. The root height and
+ the joint angles stay unchanged.
+ """
+ frame = wp.tid()
+ align = alignment[0]
+ root = wp.mul(runtime_to_model, read_root_transform(joint_q, frame))
+ # Subtract before rotating to retain precision far from the world origin.
+ position = wp.quat_rotate_inv(align.q, root.p - align.p)
+ rotation = wp.mul(wp.quat_inverse(align.q), root.q)
+ write_root_transform(wp.transform(wp.vec3(position[0], position[1], root.p[2]), rotation), qpos, frame)
+ for index in range(ROOT_COORDINATE_COUNT, joint_q.shape[1]):
+ qpos[frame, index] = joint_q[frame, index]
+
+
+def decode_motionbricks_output_kernel(
+ alignment: wp.array(dtype=wp.transform),
+ model_to_runtime: wp.transform,
+ pred_qpos: wp.array2d(dtype=wp.float32),
+ pred_foot_contacts: wp.array2d(dtype=wp.float32),
+ pred_num_tokens: wp.array(dtype=wp.int32),
+ root_position_filter: wp.array(dtype=wp.float32),
+ output_joint_q: wp.array2d(dtype=wp.float32),
+ output_foot_contacts: wp.array2d(dtype=wp.float32),
+ output_frame_count: wp.array(dtype=wp.int32),
+):
+ """Decode the predicted joint coordinates and foot contacts into world space.
+
+ It drops the boundary frames and writes the valid frame count. The root position is
+ filtered over neighboring frames. Foot contacts are clamped to 0 to 1. The alignment
+ and model_to_runtime place the root in world space.
+ """
+ frame = wp.tid()
+ # Keep reads inside the prediction buffer. The engine checks the token count.
+ raw_count = wp.clamp(pred_num_tokens[0] * MODEL_POSES_PER_TOKEN, 0, pred_qpos.shape[0])
+ frame_count = wp.max(0, raw_count - 2 * MODEL_BOUNDARY_FRAMES)
+ if frame == 0:
+ output_frame_count[0] = frame_count
+ if frame >= frame_count:
+ return
+ raw_frame = frame + MODEL_BOUNDARY_FRAMES
+ for contact in range(FOOT_CONTACT_COUNT):
+ output_foot_contacts[frame, contact] = wp.clamp(pred_foot_contacts[raw_frame, contact], 0.0, 1.0)
+ # Boundary frames provide the neighbors at each end.
+ radius = root_position_filter.shape[0] // 2
+ position = wp.vec3(0.0, 0.0, 0.0)
+ for tap in range(root_position_filter.shape[0]):
+ source = wp.clamp(raw_frame + tap - radius, 0, raw_count - 1)
+ position += root_position_filter[tap] * read_root_transform(pred_qpos, source).p
+ root = wp.mul(alignment[0], wp.transform(position, read_root_transform(pred_qpos, raw_frame).q))
+ root = wp.mul(model_to_runtime, wp.transform(wp.vec3(root.p[0], root.p[1], position[2]), root.q))
+ write_root_transform(root, output_joint_q, frame)
+ for index in range(ROOT_COORDINATE_COUNT, output_joint_q.shape[1]):
+ output_joint_q[frame, index] = pred_qpos[raw_frame, index]
+
+
+def compute_endpoint_deltas_kernel(
+ output_frame_count: wp.array(dtype=wp.int32),
+ context_joint_q: wp.array2d(dtype=wp.float32),
+ target_joint_q: wp.array2d(dtype=wp.float32),
+ output_joint_q: wp.array2d(dtype=wp.float32),
+ deltas: wp.array2d(dtype=wp.float32),
+):
+ """Compute the endpoint correction for the first and last generated frames.
+
+ Row 0 corrects toward the last context pose. Row 1 corrects toward the first target
+ pose. Each row holds the root delta in the root coordinates, then one offset per
+ joint angle.
+ """
+ endpoint = wp.tid()
+ frame_count = output_frame_count[0]
+ if frame_count < 2:
+ return
+ frame = wp.where(endpoint == 0, 0, frame_count - 1)
+ last_context_pose = context_joint_q.shape[0] - 1
+ guide_root = read_root_transform(target_joint_q, 0)
+ if endpoint == 0:
+ guide_root = read_root_transform(context_joint_q, last_context_pose)
+ root_delta = compute_root_endpoint_delta(read_root_transform(output_joint_q, frame), guide_root)
+ write_root_transform(root_delta, deltas, endpoint)
+ for index in range(ROOT_COORDINATE_COUNT, output_joint_q.shape[1]):
+ guide = target_joint_q[0, index]
+ if endpoint == 0:
+ guide = context_joint_q[last_context_pose, index]
+ # Joint angle differences are scalar offsets, without wrapping at plus or minus pi.
+ deltas[endpoint, index] = guide - output_joint_q[frame, index]
+
+
+def apply_endpoint_deltas_kernel(
+ output_frame_count: wp.array(dtype=wp.int32),
+ deltas: wp.array2d(dtype=wp.float32),
+ joint_angle_fade_frames: wp.float32,
+ output_joint_q: wp.array2d(dtype=wp.float32),
+):
+ """Apply the endpoint correction across the generated motion in place.
+
+ Root corrections span the motion. Joint angle corrections fade over
+ joint_angle_fade_frames at each end.
+ """
+ frame = wp.tid()
+ frame_count = output_frame_count[0]
+ if frame_count < 2 or frame >= frame_count:
+ return
+ end_weight = wp.float32(frame) / wp.float32(frame_count - 1)
+ root = apply_root_endpoint_correction(
+ read_root_transform(output_joint_q, frame), read_root_transform(deltas, 0), read_root_transform(deltas, 1),
+ end_weight,
+ )
+ write_root_transform(root, output_joint_q, frame)
+ # Cap the fade so the start and end correction windows do not overlap.
+ fade_frames = wp.min(joint_angle_fade_frames, 0.5 * wp.float32(frame_count - 1))
+ angle_start_weight = quadratic_fade_weight(wp.float32(frame) / fade_frames)
+ angle_end_weight = quadratic_fade_weight(wp.float32(frame_count - 1 - frame) / fade_frames)
+ for index in range(ROOT_COORDINATE_COUNT, output_joint_q.shape[1]):
+ output_joint_q[frame, index] += deltas[0, index] * angle_start_weight + deltas[1, index] * angle_end_weight
diff --git a/motionbricks/renderers/__init__.py b/motionbricks/renderers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/motionbricks/renderers/base_renderer.py b/motionbricks/renderers/base_renderer.py
new file mode 100644
index 0000000..ec2a194
--- /dev/null
+++ b/motionbricks/renderers/base_renderer.py
@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Track which Newton viewer primitives a renderer shows or hides."""
+
+from collections.abc import Callable, MutableMapping
+from typing import Protocol
+
+
+class _ViewerPrimitive(Protocol):
+ def destroy(self) -> None: ...
+
+
+class BaseRenderer:
+ """Track which named Newton viewer primitives are shown or hidden.
+
+ Each renderer supplies the geometry its Newton log function expects. This
+ class logs shown and hidden states the same way for every renderer. Hiding a
+ primitive that is already hidden logs nothing.
+ """
+
+ def __init__(self) -> None:
+ self._registered_names: set[str] = set()
+ self._hidden_names: set[str] = set()
+
+ def _log_visible(
+ self,
+ log: Callable[..., object],
+ name: str,
+ *args: object,
+ **kwargs: object,
+ ) -> None:
+ """Log a visible primitive and remember its current state."""
+ log(name, *args, hidden=False, **kwargs)
+ self._registered_names.add(name)
+ self._hidden_names.discard(name)
+
+ def _log_hidden_once(
+ self,
+ log: Callable[..., object],
+ name: str,
+ *args: object,
+ **kwargs: object,
+ ) -> None:
+ """Hide a registered primitive, logging it only once until it is shown again."""
+ if name not in self._registered_names or name in self._hidden_names:
+ return
+
+ log(name, *args, hidden=True, **kwargs)
+ self._hidden_names.add(name)
+
+ def _clear(self, primitives: MutableMapping[str, _ViewerPrimitive]) -> None:
+ """Destroy and remove every viewer primitive owned by this renderer."""
+ for name in self._registered_names:
+ primitive = primitives.pop(name, None)
+ if primitive is None:
+ continue
+
+ primitive.destroy()
+
+ self._registered_names.clear()
+ self._hidden_names.clear()
diff --git a/motionbricks/renderers/dof_mesh_renderer.py b/motionbricks/renderers/dof_mesh_renderer.py
new file mode 100644
index 0000000..706d490
--- /dev/null
+++ b/motionbricks/renderers/dof_mesh_renderer.py
@@ -0,0 +1,188 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw and pick a robot mesh using its joint coordinates."""
+
+import newton
+import numpy as np
+import warp as wp
+from newton import GeoType
+from newton._src.geometry.raycast import map_ray_to_local, ray_intersect_mesh, ray_intersect_shape
+from newton._src.viewer.gl.opengl import update_vbo_transforms
+from newton._src.viewer.kernels import update_shape_xforms
+
+from motionbricks.renderers.base_renderer import BaseRenderer
+
+
+def _raycast_shapes(
+ shapes: wp.array(dtype=int),
+ transforms: wp.array(dtype=wp.transform),
+ types: wp.array(dtype=int),
+ scales: wp.array(dtype=wp.vec3),
+ meshes: wp.array(dtype=wp.uint64),
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float,
+ distances: wp.array(dtype=float),
+):
+ index = wp.tid()
+ shape = shapes[index]
+ if types[shape] == GeoType.MESH or types[shape] == GeoType.CONVEX_MESH:
+ local_origin, local_direction = map_ray_to_local(transforms[shape], origin, direction, scales[shape])
+ distance, normal, u, v, face = ray_intersect_mesh(
+ local_origin, local_direction, scales[shape], meshes[shape], False, max_distance,
+ )
+ else:
+ distance, normal = ray_intersect_shape(
+ transforms[shape], scales[shape], types[shape], origin, direction, False,
+ )
+ distances[index] = wp.where(distance >= 0.0, wp.min(distance, max_distance), max_distance)
+
+
+class DOFMeshRenderer(BaseRenderer):
+ """Draw a Newton model's visible shapes using its joint coordinates.
+
+ Geometry is uploaded once. All pose instances share it. FK and picking
+ use scratch buffers, so the Newton model's joint coordinates and playback state
+ stay unchanged.
+ """
+
+ def __init__(self, model: newton.Model) -> None:
+ """Collect the model's visible shapes and allocate scratch buffers.
+
+ Args:
+ model: Newton model to draw.
+ """
+ super().__init__()
+ self.model = model
+ self.state = model.state()
+ self.shapes = np.flatnonzero(model.shape_flags.numpy() & int(newton.ShapeFlags.VISIBLE)).tolist()
+ self.shape_indices = wp.array(self.shapes, dtype=int, device=model.device)
+ self.world_transforms = wp.empty_like(model.shape_transform)
+ self.distances = wp.empty(len(self.shapes), dtype=float, device=model.device)
+ # GL uploads colors and materials from the host, so these constants need no GPU round trip.
+ self.color = wp.empty(1, dtype=wp.vec3, device="cpu")
+ self.shape_colors = wp.array(model.shape_color.numpy(), dtype=wp.vec3, device="cpu")
+ self.material = wp.array([wp.vec4(0.5, 0.0, 0.0, 0.0)], dtype=wp.vec4, device="cpu")
+ self.vbo_transforms = wp.empty(model.shape_count, dtype=wp.mat44, device=model.device)
+ types, scales = model.shape_type.numpy(), model.shape_scale.numpy().copy()
+ margins, solids = model.shape_margin.numpy(), model.shape_is_solid.numpy()
+ self.geometry = {
+ shape: dict(
+ geo_type=int(types[shape]), geo_scale=tuple(float(v) for v in scales[shape]),
+ geo_thickness=float(margins[shape]), geo_is_solid=bool(solids[shape]),
+ geo_src=model.shape_source[shape],
+ )
+ for shape in self.shapes
+ }
+ # log_geo bakes primitive sizes into the geometry, and mesh scales belong to the instances.
+ scales[~np.isin(types, [GeoType.MESH, GeoType.CONVEX_MESH])] = 1.0
+ self.scales = wp.array(scales, dtype=wp.vec3, device=model.device)
+ self._geometry_loaded = False
+
+ @staticmethod
+ def _name(instance_id: int | str, shape: int) -> str:
+ return f"/dof_mesh_{instance_id}_{shape}"
+
+ def _place_shapes(self, joint_q: wp.array, xform: wp.transform) -> None:
+ if joint_q.dtype != wp.float32 or joint_q.shape != (self.model.joint_coord_count,):
+ raise ValueError("joint_q must contain one pose with all of the Newton model's joint coordinates.")
+ newton.eval_fk(self.model, joint_q, self.model.joint_qd, self.state)
+ wp.launch(
+ update_shape_xforms, dim=self.model.shape_count,
+ inputs=[self.model.shape_transform, self.model.shape_body, self.state.body_q,
+ self.model.shape_world, None, xform],
+ outputs=[self.world_transforms], device=self.model.device,
+ )
+
+ def draw_pose(
+ self, viewer, joint_q: wp.array, xform: wp.transform, color: wp.vec3 | None, instance_id: int | str,
+ ) -> None:
+ """Draw one pose of the model.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ joint_q: Joint coordinates of the pose, with all of the model's coordinates.
+ xform: World transform applied to the pose.
+ color: RGB color of every shape. None uses each shape's own color.
+ instance_id: Identifier of the drawn instance. Drawing the same identifier
+ again updates it.
+ """
+ if not self._geometry_loaded:
+ for shape, geometry in self.geometry.items():
+ viewer.log_geo(f"/dof_geometry_{shape}", **geometry, hidden=True)
+ self._geometry_loaded = True
+ self._place_shapes(joint_q, xform)
+ # Pack every part together, matching Newton's batched model-rendering path.
+ # A single host copy avoids a separate GPU synchronization for each part.
+ wp.launch(
+ update_vbo_transforms, dim=self.model.shape_count,
+ inputs=[self.world_transforms, self.scales], outputs=[self.vbo_transforms],
+ device=self.model.device,
+ )
+ transforms = self.vbo_transforms.numpy()
+ if color is not None:
+ self.color.fill_(color)
+ for shape in self.shapes:
+ colors = self.color if color is not None else self.shape_colors[shape:shape + 1]
+ name = self._name(instance_id, shape)
+ if name not in self._registered_names:
+ self._log_visible(
+ viewer.log_instances, name, f"/dof_geometry_{shape}",
+ self.world_transforms[shape:shape + 1], self.scales[shape:shape + 1],
+ colors, self.material,
+ )
+ else:
+ # A viewer layer keeps its objects under the layer's name prefix.
+ instance = viewer.objects[viewer.layer.name_prefix + name]
+ instance.update_from_pinned(transforms[shape:shape + 1], 1, colors, self.material)
+ instance.hidden = False
+ self._hidden_names.discard(name)
+
+ def raycast_pose(
+ self, joint_q: wp.array, xform: wp.transform, origin: wp.vec3,
+ direction: wp.vec3, max_distance: float = 1.0e6,
+ ) -> float:
+ """Return the distance to the nearest visible shape along a ray.
+
+ Args:
+ joint_q: Joint coordinates of the pose, with all of the model's coordinates.
+ xform: World transform applied to the pose.
+ origin: Ray origin in world space.
+ direction: Unit ray direction in world space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ if not self.shapes:
+ return max_distance
+ self._place_shapes(joint_q, xform)
+ wp.launch(
+ _raycast_shapes, dim=len(self.shapes),
+ inputs=[self.shape_indices, self.world_transforms, self.model.shape_type,
+ self.model.shape_scale, self.model.shape_source_ptr, origin, direction, max_distance],
+ outputs=[self.distances], device=self.model.device,
+ )
+ return float(self.distances.numpy().min())
+
+ def hide(self, viewer, instance_id: int | str) -> None:
+ """Hide one drawn instance, keeping its data for the next draw.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ instance_id: Identifier of the instance to hide.
+ """
+ for shape in self.shapes:
+ self._log_hidden_once(
+ viewer.log_instances, self._name(instance_id, shape), f"/dof_geometry_{shape}",
+ None, None, None, None,
+ )
+
+ def clear(self, viewer) -> None:
+ """Remove every drawn instance from the viewer.
+
+ The shared geometry stays loaded, so drawing again does not upload it.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._clear(viewer.objects)
diff --git a/motionbricks/renderers/foot_contact_renderer.py b/motionbricks/renderers/foot_contact_renderer.py
new file mode 100644
index 0000000..8d28f67
--- /dev/null
+++ b/motionbricks/renderers/foot_contact_renderer.py
@@ -0,0 +1,322 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Outline the heels and toes in the Newton viewer where the model predicts foot contact."""
+
+from collections.abc import Sequence
+from typing import NamedTuple
+
+import newton
+from newton import GeoType
+import numpy as np
+from scipy.spatial import ConvexHull
+import warp as wp
+
+from motionbricks.animation.foot_contacts import FOOT_CONTACT_COUNT
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.renderers.base_renderer import BaseRenderer
+from motionbricks.utils.pose_utils import compute_world_poses
+
+_OUTLINE_LIFT = 0.004
+_FLOOR_CLEARANCE = 0.003
+
+
+class ContactOutline(NamedTuple):
+ """A closed loop of points that shows one foot contact.
+
+ The points move with one of the transforms passed to draw(). The transform
+ field picks which one.
+ """
+
+ contact: int
+ transform: int
+ points: np.ndarray
+
+
+def _update_outlines_kernel(
+ transforms: wp.array(dtype=wp.transform),
+ contacts: wp.array(dtype=wp.float32),
+ threshold: wp.float32,
+ segment_transforms: wp.array(dtype=wp.int32),
+ segment_contacts: wp.array(dtype=wp.int32),
+ local_starts: wp.array(dtype=wp.vec3),
+ local_ends: wp.array(dtype=wp.vec3),
+ floor: wp.float32,
+ starts: wp.array(dtype=wp.vec3),
+ ends: wp.array(dtype=wp.vec3),
+ colors: wp.array(dtype=wp.vec3),
+):
+ segment = wp.tid()
+ contact = wp.clamp(contacts[segment_contacts[segment]], 0.0, 1.0)
+ transform = transforms[segment_transforms[segment]]
+ start = wp.transform_point(transform, local_starts[segment])
+ end = wp.transform_point(transform, local_ends[segment])
+ start = wp.vec3(start[0], start[1], wp.max(start[2], floor))
+ end = wp.vec3(end[0], end[1], wp.max(end[2], floor))
+ starts[segment] = start
+ # A segment of zero length draws nothing.
+ ends[segment] = wp.where(contact > wp.clamp(threshold, 0.0, 1.0), end, start)
+ colors[segment] = wp.vec3(1.0, 1.0 - contact, 0.0)
+
+
+class FootContactRenderer(BaseRenderer):
+ """Draw outlines for foot contacts above the threshold.
+
+ See motionbricks.animation.foot_contacts for the foot contact order and values.
+ Colors blend from yellow at 0 to red at 1. A foot contact of 0 never shows.
+ Outlines stay just above the floor at height 0.
+ """
+
+ DEFAULT_THRESHOLD = 0.5
+
+ def __init__(self, name: str, outlines: Sequence[ContactOutline], *, device=None) -> None:
+ """Upload the outline points.
+
+ The threshold attribute starts at DEFAULT_THRESHOLD.
+
+ Args:
+ name: Viewer name of the outline lines.
+ outlines: Outlines from skeletal_mesh_sole_outlines() or
+ body_sole_outlines().
+ device: Device of the drawn poses, where the outlines and lines also live.
+ None uses the current device.
+ """
+ super().__init__()
+ if not outlines or any(not 0 <= outline.contact < FOOT_CONTACT_COUNT for outline in outlines):
+ raise ValueError(f"outlines must be non-empty, with foot contacts in [0, {FOOT_CONTACT_COUNT}).")
+ repeat = [len(outline.points) for outline in outlines]
+ self._name = f"/{name}"
+ self._device = wp.get_device(device)
+ self.threshold = self.DEFAULT_THRESHOLD
+ self._inputs = [
+ wp.array(np.repeat([outline.transform for outline in outlines], repeat), dtype=wp.int32, device=device),
+ wp.array(np.repeat([outline.contact for outline in outlines], repeat), dtype=wp.int32, device=device),
+ wp.array(np.concatenate([outline.points for outline in outlines]), dtype=wp.vec3, device=device),
+ wp.array(
+ np.concatenate([np.roll(outline.points, -1, axis=0) for outline in outlines]),
+ dtype=wp.vec3, device=device,
+ ),
+ _FLOOR_CLEARANCE,
+ ]
+ self._lines = tuple(wp.empty(sum(repeat), dtype=wp.vec3, device=device) for _ in range(3))
+
+ def draw(self, viewer, transforms: wp.array, contacts: wp.array) -> None:
+ """Draw the outlines for one pose.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ transforms: World transforms of the pose's joints or bodies, as the outlines
+ index them.
+ contacts: The pose's four sampled foot contacts.
+ """
+ wp.launch(
+ _update_outlines_kernel,
+ dim=len(self._lines[0]),
+ inputs=[transforms, contacts, self.threshold, *self._inputs],
+ outputs=list(self._lines),
+ device=self._device,
+ )
+ self._log_visible(viewer.log_lines, self._name, *self._lines)
+
+ def hide(self, viewer) -> None:
+ """Hide the outlines, keeping their data for the next draw.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._log_hidden_once(viewer.log_lines, self._name, *self._lines)
+
+ def clear(self, viewer) -> None:
+ """Remove the outlines from the viewer.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._clear(viewer.lines)
+
+
+class SkeletonFootContactRenderer(FootContactRenderer):
+ """Draw foot contact outlines on a pose of local joint transforms, such as a SOMA pose."""
+
+ def __init__(self, name: str, skeleton: Skeleton, outlines: Sequence[ContactOutline]) -> None:
+ """Upload the outline points and allocate the world joint transforms.
+
+ Args:
+ name: Viewer name of the outline lines.
+ skeleton: Skeleton of the drawn poses.
+ outlines: Outlines from skeletal_mesh_sole_outlines(), relative to the
+ skeleton's joints.
+ """
+ super().__init__(name, outlines, device=skeleton.device)
+ self._parent_indices = skeleton.parent_indices
+ self._world_transforms = wp.empty(skeleton.num_joints, dtype=wp.transform, device=skeleton.device)
+
+ def draw_pose(self, viewer, local_pose: wp.array, contacts: wp.array) -> None:
+ """Draw the outlines on one pose of local joint transforms.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ local_pose: Local joint transforms of the pose.
+ contacts: The pose's four sampled foot contacts.
+ """
+ with wp.ScopedDevice(self._device):
+ compute_world_poses(local_pose, self._parent_indices, self._world_transforms)
+ self.draw(viewer, self._world_transforms, contacts)
+
+
+class DOFFootContactRenderer(FootContactRenderer):
+ """Draw foot contact outlines on a pose of joint coordinates, such as a G1 pose.
+
+ Forward kinematics runs in the renderer's own Newton state, so the outlines never
+ depend on a mesh draw.
+ """
+
+ def __init__(self, name: str, model, outlines: Sequence[ContactOutline]) -> None:
+ """Upload the outline points and create the state for forward kinematics.
+
+ Args:
+ name: Viewer name of the outline lines.
+ model: Newton model of the drawn poses.
+ outlines: Outlines from body_sole_outlines(), relative to the model's bodies.
+ """
+ super().__init__(name, outlines, device=model.device)
+ self._model = model
+ self._state = model.state()
+
+ def draw_pose(self, viewer, joint_q: wp.array, contacts: wp.array) -> None:
+ """Draw the outlines on one pose of joint coordinates.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ joint_q: Joint coordinates of the pose, in the model's joint_q order.
+ contacts: The pose's four sampled foot contacts.
+ """
+ newton.eval_fk(self._model, joint_q, self._model.joint_qd, self._state)
+ self.draw(viewer, self._state.body_q, contacts)
+
+
+def skeletal_mesh_sole_outlines(
+ skeletal_mesh,
+ contact_joints: Sequence[str],
+ *,
+ margin: float = 0.015,
+ rings: int = 3,
+ spacing: float = 0.005,
+) -> list[ContactOutline]:
+ """Outline each foot of a skinned mesh, seen from above in its Y up bind pose.
+
+ A foot's vertices are those that its heel joint and the joints below it mainly
+ move. The outline splits at the toe joint into a heel part and a toe part.
+ Points are stored relative to their joint. Draw them with world joint
+ transforms. The bind pose must face +Z.
+
+ Args:
+ skeletal_mesh: Skeletal mesh whose feet to outline.
+ contact_joints: Joint of each foot contact, in foot contact order.
+ margin: Distance the first ring runs outside the foot, in meters.
+ rings: Number of rings around each foot.
+ spacing: Distance between rings, in meters.
+ """
+ names = list(skeletal_mesh.skeleton.joint_names)
+ parents = skeletal_mesh.skeleton.parent_indices.numpy()
+ inverse_bind = skeletal_mesh.inverse_bind_transforms.numpy()
+ outlines = []
+ for foot, (heel_name, toe_name) in enumerate(zip(contact_joints[0::2], contact_joints[1::2], strict=True)):
+ heel, toe = names.index(heel_name), names.index(toe_name)
+ joints = [heel]
+ for joint in range(len(names)):
+ if parents[joint] in joints:
+ joints.append(joint)
+ foot_points = np.concatenate([_vertices_moved_by(mesh, joints) for mesh in skeletal_mesh.skinned_meshes])
+ split = wp.transform_inverse(wp.transform(*inverse_bind[toe])).p[2]
+ height = foot_points[:, 1].min() + _OUTLINE_LIFT
+ # Columns z and x hold the forward and side coordinates.
+ for loops in _rings(foot_points[:, [2, 0]], split, margin, rings, spacing):
+ for contact, (joint, loop) in enumerate(zip((heel, toe), loops), start=2 * foot):
+ bind = np.column_stack([loop[:, 1], np.full(len(loop), height), loop[:, 0]])
+ joint_from_bind = wp.transform(*inverse_bind[joint])
+ points = np.array([wp.transform_point(joint_from_bind, wp.vec3(*point)) for point in bind])
+ outlines.append(ContactOutline(contact, joint, points))
+ return outlines
+
+
+def body_sole_outlines(
+ model,
+ contact_bodies: Sequence[str],
+ contact_offsets: Sequence[Sequence[float]],
+ *,
+ margin: float = 0.015,
+ rings: int = 3,
+ spacing: float = 0.005,
+) -> list[ContactOutline]:
+ """Outline each foot body of a Newton model, seen from above in its Z up space.
+
+ A foot's heel and toe share one body. The body must face +X. The outline splits
+ halfway between the heel and toe points. Points are stored relative to their
+ body. Draw them with world body transforms.
+
+ Args:
+ model: Newton model with the foot bodies.
+ contact_bodies: Body of each foot contact, in foot contact order.
+ contact_offsets: Each contact point in its body's local space, in meters.
+ margin: Distance the first ring runs outside the foot, in meters.
+ rings: Number of rings around each foot.
+ spacing: Distance between rings, in meters.
+ """
+ labels = [label.rsplit("/", 1)[-1] for label in model.body_label]
+ shape_bodies = model.shape_body.numpy()
+ is_mesh = np.isin(model.shape_type.numpy(), (GeoType.MESH, GeoType.CONVEX_MESH))
+ shape_transforms = model.shape_transform.numpy()
+ scales = model.shape_scale.numpy()
+ outlines = []
+ for foot in range(len(contact_bodies) // 2):
+ name, toe_name = contact_bodies[2 * foot], contact_bodies[2 * foot + 1]
+ if name != toe_name:
+ raise ValueError(f"The heel and toe contacts of {name!r} must share one body.")
+ body = labels.index(name)
+ split = (contact_offsets[2 * foot][0] + contact_offsets[2 * foot + 1][0]) / 2.0
+ points = np.array([
+ wp.transform_point(wp.transform(*shape_transforms[shape]), wp.vec3(*vertex))
+ for shape in np.flatnonzero((shape_bodies == body) & is_mesh)
+ for vertex in np.asarray(model.shape_source[shape].vertices) * scales[shape]
+ ])
+ if len(points) == 0:
+ raise ValueError(f"Body {name!r} has no mesh to outline.")
+ height = points[:, 2].min() + _OUTLINE_LIFT
+ for loops in _rings(points[:, :2], split, margin, rings, spacing):
+ for contact, loop in enumerate(loops, start=2 * foot):
+ outlines.append(ContactOutline(contact, body, np.column_stack([loop, np.full(len(loop), height)])))
+ return outlines
+
+
+def _rings(points: np.ndarray, split: float, margin: float, rings: int, spacing: float) -> list:
+ """Return the heel and toe loops of each ring around (forward, side) points.
+
+ The loops are cut at split. Each ring scales the convex hull about its center.
+ Its ends and sides move out by margin, plus spacing for each ring inside it.
+ """
+ hull = points[ConvexHull(points).vertices]
+ low, high = hull.min(axis=0), hull.max(axis=0)
+ center, reach = (low + high) / 2.0, (high - low) / 2.0
+ grown = [center + (hull - center) * (1.0 + (margin + ring * spacing) / reach) for ring in range(rings)]
+ return [(_clip(loop, split, 1.0), _clip(loop, split, -1.0)) for loop in grown]
+
+
+def _clip(polygon: np.ndarray, split: float, side: float) -> np.ndarray:
+ """Keep the part of a convex polygon where side * (forward - split) is at most zero."""
+ kept = []
+ for start, end in zip(polygon, np.roll(polygon, -1, axis=0)):
+ a, b = side * (start[0] - split), side * (end[0] - split)
+ if a <= 0.0:
+ kept.append(start)
+ if a * b < 0.0:
+ kept.append(start + (end - start) * a / (a - b))
+ return np.array(kept)
+
+
+def _vertices_moved_by(mesh, joints: Sequence[int]) -> np.ndarray:
+ """Return the vertices of a skinned mesh part that the given joints mainly move."""
+ indices = mesh.joint_indices.numpy().reshape(mesh.num_points, -1)
+ weights = mesh.joint_weights.numpy().reshape(mesh.num_points, -1)
+ return mesh.points.numpy()[np.where(np.isin(indices, joints), weights, 0.0).sum(axis=1) > 0.5]
diff --git a/motionbricks/renderers/line_renderer.py b/motionbricks/renderers/line_renderer.py
new file mode 100644
index 0000000..f081c4e
--- /dev/null
+++ b/motionbricks/renderers/line_renderer.py
@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw named batches of lines from buffers that grow to fit the largest batch."""
+
+import warp as wp
+
+from motionbricks.renderers.base_renderer import BaseRenderer
+
+
+class LineRenderer(BaseRenderer):
+ """Draw named batches of lines in the Newton viewer.
+
+ An item is one thing a batch draws, such as a pose or a box. Every item uses the
+ same number of lines. A subclass sets _NAME_PREFIX. It draws a batch in three steps:
+
+ 1. Call _ensure_capacity() with the batch's item count.
+ 2. Fill line_starts, line_ends, and line_colors.
+ 3. Call _log_batch().
+
+ hide() logs the batch's last lines as hidden.
+ """
+
+ _NAME_PREFIX: str
+
+ def __init__(self, lines_per_item: int, capacity: int, device=None) -> None:
+ """Allocate line buffers for the first batches.
+
+ Args:
+ lines_per_item: Number of lines each item uses.
+ capacity: Number of items the buffers hold at first. They grow when a batch
+ needs more. It must be positive.
+ device: Device of the buffers. None uses the current device.
+ """
+ super().__init__()
+ if capacity <= 0:
+ raise ValueError("capacity must be positive.")
+ self._lines_per_item = lines_per_item
+ self._device = device
+ self._capacity = 0
+ self._line_counts: dict[str, int] = {}
+ self._allocate_buffers(capacity)
+
+ def hide(self, viewer, instance_id: int | str) -> None:
+ """Hide one drawn batch, keeping its data for the next draw.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ instance_id: Identifier of the batch to hide.
+ """
+ name = self._name(instance_id)
+ line_count = self._line_counts.get(name)
+ if line_count is not None:
+ self._log_hidden_once(viewer.log_lines, name, *self._lines(line_count))
+
+ def clear(self, viewer) -> None:
+ """Remove every drawn batch from the viewer.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._clear(viewer.lines)
+ self._line_counts.clear()
+
+ def _name(self, instance_id: int | str) -> str:
+ return f"{self._NAME_PREFIX}{instance_id}"
+
+ def _log_batch(self, viewer, instance_id: int | str, item_count: int) -> None:
+ """Show the lines of the first item_count items as the batch named by instance_id."""
+ name = self._name(instance_id)
+ line_count = item_count * self._lines_per_item
+ self._line_counts[name] = line_count
+ self._log_visible(viewer.log_lines, name, *self._lines(line_count))
+
+ def _lines(self, line_count: int) -> tuple[wp.array, wp.array, wp.array]:
+ return self.line_starts[:line_count], self.line_ends[:line_count], self.line_colors[:line_count]
+
+ def _ensure_capacity(self, item_count: int) -> None:
+ if item_count > self._capacity:
+ self._allocate_buffers(max(item_count, self._capacity * 2))
+
+ def _allocate_buffers(self, capacity: int) -> None:
+ """Allocate the line buffers for capacity items. Subclasses extend it with their own buffers."""
+ self._capacity = capacity
+ line_count = capacity * self._lines_per_item
+ self.line_starts = wp.empty(line_count, dtype=wp.vec3, device=self._device)
+ self.line_ends = wp.empty_like(self.line_starts)
+ self.line_colors = wp.empty_like(self.line_starts)
+
+
+__all__ = ["LineRenderer"]
diff --git a/motionbricks/renderers/picking.py b/motionbricks/renderers/picking.py
new file mode 100644
index 0000000..c3ad6e7
--- /dev/null
+++ b/motionbricks/renderers/picking.py
@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Ray helpers for selecting thin rendered lines."""
+
+import warp as wp
+from newton._src.geometry.raycast import map_ray_to_local, ray_intersect_capsule
+
+_LINE_PICK_RADIUS = 0.025
+
+
+def raycast_line(
+ start: wp.vec3,
+ end: wp.vec3,
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float,
+) -> float:
+ """Return the distance where a ray hits a line, treated as a thin capsule.
+
+ Args:
+ start: Start of the line.
+ end: End of the line.
+ origin: Ray origin, in the line's space.
+ direction: Unit ray direction, in the line's space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ length = wp.length(end - start)
+ # quat_between_vectors() normalizes the line, and a zero length line gives the identity.
+ rotation = wp.quat_between_vectors(wp.vec3(0.0, 0.0, 1.0), end - start)
+ local_origin, local_direction = map_ray_to_local(wp.transform((start + end) * 0.5, rotation), origin, direction)
+ distance, _ = ray_intersect_capsule(local_origin, local_direction, _LINE_PICK_RADIUS, length * 0.5)
+ return distance if 0 <= distance < max_distance else max_distance
+
+
+def raycast_lines(
+ transform: wp.transform,
+ lines,
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float,
+) -> float:
+ """Return the distance where a ray first hits one of several lines, each a thin capsule.
+
+ Args:
+ transform: World transform of the space the lines are in.
+ lines: (start, end) pairs in that space.
+ origin: Ray origin in world space.
+ direction: Unit ray direction in world space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ origin, direction = map_ray_to_local(transform, origin, direction)
+ for start, end in lines:
+ max_distance = raycast_line(start, end, origin, direction, max_distance)
+ return max_distance
diff --git a/motionbricks/renderers/skeletal_mesh_renderer.py b/motionbricks/renderers/skeletal_mesh_renderer.py
new file mode 100644
index 0000000..02b8b29
--- /dev/null
+++ b/motionbricks/renderers/skeletal_mesh_renderer.py
@@ -0,0 +1,274 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw and pick skeletal meshes with linear blend skinning."""
+
+import warp as wp
+
+from motionbricks.animation.mesh import SkeletalMesh
+from motionbricks.renderers.base_renderer import BaseRenderer
+from motionbricks.utils.pose_utils import blend_transform
+
+
+def _skin_mesh_kernel(
+ points: wp.array(dtype=wp.vec3),
+ joint_indices: wp.array(dtype=wp.int32),
+ joint_weights: wp.array(dtype=wp.float32),
+ num_influences: wp.int32,
+ skinning_transforms: wp.array(dtype=wp.transform),
+ output_points: wp.array(dtype=wp.vec3),
+):
+ point = wp.tid()
+ skinned_point = wp.vec3(0.0, 0.0, 0.0)
+ for influence in range(num_influences):
+ index = point * num_influences + influence
+ skinned_point += (
+ wp.transform_point(
+ skinning_transforms[joint_indices[index]],
+ points[point],
+ )
+ * joint_weights[index]
+ )
+ output_points[point] = skinned_point
+
+
+def _raycast_meshes_kernel(
+ mesh_ids: wp.array(dtype=wp.uint64),
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float,
+ distances: wp.array(dtype=float),
+):
+ index = wp.tid()
+ hit = wp.mesh_query_ray(mesh_ids[index], origin, direction, max_distance)
+ distances[index] = wp.inf
+ if hit.result:
+ distances[index] = hit.t
+
+
+def _blend_override_pose_kernel(
+ local_transforms: wp.array(dtype=wp.transform),
+ override_pose: wp.array(dtype=wp.transform),
+ override_pose_mask: wp.array(dtype=wp.float32),
+ blended_transforms: wp.array(dtype=wp.transform),
+):
+ joint = wp.tid()
+ weight = wp.clamp(override_pose_mask[joint], 0.0, 1.0)
+ blended_transforms[joint] = blend_transform(local_transforms[joint], override_pose[joint], weight)
+
+
+def _compute_skinning_transforms_kernel(
+ world_transforms: wp.array(dtype=wp.transform),
+ inverse_bind_transforms: wp.array(dtype=wp.transform),
+ skinning_transforms: wp.array(dtype=wp.transform),
+):
+ # A skinning transform takes a vertex from the bind pose to the drawn pose.
+ joint = wp.tid()
+ skinning_transforms[joint] = wp.mul(world_transforms[joint], inverse_bind_transforms[joint])
+
+
+class SkeletalMeshRenderer(BaseRenderer):
+ """Draw a skeletal mesh with linear blend skinning.
+
+ set_override_pose() selects one of the mesh's override poses with a mask.
+ Each joint then blends toward the override pose by its mask weight. The
+ poses passed in are never changed.
+ """
+
+ def __init__(self, skeletal_mesh: SkeletalMesh) -> None:
+ """Allocate the skinning buffers for a skeletal mesh on its skeleton's device.
+
+ Args:
+ skeletal_mesh: Skeletal mesh to draw.
+ """
+ super().__init__()
+ self.skeletal_mesh = skeletal_mesh
+ self._device = skeletal_mesh.skeleton.device
+ self.skinning_transforms = wp.empty(
+ skeletal_mesh.skeleton.num_joints,
+ dtype=wp.transform,
+ device=self._device,
+ )
+ self._blended_pose = wp.empty_like(self.skinning_transforms)
+ self._world_pose = wp.empty_like(self.skinning_transforms)
+ self._override: tuple[wp.array, wp.array] | None = None
+ self.skinned_points = [
+ wp.empty(
+ mesh.num_points,
+ dtype=wp.vec3,
+ device=self._device,
+ )
+ for mesh in skeletal_mesh.skinned_meshes
+ ]
+ self._pick_meshes = None
+
+ @staticmethod
+ def _name(instance_id: int | str, mesh_index: int) -> str:
+ return f"/skeletal_mesh_{instance_id}_{mesh_index}"
+
+ def set_override_pose(self, pose: str | None, mask: str | None = None) -> None:
+ """Select a mesh override pose and mask by name.
+
+ Drawing clamps mask weights to the range from 0 to 1.
+
+ Args:
+ pose: Name of an override pose on the mesh. None draws poses as given.
+ mask: Name of a mask on the mesh, required with a pose. It holds one
+ float32 weight per joint on the renderer's device.
+ """
+ if pose is None:
+ self._override = None
+ return
+ if mask is None:
+ raise ValueError("An override pose needs a mask.")
+ pose_array = self.skeletal_mesh.override_poses[pose]
+ mask_array = self.skeletal_mesh.override_pose_masks[mask]
+ shape, device = self.skinning_transforms.shape, self.skinning_transforms.device
+ if pose_array.dtype != wp.transform or pose_array.shape != shape or pose_array.device != device:
+ raise ValueError(f"Override pose {pose} must hold one transform per joint on {device}.")
+ if mask_array.dtype != wp.float32 or mask_array.shape != shape or mask_array.device != device:
+ raise ValueError(f"Override pose mask {mask} must hold one float32 weight per joint on {device}.")
+ self._override = (pose_array, mask_array)
+
+ def draw_pose(
+ self,
+ viewer,
+ local_transforms: wp.array,
+ xform: wp.transform,
+ color: wp.vec3,
+ instance_id: int | str,
+ ) -> None:
+ """Skin and draw one pose of the mesh.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ local_transforms: Local joint transforms of the pose.
+ xform: World transform applied to the pose.
+ color: RGB color of the mesh.
+ instance_id: Identifier of the drawn instance. Drawing the same identifier
+ again updates it.
+ """
+ self._skin_pose(local_transforms, xform)
+ for mesh_index, mesh in enumerate(self.skeletal_mesh.skinned_meshes):
+ if mesh.num_points == 0:
+ continue
+ self._log_visible(
+ viewer.log_mesh,
+ self._name(instance_id, mesh_index),
+ self.skinned_points[mesh_index],
+ mesh.indices,
+ color=color,
+ )
+
+ def raycast_pose(
+ self,
+ local_transforms: wp.array,
+ xform: wp.transform,
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float = 1.0e6,
+ ) -> float:
+ """Return the distance to the skinned mesh along a ray.
+
+ Picking skins the pose on demand, so it adds no work to normal rendering.
+
+ Args:
+ local_transforms: Local joint transforms of the pose.
+ xform: World transform applied to the pose.
+ origin: Ray origin in world space.
+ direction: Unit ray direction in world space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ self._skin_pose(local_transforms, xform)
+ if self._pick_meshes is None:
+ self._pick_meshes = [
+ wp.Mesh(points=points, indices=mesh.indices)
+ for points, mesh in zip(self.skinned_points, self.skeletal_mesh.skinned_meshes)
+ if mesh.num_indices > 0
+ ]
+ self._pick_mesh_ids = wp.array(
+ [mesh.id for mesh in self._pick_meshes], dtype=wp.uint64, device=self._device,
+ )
+ self._pick_distances = wp.empty(len(self._pick_meshes), dtype=float, device=self._device)
+ if not self._pick_meshes:
+ return max_distance
+ for mesh in self._pick_meshes:
+ mesh.refit()
+ wp.launch(
+ _raycast_meshes_kernel,
+ dim=len(self._pick_meshes),
+ inputs=[self._pick_mesh_ids, origin, direction, max_distance],
+ outputs=[self._pick_distances],
+ device=self._device,
+ )
+ return min(max_distance, float(self._pick_distances.numpy().min()))
+
+ def _skin_pose(self, local_transforms: wp.array, xform: wp.transform) -> None:
+ skeleton = self.skeletal_mesh.skeleton
+ if (
+ local_transforms.dtype != wp.transform
+ or local_transforms.ndim != 1
+ or local_transforms.shape[0] != skeleton.num_joints
+ ):
+ raise ValueError("local_transforms must contain one transform per joint.")
+ with wp.ScopedDevice(self._device):
+ if self._override is not None:
+ override_pose, override_pose_mask = self._override
+ wp.launch(
+ _blend_override_pose_kernel,
+ dim=skeleton.num_joints,
+ inputs=[local_transforms, override_pose, override_pose_mask],
+ outputs=[self._blended_pose],
+ )
+ local_transforms = self._blended_pose
+ skeleton.compute_world_transforms(local_transforms, self._world_pose, root_tx=xform)
+ wp.launch(
+ _compute_skinning_transforms_kernel,
+ dim=skeleton.num_joints,
+ inputs=[self._world_pose, self.skeletal_mesh.inverse_bind_transforms],
+ outputs=[self.skinning_transforms],
+ )
+
+ for mesh_index, mesh in enumerate(self.skeletal_mesh.skinned_meshes):
+ if mesh.num_points == 0:
+ continue
+ wp.launch(
+ _skin_mesh_kernel,
+ dim=mesh.num_points,
+ inputs=[
+ mesh.points,
+ mesh.joint_indices,
+ mesh.joint_weights,
+ mesh.num_influences,
+ self.skinning_transforms,
+ ],
+ outputs=[self.skinned_points[mesh_index]],
+ )
+
+ def hide(self, viewer, instance_id: int | str) -> None:
+ """Hide one drawn instance, keeping its data for the next draw.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ instance_id: Identifier of the instance to hide.
+ """
+ for mesh_index, mesh in enumerate(self.skeletal_mesh.skinned_meshes):
+ name = self._name(instance_id, mesh_index)
+ self._log_hidden_once(
+ viewer.log_mesh,
+ name,
+ self.skinned_points[mesh_index],
+ mesh.indices,
+ )
+
+ def clear(self, viewer) -> None:
+ """Remove every drawn instance from the viewer.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._clear(viewer.objects)
diff --git a/motionbricks/renderers/skeleton_renderer.py b/motionbricks/renderers/skeleton_renderer.py
new file mode 100644
index 0000000..b0304aa
--- /dev/null
+++ b/motionbricks/renderers/skeleton_renderer.py
@@ -0,0 +1,291 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw SOMA and G1 skeletons in the Newton viewer, with each bone as two pyramids of lines."""
+
+from abc import ABC, abstractmethod
+
+import newton
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.renderers.line_renderer import LineRenderer
+from motionbricks.utils import pose_utils
+
+_PYRAMID_VERTICES = (
+ wp.vec3(0.0, 0.0, 0.0),
+ wp.vec3(1.0, 1.0, 1.0),
+ wp.vec3(0.0, 0.0, 0.0),
+ wp.vec3(-1.0, 1.0, 1.0),
+ wp.vec3(0.0, 0.0, 0.0),
+ wp.vec3(-1.0, -1.0, 1.0),
+ wp.vec3(0.0, 0.0, 0.0),
+ wp.vec3(1.0, -1.0, 1.0),
+ wp.vec3(1.0, 1.0, 1.0),
+ wp.vec3(1.0, -1.0, 1.0),
+ wp.vec3(1.0, -1.0, 1.0),
+ wp.vec3(-1.0, -1.0, 1.0),
+ wp.vec3(-1.0, -1.0, 1.0),
+ wp.vec3(-1.0, 1.0, 1.0),
+ wp.vec3(-1.0, 1.0, 1.0),
+ wp.vec3(1.0, 1.0, 1.0),
+)
+
+# Each pair of vertices is one line.
+_PYRAMID_LINE_COUNT = wp.constant(len(_PYRAMID_VERTICES) // 2)
+# A bone is two pyramids that share a square base. The base sits 80 percent of the way
+# from the child joint to its parent, and its half width is a twentieth of the bone length.
+_BONE_LINE_COUNT = wp.constant(2 * _PYRAMID_LINE_COUNT)
+_CHILD_PYRAMID_HEIGHT = wp.constant(0.8)
+_PARENT_PYRAMID_HEIGHT = wp.constant(1.0 - 0.8)
+_BONE_LENGTH_PER_HALF_WIDTH = wp.constant(20.0)
+
+
+def _compute_pyramid_lines(
+ in_pyramid_vertices: wp.array(dtype=wp.vec3),
+ in_tx: wp.transform,
+ in_scale: wp.vec3,
+ in_offset: wp.int32,
+ out_line_starts: wp.array(dtype=wp.vec3),
+ out_line_ends: wp.array(dtype=wp.vec3),
+):
+ for i in range(_PYRAMID_LINE_COUNT):
+ idx = in_offset + i
+ out_line_starts[idx] = wp.transform_point(
+ in_tx, wp.cw_mul(in_pyramid_vertices[i * 2], in_scale)
+ )
+ out_line_ends[idx] = wp.transform_point(
+ in_tx, wp.cw_mul(in_pyramid_vertices[1 + i * 2], in_scale)
+ )
+
+
+def _compute_bone_lines(
+ in_pyramid_vertices: wp.array(dtype=wp.vec3),
+ in_offset: wp.int32,
+ in_joint_t: wp.vec3,
+ in_parent_t: wp.vec3,
+ out_line_starts: wp.array(dtype=wp.vec3),
+ out_line_ends: wp.array(dtype=wp.vec3),
+):
+ diff = wp.sub(in_parent_t, in_joint_t)
+ q = wp.quat_between_vectors(wp.vec3(0.0, 0.0, 1.0), wp.normalize(diff))
+
+ length = wp.length(diff)
+ width = length / _BONE_LENGTH_PER_HALF_WIDTH
+
+ _compute_pyramid_lines(
+ in_pyramid_vertices,
+ wp.transform(in_joint_t, q),
+ wp.vec3(width, width, length * _CHILD_PYRAMID_HEIGHT),
+ in_offset,
+ out_line_starts,
+ out_line_ends,
+ )
+
+ _compute_pyramid_lines(
+ in_pyramid_vertices,
+ wp.transform(in_parent_t, q),
+ wp.vec3(width, width, -length * _PARENT_PYRAMID_HEIGHT),
+ in_offset + _PYRAMID_LINE_COUNT,
+ out_line_starts,
+ out_line_ends,
+ )
+
+
+def _update_bone_lines_batch_kernel(
+ in_pyramid_vertices: wp.array(dtype=wp.vec3),
+ in_world_transforms: wp.array2d(dtype=wp.transform),
+ in_bone_indices: wp.array(dtype=wp.vec2i),
+ in_colors: wp.array(dtype=wp.vec3),
+ out_line_starts: wp.array(dtype=wp.vec3),
+ out_line_ends: wp.array(dtype=wp.vec3),
+ out_line_colors: wp.array(dtype=wp.vec3),
+):
+ pose, bone_index = wp.tid()
+ bone = in_bone_indices[bone_index]
+ bone_count = in_bone_indices.shape[0]
+ offset = (pose * bone_count + bone_index) * _BONE_LINE_COUNT
+
+ _compute_bone_lines(
+ in_pyramid_vertices,
+ offset,
+ in_world_transforms[pose, bone.y].p,
+ in_world_transforms[pose, bone.x].p,
+ out_line_starts,
+ out_line_ends,
+ )
+
+ for line in range(_BONE_LINE_COUNT):
+ out_line_colors[offset + line] = in_colors[pose]
+
+
+class BaseSkeletonRenderer(LineRenderer, ABC):
+ """Draw batches of poses as bones between their world transforms.
+
+ A subclass names its bones as (parent, child) index pairs into each pose's world
+ transforms. It checks the poses it draws, and writes their world transforms into
+ world_poses.
+ """
+
+ def __init__(self, bones, transforms_per_pose: int, max_instances: int, device=None) -> None:
+ """Upload the bones and allocate the line buffers.
+
+ Args:
+ bones: (parent, child) index pairs into each pose's world transforms.
+ transforms_per_pose: Number of world transforms in each pose.
+ max_instances: Number of poses the buffers hold at first. They grow when a
+ batch needs more.
+ device: Device of the buffers. None uses the current device.
+ """
+ self._transforms_per_pose = transforms_per_pose
+ self.pyramid_vertices = wp.array(_PYRAMID_VERTICES, dtype=wp.vec3, device=device)
+ self.bones = wp.array(list(bones), dtype=wp.vec2i, device=device)
+ super().__init__(len(self.bones) * _BONE_LINE_COUNT, max_instances, device=device)
+
+ def draw_batch(
+ self,
+ viewer,
+ poses: wp.array,
+ num_poses: int,
+ xform: wp.transform,
+ colors: wp.array,
+ instance_id: int | str,
+ ) -> None:
+ """Draw the first num_poses poses as one batch.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ poses: Poses laid out as [pose, value], in the renderer's pose layout.
+ num_poses: Number of poses to draw. Zero hides the batch.
+ xform: World transform applied to every pose.
+ colors: One vec3 color per pose.
+ instance_id: Identifier of the drawn batch. Drawing the same identifier again
+ updates it.
+ """
+ self._check_poses(poses)
+ if not 0 <= num_poses <= poses.shape[0]:
+ raise ValueError(f"num_poses must be in [0, {poses.shape[0]}].")
+ if colors.dtype != wp.vec3 or colors.ndim != 1 or len(colors) < num_poses:
+ raise ValueError("colors must provide one wp.vec3 per active pose.")
+ if num_poses == 0:
+ self.hide(viewer, instance_id)
+ return
+ self._ensure_capacity(num_poses)
+ self._compute_world_poses(poses, num_poses, xform)
+ wp.launch(
+ _update_bone_lines_batch_kernel,
+ dim=(num_poses, len(self.bones)),
+ inputs=[self.pyramid_vertices, self.world_poses, self.bones, colors],
+ outputs=[self.line_starts, self.line_ends, self.line_colors],
+ device=self._device,
+ )
+ self._log_batch(viewer, instance_id, num_poses)
+
+ @abstractmethod
+ def _check_poses(self, poses: wp.array) -> None:
+ """Raise ValueError unless poses holds [pose, value] poses in the renderer's layout."""
+
+ @abstractmethod
+ def _compute_world_poses(self, poses: wp.array, num_poses: int, xform: wp.transform) -> None:
+ """Write the world transforms of the first num_poses poses, placed by xform, into world_poses."""
+
+ def _allocate_buffers(self, capacity: int) -> None:
+ super()._allocate_buffers(capacity)
+ self.world_poses = wp.empty(
+ (capacity, self._transforms_per_pose), dtype=wp.transform, device=self._device,
+ )
+
+
+class SkeletonRenderer(BaseSkeletonRenderer):
+ """Draw poses of local joint transforms along a skeleton's joint hierarchy."""
+
+ _NAME_PREFIX = "/skeleton_"
+
+ def __init__(self, skeleton: Skeleton, max_instances: int = 1):
+ """Collect the skeleton's bones and allocate the line buffers on its device.
+
+ Args:
+ skeleton: Skeleton to draw.
+ max_instances: Number of poses the buffers hold at first. They grow when a
+ batch needs more.
+ """
+ self.skeleton = skeleton
+ super().__init__(
+ [(skeleton.joint_parent(joint), joint) for joint in range(1, skeleton.num_joints)],
+ skeleton.num_joints,
+ max_instances,
+ device=skeleton.device,
+ )
+
+ def _check_poses(self, poses: wp.array) -> None:
+ if poses.dtype != wp.transform or poses.ndim != 2:
+ raise ValueError("poses must be a 2D Warp array of wp.transform.")
+ if poses.shape[1] != self.skeleton.num_joints:
+ raise ValueError(f"Expected {self.skeleton.num_joints} joints, got {poses.shape[1]}.")
+
+ def _compute_world_poses(self, poses: wp.array, num_poses: int, xform: wp.transform) -> None:
+ # compute_world_poses() launches on the current device.
+ with wp.ScopedDevice(self.skeleton.device):
+ pose_utils.compute_world_poses(
+ poses, self.skeleton.parent_indices, self.world_poses, xform, num_poses=num_poses,
+ )
+
+
+def _place_bodies_kernel(
+ xform: wp.transform,
+ body_q: wp.array(dtype=wp.transform),
+ placed_body_q: wp.array(dtype=wp.transform),
+):
+ body = wp.tid()
+ placed_body_q[body] = wp.mul(xform, body_q[body])
+
+
+class DOFSkeletonRenderer(BaseSkeletonRenderer):
+ """Draw poses of joint coordinates along the Newton model's joint hierarchy.
+
+ Each pose holds all of the Newton model's joint_q coordinates. Forward kinematics
+ uses a separate state, so drawing does not affect playback. Bones connect body
+ origins along the joint hierarchy.
+ """
+
+ _NAME_PREFIX = "/dof_skeleton_"
+
+ def __init__(self, model: newton.Model, max_instances: int = 1) -> None:
+ """Collect the model's bones and allocate the line buffers on its device.
+
+ Args:
+ model: Newton model whose joint hierarchy to draw.
+ max_instances: Number of poses the buffers hold at first. They grow when a
+ batch needs more.
+ """
+ self.model = model
+ self.state = model.state()
+ super().__init__(
+ [(parent, child) for parent, child in zip(model.joint_parent.numpy(), model.joint_child.numpy())
+ if parent >= 0 and child >= 0],
+ model.body_count,
+ max_instances,
+ device=model.device,
+ )
+
+ def _check_poses(self, poses: wp.array) -> None:
+ if poses.dtype != wp.float32 or poses.ndim != 2:
+ raise ValueError("poses must be a 2D Warp array of float32.")
+ if poses.shape[1] != self.model.joint_coord_count:
+ raise ValueError(f"Expected {self.model.joint_coord_count} joint coordinates, got {poses.shape[1]}.")
+
+ def _compute_world_poses(self, poses: wp.array, num_poses: int, xform: wp.transform) -> None:
+ for frame in range(num_poses):
+ newton.eval_fk(self.model, poses[frame], self.model.joint_qd, self.state)
+ wp.launch(
+ _place_bodies_kernel, dim=self.model.body_count,
+ inputs=[xform, self.state.body_q], outputs=[self.world_poses[frame]],
+ device=self.model.device,
+ )
+
+
+__all__ = ["BaseSkeletonRenderer", "DOFSkeletonRenderer", "SkeletonRenderer"]
diff --git a/motionbricks/renderers/solid_box_renderer.py b/motionbricks/renderers/solid_box_renderer.py
new file mode 100644
index 0000000..bfcecd0
--- /dev/null
+++ b/motionbricks/renderers/solid_box_renderer.py
@@ -0,0 +1,171 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw solid boxes that cast shadows in the Newton viewer."""
+
+from collections.abc import Sequence
+
+import newton
+import warp as wp
+from newton._src.geometry.raycast import map_ray_to_local, ray_intersect_box
+
+from motionbricks.renderers.base_renderer import BaseRenderer
+
+
+_UNIT_CUBE_HALF_EXTENTS = (0.5, 0.5, 0.5)
+_DEFAULT_MATERIAL = wp.vec4(0.5, 0.0, 0.0, 0.0)
+
+
+class SolidBoxRenderer(BaseRenderer):
+ """Draw movable colored boxes as solid Newton mesh instances."""
+
+ _PROTOTYPE_NAME = "/geometry/motionbricks_unit_cube"
+
+ def __init__(self, max_boxes: int = 1, device=None) -> None:
+ """Allocate buffers for the boxes.
+
+ Args:
+ max_boxes: Number of boxes the buffers hold at first. They grow when a batch
+ needs more.
+ device: Device for new arrays.
+ """
+ super().__init__()
+ if max_boxes <= 0:
+ raise ValueError("max_boxes must be positive.")
+ self.device = wp.get_device(device)
+ self._prototype_registered = False
+ self._capacity = 0
+ self._allocate_buffers(max_boxes)
+
+ @staticmethod
+ def _name(instance_id: int | str) -> str:
+ return f"/solid_boxes_{instance_id}"
+
+ @staticmethod
+ def raycast(
+ transform: wp.transform,
+ dimensions: wp.vec3,
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float = 1.0e6,
+ ) -> float:
+ """Return the distance where a ray hits a box.
+
+ Args:
+ transform: World transform of the box.
+ dimensions: Full size of the box along each of its axes, in meters.
+ origin: Ray origin in world space.
+ direction: Unit ray direction in world space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ origin, direction = map_ray_to_local(transform, origin, direction)
+ distance, _ = ray_intersect_box(origin, direction, dimensions * 0.5)
+ return distance if 0 <= distance < max_distance else max_distance
+
+ def draw_batch(
+ self,
+ viewer,
+ transforms: Sequence[wp.transform],
+ dimensions: Sequence[wp.vec3],
+ colors: Sequence[wp.vec3],
+ instance_id: int | str,
+ ) -> None:
+ """Draw one batch of boxes. An empty batch hides it.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ transforms: World transform of each box.
+ dimensions: Full size of each box along its axes, in meters.
+ colors: RGB color of each box.
+ instance_id: Identifier of the drawn batch. Drawing the same identifier again
+ updates it.
+ """
+ box_count = len(transforms)
+ if box_count == 0:
+ self.hide(viewer, instance_id)
+ return
+ if len(dimensions) != box_count or len(colors) != box_count:
+ raise ValueError(
+ "transforms, dimensions, and colors must have equal lengths."
+ )
+
+ self._ensure_capacity(box_count)
+ self.transforms[:box_count].assign(transforms)
+ self.dimensions[:box_count].assign(dimensions)
+ self.colors[:box_count].assign(colors)
+
+ if not self._prototype_registered:
+ viewer.log_geo(
+ self._PROTOTYPE_NAME,
+ newton.GeoType.BOX,
+ _UNIT_CUBE_HALF_EXTENTS,
+ 0.0,
+ True,
+ hidden=True,
+ )
+ self._prototype_registered = True
+
+ self._log_visible(
+ viewer.log_instances,
+ self._name(instance_id),
+ self._PROTOTYPE_NAME,
+ self.transforms[:box_count],
+ self.dimensions[:box_count],
+ self.colors[:box_count],
+ self.materials[:box_count],
+ )
+
+ def hide(self, viewer, instance_id: int | str) -> None:
+ """Hide one drawn batch, keeping its data for the next draw.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ instance_id: Identifier of the batch to hide.
+ """
+ self._log_hidden_once(
+ viewer.log_instances,
+ self._name(instance_id),
+ self._PROTOTYPE_NAME,
+ None,
+ None,
+ None,
+ None,
+ )
+
+ def clear(self, viewer) -> None:
+ """Remove every drawn batch from the viewer.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._clear(viewer.objects)
+
+ def _ensure_capacity(self, box_count: int) -> None:
+ if box_count > self._capacity:
+ self._allocate_buffers(max(box_count, self._capacity * 2))
+
+ def _allocate_buffers(self, capacity: int) -> None:
+ self._capacity = capacity
+ self.transforms = wp.empty(
+ capacity,
+ dtype=wp.transform,
+ device=self.device,
+ )
+ self.dimensions = wp.empty(
+ capacity,
+ dtype=wp.vec3,
+ device=self.device,
+ )
+ self.colors = wp.empty(
+ capacity,
+ dtype=wp.vec3,
+ device=self.device,
+ )
+ self.materials = wp.array(
+ [_DEFAULT_MATERIAL] * capacity,
+ dtype=wp.vec4,
+ device=self.device,
+ )
+
+
+__all__ = ["SolidBoxRenderer"]
diff --git a/motionbricks/renderers/vector_arrow_renderer.py b/motionbricks/renderers/vector_arrow_renderer.py
new file mode 100644
index 0000000..397bfe6
--- /dev/null
+++ b/motionbricks/renderers/vector_arrow_renderer.py
@@ -0,0 +1,117 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw directions and velocities as arrows in the Newton viewer."""
+
+import warp as wp
+
+from motionbricks.renderers.base_renderer import BaseRenderer
+
+
+def _update_vector_arrow_kernel(
+ world_xform: wp.transform,
+ local_origin: wp.vec3,
+ vector: wp.vec3,
+ color: wp.vec3,
+ arrow_starts: wp.array(dtype=wp.vec3),
+ arrow_ends: wp.array(dtype=wp.vec3),
+ arrow_colors: wp.array(dtype=wp.vec3),
+):
+ start = wp.transform_point(world_xform, local_origin)
+ arrow_starts[0] = start
+ arrow_ends[0] = start + wp.transform_vector(world_xform, vector)
+ arrow_colors[0] = color
+
+
+class VectorArrowRenderer(BaseRenderer):
+ """Draw a direction or velocity as an arrow."""
+
+ def __init__(self, name_prefix: str, color: wp.vec3) -> None:
+ """Set the arrow color and the prefix of the viewer names.
+
+ Args:
+ name_prefix: Prefix of each drawn arrow's viewer name.
+ color: RGB color of every arrow.
+ """
+ super().__init__()
+ self._name_prefix = name_prefix
+ self._color = color
+ self._buffers = {}
+
+ def _name(self, instance_id: int | str) -> str:
+ return f"/{self._name_prefix}_{instance_id}"
+
+ def draw(
+ self,
+ viewer,
+ instance_id: int | str,
+ world_xform: wp.transform,
+ local_origin: wp.vec3,
+ vector: wp.vec3,
+ ) -> None:
+ """Draw one arrow from a point along a vector, both in a local space.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ instance_id: Identifier of the drawn arrow. Drawing the same identifier
+ again updates it.
+ world_xform: World transform of the local space.
+ local_origin: Start of the arrow in the local space.
+ vector: Direction and length of the arrow in the local space.
+ """
+ buffers = self._buffers.get(instance_id)
+ if buffers is None:
+ buffers = (
+ wp.empty(1, dtype=wp.vec3),
+ wp.empty(1, dtype=wp.vec3),
+ wp.empty(1, dtype=wp.vec3),
+ )
+ self._buffers[instance_id] = buffers
+
+ arrow_starts, arrow_ends, arrow_colors = buffers
+ wp.launch(
+ _update_vector_arrow_kernel,
+ dim=1,
+ inputs=[
+ world_xform,
+ local_origin,
+ vector,
+ self._color,
+ ],
+ outputs=[arrow_starts, arrow_ends, arrow_colors],
+ )
+
+ self._log_visible(
+ viewer.log_arrows,
+ self._name(instance_id),
+ arrow_starts,
+ arrow_ends,
+ arrow_colors,
+ )
+
+ def hide(self, viewer, instance_id: int | str) -> None:
+ """Hide one drawn arrow, keeping its data for the next draw.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ instance_id: Identifier of the arrow to hide.
+ """
+ buffers = self._buffers.get(instance_id)
+ if buffers is None:
+ return
+
+ self._log_hidden_once(
+ viewer.log_arrows,
+ self._name(instance_id),
+ *buffers,
+ )
+
+ def clear(self, viewer) -> None:
+ """Remove every drawn arrow from the viewer.
+
+ Args:
+ viewer: Newton viewer that shows the drawing.
+ """
+ self._clear(viewer.arrows)
+ self._buffers.clear()
diff --git a/motionbricks/renderers/wire_box_renderer.py b/motionbricks/renderers/wire_box_renderer.py
new file mode 100644
index 0000000..62bb53e
--- /dev/null
+++ b/motionbricks/renderers/wire_box_renderer.py
@@ -0,0 +1,150 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Draw interaction boxes and the probe box as wireframes."""
+
+import warp as wp
+
+from motionbricks.renderers.line_renderer import LineRenderer
+from motionbricks.renderers.picking import raycast_lines
+from motionbricks.runtime.smart_primitive import InteractionBox
+
+
+_BOX_EDGE_COUNT = 12
+
+
+def _box_edge(half_extents: wp.vec3, edge_index: int) -> tuple[wp.vec3, wp.vec3]:
+ axis = edge_index // 4
+ corner = edge_index % 4
+ sign0 = float((corner % 2) * 2 - 1)
+ sign1 = float((corner // 2) * 2 - 1)
+
+ local_start = wp.vec3(0.0)
+ local_end = wp.vec3(0.0)
+ if axis == 0:
+ v0 = sign0 * half_extents[1]
+ v1 = sign1 * half_extents[2]
+ local_start = wp.vec3(-half_extents[0], v0, v1)
+ local_end = wp.vec3(half_extents[0], v0, v1)
+ elif axis == 1:
+ v0 = sign0 * half_extents[0]
+ v1 = sign1 * half_extents[2]
+ local_start = wp.vec3(v0, -half_extents[1], v1)
+ local_end = wp.vec3(v0, half_extents[1], v1)
+ else:
+ v0 = sign0 * half_extents[0]
+ v1 = sign1 * half_extents[1]
+ local_start = wp.vec3(v0, v1, -half_extents[2])
+ local_end = wp.vec3(v0, v1, half_extents[2])
+ return local_start, local_end
+
+
+def _update_box_lines_kernel(
+ boxes: wp.array(dtype=InteractionBox),
+ color: wp.vec3,
+ line_starts: wp.array(dtype=wp.vec3),
+ line_ends: wp.array(dtype=wp.vec3),
+ line_colors: wp.array(dtype=wp.vec3),
+):
+ box_index, edge_index = wp.tid()
+ box = boxes[box_index]
+ local_start, local_end = _box_edge(box.half_extents, edge_index)
+
+ output_index = box_index * _BOX_EDGE_COUNT + edge_index
+ line_starts[output_index] = wp.transform_point(box.transform, local_start)
+ line_ends[output_index] = wp.transform_point(box.transform, local_end)
+ line_colors[output_index] = color
+
+
+class WireBoxRenderer(LineRenderer):
+ """Draw batches of InteractionBox values as 12 wireframe edges."""
+
+ _NAME_PREFIX = "/wire_boxes_"
+
+ def __init__(self, max_boxes: int = 1) -> None:
+ """Allocate line buffers for the boxes.
+
+ Args:
+ max_boxes: Number of boxes the buffers hold at first. They grow when a batch
+ needs more.
+ """
+ super().__init__(_BOX_EDGE_COUNT, max_boxes)
+
+ @staticmethod
+ def raycast(
+ transform: wp.transform,
+ dimensions: wp.vec3,
+ origin: wp.vec3,
+ direction: wp.vec3,
+ max_distance: float = 1.0e6,
+ ) -> float:
+ """Return the distance where a ray hits a box's edges.
+
+ Only the edges count, not the faces.
+
+ Args:
+ transform: World transform of the box.
+ dimensions: Full size of the box along each of its axes, in meters.
+ origin: Ray origin in world space.
+ direction: Unit ray direction in world space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ half_extents = dimensions * 0.5
+ edges = (_box_edge(half_extents, edge_index) for edge_index in range(_BOX_EDGE_COUNT))
+ return raycast_lines(transform, edges, origin, direction, max_distance)
+
+ def raycast_batch(
+ self, boxes: wp.array, num_boxes: int, origin: wp.vec3, direction: wp.vec3, max_distance: float,
+ ) -> float:
+ """Return the distance to the nearest box edge along a ray.
+
+ The boxes are read back from the device on each call.
+
+ Args:
+ boxes: Boxes in world space.
+ num_boxes: Number of boxes to test.
+ origin: Ray origin in world space.
+ direction: Unit ray direction in world space.
+ max_distance: Longest distance to test, in meters. A miss returns it.
+ """
+ for box in boxes[:num_boxes].numpy():
+ max_distance = self.raycast(
+ wp.transform(*box["transform"]), wp.vec3(*box["half_extents"]) * 2.0,
+ origin, direction, max_distance,
+ )
+ return max_distance
+
+ def draw_batch(
+ self,
+ viewer,
+ boxes: wp.array,
+ num_boxes: int,
+ color: wp.vec3,
+ instance_id: int | str,
+ ) -> None:
+ """Draw the first num_boxes boxes as one batch.
+
+ Args:
+ viewer: Newton viewer to draw into.
+ boxes: Boxes in world space.
+ num_boxes: Number of boxes to draw, at least 1.
+ color: RGB color of every edge.
+ instance_id: Identifier of the drawn batch. Drawing the same identifier again
+ updates it.
+ """
+ if boxes.dtype != InteractionBox or boxes.ndim != 1:
+ raise ValueError("boxes must be a 1D InteractionBox Warp array.")
+ if not 1 <= num_boxes <= boxes.shape[0]:
+ raise ValueError(f"num_boxes must be in [1, {boxes.shape[0]}].")
+ self._ensure_capacity(num_boxes)
+
+ wp.launch(
+ _update_box_lines_kernel,
+ dim=(num_boxes, _BOX_EDGE_COUNT),
+ inputs=[boxes, color],
+ outputs=[self.line_starts, self.line_ends, self.line_colors],
+ device=boxes.device,
+ )
+ self._log_batch(viewer, instance_id, num_boxes)
diff --git a/motionbricks/robotics/__init__.py b/motionbricks/robotics/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/motionbricks/robotics/dof_animation_buffer.py b/motionbricks/robotics/dof_animation_buffer.py
new file mode 100644
index 0000000..1026448
--- /dev/null
+++ b/motionbricks/robotics/dof_animation_buffer.py
@@ -0,0 +1,233 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Store animation frames as joint coordinates."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.foot_contacts import sample_foot_contacts, validate_foot_contacts
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT, read_root_transform, write_root_transform
+from motionbricks.utils.pose_utils import (
+ apply_root_endpoint_correction,
+ blend_transform,
+ compute_root_endpoint_delta,
+)
+from motionbricks.utils.time_utils import frame_index_from_time
+
+
+def _loop_delta_kernel(
+ joint_q: wp.array2d(dtype=wp.float32),
+ last: wp.int32,
+ root_delta: wp.array(dtype=wp.transform),
+ angle_deltas: wp.array(dtype=wp.float32),
+):
+ coordinate = wp.tid()
+ if coordinate == 0:
+ root_delta[0] = compute_root_endpoint_delta(read_root_transform(joint_q, last), read_root_transform(joint_q, 0))
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ angle_deltas[coordinate] = joint_q[0, coordinate] - joint_q[last, coordinate]
+
+
+def _make_loopable_kernel(
+ root_delta: wp.array(dtype=wp.transform),
+ angle_deltas: wp.array(dtype=wp.float32),
+ last: wp.int32,
+ joint_q: wp.array2d(dtype=wp.float32),
+):
+ frame, coordinate = wp.tid()
+ weight = float(frame) / float(last)
+ if coordinate == 0:
+ # A loop has only an end correction.
+ root = apply_root_endpoint_correction(
+ read_root_transform(joint_q, frame), wp.transform_identity(), root_delta[0], weight,
+ )
+ write_root_transform(root, joint_q, frame)
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ joint_q[frame, coordinate] += angle_deltas[coordinate] * weight
+
+
+def _sample_dof_pose_kernel(
+ joint_q: wp.array2d(dtype=wp.float32),
+ frame: wp.int32,
+ next_frame: wp.int32,
+ blend: wp.float32,
+ root_offset: wp.transform,
+ output: wp.array(dtype=wp.float32),
+):
+ coordinate = wp.tid()
+ if coordinate == 0:
+ root = blend_transform(read_root_transform(joint_q, frame), read_root_transform(joint_q, next_frame), blend)
+ write_root_transform(root_offset * root, output)
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ # Interpolate joint angles directly, including across plus or minus pi.
+ output[coordinate] = wp.lerp(joint_q[frame, coordinate], joint_q[next_frame, coordinate], blend)
+
+
+class DOFAnimationBuffer:
+ """Store animation frames as joint coordinates at a fixed sample rate.
+
+ Each frame stores root position (XYZ, meters), rotation (XYZW quaternion),
+ and joint angles (radians), in joint_names order. Sampling blends positions
+ and joint angles linearly. It uses spherical interpolation for the root
+ rotation.
+ """
+
+ def __init__(
+ self,
+ joint_names: Sequence[str],
+ sample_rate: float,
+ poses: wp.array,
+ *,
+ num_frames: int | None = None,
+ foot_contacts: wp.array | None = None,
+ ) -> None:
+ """Create an animation whose frames live in poses.
+
+ Args:
+ joint_names: Names of the joint angles, in storage order.
+ sample_rate: Sample rate in Hz. It must be positive.
+ poses: Float32 Warp array of [capacity, 7 + len(joint_names)] joint
+ coordinates. It is used as is.
+ num_frames: Number of frames in use. None uses the whole capacity.
+ foot_contacts: Predicted foot contacts as a float32 [capacity, 4] array on
+ the same device, or None for clips.
+ """
+ self.joint_names = tuple(joint_names)
+ self.num_dofs = len(self.joint_names)
+ self.num_coordinates = ROOT_COORDINATE_COUNT + self.num_dofs
+ self.sample_rate = float(sample_rate)
+ if self.sample_rate <= 0.0:
+ raise ValueError("sample_rate must be positive.")
+ self.poses = poses
+ if (
+ self.poses.dtype != wp.float32
+ or self.poses.ndim != 2
+ or self.poses.shape[1] != self.num_coordinates
+ ):
+ raise ValueError(f"poses must have shape [capacity, {self.num_coordinates}] and dtype=float32.")
+ validate_foot_contacts(foot_contacts, self.capacity, self.device)
+ self.foot_contacts = foot_contacts
+ self.num_frames = self.capacity if num_frames is None else num_frames
+
+ @property
+ def device(self):
+ """Device of the frame storage."""
+ return self.poses.device
+
+ @property
+ def capacity(self) -> int:
+ """Number of frames the storage holds."""
+ return self.poses.shape[0]
+
+ @property
+ def num_frames(self) -> int:
+ """Number of frames in use, from 0 to capacity."""
+ return self._num_frames
+
+ @num_frames.setter
+ def num_frames(self, frame_count: int) -> None:
+ if not 0 <= frame_count <= self.capacity:
+ raise ValueError(f"num_frames must be in [0, {self.capacity}].")
+ self._num_frames = int(frame_count)
+
+ @property
+ def duration(self) -> float:
+ """Time from the first to the last frame in use, in seconds."""
+ return max(0, self.num_frames - 1) / self.sample_rate
+
+ def root_transforms(self) -> np.ndarray:
+ """Return the root of each frame in use on the host, shaped [num_frames, 7].
+
+ Each row holds the position (XYZ), then the rotation (XYZW).
+ """
+ return self.poses[: self.num_frames, :ROOT_COORDINATE_COUNT].numpy().copy()
+
+ def sample(
+ self,
+ time: float,
+ output_pose: wp.array,
+ *,
+ root_offset: wp.transform = wp.transform_identity(),
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Write the pose sampled at time into output_pose.
+
+ The two nearest frames are blended. Times outside the animation are clamped.
+
+ Args:
+ time: Sample time in seconds.
+ output_pose: Float32 array that receives the joint coordinates of one pose.
+ It can be a view into one robot's joint_q.
+ root_offset: World transform applied to the root. The default leaves the
+ root unchanged.
+ stream: Stream for the work. None uses the current stream.
+ """
+ if self.num_frames == 0:
+ raise ValueError("Cannot sample an empty animation buffer.")
+ if output_pose.dtype != wp.float32 or output_pose.shape != (self.num_coordinates,):
+ raise ValueError(f"output_pose must be a float32 vector of {self.num_coordinates} coordinates.")
+ frame, next_frame, blend = frame_index_from_time(time, self.sample_rate, self.num_frames)
+ wp.launch(
+ _sample_dof_pose_kernel,
+ dim=self.num_coordinates,
+ inputs=[self.poses, frame, next_frame, blend, root_offset],
+ outputs=[output_pose],
+ device=self.device,
+ stream=stream,
+ )
+
+ def sample_foot_contacts(self, time: float, output: wp.array, stream: wp.Stream | None = None) -> None:
+ """Write the four foot contacts sampled at time into output.
+
+ The two nearest frames are blended.
+
+ Args:
+ time: Sample time in seconds.
+ output: Float32 array that receives the four foot contacts.
+ stream: Stream for the work. None uses the current stream.
+ """
+ sample_foot_contacts(self, time, output, stream)
+
+ def copy(self) -> DOFAnimationBuffer:
+ """Return a new animation with copies of the frames in use and their foot contacts."""
+ foot_contacts = None if self.foot_contacts is None else wp.clone(self.foot_contacts[: self.num_frames])
+ return DOFAnimationBuffer(
+ self.joint_names,
+ self.sample_rate,
+ wp.clone(self.poses[: self.num_frames]),
+ foot_contacts=foot_contacts,
+ )
+
+ def make_loopable(self, stream: wp.Stream | None = None) -> None:
+ """Adjust the frames in use so the first and last poses match.
+
+ Each correction grows from zero at the first frame to the full difference at the
+ last frame in use. The root position correction blends linearly, as in endpoint
+ correction.
+
+ Args:
+ stream: Stream for the work. None uses the current stream.
+ """
+ if self.num_frames < 2:
+ return
+ last = self.num_frames - 1
+ root_delta = wp.empty(1, dtype=wp.transform, device=self.device)
+ angle_deltas = wp.empty(self.num_coordinates, dtype=wp.float32, device=self.device)
+ wp.launch(
+ _loop_delta_kernel, dim=self.num_coordinates,
+ inputs=[self.poses, last], outputs=[root_delta, angle_deltas],
+ device=self.device, stream=stream,
+ )
+ wp.launch(
+ _make_loopable_kernel, dim=(self.num_frames, self.num_coordinates),
+ inputs=[root_delta, angle_deltas, last], outputs=[self.poses],
+ device=self.device, stream=stream,
+ )
diff --git a/motionbricks/runtime/__init__.py b/motionbricks/runtime/__init__.py
new file mode 100644
index 0000000..52a7a9d
--- /dev/null
+++ b/motionbricks/runtime/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/motionbricks/runtime/blend_spaces.py b/motionbricks/runtime/blend_spaces.py
new file mode 100644
index 0000000..26db007
--- /dev/null
+++ b/motionbricks/runtime/blend_spaces.py
@@ -0,0 +1,499 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Blend target poses with a 1D blend space or a 2D directional blend space."""
+
+from __future__ import annotations
+
+import math
+from bisect import bisect_left
+from enum import Enum
+
+import warp as wp
+
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT, read_root_transform, write_root_transform
+from motionbricks.utils.pose_utils import (
+ blend_additive_accumulate_transform,
+ blend_additive_end_transform,
+ blend_transform,
+)
+
+
+_EPSILON = 1.0e-6
+
+
+class BlendSpaceType(Enum):
+ """The type of blend space used to compute target poses."""
+
+ LINEAR_1D = "linear_1d"
+ DIRECTIONAL_2D = "directional_2d"
+
+
+class BlendSample:
+ """Blend targets and blend weights that BlendSpace.evaluate() selects.
+
+ indices tells which added targets were selected. data_indices tells where
+ each target's pose data is stored.
+
+ A 2D space without a target at (0, 0) uses the average of all targets as its
+ center. uniform_weight is each target's share of the center's weight.
+ """
+
+ indices: wp.vec3i
+ weights: wp.vec3
+ data_indices: wp.array(dtype=wp.int32)
+ uniform_weight: float
+
+
+def _value_components(value) -> tuple[float, float]:
+ components = float(value[0]), float(value[1])
+ if not all(math.isfinite(component) for component in components):
+ raise ValueError("Blend space values must contain two finite components.")
+ return components
+
+
+class BlendSpace:
+ """Select targets and weights from a 1D value or a 2D direction.
+
+ Add targets with add_target(), call compile() after setup, then use
+ evaluate() to get the targets and weights for each blend.
+
+ A 1D space blends between neighboring values. A 2D directional space blends
+ between neighboring directions and an optional center target at (0, 0).
+ """
+
+ def __init__(self, blend_space_type: BlendSpaceType, device=None) -> None:
+ """Create an empty blend space.
+
+ Args:
+ blend_space_type: LINEAR_1D or DIRECTIONAL_2D.
+ device: Device for new arrays.
+ """
+ self._type = BlendSpaceType(blend_space_type)
+ self._device = wp.get_device(device)
+ self._target_values: list[tuple[float, float]] = []
+ self._target_data_indices: list[int] = []
+ self._data_indices = wp.empty(0, dtype=wp.int32, device=self._device)
+ self._compiled = False
+
+ def add_target(self, value: wp.vec2, data_index: int) -> None:
+ """Add a blend target with its value and its index in the source pose array.
+
+ Args:
+ value: Blend value of the target. A 1D space uses only x. A 2D space reads
+ it as a direction, and (0, 0) marks the center target.
+ data_index: Index of the target's poses in the source pose array. It must be
+ non-negative.
+ """
+ value = _value_components(value)
+ if data_index < 0:
+ raise ValueError("data_index must be non-negative.")
+ self._target_values.append(value)
+ self._target_data_indices.append(data_index)
+ self._compiled = False
+
+ def compile(self) -> None:
+ """Prepare the target lookup used by evaluate().
+
+ Call this after adding the targets, and again if you add more.
+ """
+ self._compiled = False
+ values = self._target_values
+ if not values:
+ raise ValueError("Cannot compile a blend space without targets.")
+
+ if self._type is BlendSpaceType.LINEAR_1D:
+ order = sorted(range(len(values)), key=lambda index: values[index][0])
+ self._keys = tuple(values[index][0] for index in order)
+ if len(set(self._keys)) != len(values):
+ raise ValueError("Blend target values in a 1D blend space must be unique.")
+ self._intervals = tuple(
+ (a, b, values[a][0], 1.0 / (values[b][0] - values[a][0]))
+ for a, b in zip(order, order[1:])
+ )
+ else:
+ centers = [index for index, value in enumerate(values) if value == (0.0, 0.0)]
+ if len(centers) > 1:
+ raise ValueError("A directional blend space can have only one center target.")
+ self._center = centers[0] if centers else -1
+ order = sorted(
+ (index for index in range(len(values)) if index != self._center),
+ key=lambda index: math.atan2(values[index][1], values[index][0]),
+ )
+ self._angles = tuple(math.atan2(values[index][1], values[index][0]) for index in order)
+ self._sectors = []
+ for upper, b in enumerate(order):
+ a = order[upper - 1]
+ gap = (self._angles[upper] - self._angles[upper - 1]) % math.tau
+ if len(order) > 1 and gap < _EPSILON:
+ raise ValueError("Directional targets must have distinct directions.")
+ ax, ay = values[a]
+ bx, by = values[b]
+ determinant = ax * by - ay * bx
+ # A valid sector needs two directions less than 180 degrees apart.
+ if gap >= math.pi or determinant <= 0.0:
+ self._sectors.append(None)
+ continue
+ inverse = (by / determinant, -bx / determinant, -ay / determinant, ax / determinant)
+ slots = (a, b, max(self._center, 0))
+ weight_order = tuple(sorted(range(3), key=lambda slot: slots[slot]))
+ self._sectors.append((inverse, tuple(slots[slot] for slot in weight_order), weight_order))
+ self._data_indices = wp.array(self._target_data_indices, dtype=wp.int32, device=self._device)
+ self._compiled = True
+
+ @property
+ def type(self) -> BlendSpaceType:
+ """Kind of blend space, 1D or 2D directional."""
+ return self._type
+
+ @property
+ def target_count(self) -> int:
+ """Number of added targets."""
+ return len(self._target_values)
+
+ @property
+ def data_indices(self) -> wp.array:
+ """Source pose indices, in the order the targets were added."""
+ return self._data_indices
+
+ @property
+ def device(self):
+ """Device of the blend space's arrays."""
+ return self._device
+
+ def _sample(self, indices=(0, 0, 0), weights=(0.0, 0.0, 0.0), uniform_weight=0.0) -> BlendSample:
+ sample = BlendSample()
+ sample.indices = wp.vec3i(*indices)
+ sample.weights = wp.vec3(*weights)
+ sample.data_indices = self._data_indices
+ sample.uniform_weight = uniform_weight
+ return sample
+
+ def evaluate(self, value: wp.vec2) -> BlendSample:
+ """Select targets and compute their blend weights for the given input.
+
+ 1D targets are ordered from the lower value to the higher one. 2D targets
+ follow the order they were added. Pass the result to a blend function, such as
+ linear_1d_pose_blend(), to compute the final poses.
+
+ Args:
+ value: Blend value. It must be finite. A 1D space clamps x to the target
+ range. A 2D space reads (x, y) as a direction and a distance from the
+ center. Near zero, it selects the center target. Without a center
+ target, every target then gets the same weight.
+ """
+ if not self._compiled:
+ raise RuntimeError("Cannot evaluate before compile(). Call it after adding blend targets.")
+ x, y = _value_components(value)
+ if self.target_count == 1:
+ return self._sample(weights=(1.0, 0.0, 0.0))
+ if self._type is BlendSpaceType.LINEAR_1D:
+ x = min(max(x, self._keys[0]), self._keys[-1])
+ interval = max(0, bisect_left(self._keys, x) - 1)
+ a, b, start, inverse_width = self._intervals[interval]
+ blend = (x - start) * inverse_width
+ return self._sample((a, b, 0), (1.0 - blend, blend, 0.0))
+
+ if abs(x) > _EPSILON or abs(y) > _EPSILON:
+ if self._angles:
+ upper = bisect_left(self._angles, math.atan2(y, x)) % len(self._angles)
+ sector = self._sectors[upper]
+ if sector is not None:
+ inverse, indices, order = sector
+ a = max(0.0, inverse[0] * x + inverse[1] * y)
+ b = max(0.0, inverse[2] * x + inverse[3] * y)
+ total = max(1.0, a + b)
+ a, b = a / total, b / total
+ center = max(0.0, 1.0 - a - b)
+ weights = (a, b, center if self._center >= 0 else 0.0)
+ return self._sample(
+ indices, tuple(weights[slot] for slot in order),
+ center / self.target_count if self._center < 0 else 0.0,
+ )
+ if self._center >= 0:
+ return self._sample((self._center, 0, 0), (1.0, 0.0, 0.0))
+ return self._sample(uniform_weight=1.0 / self.target_count)
+
+
+def _contribution_count(sample: BlendSample):
+ return wp.where(sample.uniform_weight > 0.0, sample.data_indices.shape[0], 3)
+
+
+def _contribution(sample: BlendSample, slot: wp.int32):
+ target = slot
+ weight = sample.uniform_weight
+ if sample.uniform_weight > 0.0:
+ for selected in range(3):
+ if sample.indices[selected] == slot:
+ weight += sample.weights[selected]
+ else:
+ target = sample.indices[slot]
+ weight = sample.weights[slot]
+ return sample.data_indices[target], weight
+
+
+def _prepare_directional_poses_kernel(
+ poses: wp.array3d(dtype=wp.transform),
+ reference_pose: wp.array(dtype=wp.transform),
+):
+ target, frame, joint = wp.tid()
+ pose = poses[target, frame, joint]
+ if wp.dot(reference_pose[joint].q, pose.q) < 0.0:
+ poses[target, frame, joint] = wp.transform(pose.p, -pose.q)
+
+
+def prepare_directional_poses(
+ poses: wp.array, reference_pose: wp.array, stream: wp.Stream | None = None,
+) -> None:
+ """Give target quaternions consistent signs before 2D directional blending.
+
+ Each quaternion takes the sign that matches the reference pose's rotation for its
+ joint. The poses are edited in place.
+
+ Args:
+ poses: Local joint transforms of every target, laid out as [target, frame, joint].
+ reference_pose: Reference pose with one transform per joint.
+ stream: Stream for the work. None uses the current stream.
+ """
+ if poses.ndim != 3 or reference_pose.shape != (poses.shape[2],):
+ raise ValueError("Expected [target, frame, joint] poses and one reference transform per joint.")
+ wp.launch(
+ _prepare_directional_poses_kernel, dim=poses.shape,
+ inputs=[poses, reference_pose], device=poses.device, stream=stream,
+ )
+
+
+def _validate_blend_arrays(data: wp.array, sample: BlendSample, output: wp.array) -> None:
+ """Check that the source and output arrays have compatible shapes."""
+ if data.ndim != 3 or output.ndim != 2:
+ raise ValueError("Blend data must be [target, frame, component] and output [frame, component].")
+ if output.shape[0] < data.shape[1] or output.shape[1] != data.shape[2]:
+ raise ValueError("Blend output must have frame capacity and matching components.")
+ if sample.data_indices.size == 0:
+ raise ValueError("Blending requires registered data indices.")
+
+
+def _linear_1d_pose_blend_kernel(
+ poses: wp.array3d(dtype=wp.transform),
+ sample: BlendSample,
+ output: wp.array2d(dtype=wp.transform),
+):
+ frame, joint = wp.tid()
+ first = sample.data_indices[sample.indices[0]]
+ second = sample.data_indices[sample.indices[1]]
+ blend = sample.weights[1]
+ result = poses[first, frame, joint]
+ if blend >= 1.0:
+ result = poses[second, frame, joint]
+ elif blend > 0.0 and first != second:
+ result = blend_transform(result, poses[second, frame, joint], blend)
+ output[frame, joint] = result
+
+
+def _directional_2d_pose_blend_kernel(
+ poses: wp.array3d(dtype=wp.transform),
+ sample: BlendSample,
+ reference_pose: wp.array(dtype=wp.transform),
+ output: wp.array2d(dtype=wp.transform),
+):
+ frame, joint = wp.tid()
+ accumulated = wp.transform(wp.vec3(0.0), wp.quat(0.0, 0.0, 0.0, 0.0))
+ weight_sum = wp.float32(0.0)
+ for slot in range(_contribution_count(sample)):
+ target, weight = _contribution(sample, slot)
+ if weight > 0.0:
+ accumulated = accumulated + poses[target, frame, joint] * weight
+ weight_sum += weight
+ reference = reference_pose[joint]
+ missing = wp.max(0.0, 1.0 - weight_sum)
+ output[frame, joint] = wp.transform(
+ accumulated.p + reference.p * missing,
+ wp.normalize(accumulated.q + reference.q * missing),
+ )
+
+
+def linear_1d_pose_blend(
+ poses: wp.array,
+ sample: BlendSample,
+ output: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Blend the selected 1D targets into one sequence of local joint transforms.
+
+ Args:
+ poses: Local joint transforms of every target, laid out as [target, frame, joint].
+ sample: Targets and weights from BlendSpace.evaluate().
+ output: Array that receives the blended frames, laid out as [frame, joint]. It
+ needs room for every source frame.
+ stream: Stream for the work. None uses the current stream.
+ """
+ _validate_blend_arrays(poses, sample, output)
+ wp.launch(
+ _linear_1d_pose_blend_kernel,
+ dim=(poses.shape[1], poses.shape[2]),
+ inputs=[poses, sample],
+ outputs=[output],
+ device=output.device,
+ stream=stream,
+ )
+
+
+def directional_2d_pose_blend(
+ poses: wp.array,
+ sample: BlendSample,
+ reference_pose: wp.array,
+ output: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Blend the selected 2D targets into one sequence of local joint transforms.
+
+ Call prepare_directional_poses() on poses once during setup. When the weights add
+ up to less than one, the reference pose supplies the rest.
+
+ Args:
+ poses: Local joint transforms of every target, laid out as [target, frame, joint].
+ sample: Targets and weights from BlendSpace.evaluate().
+ reference_pose: Reference pose with one transform per joint.
+ output: Array that receives the blended frames, laid out as [frame, joint]. It
+ needs room for every source frame.
+ stream: Stream for the work. None uses the current stream.
+ """
+ _validate_blend_arrays(poses, sample, output)
+ if reference_pose.shape != (poses.shape[2],):
+ raise ValueError("reference_pose must contain one transform per joint.")
+ wp.launch(
+ _directional_2d_pose_blend_kernel,
+ dim=(poses.shape[1], poses.shape[2]),
+ inputs=[poses, sample, reference_pose],
+ outputs=[output],
+ device=output.device,
+ stream=stream,
+ )
+
+
+def _linear_1d_dof_blend_kernel(
+ joint_q: wp.array3d(dtype=wp.float32),
+ sample: BlendSample,
+ output: wp.array2d(dtype=wp.float32),
+):
+ frame, coordinate = wp.tid()
+ if coordinate == 0 or coordinate >= ROOT_COORDINATE_COUNT:
+ first = sample.data_indices[sample.indices[0]]
+ second = sample.data_indices[sample.indices[1]]
+ blend = sample.weights[1]
+ if coordinate == 0:
+ root = read_root_transform(joint_q, first, frame)
+ if blend >= 1.0:
+ root = read_root_transform(joint_q, second, frame)
+ elif blend > 0.0 and first != second:
+ root = blend_transform(root, read_root_transform(joint_q, second, frame), blend)
+ write_root_transform(root, output, frame)
+ else:
+ value = joint_q[first, frame, coordinate]
+ if blend >= 1.0:
+ value = joint_q[second, frame, coordinate]
+ elif blend > 0.0:
+ value = wp.lerp(value, joint_q[second, frame, coordinate], blend)
+ output[frame, coordinate] = value
+
+
+def _directional_2d_dof_blend_kernel(
+ joint_q: wp.array3d(dtype=wp.float32),
+ sample: BlendSample,
+ reference_joint_q: wp.array(dtype=wp.float32),
+ output: wp.array2d(dtype=wp.float32),
+):
+ frame, coordinate = wp.tid()
+ if coordinate == 0:
+ accumulated = wp.transform(wp.vec3(0.0), wp.quat(0.0, 0.0, 0.0, 0.0))
+ weight_sum = wp.float32(0.0)
+ for slot in range(_contribution_count(sample)):
+ target, weight = _contribution(sample, slot)
+ if weight > 0.0:
+ accumulated = blend_additive_accumulate_transform(
+ accumulated, read_root_transform(joint_q, target, frame), weight,
+ )
+ weight_sum += weight
+ reference_root = read_root_transform(reference_joint_q)
+ write_root_transform(blend_additive_end_transform(accumulated, reference_root, weight_sum), output, frame)
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ value = wp.float32(0.0)
+ weight_sum = wp.float32(0.0)
+ for slot in range(_contribution_count(sample)):
+ target, weight = _contribution(sample, slot)
+ if weight > 0.0:
+ value += joint_q[target, frame, coordinate] * weight
+ weight_sum += weight
+ output[frame, coordinate] = value + reference_joint_q[coordinate] * wp.max(0.0, 1.0 - weight_sum)
+
+
+def linear_1d_dof_blend(
+ joint_q: wp.array,
+ sample: BlendSample,
+ output: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Blend the selected 1D targets into one sequence of joint coordinates.
+
+ Args:
+ joint_q: Joint coordinates of every target, laid out as [target, frame,
+ coordinate]. Each frame starts with the root position and XYZW quaternion.
+ sample: Targets and weights from BlendSpace.evaluate().
+ output: Array that receives the blended frames, laid out as [frame, coordinate].
+ It needs room for every source frame.
+ stream: Stream for the work. None uses the current stream.
+ """
+ _validate_blend_arrays(joint_q, sample, output)
+ if joint_q.shape[2] < ROOT_COORDINATE_COUNT:
+ raise ValueError(
+ "joint_q must contain the root position and XYZW quaternion before the joint angles."
+ )
+ wp.launch(
+ _linear_1d_dof_blend_kernel,
+ dim=(joint_q.shape[1], joint_q.shape[2]),
+ inputs=[joint_q, sample],
+ outputs=[output],
+ device=output.device,
+ stream=stream,
+ )
+
+
+def directional_2d_dof_blend(
+ joint_q: wp.array,
+ sample: BlendSample,
+ reference_joint_q: wp.array,
+ output: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Blend the selected 2D targets into one sequence of joint coordinates.
+
+ When the weights add up to less than one, reference_joint_q supplies the rest.
+
+ Args:
+ joint_q: Joint coordinates of every target, laid out as [target, frame,
+ coordinate]. Each frame starts with the root position and XYZW quaternion.
+ sample: Targets and weights from BlendSpace.evaluate().
+ reference_joint_q: Joint coordinates of the reference pose.
+ output: Array that receives the blended frames, laid out as [frame, coordinate].
+ It needs room for every source frame.
+ stream: Stream for the work. None uses the current stream.
+ """
+ _validate_blend_arrays(joint_q, sample, output)
+ if joint_q.shape[2] < ROOT_COORDINATE_COUNT or reference_joint_q.shape != (joint_q.shape[2],):
+ raise ValueError("reference_joint_q must hold the root position, XYZW quaternion, and joint angles.")
+ wp.launch(
+ _directional_2d_dof_blend_kernel,
+ dim=(joint_q.shape[1], joint_q.shape[2]),
+ inputs=[joint_q, sample, reference_joint_q],
+ outputs=[output],
+ device=output.device,
+ stream=stream,
+ )
diff --git a/motionbricks/runtime/motion_player.py b/motionbricks/runtime/motion_player.py
new file mode 100644
index 0000000..1812534
--- /dev/null
+++ b/motionbricks/runtime/motion_player.py
@@ -0,0 +1,206 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Playback and context history for motion generated by MotionBricks."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import replace
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.config import MotionBricksInferenceConfig
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.model.soma.buffers import PoseToken
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+from motionbricks.runtime.motion_recorder import MotionRecorder
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+from motionbricks.utils.pose_utils import sample_root_position
+
+
+class _GeneratedMotionPlayer:
+ """Manage generation, playback timing, and recorded motion."""
+
+ def __init__(self, engine, context, target, output, motion_history) -> None:
+ self.engine = engine
+ self.context = context
+ self.target = target
+ self.output = output
+ self.motion_history = motion_history
+
+ self.playback_time = 0.0
+ # The current target's transition point, in frames before the end of its motion.
+ self.transition_early_by_frames = 0
+ self._generated_root_positions = np.zeros((1, 3), dtype=np.float32)
+
+ @property
+ def playback_duration(self) -> float:
+ """Playback time of the transition point."""
+
+ end_frame = max(0, self.output.num_frames - 1 - self.transition_early_by_frames)
+ return end_frame / self.output.sample_rate
+
+ @property
+ def time_to_transition(self) -> float:
+ """Seconds until the transition point. Sampling can continue past it."""
+
+ return max(0.0, self.playback_duration - self.playback_time)
+
+ def generate(
+ self,
+ target_poses: wp.array,
+ inference_params: TargetPoseInferenceParams,
+ *,
+ config: MotionBricksInferenceConfig | None = None,
+ ) -> None:
+ """Generate toward a target from the recorded history, then restart playback.
+
+ Args:
+ target_poses: The target's poses. Local joint transforms for SOMA, or joint
+ coordinates for G1.
+ inference_params: Generation settings of the target. Its num_poses_to_use
+ sets how many target poses inform the model. Its
+ transition_early_by_frames sets the transition point. Its
+ allowed_token_counts, when set, replaces the counts in config.
+ config: Other generation settings. None uses the defaults.
+ """
+
+ generation_config = config if config is not None else MotionBricksInferenceConfig()
+ if inference_params.allowed_token_counts is not None:
+ generation_config = replace(
+ generation_config, allowed_token_counts=inference_params.allowed_token_counts,
+ )
+ self.target.update_from_poses(
+ target_poses[: inference_params.num_poses_to_use],
+ stream=self.engine.stream,
+ )
+ self.transition_early_by_frames = inference_params.transition_early_by_frames
+ self.refresh_context()
+ self.engine.generate_animation(
+ self.context,
+ self.target,
+ self.output,
+ config=generation_config,
+ )
+ self.playback_time = 0.0
+ self._generated_root_positions = self.output.root_transforms()[:, :3]
+
+ def sample(self, delta_time: float, destination_pose: wp.array, destination_foot_contacts: wp.array) -> None:
+ """Advance playback, then write the pose and its foot contacts.
+
+ Args:
+ delta_time: Time to advance, in seconds. It must be finite and non-negative.
+ destination_pose: Array that receives the pose at the new playback time.
+ destination_foot_contacts: Array that receives the four foot contacts at that
+ time.
+ """
+
+ if not math.isfinite(delta_time) or delta_time < 0.0:
+ raise ValueError("delta_time must be finite and non-negative.")
+ self.playback_time += delta_time
+ self.output.sample(
+ self.playback_time,
+ destination_pose,
+ stream=self.engine.stream,
+ )
+ self.output.sample_foot_contacts(
+ self.playback_time,
+ destination_foot_contacts,
+ stream=self.engine.stream,
+ )
+
+ def record_pose(self, delta_time: float, pose: wp.array) -> None:
+ """Record an evaluated character pose for the next generation context.
+
+ Args:
+ delta_time: Time since the previous recorded pose, in seconds. It must be
+ finite and positive.
+ pose: The character's pose. Local joint transforms for SOMA, or joint
+ coordinates for G1.
+ """
+
+ self.motion_history.record(
+ delta_time,
+ pose,
+ stream=self.engine.stream,
+ )
+
+ def seed_history_from_pose(self, pose: wp.array) -> None:
+ """Fill every history slot and the context with one pose.
+
+ Args:
+ pose: Local joint transforms for SOMA, or joint coordinates for G1.
+ """
+
+ self.motion_history.fill(pose, stream=self.engine.stream)
+ self.refresh_context()
+
+ def refresh_context(self) -> None:
+ """Update context poses from the recorded playback history."""
+
+ self.context.update_from_recorder(
+ self.motion_history,
+ stream=self.engine.stream,
+ )
+
+ def current_root_position(self) -> np.ndarray:
+ """Interpolate the generated root position at the playback time."""
+
+ return sample_root_position(
+ self._generated_root_positions, self.playback_time, self.output.sample_rate,
+ )
+
+
+class GeneratedMotionPlayer(_GeneratedMotionPlayer):
+ """Play SOMA motion generated from recorded poses and targets."""
+
+ context: PoseToken
+ target: PoseToken
+ output: AnimationBuffer
+
+ def __init__(self, engine: MotionBricksSOMAEngine, skeleton: Skeleton, *, history_capacity: int = 32) -> None:
+ """Create the context token, target token, output buffer, and motion history.
+
+ Args:
+ engine: SOMA engine that generates the motion. Playback and recording use
+ its stream.
+ skeleton: Skeleton of the generated motion. Its reference pose fills the
+ history until poses are recorded.
+ history_capacity: Number of recent poses kept for the context.
+ """
+ super().__init__(
+ engine,
+ engine.create_input(skeleton),
+ engine.create_input(skeleton),
+ engine.create_output(skeleton),
+ MotionRecorder(skeleton.reference_local_transforms, capacity=history_capacity, stream=engine.stream),
+ )
+
+
+class GeneratedDOFMotionPlayer(_GeneratedMotionPlayer):
+ """Play G1 motion generated from recorded poses and targets."""
+
+ def __init__(self, engine: MotionBricksUnitreeG1Engine, reference_joint_q: wp.array, *, history_capacity: int = 32):
+ """Create the context token, target token, output buffer, and motion history.
+
+ Args:
+ engine: G1 engine that generates the motion. Playback and recording use its
+ stream.
+ reference_joint_q: Joint coordinates of the reference pose. They fill the
+ history until poses are recorded.
+ history_capacity: Number of recent poses kept for the context.
+ """
+ super().__init__(
+ engine,
+ engine.create_input(),
+ engine.create_input(),
+ engine.create_output(),
+ MotionRecorder(reference_joint_q, capacity=history_capacity, stream=engine.stream),
+ )
+
+
+__all__ = ["GeneratedMotionPlayer", "GeneratedDOFMotionPlayer"]
diff --git a/motionbricks/runtime/motion_recorder.py b/motionbricks/runtime/motion_recorder.py
new file mode 100644
index 0000000..4050768
--- /dev/null
+++ b/motionbricks/runtime/motion_recorder.py
@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Record playback poses for use as model context."""
+
+from typing import Any
+
+import numpy as np
+import warp as wp
+
+from motionbricks.utils.pose_utils import fill_poses
+
+
+def _shift_and_store_kernel(
+ pose: wp.array(dtype=Any),
+ history: wp.array2d(dtype=Any),
+):
+ joint = wp.tid()
+ for frame in range(history.shape[0] - 1):
+ history[frame, joint] = history[frame + 1, joint]
+ history[history.shape[0] - 1, joint] = pose[joint]
+
+
+class MotionRecorder:
+ """Store a fixed number of recent poses and their frame durations.
+
+ poses holds the recorded poses, oldest first, one row per history slot. They keep
+ the reference pose's layout: local joint transforms for SOMA, or joint coordinates
+ for G1. delta_times holds the time from each pose to the next, in seconds. The
+ latest pose's value is always zero. Unrecorded slots hold the pose from the last
+ fill() with zero duration. Recording shifts out the oldest pose and adds the newest
+ at the end.
+ """
+
+ def __init__(
+ self,
+ reference_pose: wp.array,
+ capacity: int = 32,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Fill the history with the reference pose.
+
+ Args:
+ reference_pose: Pose that sets the layout and fills the history, such as a
+ skeleton's reference local transforms or a robot's reference joint
+ coordinates.
+ capacity: Number of recent poses kept. It must be positive.
+ stream: Stream for the work. None uses the current stream.
+ """
+ if capacity <= 0:
+ raise ValueError("capacity must be positive.")
+
+ self.capacity = capacity
+ self.poses = wp.empty(
+ (self.capacity, reference_pose.shape[0]),
+ dtype=reference_pose.dtype,
+ device=reference_pose.device,
+ )
+ self.delta_times = np.zeros(self.capacity, dtype=np.float32)
+ self.fill(reference_pose, stream)
+
+ def fill(self, pose: wp.array, stream: wp.Stream | None = None) -> None:
+ """Fill every slot with one pose and zero durations, as if the character held it.
+
+ Args:
+ pose: Pose to store, with the reference pose's shape and dtype.
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._check_pose(pose)
+ fill_poses(pose, self.poses, stream)
+ self.delta_times.fill(0.0)
+
+ def record(
+ self,
+ delta_time: float,
+ pose: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Store a pose sampled delta_time seconds after the previous pose.
+
+ Args:
+ delta_time: Time since the previous pose, in seconds. It must be finite and
+ positive.
+ pose: Pose to store, as local joint transforms or joint coordinates, with the
+ reference pose's shape and dtype.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ dt = np.float32(delta_time)
+ self._check_pose(pose)
+ if not np.isfinite(dt) or dt <= 0.0:
+ raise ValueError("delta_time must be finite and positive.")
+
+ self.delta_times[-1] = dt
+ self.delta_times[:-1] = self.delta_times[1:]
+ self.delta_times[-1] = 0.0
+ wp.launch(
+ _shift_and_store_kernel,
+ dim=self.poses.shape[1],
+ inputs=[pose],
+ outputs=[self.poses],
+ stream=stream,
+ )
+
+ def _check_pose(self, pose: wp.array) -> None:
+ if pose.dtype != self.poses.dtype or pose.shape != (self.poses.shape[1],):
+ raise ValueError("pose must match the reference pose's shape and dtype.")
diff --git a/motionbricks/runtime/pivot.py b/motionbricks/runtime/pivot.py
new file mode 100644
index 0000000..a594e07
--- /dev/null
+++ b/motionbricks/runtime/pivot.py
@@ -0,0 +1,288 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Move and turn a Smart Primitive pivot to match the character's approach."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import math
+from typing import TYPE_CHECKING
+
+import warp as wp
+
+from motionbricks.utils.math_utils import wrap_angle
+
+if TYPE_CHECKING:
+ from motionbricks.runtime.smart_primitive import CharacterProperties
+
+
+class Axis(Enum):
+ """Local axis of a pivot rule. NONE turns the rule off."""
+
+ NONE = "none"
+ X = "x"
+ Y = "y"
+ Z = "z"
+
+
+class ConstraintType(Enum):
+ """Limit of a pivot rule.
+
+ Translation allows LINE_PROJECTION. Rotation allows CONE.
+ """
+
+ UNCONSTRAINED = "unconstrained"
+ CONE = "cone"
+ LINE_PROJECTION = "line_projection"
+
+
+class ConeSide(Enum):
+ """Where the rotation cone points, relative to the motion direction."""
+
+ FORWARD = "forward"
+ MIRRORED = "mirrored"
+ BOTH = "both"
+
+
+class OperationOrder(Enum):
+ """Order in which a pivot applies its translation and rotation."""
+
+ TRANSLATION_THEN_ROTATION = "translation_then_rotation"
+ ROTATION_THEN_TRANSLATION = "rotation_then_translation"
+
+
+_AXIS_VECTORS = {
+ Axis.X: wp.vec3(1.0, 0.0, 0.0),
+ Axis.Y: wp.vec3(0.0, 1.0, 0.0),
+ Axis.Z: wp.vec3(0.0, 0.0, 1.0),
+}
+
+
+@dataclass
+class Pivot:
+ """Rules that move and turn a pivot node before its sequence plays.
+
+ The rules measure from the pivot's authored world transform. Moving the pivot does
+ not move its limits, so repeated alignments never drift. Axes are local to the
+ authored transform, so tilting the node tilts its rules. Invalid settings raise
+ ValueError.
+
+ Attributes:
+ motion_direction: Local direction that lines up with the approach. It is
+ stored at unit length.
+ operation_order: Whether translation or rotation comes first. Rotating first
+ also turns the line the pivot slides along.
+ translation_axis: Local axis the pivot slides along. NONE keeps its position.
+ translation_constraint: UNCONSTRAINED or LINE_PROJECTION. LINE_PROJECTION keeps
+ the pivot between the line offsets.
+ line_min_offset: Start of the line, in meters from the authored position.
+ line_max_offset: End of the line, in meters from the authored position. It must
+ be at least line_min_offset.
+ rotation_axis: Local axis the pivot turns around. NONE keeps its rotation.
+ rotation_constraint: UNCONSTRAINED or CONE.
+ cone_half_angle_degrees: Allowed turn to each side of the cone's center, from 0
+ to 180 degrees.
+ cone_side: FORWARD centers the cone on motion_direction. MIRRORED centers it on
+ the opposite direction. BOTH allows either cone.
+ """
+
+ motion_direction: tuple[float, float, float] = (0.0, 1.0, 0.0)
+ operation_order: OperationOrder = OperationOrder.TRANSLATION_THEN_ROTATION
+ translation_axis: Axis = Axis.NONE
+ translation_constraint: ConstraintType = ConstraintType.UNCONSTRAINED
+ line_min_offset: float = -0.5
+ line_max_offset: float = 0.5
+ rotation_axis: Axis = Axis.NONE
+ rotation_constraint: ConstraintType = ConstraintType.UNCONSTRAINED
+ cone_half_angle_degrees: float = 45.0
+ cone_side: ConeSide = ConeSide.FORWARD
+
+ def __post_init__(self) -> None:
+ self.set_motion_direction(self.motion_direction)
+ self.validate()
+
+ def validate(self) -> None:
+ """Check the settings, and raise ValueError for any that are invalid."""
+ if self.translation_constraint not in (ConstraintType.UNCONSTRAINED, ConstraintType.LINE_PROJECTION):
+ raise ValueError("Translation only supports Unconstrained or Line Projection.")
+ if self.rotation_constraint not in (ConstraintType.UNCONSTRAINED, ConstraintType.CONE):
+ raise ValueError("Rotation only supports Unconstrained or Cone.")
+ if (
+ not all(math.isfinite(offset) for offset in (self.line_min_offset, self.line_max_offset))
+ or self.line_min_offset > self.line_max_offset
+ ):
+ raise ValueError("Line offsets must be finite, with Min Offset <= Max Offset.")
+ if not math.isfinite(self.cone_half_angle_degrees) or not 0.0 <= self.cone_half_angle_degrees <= 180.0:
+ raise ValueError("Cone Half Angle must be between 0 and 180 degrees.")
+
+ def set_motion_direction(self, direction) -> None:
+ """Store direction at unit length.
+
+ Args:
+ direction: Three finite numbers, not all zero. Invalid input raises
+ ValueError and keeps the stored direction.
+ """
+ if len(direction) != 3:
+ raise ValueError("Motion Direction must contain three numbers.")
+ length = math.hypot(*direction)
+ if not math.isfinite(length) or length == 0.0:
+ raise ValueError("Motion Direction must be finite and non-zero.")
+ self.motion_direction = tuple(float(value / length) for value in direction)
+
+ def line_endpoints(self, limits_transform: wp.transform) -> tuple[wp.vec3, wp.vec3]:
+ """Return both ends of the line the pivot slides along, in world space.
+
+ The pivot must have a translation axis.
+
+ Args:
+ limits_transform: Transform the limits measure from, normally the pivot's
+ authored world transform.
+ """
+ direction = wp.transform_vector(limits_transform, _AXIS_VECTORS[self.translation_axis])
+ return (
+ limits_transform.p + self.line_min_offset * direction,
+ limits_transform.p + self.line_max_offset * direction,
+ )
+
+ def aligned_transform(
+ self,
+ authored_world_transform: wp.transform,
+ current_world_transform: wp.transform,
+ character: CharacterProperties,
+ ) -> wp.transform:
+ """Return the pivot's world transform aligned to the character's approach.
+
+ An axis set to NONE keeps the current position or rotation.
+
+ Args:
+ authored_world_transform: The pivot's authored world transform. The limits
+ measure from it.
+ current_world_transform: The pivot's world transform before this alignment.
+ character: The approaching character. Line projection uses its probe segment.
+ The other rules use its position and desired velocity.
+ """
+ limits_transform = authored_world_transform
+ position = current_world_transform.p
+ rotation = current_world_transform.q
+
+ if self.operation_order is OperationOrder.ROTATION_THEN_TRANSLATION:
+ rotation = self._aligned_rotation(limits_transform, rotation, character)
+ if self.rotation_axis is not Axis.NONE:
+ limits_transform = wp.transform(limits_transform.p, rotation)
+ position = self._aligned_position(limits_transform, position, character)
+ else:
+ position = self._aligned_position(limits_transform, position, character)
+ rotation = self._aligned_rotation(limits_transform, rotation, character)
+ return wp.transform(position, rotation)
+
+ def _aligned_position(
+ self,
+ limits_transform: wp.transform,
+ current_position: wp.vec3,
+ character: CharacterProperties,
+ ) -> wp.vec3:
+ if self.translation_axis is Axis.NONE:
+ return current_position
+ if self.translation_constraint is ConstraintType.LINE_PROJECTION:
+ line_start, line_end = self.line_endpoints(limits_transform)
+ approach_start, approach_end = character.probe_segment
+ return _closest_point_to_segment(
+ line_start, line_end, wp.vec3(*approach_start), wp.vec3(*approach_end),
+ )
+
+ # Without line limits, the pivot can slide any distance along its axis.
+ character_position = wp.vec3(*character.position)
+ desired = wp.vec3(*character.desired_velocity)
+ origin = limits_transform.p
+ axis = wp.normalize(wp.transform_vector(limits_transform, _AXIS_VECTORS[self.translation_axis]))
+ relative = character_position - origin
+ nearest_offset = float(wp.dot(relative, axis))
+ offset = nearest_offset
+ speed = float(wp.length(desired))
+ if math.isfinite(speed) and speed > 1.0e-6:
+ ray = desired / speed
+ cosine = float(wp.dot(axis, ray))
+ denominator = 1.0 - cosine * cosine
+ if denominator > 1.0e-6:
+ offset = (nearest_offset - cosine * float(wp.dot(relative, ray))) / denominator
+ if wp.dot(origin + offset * axis - character_position, ray) < 0.0:
+ offset = nearest_offset
+ return origin + offset * axis
+
+ def _aligned_rotation(
+ self,
+ limits_transform: wp.transform,
+ current_rotation: wp.quat,
+ character: CharacterProperties,
+ ) -> wp.quat:
+ if self.rotation_axis is Axis.NONE:
+ return current_rotation
+
+ axis = wp.normalize(wp.transform_vector(limits_transform, _AXIS_VECTORS[self.rotation_axis]))
+ motion = wp.transform_vector(limits_transform, wp.vec3(*self.motion_direction))
+ # Movement along the rotation axis cannot tell us which way to turn.
+ motion = motion - wp.dot(motion, axis) * axis
+ desired = wp.vec3(*character.desired_velocity)
+ desired = desired - wp.dot(desired, axis) * axis
+ for length in (wp.length(motion), wp.length(desired)):
+ if not math.isfinite(length) or length <= 1.0e-6:
+ return current_rotation
+
+ angle = math.atan2(wp.dot(axis, wp.cross(motion, desired)), wp.dot(motion, desired))
+ if self.rotation_constraint is ConstraintType.CONE:
+ half_angle = math.radians(self.cone_half_angle_degrees)
+ # Find the nearest allowed heading, checking both cones when enabled.
+ centers = (0.0, math.pi) if self.cone_side is ConeSide.BOTH else (
+ math.pi if self.cone_side is ConeSide.MIRRORED else 0.0,
+ )
+ candidates = []
+ for center in centers:
+ delta = wrap_angle(angle - center)
+ clamped = max(-half_angle, min(half_angle, delta))
+ candidates.append((abs(delta - clamped), center + clamped))
+ angle = min(candidates, key=lambda candidate: candidate[0])[1]
+ turn = wp.quat_from_axis_angle(axis, angle)
+ return wp.mul(turn, limits_transform.q)
+
+
+def _closest_point_on_segment(start: wp.vec3, end: wp.vec3, point: wp.vec3) -> wp.vec3:
+ segment = end - start
+ t = wp.dot(point - start, segment) / (wp.length_sq(segment) + 1.0e-6)
+ return start + min(max(t, 0.0), 1.0) * segment
+
+
+def _half_length_and_direction(start: wp.vec3, end: wp.vec3) -> tuple[float, wp.vec3]:
+ vector = end - start
+ length = wp.length(vector)
+ return 0.5 * length, vector / length if length > 0.0 else vector
+
+
+def _closest_point_to_segment(
+ start: wp.vec3, end: wp.vec3, other_start: wp.vec3, other_end: wp.vec3,
+) -> wp.vec3:
+ """Return the point between start and end that is closest to the other segment."""
+ half_length, direction = _half_length_and_direction(start, end)
+ other_half_length, other_direction = _half_length_and_direction(other_start, other_end)
+ center = start + half_length * direction
+ other_center = other_start + other_half_length * other_direction
+ offset = center - other_center
+ cosine = wp.dot(direction, other_direction)
+ along = wp.dot(direction, offset)
+ other_along = wp.dot(other_direction, offset)
+ # The bias keeps parallel segments finite. Any point where they overlap is closest.
+ t = (cosine * other_along - along) / (1.0 - cosine * cosine + 1.0e-6)
+ other_t = other_along + cosine * t
+ point = center + min(max(t, -half_length), half_length) * direction
+ other_point = other_center + min(max(other_t, -other_half_length), other_half_length) * other_direction
+ # Clamping can leave one point off the closest pair. Project each point onto the
+ # other segment, and keep the pair that ends up closer.
+ projected = _closest_point_on_segment(start, end, other_point)
+ other_projected = _closest_point_on_segment(other_start, other_end, point)
+ if wp.length_sq(other_point - projected) < wp.length_sq(point - other_projected):
+ return projected
+ return point
+
+
+__all__ = ["Axis", "ConeSide", "ConstraintType", "OperationOrder", "Pivot"]
diff --git a/motionbricks/runtime/smart_primitive.py b/motionbricks/runtime/smart_primitive.py
new file mode 100644
index 0000000..43af28f
--- /dev/null
+++ b/motionbricks/runtime/smart_primitive.py
@@ -0,0 +1,913 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Smart Primitive assets, and the runtime instances that share them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+import numpy as np
+import warp as wp
+
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, ModelRig
+from motionbricks.runtime.pivot import Pivot
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+from motionbricks.utils import pose_utils
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT, read_root_transform, write_root_transform
+
+
+@dataclass(frozen=True, slots=True)
+class CharacterProperties:
+ """Character values in world space, for Smart Primitive behaviors.
+
+ Attributes:
+ position: Character position on the ground, in meters.
+ velocity: Actual velocity of the character, in m/s.
+ facing: Direction the character faces on the ground, for custom behaviors.
+ desired_velocity: Velocity the character aims for, in m/s.
+ probe_segment: Near and far ends of the character's probe box on the
+ ground.
+ """
+
+ position: np.ndarray
+ velocity: np.ndarray
+ facing: np.ndarray
+ desired_velocity: np.ndarray
+ probe_segment: tuple[np.ndarray, np.ndarray]
+
+
+@dataclass(frozen=True, slots=True)
+class SmartPrimitiveSequence:
+ """Target nodes in playback order, with their approach settings.
+
+ Attributes:
+ name: Name of the sequence.
+ node_indices: Target nodes in playback order.
+ start_speed: Authored speed of the first target pose, in m/s.
+ pivot_node_index: Node whose pivot aligns the sequence, or -1 without one.
+ """
+
+ name: str
+ node_indices: tuple[int, ...]
+ start_speed: float
+ pivot_node_index: int = -1
+
+
+@dataclass(frozen=True, slots=True)
+class SmartPrimitiveData:
+ """Sampled poses and metadata used to build a runtime asset.
+
+ Node zero is the root node. Each parent comes before its children. Component and
+ sequence references use these node indices.
+
+ Attributes:
+ rig: Rig of the sampled poses.
+ node_local_transforms: Each node's transform relative to its parent, as 7
+ values: position, then XYZW quaternion.
+ node_parent_indices: Each node's parent index, or -1 for the root node.
+ node_names: Display name of each node.
+ target_node_indices: Node of each target.
+ target_poses: Four poses per target, in target order. SOMA stores local joint
+ transforms as [poses, joints, 7]. G1 stores joint coordinates as [poses,
+ coordinates]. Both store the root transform first.
+ target_inference_params: Generation settings of each target.
+ box_node_indices: Node of each interaction box.
+ box_half_extents: Half size of each interaction box along its node's axes, in
+ meters.
+ pivot_node_indices: Node of each pivot.
+ pivots: Pivot rules, in the order of pivot_node_indices.
+ sequences: Sequences in authored order. Their steps keep their authored order.
+ """
+
+ rig: ModelRig
+ node_local_transforms: np.ndarray
+ node_parent_indices: np.ndarray
+ node_names: tuple[str, ...]
+ target_node_indices: np.ndarray
+ target_poses: np.ndarray
+ target_inference_params: tuple[TargetPoseInferenceParams, ...]
+ box_node_indices: np.ndarray
+ box_half_extents: np.ndarray
+ pivot_node_indices: np.ndarray
+ pivots: tuple[Pivot, ...]
+ sequences: tuple[SmartPrimitiveSequence, ...]
+
+
+class InteractionBox:
+ """Oriented box for interaction boxes and the probe box.
+
+ Attributes:
+ transform: Transform of the box center.
+ half_extents: Half size along each of the box's axes, in meters.
+ """
+
+ transform: wp.transform
+ half_extents: wp.vec3
+
+
+def _set_local_transform_kernel(
+ node_index: wp.int32,
+ transform: wp.transform,
+ local_transforms: wp.array(dtype=wp.transform),
+):
+ local_transforms[node_index] = transform
+
+
+def _set_world_transform_kernel(
+ node_index: wp.int32,
+ transform: wp.transform,
+ parent_indices: wp.array(dtype=wp.int32),
+ world_transforms: wp.array(dtype=wp.transform),
+ local_transforms: wp.array(dtype=wp.transform),
+):
+ parent_index = parent_indices[node_index]
+ if parent_index < 0:
+ local_transforms[node_index] = transform
+ else:
+ local_transforms[node_index] = wp.mul(
+ wp.transform_inverse(world_transforms[parent_index]),
+ transform,
+ )
+
+
+def _write_skeleton_target_poses_kernel(
+ source_frame_offset: wp.int32,
+ node_index: wp.int32,
+ node_transforms: wp.array(dtype=wp.transform),
+ target_poses: wp.array2d(dtype=wp.transform),
+ output_poses: wp.array2d(dtype=wp.transform),
+):
+ frame, joint = wp.tid()
+ transform = target_poses[source_frame_offset + frame, joint]
+ # Joint 0 is the root, which the node places.
+ if joint == 0:
+ transform = wp.mul(node_transforms[node_index], transform)
+ output_poses[frame, joint] = transform
+
+
+def _write_dof_target_poses_kernel(
+ source_frame_offset: wp.int32,
+ node_index: wp.int32,
+ node_transforms: wp.array(dtype=wp.transform),
+ target_poses: wp.array2d(dtype=wp.float32),
+ output_poses: wp.array2d(dtype=wp.float32),
+):
+ frame, coordinate = wp.tid()
+ source_frame = source_frame_offset + frame
+ if coordinate == 0:
+ root = wp.mul(node_transforms[node_index], read_root_transform(target_poses, source_frame))
+ write_root_transform(root, output_poses, frame)
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ output_poses[frame, coordinate] = target_poses[source_frame, coordinate]
+
+
+def _write_interaction_boxes_kernel(
+ box_offset: wp.int32,
+ box_node_indices: wp.array(dtype=wp.int32),
+ node_transforms: wp.array(dtype=wp.transform),
+ box_half_extents: wp.array(dtype=wp.vec3),
+ output_boxes: wp.array(dtype=InteractionBox),
+):
+ output_index = wp.tid()
+ box_index = box_offset + output_index
+ box = InteractionBox()
+ box.transform = node_transforms[box_node_indices[box_index]]
+ box.half_extents = box_half_extents[box_index]
+ output_boxes[output_index] = box
+
+
+def _boxes_overlap(a: InteractionBox, b: InteractionBox) -> bool:
+ """Test two oriented boxes on every separating axis. Touching boxes overlap."""
+ rotation_a = wp.quat_to_matrix(a.transform.q)
+ # Express b's axes and center in a's local space.
+ r = wp.mul(wp.transpose(rotation_a), wp.quat_to_matrix(b.transform.q))
+ t = wp.mul(wp.transpose(rotation_a), b.transform.p - a.transform.p)
+ ea = a.half_extents
+ eb = b.half_extents
+ # A small bias keeps nearly parallel edges from reporting a false gap.
+ abs_r = wp.mat33()
+ for i in range(3):
+ for j in range(3):
+ abs_r[i, j] = wp.abs(r[i, j]) + 1.0e-6
+
+ for i in range(3):
+ if wp.abs(t[i]) > ea[i] + eb[0] * abs_r[i, 0] + eb[1] * abs_r[i, 1] + eb[2] * abs_r[i, 2]:
+ return False
+ for j in range(3):
+ distance = wp.abs(t[0] * r[0, j] + t[1] * r[1, j] + t[2] * r[2, j])
+ if distance > ea[0] * abs_r[0, j] + ea[1] * abs_r[1, j] + ea[2] * abs_r[2, j] + eb[j]:
+ return False
+ for i in range(3):
+ i1 = (i + 1) % 3
+ i2 = (i + 2) % 3
+ for j in range(3):
+ j1 = (j + 1) % 3
+ j2 = (j + 2) % 3
+ radius_a = ea[i1] * abs_r[i2, j] + ea[i2] * abs_r[i1, j]
+ radius_b = eb[j1] * abs_r[i, j2] + eb[j2] * abs_r[i, j1]
+ if wp.abs(t[i2] * r[i1, j] - t[i1] * r[i2, j]) > radius_a + radius_b:
+ return False
+ return True
+
+
+def _test_interaction_box_overlap_kernel(
+ interaction_boxes: wp.array(dtype=InteractionBox),
+ probe_box: wp.array(dtype=InteractionBox),
+ overlap_results: wp.array(dtype=wp.int32),
+):
+ box_index = wp.tid()
+ overlap_results[box_index] = wp.where(
+ _boxes_overlap(interaction_boxes[box_index], probe_box[0]), 1, 0,
+ )
+
+
+def compute_interaction_box_overlaps(
+ interaction_boxes: wp.array,
+ probe_box: wp.array,
+ overlap_results: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Test every interaction box against the character's probe box, without waiting.
+
+ Touching boxes count as overlapping.
+
+ Args:
+ interaction_boxes: Interaction boxes in world space.
+ probe_box: Array whose first element is the character's probe box.
+ overlap_results: Array that receives 1 for each overlapping box and 0 for the
+ others. It needs room for every interaction box.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if interaction_boxes.dtype != InteractionBox or interaction_boxes.ndim != 1:
+ raise ValueError("interaction_boxes must be a 1D InteractionBox array.")
+ if (
+ probe_box.dtype != InteractionBox
+ or probe_box.ndim != 1
+ or probe_box.shape[0] < 1
+ ):
+ raise ValueError(
+ "probe_box must be a 1D InteractionBox array with "
+ "capacity for at least 1 box."
+ )
+
+ box_count = interaction_boxes.shape[0]
+ if (
+ overlap_results.dtype != wp.int32
+ or overlap_results.ndim != 1
+ or overlap_results.shape[0] < box_count
+ ):
+ raise ValueError(
+ "overlap_results must be a 1D wp.int32 array with capacity for "
+ f"at least {box_count} results."
+ )
+ if box_count == 0:
+ return
+
+ wp.launch(
+ _test_interaction_box_overlap_kernel,
+ dim=box_count,
+ inputs=[interaction_boxes, probe_box],
+ outputs=[overlap_results],
+ device=interaction_boxes.device,
+ stream=stream,
+ )
+
+
+class SmartPrimitiveAsset:
+ """Immutable Smart Primitive data shared by runtime instances."""
+
+ def __init__(self, data: SmartPrimitiveData, device=None) -> None:
+ """Copy the sampled data into device arrays.
+
+ Args:
+ data: Sampled poses and metadata.
+ device: Device for new arrays.
+ """
+ self.rig = data.rig
+ self.device = wp.get_device(device)
+ self.node_names = data.node_names
+ self.node_indices_by_name = {
+ name: index for index, name in enumerate(self.node_names)
+ }
+ self.node_local_transforms = wp.array(
+ data.node_local_transforms,
+ dtype=wp.transform,
+ device=self.device,
+ )
+ self.node_parent_indices = wp.array(
+ data.node_parent_indices,
+ dtype=wp.int32,
+ device=self.device,
+ )
+ self.target_poses = wp.array(
+ data.target_poses,
+ dtype=wp.transform if self.rig is ModelRig.SOMA else wp.float32,
+ device=self.device,
+ )
+ self.target_node_indices = tuple(
+ int(value) for value in data.target_node_indices
+ )
+ self.target_inference_params = data.target_inference_params
+ self.target_index_by_node = {
+ node_index: target_index
+ for target_index, node_index in enumerate(self.target_node_indices)
+ }
+
+ self.pivot_node_indices = tuple(int(value) for value in data.pivot_node_indices)
+ self.pivot_index_by_node = {
+ node_index: index for index, node_index in enumerate(self.pivot_node_indices)
+ }
+ # Copies keep the asset unchanged when the source pivots are edited later.
+ self.pivots = tuple(replace(pivot) for pivot in data.pivots)
+ self.sequences = data.sequences
+ self.sequence_indices_by_name = {
+ sequence.name: index for index, sequence in enumerate(self.sequences)
+ }
+ self.max_sequence_length = max(
+ (len(sequence.node_indices) for sequence in self.sequences),
+ default=0,
+ )
+
+ self.box_node_indices = tuple(
+ int(value) for value in data.box_node_indices
+ )
+ self.box_node_indices_device = wp.array(
+ data.box_node_indices,
+ dtype=wp.int32,
+ device=self.device,
+ )
+ self.box_index_by_node = {
+ node_index: box_index
+ for box_index, node_index in enumerate(self.box_node_indices)
+ }
+ self.box_half_extents = wp.array(
+ data.box_half_extents,
+ dtype=wp.vec3,
+ device=self.device,
+ )
+
+
+class SmartPrimitive:
+ """A runtime instance with its own hierarchy, backed by shared asset data.
+
+ Node and sequence indices out of range raise IndexError.
+ """
+
+ def __init__(self, asset: SmartPrimitiveAsset) -> None:
+ """Create an instance with its own copy of the node transforms.
+
+ Args:
+ asset: Data shared with the other instances of the same document.
+ """
+ self.asset = asset
+ self._node_local_transforms = wp.clone(asset.node_local_transforms)
+ self._node_world_transforms = wp.empty_like(self._node_local_transforms)
+ self._authored_pivot_transforms: dict[int, wp.transform] | None = None
+ self._world_transforms_dirty = True
+
+ @property
+ def device(self):
+ """Device of the instance's arrays."""
+ return self.asset.device
+
+ @property
+ def rig(self) -> ModelRig:
+ """Rig of the asset's poses."""
+ return self.asset.rig
+
+ @property
+ def node_count(self) -> int:
+ """Number of nodes, including the root node."""
+ return len(self.asset.node_names)
+
+ @property
+ def target_pose_count(self) -> int:
+ """Number of nodes with a target pose."""
+ return len(self.asset.target_node_indices)
+
+ @property
+ def sequence_count(self) -> int:
+ """Number of authored sequences."""
+ return len(self.asset.sequences)
+
+ @property
+ def max_sequence_length(self) -> int:
+ """Most steps in any sequence, or 0 without sequences."""
+ return self.asset.max_sequence_length
+
+ @property
+ def interaction_box_count(self) -> int:
+ """Number of interaction boxes."""
+ return len(self.asset.box_node_indices)
+
+ @property
+ def pivot_node_indices(self) -> tuple[int, ...]:
+ """Nodes with a Pivot, independent of their display names."""
+ return self.asset.pivot_node_indices
+
+ def pivot(self, node_index: int) -> Pivot:
+ """Return a copy of the node's pivot rules.
+
+ Args:
+ node_index: A node from pivot_node_indices.
+ """
+ self._validate_node_index(node_index)
+ return replace(self.asset.pivots[self.asset.pivot_index_by_node[node_index]])
+
+ @property
+ def pose_size(self) -> int:
+ """Values in one target pose: joints for SOMA, or joint coordinates for G1."""
+ return self.asset.target_poses.shape[1]
+
+ @property
+ def node_local_transforms(self) -> wp.array:
+ """Current local transform of each node. Change them with the setter methods."""
+
+ return self._node_local_transforms
+
+ @property
+ def node_parent_indices(self) -> wp.array:
+ """Each node's parent index, or -1 for the root node."""
+ return self.asset.node_parent_indices
+
+ def node_name(self, node_index: int) -> str:
+ """Return the node's display name.
+
+ Args:
+ node_index: Index of the node.
+ """
+ self._validate_node_index(node_index)
+ return self.asset.node_names[node_index]
+
+ def node_index(self, name: str) -> int:
+ """Return the node index for name, or -1 when it is absent.
+
+ Args:
+ name: Display name of the node.
+ """
+
+ return self.asset.node_indices_by_name.get(name, -1)
+
+ def sequence_name(self, sequence_index: int) -> str:
+ """Return the sequence's name.
+
+ Args:
+ sequence_index: Index of the sequence.
+ """
+ self._validate_sequence_index(sequence_index)
+ return self.asset.sequences[sequence_index].name
+
+ def sequence_index(self, name: str) -> int:
+ """Return the sequence index for name, or -1 when it is absent.
+
+ Args:
+ name: Name of the sequence.
+ """
+
+ return self.asset.sequence_indices_by_name.get(name, -1)
+
+ def sequence_length(self, sequence_index: int) -> int:
+ """Return the number of steps in the sequence.
+
+ Args:
+ sequence_index: Index of the sequence.
+ """
+ self._validate_sequence_index(sequence_index)
+ return len(self.asset.sequences[sequence_index].node_indices)
+
+ def sequence_start_speed(self, sequence_index: int) -> float:
+ """Return the authored speed of the sequence's first target pose, in m/s.
+
+ Args:
+ sequence_index: Index of the sequence.
+ """
+
+ self._validate_sequence_index(sequence_index)
+ return self.asset.sequences[sequence_index].start_speed
+
+ def sequence_pivot_node_index(self, sequence_index: int) -> int:
+ """Return the sequence's pivot node, or -1 when it has none.
+
+ Args:
+ sequence_index: Index of the sequence.
+ """
+ self._validate_sequence_index(sequence_index)
+ return self.asset.sequences[sequence_index].pivot_node_index
+
+ def target_names_for_sequence(self, sequence_index: int) -> tuple[str, ...]:
+ """Return the display names of the sequence's target nodes, in playback order.
+
+ Args:
+ sequence_index: Index of the sequence.
+ """
+ self._validate_sequence_index(sequence_index)
+ return tuple(
+ self.asset.node_names[node_index]
+ for node_index in self.asset.sequences[sequence_index].node_indices
+ )
+
+ def has_target_pose(self, node_index: int) -> bool:
+ """Return whether the node has a target pose.
+
+ Args:
+ node_index: Index of the node.
+ """
+
+ self._validate_node_index(node_index)
+ return node_index in self.asset.target_index_by_node
+
+ def has_interaction_box(self, node_index: int) -> bool:
+ """Return whether the node has an interaction box.
+
+ Args:
+ node_index: Index of the node.
+ """
+
+ self._validate_node_index(node_index)
+ return node_index in self.asset.box_index_by_node
+
+ def set_node_local_transform(
+ self,
+ node_index: int,
+ transform: wp.transform,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Set the node's transform relative to its parent. Its children move with it.
+
+ Args:
+ node_index: Index of the node.
+ transform: New transform relative to the parent.
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._validate_node_index(node_index)
+ wp.launch(
+ _set_local_transform_kernel,
+ dim=1,
+ inputs=[node_index, transform],
+ outputs=[self._node_local_transforms],
+ device=self.asset.device,
+ stream=stream,
+ )
+ self._world_transforms_dirty = True
+
+ def set_node_world_transform(
+ self,
+ node_index: int,
+ transform: wp.transform,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Place the node in world space. Its children move with it.
+
+ Args:
+ node_index: Index of the node.
+ transform: New world transform.
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._validate_node_index(node_index)
+ self._ensure_world_transforms(stream)
+ wp.launch(
+ _set_world_transform_kernel,
+ dim=1,
+ inputs=[
+ node_index,
+ transform,
+ self.asset.node_parent_indices,
+ self._node_world_transforms,
+ ],
+ outputs=[self._node_local_transforms],
+ device=self.asset.device,
+ stream=stream,
+ )
+ self._world_transforms_dirty = True
+
+ def compute_world_transforms(
+ self,
+ output_transforms: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Compute every node's world transform into output_transforms.
+
+ Args:
+ output_transforms: Array that receives one world transform per node.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if (
+ output_transforms.dtype != wp.transform
+ or output_transforms.ndim != 1
+ or output_transforms.shape[0] < self.node_count
+ ):
+ raise ValueError(
+ f"output_transforms must be a 1D wp.transform array with room for {self.node_count} transforms."
+ )
+ self._ensure_world_transforms(stream)
+ wp.copy(
+ output_transforms,
+ self._node_world_transforms,
+ count=self.node_count,
+ stream=stream,
+ )
+
+ def get_local_target_poses(
+ self,
+ node_index: int,
+ output_poses: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> TargetPoseInferenceParams:
+ """Write the node's four poses in its parent's space, and return their settings.
+
+ Only the root moves by the node's local transform. Joint values are
+ unchanged.
+
+ Args:
+ node_index: Node with a target pose.
+ output_poses: Array that receives the four poses: local joint transforms for
+ SOMA, or joint coordinates for G1.
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._validate_node_index(node_index)
+ self._validate_target_pose_output(output_poses, "output_poses")
+ return self._get_target_poses(
+ node_index,
+ output_poses,
+ self._node_local_transforms,
+ stream,
+ )
+
+ def get_world_target_poses(
+ self,
+ node_index: int,
+ output_poses: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> TargetPoseInferenceParams:
+ """Write the node's four poses in world space, and return their settings.
+
+ Only the root moves by the node's world transform. Joint values are
+ unchanged.
+
+ Args:
+ node_index: Node with a target pose.
+ output_poses: Array that receives the four poses: local joint transforms for
+ SOMA, or joint coordinates for G1.
+ stream: Stream for the work. None uses the current stream.
+ """
+ self._validate_node_index(node_index)
+ self._validate_target_pose_output(output_poses, "output_poses")
+ self._ensure_world_transforms(stream)
+ return self._get_target_poses(
+ node_index,
+ output_poses,
+ self._node_world_transforms,
+ stream,
+ )
+
+ def align_sequence_pivot(
+ self,
+ sequence_index: int,
+ character: CharacterProperties,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Move and turn the sequence's pivot node to match the character's approach.
+
+ Call it before reading the sequence's targets. A sequence without a pivot keeps
+ its placement. The first call records the world transform of every pivot, and
+ each alignment measures its limits from that record. Repeated alignments never
+ drift, even when one pivot is a child of another. The call waits for stream to
+ finish before it reads the node transforms.
+
+ Args:
+ sequence_index: Sequence whose pivot to align.
+ character: The approaching character.
+ stream: Stream for the work. None uses the current stream.
+ """
+ node_index = self.sequence_pivot_node_index(sequence_index)
+ if node_index < 0:
+ return
+ self._ensure_world_transforms(stream)
+ if stream is not None:
+ wp.synchronize_stream(stream)
+ transforms = self._node_world_transforms.numpy()
+ if self._authored_pivot_transforms is None:
+ self._authored_pivot_transforms = {
+ node: wp.transform(*transforms[node])
+ for node in self.pivot_node_indices
+ }
+ current = wp.transform(*transforms[node_index])
+ rules = self.asset.pivots[self.asset.pivot_index_by_node[node_index]]
+ self.set_node_world_transform(
+ node_index,
+ rules.aligned_transform(self._authored_pivot_transforms[node_index], current, character),
+ stream=stream,
+ )
+
+ def get_world_target_poses_for_sequence(
+ self,
+ sequence_index: int,
+ output_target_poses: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> tuple[TargetPoseInferenceParams, ...]:
+ """Write one sequence in world space, and return the settings of each step.
+
+ Args:
+ sequence_index: Index of the sequence.
+ output_target_poses: Array that receives four poses per step, in step order.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ self._validate_sequence_index(sequence_index)
+ node_indices = self.asset.sequences[sequence_index].node_indices
+ required_frame_count = len(node_indices) * MODEL_POSES_PER_TOKEN
+ self._validate_target_pose_output(output_target_poses, "output_target_poses", required_frame_count)
+
+ self._ensure_world_transforms(stream)
+ inference_params = []
+ for target_index, node_index in enumerate(node_indices):
+ frame_offset = target_index * MODEL_POSES_PER_TOKEN
+ inference_params.append(
+ self._get_target_poses(
+ node_index,
+ output_target_poses[
+ frame_offset : frame_offset + MODEL_POSES_PER_TOKEN
+ ],
+ self._node_world_transforms,
+ stream,
+ )
+ )
+ return tuple(inference_params)
+
+ def get_local_interaction_box(
+ self,
+ node_index: int,
+ output_box: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Write the node's interaction box in its parent's space.
+
+ Args:
+ node_index: Node with an interaction box.
+ output_box: Array whose first element receives the box.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ self._get_interaction_box(
+ node_index,
+ output_box,
+ self._node_local_transforms,
+ stream,
+ )
+
+ def get_world_interaction_box(
+ self,
+ node_index: int,
+ output_box: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Write the node's interaction box in world space.
+
+ Args:
+ node_index: Node with an interaction box.
+ output_box: Array whose first element receives the box.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ self._ensure_world_transforms(stream)
+ self._get_interaction_box(
+ node_index,
+ output_box,
+ self._node_world_transforms,
+ stream,
+ )
+
+ def get_world_interaction_boxes(
+ self,
+ output_boxes: wp.array,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Write every interaction box in world space, ready for overlap tests.
+
+ Args:
+ output_boxes: Array that receives the boxes in asset order. It needs room for
+ interaction_box_count boxes.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ box_count = self.interaction_box_count
+ self._validate_box_output(output_boxes, "output_boxes", box_count)
+ if box_count == 0:
+ return
+
+ self._ensure_world_transforms(stream)
+ wp.launch(
+ _write_interaction_boxes_kernel,
+ dim=box_count,
+ inputs=[
+ 0,
+ self.asset.box_node_indices_device,
+ self._node_world_transforms,
+ self.asset.box_half_extents,
+ ],
+ outputs=[output_boxes],
+ device=self.asset.device,
+ stream=stream,
+ )
+
+ def _ensure_world_transforms(self, stream: wp.Stream | None) -> None:
+ if self._world_transforms_dirty:
+ pose_utils.compute_world_poses(
+ self._node_local_transforms,
+ self.asset.node_parent_indices,
+ self._node_world_transforms,
+ stream=stream,
+ )
+ self._world_transforms_dirty = False
+
+ def _get_target_poses(
+ self,
+ node_index: int,
+ output_poses: wp.array,
+ node_transforms: wp.array,
+ stream: wp.Stream | None,
+ ) -> TargetPoseInferenceParams:
+ target_index = self.asset.target_index_by_node[node_index]
+ frame_offset = target_index * MODEL_POSES_PER_TOKEN
+ # SOMA poses hold local joint transforms, and G1 poses hold joint coordinates. The
+ # node places the root either way.
+ kernel = (
+ _write_skeleton_target_poses_kernel if self.rig is ModelRig.SOMA else _write_dof_target_poses_kernel
+ )
+ wp.launch(
+ kernel,
+ dim=(MODEL_POSES_PER_TOKEN, self.pose_size),
+ inputs=[frame_offset, node_index, node_transforms, self.asset.target_poses],
+ outputs=[output_poses],
+ device=self.asset.device,
+ stream=stream,
+ )
+ return self.asset.target_inference_params[target_index]
+
+ def _get_interaction_box(
+ self,
+ node_index: int,
+ output_box: wp.array,
+ node_transforms: wp.array,
+ stream: wp.Stream | None,
+ ) -> None:
+ self._validate_node_index(node_index)
+ self._validate_box_output(output_box, "output_box", 1)
+ box_index = self.asset.box_index_by_node[node_index]
+ wp.launch(
+ _write_interaction_boxes_kernel,
+ dim=1,
+ inputs=[
+ box_index,
+ self.asset.box_node_indices_device,
+ node_transforms,
+ self.asset.box_half_extents,
+ ],
+ outputs=[output_box],
+ device=self.asset.device,
+ stream=stream,
+ )
+
+ def _validate_node_index(self, node_index: int) -> None:
+ if not 0 <= node_index < self.node_count:
+ raise IndexError(f"Node index {node_index!r} is out of range.")
+
+ def _validate_sequence_index(self, sequence_index: int) -> None:
+ if not 0 <= sequence_index < self.sequence_count:
+ raise IndexError(f"Sequence index {sequence_index!r} is out of range.")
+
+ def _validate_target_pose_output(
+ self, output_poses: wp.array, name: str, count: int = MODEL_POSES_PER_TOKEN,
+ ) -> None:
+ if (
+ output_poses.dtype != self.asset.target_poses.dtype
+ or output_poses.ndim != 2
+ or output_poses.shape[0] < count
+ or output_poses.shape[1] != self.pose_size
+ ):
+ raise ValueError(
+ f"{name} must be a 2D array of the target pose type with capacity for "
+ f"at least {count} poses and exactly {self.pose_size} values per pose."
+ )
+
+ def _validate_box_output(self, output_boxes: wp.array, name: str, count: int) -> None:
+ if (
+ output_boxes.dtype != InteractionBox
+ or output_boxes.ndim != 1
+ or output_boxes.shape[0] < count
+ ):
+ raise ValueError(
+ f"{name} must be a 1D InteractionBox array with capacity for "
+ f"at least {count} boxes."
+ )
diff --git a/motionbricks/runtime/target_pose.py b/motionbricks/runtime/target_pose.py
new file mode 100644
index 0000000..3df4bf5
--- /dev/null
+++ b/motionbricks/runtime/target_pose.py
@@ -0,0 +1,562 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Target pose generation settings, target pose IK, and locomotion target placement."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import IntFlag
+import math
+from typing import TYPE_CHECKING
+
+import warp as wp
+
+from motionbricks.animation.ik import TwoBoneIKChain, apply_two_bone_ik_chains_kernel
+from motionbricks.model.contract import MODEL_SAMPLE_RATE
+from motionbricks.utils.dof_utils import ROOT_COORDINATE_COUNT, read_root_transform, write_root_transform
+
+if TYPE_CHECKING:
+ from motionbricks.animation.skeleton import Skeleton
+
+
+MAX_TRANSITION_EARLY_BY_FRAMES = 20
+
+
+class IKPin(IntFlag):
+ """Hands and feet that a target pose can pin with IK."""
+
+ NONE = 0
+ LEFT_HAND = 1 << 0
+ RIGHT_HAND = 1 << 1
+ LEFT_FOOT = 1 << 2
+ RIGHT_FOOT = 1 << 3
+ ALL = LEFT_HAND | RIGHT_HAND | LEFT_FOOT | RIGHT_FOOT
+
+
+IK_PINS = (
+ IKPin.LEFT_HAND,
+ IKPin.RIGHT_HAND,
+ IKPin.LEFT_FOOT,
+ IKPin.RIGHT_FOOT,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class TargetPoseInferenceParams:
+ """Generation settings for reaching one target.
+
+ Attributes:
+ transition_early_by_frames: How many frames before the end of the generated
+ motion the transition point sits.
+ num_poses_to_use: How many of the target's four poses inform the model, from 1
+ to 4.
+ ik_pin_mask: IKPin flags for the hands and feet that target pose IK pins.
+ allowed_token_counts: Token counts the model may choose from. They set the
+ generated length, whatever the number of target poses. None keeps the
+ counts of the generation config.
+ """
+
+ transition_early_by_frames: int
+ num_poses_to_use: int
+ ik_pin_mask: IKPin = IKPin.NONE
+ allowed_token_counts: tuple[int, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TwoBoneIKChainConfig:
+ """Resolved joint indices and hint offset for an IK chain with two bones.
+
+ A pin other than one of IK_PINS raises ValueError.
+
+ Attributes:
+ pin: The one IK pin the chain serves.
+ root_index: Joint index of the chain start.
+ mid_index: Joint index of the middle joint, a child of the chain start.
+ tip_index: Joint index of the tip, a child of the middle joint. The pin holds
+ the tip in place.
+ hint_offset_local: Point in the middle joint's local space that the chain bends
+ toward, in meters.
+ """
+
+ pin: IKPin
+ root_index: int
+ mid_index: int
+ tip_index: int
+ hint_offset_local: tuple[float, float, float]
+
+ def __post_init__(self) -> None:
+ if self.pin not in IK_PINS:
+ raise ValueError("pin must identify exactly one supported IK pin.")
+
+ @classmethod
+ def from_joint_names(
+ cls,
+ pin: IKPin,
+ skeleton: Skeleton,
+ root_joint: str,
+ mid_joint: str,
+ tip_joint: str,
+ hint_offset_local: tuple[float, float, float],
+ ) -> TwoBoneIKChainConfig:
+ """Build a config from joint names, storing only their indices.
+
+ A name missing from the skeleton raises ValueError.
+
+ Args:
+ pin: The one IK pin the chain serves.
+ skeleton: Skeleton that holds the joints.
+ root_joint: Name of the chain start.
+ mid_joint: Name of the middle joint.
+ tip_joint: Name of the tip.
+ hint_offset_local: Point in the middle joint's local space that the chain
+ bends toward, in meters.
+ """
+
+ joint_names = (root_joint, mid_joint, tip_joint)
+ joint_indices = tuple(skeleton.joint_index(name) for name in joint_names)
+ missing_names = [
+ name for name, index in zip(joint_names, joint_indices) if index < 0
+ ]
+ if missing_names:
+ names = ", ".join(repr(name) for name in missing_names)
+ raise ValueError(
+ f"{pin.name} IK chain joints are missing from the skeleton: "
+ f"{names}."
+ )
+
+ return cls(pin, *joint_indices, hint_offset_local)
+
+
+_SOMA_IK_CHAINS = (
+ (IKPin.LEFT_HAND, "LeftArm", "LeftForeArm", "LeftHand", (0.0, -0.25, 0.0)),
+ (IKPin.RIGHT_HAND, "RightArm", "RightForeArm", "RightHand", (0.0, 0.25, 0.0)),
+ (IKPin.LEFT_FOOT, "LeftLeg", "LeftShin", "LeftFoot", (0.0, -0.25, 0.0)),
+ (IKPin.RIGHT_FOOT, "RightLeg", "RightShin", "RightFoot", (0.0, 0.25, 0.0)),
+)
+
+
+def create_soma_target_pose_ik_rig(
+ skeleton: Skeleton,
+) -> tuple[TwoBoneIKChainConfig, ...]:
+ """Resolve the SOMA target pose IK chains and local hint offsets.
+
+ Args:
+ skeleton: SOMA skeleton that holds the arm and leg joints.
+ """
+ return tuple(
+ TwoBoneIKChainConfig.from_joint_names(pin, skeleton, root, mid, tip, hint)
+ for pin, root, mid, tip, hint in _SOMA_IK_CHAINS
+ )
+
+
+def _capture_pinned_transforms_kernel(
+ chains: wp.array(dtype=TwoBoneIKChain),
+ world_transforms: wp.array(dtype=wp.transform),
+ pinned_transforms: wp.array(dtype=wp.transform),
+):
+ """Copy the world transform of each chain's tip as its pinned transform."""
+
+ chain_index = wp.tid()
+ pinned_transforms[chain_index] = world_transforms[chains[chain_index].tip_index]
+
+
+class TargetPoseIKCorrector:
+ """Apply IK pins to motion generated toward a target pose."""
+
+ def __init__(
+ self,
+ skeleton: Skeleton,
+ chains: Sequence[TwoBoneIKChainConfig],
+ ) -> None:
+ """Check the chains and allocate the solver arrays on the skeleton's device.
+
+ No chains, or a chain whose joints do not form a parent chain, raise ValueError.
+
+ Args:
+ skeleton: Skeleton of the corrected poses.
+ chains: One chain per pin, as create_soma_target_pose_ik_rig() returns.
+ Chains cannot share joints.
+ """
+ if not chains:
+ raise ValueError("Target pose IK chains cannot be empty.")
+ self._skeleton = skeleton
+ self._device = skeleton.parent_indices.device
+ self._pin_mask = IKPin.NONE
+ warp_chains = []
+ for chain in chains:
+ if (
+ skeleton.joint_parent(chain.mid_index) != chain.root_index
+ or skeleton.joint_parent(chain.tip_index) != chain.mid_index
+ ):
+ raise ValueError(
+ "An IK chain's mid joint must be a child of its chain start, "
+ "and its tip must be a child of its mid joint."
+ )
+ warp_chain = TwoBoneIKChain()
+ warp_chain.pin = int(chain.pin)
+ warp_chain.root_index = chain.root_index
+ warp_chain.mid_index = chain.mid_index
+ warp_chain.tip_index = chain.tip_index
+ warp_chain.hint_offset_local = wp.vec3(*chain.hint_offset_local)
+ warp_chains.append(warp_chain)
+ self._chains = wp.array(warp_chains, dtype=TwoBoneIKChain, device=self._device)
+ self._pinned_transforms = wp.empty(
+ len(self._chains),
+ dtype=wp.transform,
+ device=self._device,
+ )
+ self._world_transforms = wp.empty(
+ skeleton.num_joints,
+ dtype=wp.transform,
+ device=self._device,
+ )
+
+ @property
+ def pin_mask(self) -> IKPin:
+ """Pins captured from the current target pose."""
+
+ return self._pin_mask
+
+ def capture_pins(
+ self,
+ target_pose: wp.array,
+ pin_mask: IKPin,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Capture the pinned hand and foot transforms from a target's local pose.
+
+ A mask of IKPin.NONE clears the pins.
+
+ Args:
+ target_pose: Local joint transforms of the target pose, on the corrector's
+ device.
+ pin_mask: IKPin flags to pin. A pin without a chain has no effect.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if pin_mask == IKPin.NONE:
+ self.clear_pins()
+ return
+
+ self._validate_pose(target_pose, "target_pose")
+ self._skeleton.compute_world_transforms(
+ target_pose,
+ self._world_transforms,
+ stream=stream,
+ )
+ wp.launch(
+ _capture_pinned_transforms_kernel,
+ dim=len(self._chains),
+ inputs=[self._chains, self._world_transforms],
+ outputs=[self._pinned_transforms],
+ device=self._device,
+ stream=stream,
+ )
+ self._pin_mask = pin_mask
+
+ def apply(
+ self,
+ current_pose: wp.array,
+ weight: float,
+ stream: wp.Stream | None = None,
+ ) -> None:
+ """Correct the pinned chains of a sampled local pose in place.
+
+ Nothing changes without captured pins or with a weight of zero or less.
+
+ Args:
+ current_pose: Local joint transforms to correct, on the corrector's device.
+ weight: Blend from the sampled pose at 0 to the pinned pose at 1. Values
+ above 1 count as 1.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if self._pin_mask == IKPin.NONE or weight <= 0.0:
+ return
+
+ self._validate_pose(current_pose, "current_pose")
+ self._skeleton.compute_world_transforms(
+ current_pose,
+ self._world_transforms,
+ stream=stream,
+ )
+ wp.launch(
+ apply_two_bone_ik_chains_kernel,
+ dim=len(self._chains),
+ inputs=[
+ weight,
+ int(self._pin_mask),
+ self._chains,
+ self._pinned_transforms,
+ self._skeleton.parent_indices,
+ self._world_transforms,
+ ],
+ outputs=[current_pose],
+ device=self._device,
+ stream=stream,
+ )
+
+ def clear_pins(self) -> None:
+ """Disable all IK pins without reallocating device storage."""
+
+ self._pin_mask = IKPin.NONE
+
+ def _validate_pose(self, pose: wp.array, name: str) -> None:
+ if (
+ pose.dtype != wp.transform
+ or pose.ndim != 1
+ or pose.shape[0] != self._skeleton.num_joints
+ ):
+ raise ValueError(
+ f"{name} must contain one wp.transform per skeleton joint."
+ )
+ if pose.device != self._device:
+ raise ValueError(f"{name} must be stored on the corrector device.")
+
+
+def _ground_speed_scale(
+ start: wp.vec3,
+ end: wp.vec3,
+ pose_count: wp.int32,
+ desired_speed: wp.float32,
+) -> wp.float32:
+ """Return the scale that brings the mean ground speed from start to end to desired_speed.
+
+ The poses are 30 Hz apart. Targets that barely move keep a scale of 1.
+ """
+ velocity = (end - start) * (MODEL_SAMPLE_RATE / wp.float32(pose_count - 1))
+ source_speed = wp.length(wp.vec2(velocity[0], velocity[1]))
+ if source_speed <= 1.0e-6:
+ return 1.0
+ return desired_speed / source_speed
+
+
+def _scaled_ground_offset(position: wp.vec3, start: wp.vec3, scale: wp.float32) -> wp.vec3:
+ """Scale position's ground offset from start, and keep its height."""
+ return wp.vec3(
+ start[0] + (position[0] - start[0]) * scale,
+ start[1] + (position[1] - start[1]) * scale,
+ position[2],
+ )
+
+
+def _ground_placement(ground_position: wp.vec3, facing_direction: wp.vec3) -> wp.transform:
+ """Return the transform that moves a target to ground_position, turned to face facing_direction."""
+ yaw = wp.atan2(facing_direction[1], facing_direction[0])
+ return wp.transform(ground_position, wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), yaw))
+
+
+def _adjust_speed_kernel(
+ desired_speed: wp.float32,
+ target_poses: wp.array2d(dtype=wp.transform),
+):
+ pose_count = target_poses.shape[0]
+ start = target_poses[0, 0].p
+ scale = _ground_speed_scale(start, target_poses[pose_count - 1, 0].p, pose_count, desired_speed)
+ for frame in range(1, pose_count):
+ root = target_poses[frame, 0]
+ target_poses[frame, 0] = wp.transform(_scaled_ground_offset(root.p, start, scale), root.q)
+
+
+def adjust_target_pose_speed(
+ target_poses: wp.array,
+ desired_speed: float,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Scale the root's ground motion to a desired mean speed, with poses sampled at 30 Hz.
+
+ One scale applies to each pose's ground offset from the first pose. The mean
+ speed comes from the offset between the first and last poses. Height,
+ rotations, and the other joints are kept. Targets that barely move stay
+ unchanged.
+
+ Args:
+ target_poses: Local joint transforms of the target poses, laid out as [pose,
+ joint]. It needs at least two poses. The poses are edited in place.
+ desired_speed: Mean ground speed to reach, in m/s. It must be finite and
+ non-negative.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if (
+ target_poses.dtype != wp.transform
+ or target_poses.ndim != 2
+ or target_poses.shape[0] < 2
+ or target_poses.shape[1] == 0
+ ):
+ raise ValueError("target_poses must contain at least two poses.")
+ if not math.isfinite(desired_speed) or desired_speed < 0.0:
+ raise ValueError("desired_speed must be finite and non-negative.")
+
+ wp.launch(
+ _adjust_speed_kernel,
+ dim=1,
+ inputs=[desired_speed],
+ outputs=[target_poses],
+ stream=stream,
+ )
+
+
+def _adjust_dof_speed_kernel(
+ desired_speed: wp.float32,
+ target_joint_q: wp.array2d(dtype=wp.float32),
+):
+ pose_count = target_joint_q.shape[0]
+ start = read_root_transform(target_joint_q, 0).p
+ end = read_root_transform(target_joint_q, pose_count - 1).p
+ scale = _ground_speed_scale(start, end, pose_count, desired_speed)
+ for frame in range(1, pose_count):
+ position = _scaled_ground_offset(read_root_transform(target_joint_q, frame).p, start, scale)
+ target_joint_q[frame, 0] = position[0]
+ target_joint_q[frame, 1] = position[1]
+
+
+def adjust_target_dof_speed(
+ target_joint_q: wp.array,
+ desired_speed: float,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Scale the root's ground motion to a desired mean speed, with poses sampled at 30 Hz.
+
+ One scale applies to each pose's ground offset from the first pose. The mean speed
+ comes from the offset between the first and last poses. Root height, rotation,
+ and joint angles are kept. Targets that barely move stay unchanged.
+
+ Args:
+ target_joint_q: Joint coordinates of the target poses, laid out as [pose,
+ coordinate]. Each pose starts with the root position and XYZW quaternion.
+ It needs at least two poses. The poses are edited in place.
+ desired_speed: Mean ground speed to reach, in m/s. It must be finite and
+ non-negative.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ if (
+ target_joint_q.dtype != wp.float32
+ or target_joint_q.ndim != 2
+ or target_joint_q.shape[0] < 2
+ or target_joint_q.shape[1] < ROOT_COORDINATE_COUNT
+ ):
+ raise ValueError("target_joint_q must contain at least two poses with root XYZ and XYZW values.")
+ if not math.isfinite(desired_speed) or desired_speed < 0.0:
+ raise ValueError("desired_speed must be finite and non-negative.")
+
+ wp.launch(
+ _adjust_dof_speed_kernel,
+ dim=1,
+ inputs=[desired_speed],
+ outputs=[target_joint_q],
+ device=target_joint_q.device,
+ stream=stream,
+ )
+
+
+def _place_target_poses_kernel(
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_poses: wp.array2d(dtype=wp.transform),
+ target_poses: wp.array2d(dtype=wp.transform),
+):
+ frame, joint = wp.tid()
+ pose = blended_poses[frame, joint]
+ # Joint 0 is the root, the only joint that moves.
+ if joint == 0:
+ pose = wp.mul(_ground_placement(ground_position, facing_direction), pose)
+ target_poses[frame, joint] = pose
+
+
+def place_target_poses(
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_poses: wp.array,
+ target_poses: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Place blended target poses at a ground position, turned to a facing direction.
+
+ Only the root moves. The other joints keep their local transforms.
+
+ Args:
+ ground_position: Where the targets' origin goes, in world space.
+ facing_direction: Ground direction the targets face.
+ blended_poses: Local joint transforms of the blended targets, laid out as [pose,
+ joint].
+ target_poses: Array of the same shape that receives the placed poses.
+ stream: Stream for the work. None uses the current stream.
+ """
+ wp.launch(
+ _place_target_poses_kernel,
+ dim=target_poses.shape,
+ inputs=[ground_position, facing_direction, blended_poses],
+ outputs=[target_poses],
+ device=target_poses.device,
+ stream=stream,
+ )
+
+
+def _place_target_dof_kernel(
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_joint_q: wp.array2d(dtype=wp.float32),
+ target_joint_q: wp.array2d(dtype=wp.float32),
+):
+ frame, coordinate = wp.tid()
+ if coordinate == 0:
+ placement = _ground_placement(ground_position, facing_direction)
+ write_root_transform(wp.mul(placement, read_root_transform(blended_joint_q, frame)), target_joint_q, frame)
+ elif coordinate >= ROOT_COORDINATE_COUNT:
+ target_joint_q[frame, coordinate] = blended_joint_q[frame, coordinate]
+
+
+def place_target_dof(
+ ground_position: wp.vec3,
+ facing_direction: wp.vec3,
+ blended_joint_q: wp.array,
+ target_joint_q: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Place blended target poses of joint coordinates at a ground position, turned to a facing direction.
+
+ Only the root coordinates move. The joint angles are kept.
+
+ Args:
+ ground_position: Where the targets' origin goes, in world space.
+ facing_direction: Ground direction the targets face.
+ blended_joint_q: Joint coordinates of the blended targets, laid out as [pose,
+ coordinate].
+ target_joint_q: Array of the same shape that receives the placed poses.
+ stream: Stream for the work. None uses the current stream.
+ """
+ wp.launch(
+ _place_target_dof_kernel,
+ dim=target_joint_q.shape,
+ inputs=[ground_position, facing_direction, blended_joint_q],
+ outputs=[target_joint_q],
+ device=target_joint_q.device,
+ stream=stream,
+ )
+
+
+__all__ = [
+ "IKPin",
+ "IK_PINS",
+ "MAX_TRANSITION_EARLY_BY_FRAMES",
+ "TargetPoseIKCorrector",
+ "TargetPoseInferenceParams",
+ "TwoBoneIKChainConfig",
+ "adjust_target_dof_speed",
+ "adjust_target_pose_speed",
+ "create_soma_target_pose_ik_rig",
+ "place_target_dof",
+ "place_target_poses",
+]
diff --git a/motionbricks/utils/__init__.py b/motionbricks/utils/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/motionbricks/utils/dof_utils.py b/motionbricks/utils/dof_utils.py
new file mode 100644
index 0000000..6e46af8
--- /dev/null
+++ b/motionbricks/utils/dof_utils.py
@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Read and write root transforms in arrays of joint coordinates."""
+
+import warp as wp
+
+# Each pose's joint coordinates start with the root: position (XYZ), then rotation (XYZW).
+ROOT_COORDINATE_COUNT = 7
+
+
+def read_root_transform(joint_q: wp.array(dtype=wp.float32)):
+ """Read the root transform of one pose of joint coordinates, with a normalized rotation."""
+ return wp.transform(
+ wp.vec3(joint_q[0], joint_q[1], joint_q[2]),
+ wp.normalize(wp.quat(joint_q[3], joint_q[4], joint_q[5], joint_q[6])),
+ )
+
+
+def read_root_transform(joint_q: wp.array2d(dtype=wp.float32), frame: wp.int32):
+ """Read a frame's root transform from joint coordinates, with a normalized rotation."""
+ return wp.transform(
+ wp.vec3(joint_q[frame, 0], joint_q[frame, 1], joint_q[frame, 2]),
+ wp.normalize(wp.quat(joint_q[frame, 3], joint_q[frame, 4], joint_q[frame, 5], joint_q[frame, 6])),
+ )
+
+
+def read_root_transform(joint_q: wp.array3d(dtype=wp.float32), target: wp.int32, frame: wp.int32):
+ """Read the root transform of one blend target's frame from stacked joint coordinates."""
+ return wp.transform(
+ wp.vec3(joint_q[target, frame, 0], joint_q[target, frame, 1], joint_q[target, frame, 2]),
+ wp.normalize(wp.quat(
+ joint_q[target, frame, 3], joint_q[target, frame, 4],
+ joint_q[target, frame, 5], joint_q[target, frame, 6],
+ )),
+ )
+
+
+def write_root_transform(root: wp.transform, output: wp.array2d(dtype=wp.float32), frame: wp.int32):
+ """Write a root transform, normalized, into a frame of joint coordinates."""
+ for coordinate in range(3):
+ output[frame, coordinate] = root.p[coordinate]
+ rotation = wp.normalize(root.q)
+ for coordinate in range(4):
+ output[frame, coordinate + 3] = rotation[coordinate]
+
+
+def write_root_transform(root: wp.transform, output: wp.array(dtype=wp.float32)):
+ """Write a root transform, normalized, into the joint coordinates of one pose."""
+ for coordinate in range(3):
+ output[coordinate] = root.p[coordinate]
+ rotation = wp.normalize(root.q)
+ for coordinate in range(4):
+ output[coordinate + 3] = rotation[coordinate]
diff --git a/motionbricks/utils/math_utils.py b/motionbricks/utils/math_utils.py
new file mode 100644
index 0000000..e379e29
--- /dev/null
+++ b/motionbricks/utils/math_utils.py
@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Common scalar and transform math helpers."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import warp as wp
+
+
+def quadratic_fade_weight(value: wp.float32) -> wp.float32:
+ """Fade from 1 to 0 with a quadratic ease in and out as value goes from 0 to 1."""
+ t = wp.clamp(value, 0.0, 1.0)
+ remaining = 1.0 - t
+ return wp.where(t < 0.5, 1.0 - 2.0 * t * t, 2.0 * remaining * remaining)
+
+
+def project_to_plane(
+ transform: wp.transform,
+ plane_normal: wp.vec3,
+) -> wp.transform:
+ """Project a transform onto the plane through the origin with this normal."""
+
+ normal = wp.normalize(plane_normal)
+ position = transform.p - normal * wp.dot(transform.p, normal)
+ return wp.transform(position, wp.quat_twist(normal, transform.q))
+
+
+def critical_spring_damper_exact(
+ current: float,
+ current_rate: float,
+ goal: float,
+ halflife: float,
+ delta_time: float,
+) -> tuple[float, float]:
+ """Advance a critically damped spring, and return its new value and rate.
+
+ A spring within 1e-4 of the goal and nearly still snaps to the goal.
+
+ Args:
+ current: Current value.
+ current_rate: Current rate of change, per second.
+ goal: Value the spring moves toward.
+ halflife: Half-life of the spring's response, in seconds. Smaller values reach
+ the goal faster.
+ delta_time: Time to advance, in seconds.
+ """
+
+ damping = (4.0 * math.log(2.0)) / (halflife + 1.0e-5)
+ decay_rate = damping / 2.0
+ position_offset = current - goal
+ velocity_offset = current_rate + position_offset * decay_rate
+ decay = math.exp(-decay_rate * delta_time)
+
+ next_current = decay * (position_offset + velocity_offset * delta_time) + goal
+ next_rate = decay * (
+ current_rate - velocity_offset * decay_rate * delta_time
+ )
+ if abs(next_current - goal) <= 1.0e-4 and abs(next_rate) <= 1.0e-4:
+ return goal, 0.0
+ return next_current, next_rate
+
+
+def wrap_angle(angle: float) -> float:
+ """Wrap an angle to [-pi, pi).
+
+ Args:
+ angle: Angle in radians.
+ """
+
+ return (angle + math.pi) % math.tau - math.pi
+
+
+def critical_spring_angle(
+ current_angle: float,
+ current_rate: float,
+ desired_direction: np.ndarray,
+ halflife: float,
+ delta_time: float,
+) -> tuple[float, float]:
+ """Advance an angle spring toward a 2D direction by the shortest arc.
+
+ Returns the new angle, wrapped to [-pi, pi), and its rate.
+
+ Args:
+ current_angle: Current angle in radians.
+ current_rate: Current rate of change, in radians per second.
+ desired_direction: 2D direction (x, y) to turn toward. Its length does not
+ matter.
+ halflife: Half-life of the spring's response, in seconds. Smaller values reach
+ the goal faster.
+ delta_time: Time to advance, in seconds.
+ """
+
+ desired_angle = math.atan2(desired_direction[1], desired_direction[0])
+ goal_angle = current_angle + wrap_angle(desired_angle - current_angle)
+ angle, rate = critical_spring_damper_exact(
+ current_angle,
+ current_rate,
+ goal_angle,
+ halflife,
+ delta_time,
+ )
+ return wrap_angle(angle), rate
diff --git a/motionbricks/utils/pose_utils.py b/motionbricks/utils/pose_utils.py
new file mode 100644
index 0000000..f4773ab
--- /dev/null
+++ b/motionbricks/utils/pose_utils.py
@@ -0,0 +1,429 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Convert poses through the skeleton hierarchy, blend transforms, and apply pose deltas."""
+
+from typing import Any
+
+import numpy as np
+import warp as wp
+
+from motionbricks.utils.time_utils import frame_index_from_time
+
+
+def _fill_poses_kernel(
+ pose: wp.array(dtype=Any),
+ poses: wp.array2d(dtype=Any),
+):
+ frame, joint = wp.tid()
+ poses[frame, joint] = pose[joint]
+
+
+def fill_poses(pose: wp.array, poses: wp.array, stream: wp.Stream | None = None) -> None:
+ """Copy one pose into every row of poses.
+
+ Args:
+ pose: One pose, as local joint transforms or joint coordinates.
+ poses: Array of [frame, joint] or [frame, coordinate] with the same dtype.
+ stream: Stream for the work. None uses the current stream.
+ """
+ wp.launch(_fill_poses_kernel, dim=poses.shape, inputs=[pose], outputs=[poses], device=poses.device, stream=stream)
+
+
+def sample_root_position(
+ positions: np.ndarray, time: float, sample_rate: float,
+ root_offset: wp.transform | None = None,
+) -> np.ndarray:
+ """Interpolate cached root positions and optionally place them in world space.
+
+ Times outside the positions are clamped.
+
+ Args:
+ positions: Root position of each frame, as a host array of [frame, 3].
+ time: Sample time in seconds.
+ sample_rate: Sample rate in Hz.
+ root_offset: World transform applied to the result. None returns the position
+ as stored.
+ """
+ frame, next_frame, blend = frame_index_from_time(time, sample_rate, len(positions))
+ position = positions[frame] * (1.0 - blend) + positions[next_frame] * blend
+ if root_offset is not None:
+ position = np.asarray(
+ wp.transform_point(root_offset, wp.vec3(*position)), dtype=np.float32,
+ )
+ return position
+
+
+def _as_2d_view(poses: wp.array) -> wp.array:
+ """Return a 1D pose as a 2D view with one row, or a 2D array unchanged."""
+
+ if poses.dtype != wp.transform or poses.ndim not in (1, 2):
+ raise ValueError("Poses must be a 1D or 2D Warp transform array.")
+ if poses.ndim == 1:
+ return poses.reshape((1, poses.shape[0]))
+ return poses
+
+
+# Local to world
+
+
+def compute_world_pose_frame(
+ num_joints: wp.int32,
+ root_tx: wp.transform,
+ input_frame: wp.int32,
+ output_frame: wp.int32,
+ parent_indices: wp.array(dtype=wp.int32),
+ local_poses: wp.array2d(dtype=wp.transform),
+ world_poses: wp.array2d(dtype=wp.transform),
+):
+ """Compose one frame of local joint transforms through the hierarchy.
+
+ root_tx places the root and sets the space of the result. Each parent comes before
+ its children.
+ """
+ world_poses[output_frame, 0] = wp.mul(root_tx, local_poses[input_frame, 0])
+ for joint in range(1, num_joints):
+ parent = parent_indices[joint]
+ world_poses[output_frame, joint] = wp.mul(
+ world_poses[output_frame, parent],
+ local_poses[input_frame, joint],
+ )
+
+
+def _compute_world_poses_kernel(
+ num_joints: wp.int32,
+ root_tx: wp.transform,
+ parent_indices: wp.array(dtype=wp.int32),
+ local_poses: wp.array2d(dtype=wp.transform),
+ world_poses: wp.array2d(dtype=wp.transform),
+):
+ frame = wp.tid()
+ compute_world_pose_frame(
+ num_joints,
+ root_tx,
+ frame,
+ frame,
+ parent_indices,
+ local_poses,
+ world_poses,
+ )
+
+
+def compute_world_poses(
+ local_poses: wp.array,
+ parent_indices: wp.array,
+ world_poses: wp.array,
+ root_tx=wp.transform_identity(),
+ num_poses: int | None = None,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Compute one or more world poses into existing storage.
+
+ Args:
+ local_poses: Local joint transforms of one pose [joint] or several [pose,
+ joint].
+ parent_indices: Parent index of each joint. Each parent comes before its
+ children.
+ world_poses: Array that receives the world transforms, in the same layout.
+ root_tx: Transform applied to each root. It sets the space of the result.
+ num_poses: Number of poses to compute. None computes them all.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ local_batch = _as_2d_view(local_poses)
+ world_batch = _as_2d_view(world_poses)
+ count = local_batch.shape[0] if num_poses is None else num_poses
+ wp.launch(
+ _compute_world_poses_kernel,
+ dim=count,
+ inputs=[local_batch.shape[1], root_tx, parent_indices, local_batch],
+ outputs=[world_batch],
+ stream=stream,
+ )
+
+
+# World to local
+
+
+def _compute_local_poses_kernel(
+ root_tx: wp.transform,
+ parent_indices: wp.array(dtype=wp.int32),
+ world_poses: wp.array2d(dtype=wp.transform),
+ local_poses: wp.array2d(dtype=wp.transform),
+):
+ frame, joint = wp.tid()
+ parent = parent_indices[joint]
+ if parent < 0:
+ parent_tx = root_tx
+ else:
+ parent_tx = world_poses[frame, parent]
+ local_poses[frame, joint] = wp.mul(
+ wp.transform_inverse(parent_tx),
+ world_poses[frame, joint],
+ )
+
+
+def compute_local_poses(
+ world_poses: wp.array,
+ parent_indices: wp.array,
+ local_poses: wp.array,
+ root_tx=wp.transform_identity(),
+ num_poses: int | None = None,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Compute the local joint transforms of one or more poses into existing storage.
+
+ Args:
+ world_poses: World transforms of one pose [joint] or several [pose, joint].
+ parent_indices: Parent index of each joint, or -1 for the root.
+ local_poses: Array that receives the local joint transforms, in the same
+ layout.
+ root_tx: Transform that each root is measured from.
+ num_poses: Number of poses to compute. None computes them all.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ world_batch = _as_2d_view(world_poses)
+ local_batch = _as_2d_view(local_poses)
+ count = world_batch.shape[0] if num_poses is None else num_poses
+ wp.launch(
+ _compute_local_poses_kernel,
+ dim=(count, world_batch.shape[1]),
+ inputs=[root_tx, parent_indices, world_batch],
+ outputs=[local_batch],
+ stream=stream,
+ )
+
+
+# Blending
+
+
+def blend_transform(
+ transform0: wp.transform,
+ transform1: wp.transform,
+ blend: wp.float32,
+) -> wp.transform:
+ """Interpolate positions linearly and rotations spherically between two transforms."""
+ p = wp.lerp(transform0.p, transform1.p, blend)
+ q = wp.quat_slerp(transform0.q, transform1.q, blend)
+ return wp.transform(p, q)
+
+
+def blend_pose_joints_with_root_offset_kernel(
+ local_poses: wp.array2d(dtype=wp.transform),
+ frame0: wp.int32,
+ frame1: wp.int32,
+ blend: wp.float32,
+ root_offset: wp.transform,
+ output_pose: wp.array(dtype=wp.transform),
+):
+ """Blend two frames into output_pose, and apply root_offset to the root."""
+ joint = wp.tid()
+ transform = blend_transform(
+ local_poses[frame0, joint],
+ local_poses[frame1, joint],
+ blend,
+ )
+ if joint == 0:
+ transform = wp.mul(root_offset, transform)
+ output_pose[joint] = transform
+
+
+def compute_delta_transform(
+ src_transform: wp.transform,
+ dst_transform: wp.transform,
+) -> wp.transform:
+ """Return the delta from ``src_transform`` to ``dst_transform``."""
+
+ return wp.mul(wp.transform_inverse(src_transform), dst_transform)
+
+
+def apply_delta_transform(
+ transform: wp.transform,
+ delta_transform: wp.transform,
+ weight: wp.float32,
+) -> wp.transform:
+ """Apply a weighted transform delta."""
+
+ weighted_delta = blend_transform(
+ wp.transform_identity(),
+ delta_transform,
+ weight,
+ )
+ return wp.mul(transform, weighted_delta)
+
+
+def compute_root_endpoint_delta(
+ generated_root: wp.transform,
+ guide_root: wp.transform,
+) -> wp.transform:
+ """Return the endpoint correction that moves a generated root onto a context or target root.
+
+ The position delta is a world space offset. The rotation delta applies after the
+ generated rotation.
+ """
+ rotation = wp.mul(wp.quat_inverse(wp.normalize(generated_root.q)), wp.normalize(guide_root.q))
+ return wp.transform(guide_root.p - generated_root.p, wp.normalize(rotation))
+
+
+def apply_root_endpoint_correction(
+ root: wp.transform,
+ start_delta: wp.transform,
+ end_delta: wp.transform,
+ end_weight: wp.float32,
+) -> wp.transform:
+ """Apply the start and end root corrections at one frame of the generated motion.
+
+ end_weight runs from 0 at the first frame to 1 at the last frame. The start
+ correction fades out as the end correction fades in. Positions blend linearly, so
+ the root does not swing along an arc.
+ """
+ start_weight = 1.0 - end_weight
+ rotation = wp.mul(
+ wp.mul(root.q, wp.quat_slerp(wp.quat_identity(), start_delta.q, start_weight)),
+ wp.quat_slerp(wp.quat_identity(), end_delta.q, end_weight),
+ )
+ return wp.transform(
+ root.p + start_delta.p * start_weight + end_delta.p * end_weight,
+ wp.normalize(rotation),
+ )
+
+
+def _compute_delta_pose_kernel(
+ src_pose: wp.array(dtype=wp.transform),
+ dst_pose: wp.array(dtype=wp.transform),
+ delta_pose: wp.array(dtype=wp.transform),
+):
+ joint = wp.tid()
+ delta_pose[joint] = compute_delta_transform(
+ src_pose[joint],
+ dst_pose[joint],
+ )
+
+
+def _apply_delta_pose_kernel(
+ delta_pose: wp.array(dtype=wp.transform),
+ weight: wp.float32,
+ pose: wp.array(dtype=wp.transform),
+):
+ joint = wp.tid()
+ pose[joint] = apply_delta_transform(
+ pose[joint],
+ delta_pose[joint],
+ weight,
+ )
+
+
+def _validate_matching_poses(*poses: wp.array) -> None:
+ if any(pose.dtype != wp.transform or pose.ndim != 1 for pose in poses):
+ raise ValueError("Poses must be 1D Warp transform arrays.")
+ if any(pose.shape != poses[0].shape for pose in poses[1:]):
+ raise ValueError("Pose storage must have matching shapes.")
+
+
+def compute_delta_pose(
+ src_pose: wp.array,
+ dst_pose: wp.array,
+ output_delta_pose: wp.array,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Compute the transform delta of each joint from src_pose to dst_pose.
+
+ Args:
+ src_pose: Start pose, one transform per joint.
+ dst_pose: End pose, with the same shape.
+ output_delta_pose: Array that receives one delta per joint. Applying it to
+ src_pose gives dst_pose.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ _validate_matching_poses(src_pose, dst_pose, output_delta_pose)
+ wp.launch(
+ _compute_delta_pose_kernel,
+ dim=src_pose.shape[0],
+ inputs=[src_pose, dst_pose],
+ outputs=[output_delta_pose],
+ device=output_delta_pose.device,
+ stream=stream,
+ )
+
+
+def apply_delta_pose(
+ pose: wp.array,
+ delta_pose: wp.array,
+ weight: float,
+ stream: wp.Stream | None = None,
+) -> None:
+ """Apply one weighted delta pose in place.
+
+ Args:
+ pose: Pose to change, one transform per joint.
+ delta_pose: Deltas from compute_delta_pose(), with the same shape.
+ weight: Share of each delta to apply, clamped to 0 to 1.
+ stream: Stream for the work. None uses the current stream.
+ """
+
+ _validate_matching_poses(pose, delta_pose)
+ wp.launch(
+ _apply_delta_pose_kernel,
+ dim=pose.shape[0],
+ inputs=[delta_pose, wp.clamp(weight, 0.0, 1.0)],
+ outputs=[pose],
+ device=pose.device,
+ stream=stream,
+ )
+
+
+def blend_additive_accumulate_transform(
+ accumulated: wp.transform,
+ pose: wp.transform,
+ weight: wp.float32,
+) -> wp.transform:
+ """Add a weighted transform to a running sum.
+
+ The rotation is flipped onto the sum's side of the quaternion sphere first.
+ """
+ rotation = pose.q
+ rotation = wp.where(
+ wp.dot(accumulated.q, rotation) < 0.0,
+ -rotation,
+ rotation,
+ )
+
+ return accumulated + wp.transform(pose.p, rotation) * weight
+
+
+def blend_additive_end_transform(
+ accumulated: wp.transform,
+ default_transform: wp.transform,
+ weight_sum: wp.float32,
+) -> wp.transform:
+ """Finish an additive blend and normalize its rotation.
+
+ Weight missing below one comes from default_transform.
+ """
+ if weight_sum < 1.0:
+ accumulated = blend_additive_accumulate_transform(
+ accumulated,
+ default_transform,
+ 1.0 - weight_sum,
+ )
+
+ return wp.transform(
+ accumulated.p,
+ wp.normalize(accumulated.q),
+ )
diff --git a/motionbricks/utils/space_conversion_utils.py b/motionbricks/utils/space_conversion_utils.py
new file mode 100644
index 0000000..e55675e
--- /dev/null
+++ b/motionbricks/utils/space_conversion_utils.py
@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Convert transforms from Y up source data to Newton's Z up space."""
+
+from enum import IntEnum, auto
+
+import warp as wp
+
+
+class FacingDirectionType(IntEnum):
+ """How converted characters face, following Maya or MuJoCo conventions."""
+ MAYA = auto()
+ MUJOCO = auto()
+
+
+class SpaceConverter:
+ """Convert source data from Y up to Newton's Z up space.
+
+ The facing direction type sets which way characters face after conversion.
+ """
+ def __init__(self, facing_direction: FacingDirectionType):
+ """Choose the rotation for a facing direction convention.
+
+ Args:
+ facing_direction: MAYA or MUJOCO. Any other value keeps transforms
+ unchanged.
+ """
+ if facing_direction == FacingDirectionType.MUJOCO:
+ self.converter = wp.quat_from_axis_angle(wp.vec3(1, 0, 0), wp.radians(90.0))
+ elif facing_direction == FacingDirectionType.MAYA:
+ q1 = wp.quat_from_axis_angle(wp.vec3(0, 1, 0), wp.radians(90.0))
+ q2 = wp.quat_from_axis_angle(wp.vec3(0, 0, 1), wp.radians(90.0))
+ self.converter = q1 * q2
+ else:
+ self.converter = wp.quat_identity()
+
+ def convert_transform(self, transform):
+ """Convert a transform from the source space to Newton's space.
+
+ Args:
+ transform: Transform in the source space.
+ """
+ return wp.mul(wp.transform(wp.vec3(0, 0, 0), self.converter), transform)
diff --git a/motionbricks/utils/time_utils.py b/motionbricks/utils/time_utils.py
new file mode 100644
index 0000000..88048d9
--- /dev/null
+++ b/motionbricks/utils/time_utils.py
@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Map times to animation frames and to samples of recorded history."""
+
+import numpy as np
+import warp as wp
+
+
+def history_sample_indices(delta_times: np.ndarray, num_samples: int, sample_rate: float):
+ """Find samples at a fixed rate, ending at the latest recorded pose.
+
+ Returns the lower frame, upper frame, and blend of each sample. Samples
+ before the available history clamp to its oldest pose.
+
+ Args:
+ delta_times: Time from each recorded pose to the next, in seconds. The last
+ value is zero.
+ num_samples: Number of samples to find.
+ sample_rate: Sample rate in Hz.
+ """
+ pose_times = np.zeros_like(delta_times)
+ for frame in range(len(pose_times) - 2, -1, -1):
+ pose_times[frame] = pose_times[frame + 1] - delta_times[frame]
+ lower_frames = np.empty(num_samples, dtype=np.int32)
+ upper_frames = np.empty(num_samples, dtype=np.int32)
+ blends = np.empty(num_samples, dtype=np.float32)
+ first_sample = -(num_samples - 1) / sample_rate
+ for sample in range(num_samples):
+ sample_time = first_sample + sample / sample_rate
+ upper = min(int(np.searchsorted(pose_times, sample_time, side="right")), len(pose_times) - 1)
+ lower = max(upper - 1, 0)
+ frame_time = float(pose_times[upper] - pose_times[lower])
+ if frame_time > 0.0:
+ blend = (sample_time - float(pose_times[lower])) / frame_time
+ else:
+ lower = upper
+ blend = 0.0
+ lower_frames[sample] = lower
+ upper_frames[sample] = upper
+ blends[sample] = np.clip(blend, 0.0, 1.0)
+ return lower_frames, upper_frames, blends
+
+
+def frame_index_from_time(time, sample_rate, num_frames):
+ """Return the frame at a time, the next frame, and the blend toward the next frame.
+
+ Both frames are clamped to [0, num_frames - 1], so the last frame is its own next
+ frame. The blend is in [0, 1]. A blend of 0 uses only the frame, and 1 uses only
+ the next one.
+
+ Args:
+ time: Time in seconds.
+ sample_rate: Sample rate in Hz.
+ num_frames: Number of frames.
+ """
+ last_frame = wp.max(0, num_frames - 1)
+ fractional = time * sample_rate
+ frame = wp.clamp(int(wp.floor(fractional)), 0, last_frame)
+ next_frame_blend = 0.0
+ if frame < last_frame:
+ next_frame_blend = wp.clamp(fractional - frame, 0.0, 1.0)
+
+ return frame, min(frame + 1, last_frame), next_frame_blend
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..4911f9d
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools >= 77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "motionbricks"
+dynamic = ["version"]
+license = "Apache-2.0 AND CC-BY-4.0"
+license-files = ["LICENSE", "licenses/**/*.txt"]
+requires-python = ">=3.12"
+
+dependencies = [
+ "newton==1.6.0",
+ "warp-lang>=1.17.0",
+ "pyglet==2.1.13",
+ "numpy==2.4.3",
+ "trimesh>=4.6.8",
+ "imgui-bundle==1.92.4",
+ "pillow>=13.0.0",
+ "usd-core==26.3",
+ "scipy==1.17.1",
+ "tensorrt-cu12==10.8.0.43",
+ "tensorrt-cu12-bindings==10.8.0.43",
+ "tensorrt-cu12-libs==10.8.0.43",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["motionbricks*"]
+exclude = ["app*", "assets*"]
+
+[tool.setuptools.package-data]
+motionbricks = ["assets/**/*"]
+
+[tool.setuptools.dynamic]
+version = { attr = "motionbricks.__version__" }
+
+[tool.uv]
+managed = true
diff --git a/tests/app/test_cli.py b/tests/app/test_cli.py
new file mode 100644
index 0000000..e053b55
--- /dev/null
+++ b/tests/app/test_cli.py
@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Output levels shared by the apps."""
+
+import argparse
+import logging
+import unittest
+
+import warp as wp
+
+from app.utils.cli import configure_logging
+
+
+class ConfigureLoggingTests(unittest.TestCase):
+ def setUp(self):
+ root = logging.getLogger()
+ names = ("__main__", "app", "motionbricks")
+ state = (root.level, list(root.handlers), {name: logging.getLogger(name).level for name in names})
+ self.addCleanup(self._restore, *state)
+ self.addCleanup(setattr, wp.config, "log_level", wp.config.log_level)
+
+ @staticmethod
+ def _restore(level, handlers, levels):
+ root = logging.getLogger()
+ for handler in list(root.handlers):
+ root.removeHandler(handler)
+ for handler in handlers:
+ root.addHandler(handler)
+ root.setLevel(level)
+ for name, value in levels.items():
+ logging.getLogger(name).setLevel(value)
+
+ def test_quiet_default_and_verbose_levels(self):
+ for quiet, verbose, level in (
+ (True, False, logging.WARNING),
+ (False, False, logging.INFO),
+ (False, True, logging.DEBUG),
+ ):
+ with self.subTest(quiet=quiet, verbose=verbose):
+ configure_logging(argparse.Namespace(quiet=quiet, verbose=verbose))
+ for name in ("__main__", "app.scene_preview", "motionbricks.io.bvh"):
+ self.assertEqual(logging.getLogger(name).getEffectiveLevel(), level)
+ self.assertEqual(logging.getLogger("other.library").getEffectiveLevel(), logging.WARNING)
+ self.assertEqual(wp.config.log_level >= wp.LOG_WARNING, not verbose)
+ wp.config.log_level = wp.LOG_INFO
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_clip_registry.py b/tests/app/test_clip_registry.py
new file mode 100644
index 0000000..63521ff
--- /dev/null
+++ b/tests/app/test_clip_registry.py
@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Source clips stay bound to a demo's rig and device."""
+
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+from unittest.mock import patch
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.clip_registry import ClipLoadError, ClipRegistry
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.csv import CSV_SAMPLE_RATE, load_csv, save_csv
+from motionbricks.model.contract import ModelRig
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+
+class ClipRegistryTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+
+ def setUp(self):
+ folder = TemporaryDirectory()
+ self.addCleanup(folder.cleanup)
+ self.root = Path(folder.name)
+
+ def test_rejects_loading_configuration_for_another_rig(self):
+ with wp.ScopedDevice("cpu"):
+ skeleton = Skeleton(["Hips"], [-1], [wp.transform_identity()])
+ soma = {"skeleton": skeleton}
+ g1 = {"joint_names": ("hinge",)}
+ for rig, configuration in (
+ (ModelRig.SOMA, g1),
+ (ModelRig.UNITREE_G1, soma),
+ (ModelRig.SOMA, {**soma, **g1}),
+ (ModelRig.UNITREE_G1, {**g1, **soma}),
+ ):
+ with self.subTest(rig=rig, configuration=configuration):
+ with self.assertRaises(ValueError):
+ ClipRegistry(rig, **configuration)
+
+ def test_bvh_uses_each_registrys_skeleton_and_device(self):
+ path = self.root / "source.bvh"
+ path.write_text(
+ "HIERARCHY\nROOT Hips\n{\n OFFSET 0 0 0\n"
+ " CHANNELS 6 Xposition Yposition Zposition Xrotation Yrotation Zrotation\n"
+ "}\nMOTION\nFrames: 2\nFrame Time: 0.03333333333333333\n"
+ "100 200 300 0 0 0\n400 500 600 0 0 0\n",
+ encoding="utf-8",
+ )
+ previous = None
+ for device in wp.get_devices():
+ for extra_joint_height in (1.0, 2.0):
+ with self.subTest(device=device, height=extra_joint_height):
+ with wp.ScopedDevice(device):
+ skeleton = Skeleton(["Hips", "Extra"], [-1, 0], [
+ wp.transform_identity(),
+ wp.transform(wp.vec3(0, extra_joint_height, 0), wp.quat_identity()),
+ ])
+ registry = ClipRegistry(ModelRig.SOMA, skeleton=skeleton)
+ # Loading must follow the registry, even with a different current device.
+ with wp.ScopedDevice("cpu"):
+ clip = registry.load(path)
+ self.assertIs(registry.load(path.parent / "unused" / ".." / path.name), clip)
+ self.assertIs(clip.animation.skeleton, skeleton)
+ self.assertEqual(clip.animation.poses.device, device)
+ poses = clip.animation.poses.numpy()
+ np.testing.assert_allclose(poses[:, 0, :3], [[1, 2, 3], [4, 5, 6]])
+ np.testing.assert_allclose(poses[:, 1, 1], extra_joint_height)
+ self.assertIsNot(clip, previous)
+ previous = clip
+
+ def test_csv_preserves_joint_order_at_the_csv_sample_rate(self):
+ path = self.root / "source.csv"
+ with wp.ScopedDevice("cpu"):
+ data = np.zeros((3, 9), dtype=np.float32)
+ data[:, 6] = 1.0
+ data[:, 7:] = [[0.1, -0.2], [0.2, -0.3], [0.3, -0.4]]
+ source = DOFAnimationBuffer(("hip", "knee"), 120.0, wp.array(data, dtype=wp.float32))
+ save_csv(str(path), source)
+ registry = ClipRegistry(ModelRig.UNITREE_G1, joint_names=("hip", "knee"), device="cpu")
+ with patch("app.runtime.common.clip_registry.load_csv", wraps=load_csv) as read_csv:
+ clip = registry.load(path)
+ self.assertIs(clip, registry.load(path))
+ self.assertEqual(read_csv.call_count, 1)
+ self.assertEqual(clip.animation.sample_rate, CSV_SAMPLE_RATE)
+ np.testing.assert_allclose(clip.animation.poses.numpy(), data, atol=1e-7)
+ wrong_order = ClipRegistry(ModelRig.UNITREE_G1, joint_names=("knee", "hip"), device="cpu")
+ with self.assertRaisesRegex(ClipLoadError, "joint order"):
+ wrong_order.load(path)
+ with self.assertRaisesRegex(ClipLoadError, r"loads \.csv clips"):
+ registry.load(self.root / "source.bvh")
+
+ def test_failed_load_does_not_cache_a_missing_or_incompatible_clip(self):
+ path = self.root / "source.csv"
+ registry = ClipRegistry(ModelRig.UNITREE_G1, joint_names=("hinge",), device="cpu")
+ with self.assertRaisesRegex(ClipLoadError, "Could not find clip"):
+ registry.load(path)
+ header = "Frame,root_translateX,root_translateY,root_translateZ,root_rotateX,root_rotateY,root_rotateZ,"
+ path.write_text(header + "wrong_joint\n0,0,0,0,0,0,0,30\n", encoding="utf-8")
+ with self.assertRaisesRegex(ClipLoadError, "joint order"):
+ registry.load(path)
+ path.write_text(header + "hinge\n0,0,0,0,0,0,0,30\n", encoding="utf-8")
+ clip = registry.load(path)
+ self.assertEqual(clip.animation.joint_names, ("hinge",))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_editor_exit.py b/tests/app/test_editor_exit.py
new file mode 100644
index 0000000..1c488a8
--- /dev/null
+++ b/tests/app/test_editor_exit.py
@@ -0,0 +1,142 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+import warp as wp
+from imgui_bundle import imgui
+
+from app.authoring.common import FileAction
+from app.runtime.common.io.scene_document import SceneDefinition
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveDocument
+from app.scene_editor import SceneEditor
+from app.smart_primitive_editor import SmartPrimitiveEditor
+
+
+_EDITORS = (SceneEditor, SmartPrimitiveEditor)
+
+
+def _editor(editor_type):
+ editor = editor_type.__new__(editor_type)
+ editor.viewer = Mock()
+ editor.viewer.is_running.return_value = True
+ editor._exit_requested = False
+ editor._document_path = None
+ editor._status = None
+ editor._update_window_title = Mock()
+ editor._capture_camera_state = Mock(return_value={
+ "pos": [1.0, 2.0, 3.0], "pivot": [0.0, 0.0, 0.0],
+ "pitch": -20.0, "yaw": 45.0, "fov": 60.0, "near": 0.01, "far": 1000.0,
+ })
+ if editor_type is SceneEditor:
+ editor.scene = SceneDefinition()
+ item = editor.scene.add_solid_cube()
+ editor.selected_item_id = item.id
+ else:
+ editor.authoring = SmartPrimitiveDocument("soma", SimpleNamespace(), wp.transform_identity())
+ item = editor.authoring.add_node()
+ editor.selected_id = item.id
+ item.name = "Unsaved edit"
+ # The Save As dialog returns this mock's value.
+ return editor, Mock(return_value="")
+
+
+def _confirmation_ui(choice):
+ ui = Mock()
+ ui.begin_popup_modal.return_value = (True, None)
+ ui.button.side_effect = lambda label: label == choice
+ return ui
+
+
+class EditorExitTests(unittest.TestCase):
+ def test_save_writes_current_document_and_closes_only_after_the_frame(self):
+ for editor_type in _EDITORS:
+ for new_document in (False, True):
+ with self.subTest(editor=editor_type.__name__, new=new_document):
+ with tempfile.TemporaryDirectory() as directory:
+ editor, chooser = _editor(editor_type)
+ suffix = "scene" if editor_type is SceneEditor else "smart_primitive"
+ path = Path(directory) / f"saved.{suffix}.json"
+ chooser.return_value = str(path)
+ if not new_document:
+ editor._document_path = path
+ events = []
+
+ def render():
+ events.append("frame start")
+ editor._draw_exit_confirmation(_confirmation_ui("Save"))
+ self.assertIn("Unsaved edit", path.read_text(encoding="utf-8"))
+ editor.viewer.close.assert_not_called()
+ events.append("frame complete")
+
+ editor.render = Mock(side_effect=render)
+ editor.viewer.close.side_effect = lambda: events.append("close")
+ with patch("app.authoring.common.choose_file", chooser):
+ editor.run(max_frames=3)
+
+ self.assertEqual(events, ["frame start", "frame complete", "close"])
+ self.assertEqual(chooser.call_count, int(new_document))
+ self.assertTrue(editor._exit_requested)
+
+ def test_failed_save_keeps_the_editor_open_and_preserves_the_existing_file(self):
+ for editor_type in _EDITORS:
+ with self.subTest(editor=editor_type.__name__):
+ with tempfile.TemporaryDirectory() as directory:
+ editor, chooser = _editor(editor_type)
+ chooser.return_value = str(Path(directory) / "existing")
+ with patch("app.authoring.common.choose_file", chooser):
+ self.assertTrue(editor._handle_file_action(FileAction.SAVE))
+ path = editor._document_path
+ original = path.read_bytes()
+ editor.selected.name = "Another unsaved edit"
+ with patch("os.replace", side_effect=OSError("disk full")):
+ editor._draw_exit_confirmation(_confirmation_ui("Save"))
+ self.assertFalse(editor._exit_requested)
+ self.assertIn("disk full", editor._status)
+ self.assertEqual(path.read_bytes(), original)
+ self.assertEqual(list(path.parent.iterdir()), [path])
+ editor.viewer.close.assert_not_called()
+
+ def test_dont_save_and_cancel_never_save(self):
+ # The document is new, so Save opens Save As. The user cancels it.
+ for editor_type in _EDITORS:
+ for choice, should_exit in (("Don't Save", True), ("Cancel", False), ("Save", False)):
+ with self.subTest(editor=editor_type.__name__, choice=choice):
+ editor, chooser = _editor(editor_type)
+ with patch("app.authoring.common.choose_file", chooser):
+ editor._draw_exit_confirmation(_confirmation_ui(choice))
+ self.assertEqual(chooser.call_count, int(choice == "Save"))
+ self.assertEqual(editor._exit_requested, should_exit)
+ self.assertIsNone(editor._document_path)
+ editor.viewer.close.assert_not_called()
+
+ def test_menu_exit_opens_a_real_imgui_modal_without_closing_the_viewer(self):
+ for editor_type in _EDITORS:
+ with self.subTest(editor=editor_type.__name__):
+ context = imgui.create_context()
+ try:
+ io = imgui.get_io()
+ io.set_ini_filename("")
+ io.display_size = (1000.0, 700.0)
+ io.delta_time = 1.0 / 60.0
+ io.backend_flags |= imgui.BackendFlags_.renderer_has_textures
+ editor, _ = _editor(editor_type)
+ editor._draw_file_menu = Mock(return_value=FileAction.EXIT)
+ editor._draw_tools_menu = Mock()
+ imgui.new_frame()
+ editor._draw_main_menu_bar(imgui)
+ editor._draw_exit_confirmation(imgui)
+ self.assertTrue(imgui.is_popup_open("Exit"))
+ imgui.render()
+ self.assertFalse(editor._exit_requested)
+ editor.viewer.close.assert_not_called()
+ finally:
+ imgui.destroy_context(context)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_g1_locomotion.py b/tests/app/test_g1_locomotion.py
new file mode 100644
index 0000000..a352111
--- /dev/null
+++ b/tests/app/test_g1_locomotion.py
@@ -0,0 +1,739 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Synthetic DOF history, CSV targets, and locomotion, idle and interaction lifecycle tests."""
+
+from dataclasses import replace
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+import unittest
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.clip_registry import ClipRegistry
+from app.runtime.common.interaction import InteractionProbe
+from app.runtime.common.motion import (
+ CROUCH_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE, LINEAR_LOCOMOTION_MODE,
+ LocomotionCommand, LocomotionMode, LocomotionModeRuntime, PlaybackSource, load_locomotion_mode,
+)
+from app.runtime.common.smart_primitive_behaviors import SmartPrimitiveBehavior
+from app.runtime.common.io.smart_primitive_document import (
+ PlaybackMode, SmartPrimitiveAssetPool, SmartPrimitiveDocument, save_smart_primitive_document,
+)
+from app.runtime.unitree_g1.character import UnitreeG1Character
+from app.runtime.common.states import LocomotionState
+from app.runtime.unitree_g1.target_pose_blender import G1TargetPoseBlender
+from motionbricks.io.csv import save_csv
+from motionbricks.model.config import MotionBricksInferenceConfig
+from motionbricks.model.contract import ModelRig
+from motionbricks.model.unitree_g1.buffers import DOFToken
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+from motionbricks.utils.math_utils import project_to_plane
+from motionbricks.runtime.motion_recorder import MotionRecorder
+from motionbricks.runtime.motion_player import GeneratedDOFMotionPlayer
+from motionbricks.runtime.blend_spaces import BlendSpace, BlendSpaceType
+from motionbricks.runtime.target_pose import TargetPoseInferenceParams
+
+
+# Test-owned keys and speeds keep these cases independent of demo tuning.
+LINEAR_LOCOMOTION = LocomotionMode(
+ LINEAR_LOCOMOTION_MODE, Path("unused.json"), BlendSpaceType.LINEAR_1D,
+ (("Idle", (0, 0)), ("Walk", (.3, 0)), ("Jog", (.6, 0)), ("Run", (1, 0))),
+ max_speed=4., default_speed=1.5, minimum_speed=.5, transition_early_by_frames=10,
+)
+DIRECTIONAL_LOCOMOTION = replace(
+ LINEAR_LOCOMOTION, name=DIRECTIONAL_LOCOMOTION_MODE,
+ blend_space_type=BlendSpaceType.DIRECTIONAL_2D,
+ target_values=(("Idle", (0, 0)), ("Forward", (1, 0)), ("Backward", (-1, 0)),
+ ("Left", (0, 1)), ("Right", (0, -1))),
+ max_speed=2., default_speed=1.,
+)
+CROUCH_LOCOMOTION = replace(
+ DIRECTIONAL_LOCOMOTION, name=CROUCH_LOCOMOTION_MODE,
+ max_speed=1., default_speed=.5, minimum_speed=.3,
+)
+_CAMERA = {"pos": [0.0, -3.0, 1.0], "pivot": [0.0, 0.0, 1.0], "pitch": -10.0, "yaw": 90.0,
+ "fov": 45.0, "near": 0.1, "far": 100.0}
+
+
+def _poses(times):
+ times = np.asarray(times, dtype=np.float32)
+ data = np.zeros((len(times), 8), dtype=np.float32)
+ data[:, 0] = 2.0 + times
+ data[:, 1] = -1.0 + times * 0.5
+ data[:, 2] = 0.8 + times * 0.1
+ data[:, 5] = np.sin(times * 0.4)
+ data[:, 6] = np.cos(times * 0.4)
+ data[:, 7] = times * 0.7
+ return data
+
+
+def _facing_minus_y(poses):
+ """Turn each root a quarter turn clockwise, so the clip starts facing -Y like the real G1 clips."""
+ turn = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), -0.5 * np.pi)
+ for row in poses:
+ row[3:7] = wp.mul(turn, wp.quat(*row[3:7]))
+ return poses
+
+
+def _reference_pose():
+ return wp.array(_poses([0])[0], dtype=wp.float32)
+
+
+class _Engine:
+ """Deterministic endpoint interpolation; no ONNX or robot assets needed."""
+
+ def __init__(self):
+ self.device = wp.get_device("cpu")
+ self.stream = None
+ self.contract = SimpleNamespace(joint_names=("hinge",), sample_rate=30.0)
+ self.contexts = []
+ self.targets = []
+ self.configs = []
+
+ def create_input(self):
+ return DOFToken(1, device=self.device)
+
+ def create_output(self):
+ return DOFAnimationBuffer(
+ ("hinge",), 30.0, wp.full((58, 8), 999.0, dtype=wp.float32, device=self.device), num_frames=0,
+ foot_contacts=wp.zeros((58, 4), dtype=wp.float32, device=self.device),
+ )
+
+ def generate_animation(self, context, target, output, *, config):
+ self.contexts.append(context.poses.numpy().copy())
+ self.targets.append(target.poses.numpy()[: target.num_poses].copy())
+ self.configs.append(config)
+ start, end = self.contexts[-1][-1], target.poses.numpy()[0]
+ values = np.linspace(start, end, 26, dtype=np.float32)
+ for frame in range(26):
+ values[frame, 3:7] = wp.quat_slerp(wp.quat(*start[3:7]), wp.quat(*end[3:7]), frame / 25)
+ output.poses[:26].assign(values)
+ output.foot_contacts[:26].assign(np.repeat(np.linspace(0.1, 0.9, 26, dtype=np.float32)[:, None], 4, axis=1))
+ output.num_frames = 26
+
+
+class _SequenceLoop(SmartPrimitiveBehavior):
+ """Enter through a sequence, loop a clip until interact(), then leave through another sequence."""
+
+ required_sequences = ("Entry", "Exit")
+
+ def enter(self):
+ self.interaction_state.play_target_pose_sequence("Entry", on_complete=self._loop)
+
+ def _loop(self):
+ self.interaction_state.play_clip(self.clip_paths[0], loop=True)
+
+ def interact(self):
+ if self.interaction_state.is_looping:
+ self.interaction_state.play_target_pose_sequence("Exit")
+
+
+class _PlayOnce(SmartPrimitiveBehavior):
+ """Play one clip once, then return to movement."""
+
+ def enter(self):
+ self.interaction_state.play_clip(self.clip_paths[0])
+
+
+class G1LocomotionTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def setUp(self):
+ self.folder = TemporaryDirectory()
+ self.addCleanup(self.folder.cleanup)
+ self.root = Path(self.folder.name)
+ self.source = DOFAnimationBuffer(("hinge",), 120.0, wp.array(_poses(np.arange(121) / 120), dtype=wp.float32))
+ self.csv_path = self.root / "source.csv"
+ save_csv(str(self.csv_path), self.source)
+ idle_data = _facing_minus_y(_poses(np.arange(121) / 120))
+ idle_data[:, 2] += 0.03 * np.sin(np.arange(121) / 120 * 2 * np.pi)
+ idle_data[:, 7] += 0.2 * np.sin(np.arange(121) / 120 * 2 * np.pi)
+ self.idle_path = self.root / "idle.csv"
+ save_csv(
+ str(self.idle_path), DOFAnimationBuffer(("hinge",), 120, wp.array(idle_data, dtype=wp.float32)),
+ )
+ crouch_data = _facing_minus_y(_poses(np.arange(121) / 120))
+ crouch_data[:, 2] -= 0.4
+ crouch_data[:, 7] += 1.0
+ crouch_buffer = DOFAnimationBuffer(("hinge",), 120, wp.array(crouch_data, dtype=wp.float32))
+ crouch_path = self.root / "crouch.csv"
+ save_csv(str(crouch_path), crouch_buffer)
+ self.crouch_idle_path = self.root / "crouch_idle.csv"
+ save_csv(str(self.crouch_idle_path), crouch_buffer)
+
+ self.clip_registry = ClipRegistry(
+ ModelRig.UNITREE_G1, joint_names=("hinge",), device="cpu",
+ )
+ self.selection_times = (0.014, 0.2, 0.4, 0.6)
+ linear_targets = [
+ (name, self.csv_path, self.selection_times[index], index > 0)
+ for index, name in enumerate(("Idle", "Walk", "Jog", "Run"))
+ ]
+ self.mode = replace(LINEAR_LOCOMOTION, smart_primitive_path=self._save_targets("linear", linear_targets))
+ directional_modes = []
+ for definition, path in ((DIRECTIONAL_LOCOMOTION, self.csv_path), (CROUCH_LOCOMOTION, crouch_path)):
+ targets = [(name, path, index * 0.15, True) for index, (name, _) in enumerate(definition.target_values)]
+ directional_modes.append(replace(
+ definition, smart_primitive_path=self._save_targets(definition.name, targets),
+ ))
+ self.modes = (self.mode, *directional_modes)
+ self.asset_pool = SmartPrimitiveAssetPool(
+ self.clip_registry, _reference_pose(), wp.transform_identity(),
+ )
+
+ def _save_targets(self, name, targets):
+ """Save targets that start at the origin facing +X, as the bundled G1 documents do."""
+ document = SmartPrimitiveDocument("unitree_g1", _reference_pose(), wp.transform_identity())
+ for node_name, path, sample_time, use_frames in targets:
+ node = document.add_node()
+ node.name = node_name
+ target = document.add_target_pose(node)
+ target.set_clip(self.clip_registry.load(path))
+ if use_frames:
+ target.playback_mode = PlaybackMode.FRAMES
+ target.set_time(round(sample_time * 120) / 120)
+ else:
+ target.set_time(sample_time)
+ target.constrain_hips(True)
+ root = target.pose.numpy()
+ heading = project_to_plane(wp.transform(wp.vec3(*root[:3]), wp.quat(*root[3:7])), wp.vec3(0.0, 0.0, 1.0))
+ node.local_xform = wp.transform(wp.vec3(0.0, 0.0, 0.0), wp.quat_inverse(heading.q))
+ return save_smart_primitive_document(document, self.root / name, document.root.id, _CAMERA)
+
+ def _character(self, initial_mode=LINEAR_LOCOMOTION.name, **options):
+ engine = _Engine()
+ # Ensure sampling honors a single-embodiment view in a larger flat array.
+ storage = wp.full(18, -99.0, dtype=wp.float32)
+ joint_q = storage[5:13]
+ joint_q.assign(_poses([0])[0])
+ character = UnitreeG1Character(
+ engine, current_pose=joint_q, asset_pool=self.asset_pool, modes=self.modes, initial_mode=initial_mode,
+ idle_paths=(self.idle_path,), crouch_idle_paths=(self.crouch_idle_path,), **options,
+ )
+ return character, engine, storage
+
+ def _save_interaction(self):
+ """Save an Entry sequence of two targets and an Exit sequence of one, all from the source clip."""
+ document = SmartPrimitiveDocument("unitree_g1", _reference_pose(), wp.transform_identity())
+ clip = self.clip_registry.load(self.csv_path)
+ nodes = {}
+ for name, frame, poses_to_use in (("Approach", 24, 4), ("Hold", 60, 1), ("Depart", 96, 4)):
+ nodes[name] = document.add_node()
+ nodes[name].name = name
+ target = document.add_target_pose(nodes[name])
+ target.set_clip(clip)
+ target.playback_mode = PlaybackMode.FRAMES
+ target.set_time(frame / 120)
+ target.set_num_poses_to_use(poses_to_use)
+ for name, targets in (("Entry", ("Approach", "Hold")), ("Exit", ("Depart",))):
+ sequence = document.add_sequence()
+ sequence.name = name
+ for target in targets:
+ document.add_sequence_node(sequence, nodes[target])
+ return save_smart_primitive_document(document, self.root / "interaction", document.root.id, _CAMERA)
+
+ def _step(self, character, engine, command, delta_time=0.03):
+ """Step once and check that every new generation continues from the pose shown before the step."""
+ before = character.current_pose.numpy().copy()
+ generations = len(engine.contexts)
+ character.step(delta_time, command)
+ for context in engine.contexts[generations:]:
+ np.testing.assert_allclose(context[-1], before, atol=1e-6)
+ return before
+
+ def _step_until(self, character, engine, command, done, limit=200):
+ """Step until done() is true and return the pose shown before the last step."""
+ for _ in range(limit):
+ before = self._step(character, engine, command)
+ if done():
+ return before
+ self.fail("The character never reached the expected state.")
+
+ def test_selection_modes_sampling_rate_and_root_normalization(self):
+ primitive = self.asset_pool.instantiate(self.mode.smart_primitive_path)
+ self.assertEqual(primitive.rig, "unitree_g1")
+ self.assertEqual(primitive.asset.rig, "unitree_g1")
+ self.assertEqual(primitive.pose_size, self.source.num_coordinates)
+ runtime = load_locomotion_mode(self.mode, self.asset_pool)
+ targets = runtime.target_poses.numpy()
+ for index, start in enumerate(self.selection_times):
+ times = start + np.arange(4) / 30
+ np.testing.assert_allclose(targets[index, :, 7], times * 0.7, atol=2e-7)
+ np.testing.assert_allclose(targets[index, :, 2], 0.8 + times * 0.1, atol=1e-6)
+ np.testing.assert_allclose(targets[index, 0, :2], 0.0, atol=3e-7)
+ np.testing.assert_allclose(targets[index, 0, 3:7], [0, 0, 0, 1], atol=3e-7)
+
+ def test_modes_and_idles_share_source_clips_without_looping_the_source(self):
+ source = self.clip_registry.load(self.csv_path).animation
+ original = source.poses.numpy().copy()
+ load_locomotion_mode(self.mode, self.asset_pool)
+ load_locomotion_mode(self.modes[1], self.asset_pool)
+ character = UnitreeG1Character.__new__(UnitreeG1Character)
+ character.engine = SimpleNamespace(stream=None)
+ character.clip_registry = self.clip_registry
+ character.model_to_runtime = wp.transform_identity()
+ looped = character.load_clip(self.csv_path, loop=True)
+ second_loop = character.load_clip(self.csv_path, loop=True)
+ once = character.load_clip(self.csv_path, loop=False)
+ np.testing.assert_array_equal(source.poses.numpy(), original)
+ # A clip played once uses the shared source directly.
+ self.assertIs(once.animation, source)
+ self.assertIsNot(looped.animation.poses, source.poses)
+ self.assertIsNot(second_loop.animation.poses, looped.animation.poses)
+ np.testing.assert_allclose(looped.animation.poses.numpy()[-1], original[0], atol=1e-6)
+
+ def test_dof_target_reports_root_velocity_and_constrained_trajectory(self):
+ document = SmartPrimitiveDocument("unitree_g1", _reference_pose(), wp.transform_identity())
+ target = document.add_target_pose(document.add_node())
+ target.set_clip(self.clip_registry.load(self.csv_path))
+ target.set_time(0.5)
+ target.constrain_hips(True)
+
+ # The clip's root moves at (1, 0.5, 0.1) m/s; the constraint keeps only its height.
+ np.testing.assert_allclose([float(target.velocity[axis]) for axis in range(3)], [1.0, 0.5, 0.1], atol=1e-4)
+ times = np.clip(0.5 + (np.arange(21) - 10) * target.trajectory_scale / 30, 0.0, 1.0)
+ trajectory = target.trajectory_transforms.numpy()
+ np.testing.assert_allclose(trajectory[:, 0], times - 0.5, atol=1e-5)
+ np.testing.assert_allclose(trajectory[:, 1], 0.5 * (times - 0.5), atol=1e-5)
+ np.testing.assert_allclose(trajectory[:, 2], 0.8 + 0.1 * times, atol=1e-5)
+
+ def test_locomotion_targets_must_use_all_four_frames(self):
+ document = SmartPrimitiveDocument("unitree_g1", _reference_pose(), wp.transform_identity())
+ for node_name, _ in LINEAR_LOCOMOTION.target_values:
+ node = document.add_node()
+ node.name = node_name
+ target = document.add_target_pose(node)
+ target.set_clip(self.clip_registry.load(self.csv_path))
+ # Interactions may use fewer frames, but locomotion blends whole four-frame windows.
+ target.set_num_poses_to_use(1)
+ path = save_smart_primitive_document(
+ document, self.root / "one_frame", document.root.id, _CAMERA,
+ )
+
+ with self.assertRaisesRegex(ValueError, "'Run' must use 4 poses"):
+ load_locomotion_mode(replace(LINEAR_LOCOMOTION, smart_primitive_path=path), self.asset_pool)
+
+ def test_modes_blend_then_scale_speed_and_place_only_the_root(self):
+ # Nonuniform steps catch changes to the authored velocity pattern.
+ progress = np.array([0, 0.2, 0.7, 1.0], dtype=np.float32)
+ height_motion = np.array([0, 0.06, -0.02, 0.1], dtype=np.float32)
+ hinge_motion = np.array([0, 0.1, 0.15, 0.2], dtype=np.float32)
+ for definition, speed, facing, height, hinge in (
+ (LINEAR_LOCOMOTION, 2.25, (0, 1, 0), 2, 1),
+ (DIRECTIONAL_LOCOMOTION, 4.5, (1, 0, 0), 3, 1.5),
+ ):
+ for device in wp.get_devices():
+ with self.subTest(mode=definition.name, device=str(device)), wp.ScopedDevice(device):
+ mode = replace(definition, max_speed=4.5, velocity_scale=0.9, position_scale=0.8)
+ keys = ((0, 0), (1, 0)) if definition is LINEAR_LOCOMOTION else ((0, 0), (1, 0), (0, -1))
+ space = BlendSpace(mode.blend_space_type)
+ for index, key in enumerate(keys):
+ space.add_target(wp.vec2(*key), index)
+ space.compile()
+ data = np.zeros((len(keys), 4, 8), dtype=np.float32)
+ data[..., 6] = 1
+ data[0, :, 0] = progress * 0.3
+ data[1, :, 0] = progress * 0.9
+ data[0, :, 2] = 1 + height_motion
+ data[1, :, 2] = 3 + height_motion
+ data[0, :, 7] = 0.5 + hinge_motion
+ data[1, :, 7] = 1.5 + hinge_motion
+ runtime = LocomotionModeRuntime(
+ mode, space, wp.array(data, dtype=wp.float32),
+ )
+ state = LocomotionState("test", (runtime,), mode.name, wp.empty((1, 8), dtype=wp.float32))
+ direction = np.asarray(facing, dtype=np.float32)
+ character = SimpleNamespace(
+ engine=SimpleNamespace(device=device, stream=None),
+ target_pose_blender=G1TargetPoseBlender(),
+ character_ground_position=np.array([10, 2, 0], dtype=np.float32),
+ movement=SimpleNamespace(current_facing=direction, desired_velocity=direction * speed),
+ )
+ blended = wp.empty((4, 8), dtype=wp.float32)
+ targets = wp.empty_like(blended)
+
+ state.evaluate_current_target_poses(character, blended, targets)
+
+ result = targets.numpy()
+ ground = character.character_ground_position + direction * speed * 0.9 * 0.8
+ expected_xy = ground[:2] + progress[:, None] * direction[:2] * speed * 0.9 * 0.1
+ np.testing.assert_allclose(result[:, :2], expected_xy, atol=2e-6)
+ np.testing.assert_allclose(result[:, 2], height + height_motion, atol=3e-7)
+ yaw = wp.quat_from_axis_angle(wp.vec3(0, 0, 1), np.arctan2(direction[1], direction[0]))
+ np.testing.assert_allclose(result[:, 3:7], np.tile(yaw, (4, 1)), atol=2e-7)
+ np.testing.assert_allclose(result[:, 7], hinge + hinge_motion, atol=2e-7)
+ np.testing.assert_array_equal(runtime.target_poses.numpy(), data)
+
+ def test_directional_targets_follow_facing_and_blend_diagonal_dof_motion(self):
+ mode = replace(DIRECTIONAL_LOCOMOTION, max_speed=2.0)
+ height = 0.8
+ for device in wp.get_devices():
+ with self.subTest(device=str(device)), wp.ScopedDevice(device):
+ space = BlendSpace(mode.blend_space_type)
+ data = np.zeros((5, 4, 8), dtype=np.float32)
+ data[:, :, 2] = height
+ data[:, :, 6] = 1
+ for index, (_, value) in enumerate(mode.target_values):
+ space.add_target(wp.vec2(*value), index)
+ data[index, :, :2] = np.arange(4)[:, None] / 30 * np.array(value) * 2
+ data[index, :, 7] = index + np.arange(4) * 0.1
+ space.compile()
+ runtime = LocomotionModeRuntime(mode, space, wp.array(data, dtype=wp.float32))
+ state = LocomotionState("test", (runtime,), mode.name, wp.empty((1, 8), dtype=wp.float32))
+ character = SimpleNamespace(
+ engine=SimpleNamespace(device=device, stream=None),
+ target_pose_blender=G1TargetPoseBlender(),
+ character_ground_position=np.array([10, 20, 0], dtype=np.float32),
+ movement=SimpleNamespace(
+ current_facing=np.array([0, 1, 0], dtype=np.float32),
+ desired_velocity=np.zeros(3, dtype=np.float32),
+ ),
+ )
+ blended = wp.empty((4, 8), dtype=wp.float32)
+ targets = wp.empty_like(blended)
+ # Facing +Y puts left at -X. A request half forward and half left
+ # uses three positive weights, including the idle.
+ for velocity, weights in (
+ ((0, 0, 0), (1, 0, 0, 0, 0)),
+ ((0, 2, 0), (0, 1, 0, 0, 0)),
+ ((0, -2, 0), (0, 0, 1, 0, 0)),
+ ((-2, 0, 0), (0, 0, 0, 1, 0)),
+ ((2, 0, 0), (0, 0, 0, 0, 1)),
+ ((-0.5, 0.5, 0), (0.5, 0.25, 0, 0.25, 0)),
+ ):
+ with self.subTest(velocity=velocity):
+ character.movement.desired_velocity[:] = velocity
+ state.evaluate_current_target_poses(character, blended, targets)
+ actual = targets.numpy()
+ expected_root = character.character_ground_position + velocity
+ expected_root[2] = height
+ np.testing.assert_allclose(
+ actual[:, :3], expected_root + np.arange(4)[:, None] / 30 * velocity, atol=3e-6,
+ )
+ np.testing.assert_allclose(
+ actual[:, 7], np.dot(weights, np.arange(5)) + np.arange(4) * 0.1, atol=2e-7,
+ )
+ np.testing.assert_allclose(
+ actual[:, 3:7], np.tile([0, 0, np.sqrt(0.5), np.sqrt(0.5)], (4, 1)), atol=2e-7,
+ )
+ np.testing.assert_array_equal(runtime.target_poses.numpy(), data)
+
+ def test_idle_mode_switches_generate_between_standing_and_crouching_clips(self):
+ character, engine, _ = self._character()
+ machine = character.state_machine
+ self.assertFalse(machine.is_interacting)
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ character.step(0.03, LocomotionCommand(facing, None, requested_mode=DIRECTIONAL_LOCOMOTION.name))
+ self.assertEqual(len(engine.contexts), 0)
+ self.assertIs(machine.state, machine.standing_idle_state)
+ for mode, idle in ((CROUCH_LOCOMOTION, machine.crouching_idle_state),
+ (LINEAR_LOCOMOTION, machine.standing_idle_state),
+ (CROUCH_LOCOMOTION, machine.crouching_idle_state)):
+ before = character.current_pose.numpy().copy()
+ character.step(0.03, LocomotionCommand(facing, None, requested_mode=mode.name))
+ self.assertIs(machine.state, idle)
+ self.assertEqual(machine.active_locomotion_state.active_mode.name, mode.name)
+ self.assertIs(character._playback_source, PlaybackSource.CLIP_TRANSITION)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ self.assertIn(character.current_clip, idle.clips)
+ for _ in range(40):
+ character.step(0.03, LocomotionCommand(facing, None))
+ self.assertIs(character._playback_source, PlaybackSource.CLIP)
+ self.assertLess(character.current_pose.numpy()[2], 0.6)
+
+ def test_moving_mode_switches_reuse_displayed_history_and_matching_idle(self):
+ character, engine, storage = self._character()
+ machine = character.state_machine
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ for mode in (LINEAR_LOCOMOTION, DIRECTIONAL_LOCOMOTION, CROUCH_LOCOMOTION,
+ DIRECTIONAL_LOCOMOTION, LINEAR_LOCOMOTION):
+ before = character.current_pose.numpy().copy()
+ generations = len(engine.contexts)
+ character.step(0.03, LocomotionCommand(facing, facing, requested_mode=mode.name))
+ self.assertTrue(machine.is_locomoting)
+ self.assertEqual(machine.active_locomotion_state.active_mode.name, mode.name)
+ self.assertGreater(len(engine.contexts), generations)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ for _ in range(4):
+ character.step(0.03, LocomotionCommand(facing, facing))
+ for mode in (LINEAR_LOCOMOTION, CROUCH_LOCOMOTION):
+ character.step(0.03, LocomotionCommand(facing, facing, requested_mode=mode.name))
+ character.step(0.03, LocomotionCommand(facing, None))
+ idle = machine.crouching_idle_state if mode is CROUCH_LOCOMOTION else machine.standing_idle_state
+ self.assertIs(machine.state, idle)
+ self.assertIn(character.current_clip, idle.clips)
+ np.testing.assert_array_equal(storage.numpy()[:5], -99.0)
+ np.testing.assert_array_equal(storage.numpy()[13:], -99.0)
+
+ def test_initial_crouch_uses_the_crouching_idle_without_generation(self):
+ character, engine, _ = self._character(CROUCH_LOCOMOTION.name)
+ self.assertIs(character.state_machine.state, character.state_machine.crouching_idle_state)
+ self.assertLess(character.current_pose.numpy()[2], 0.6)
+ self.assertEqual(len(engine.contexts), 0)
+
+ def test_loop_closes_root_and_hinges_without_touching_capacity(self):
+ data = _poses([0, 0.25, 0.5, 0.75, 1.0, 1.25])
+ # Nontrivial intermediate motion should survive the endpoint correction.
+ data[2, 2] += 0.15
+ data[2, 7] += 0.2
+ # The last quaternion can use the opposite sign for the same rotation.
+ data[4, 3:7] *= -1
+ animation = DOFAnimationBuffer(("hinge",), 30, wp.array(data, dtype=wp.float32), num_frames=5)
+ animation.make_loopable()
+ result = animation.poses.numpy()
+ np.testing.assert_allclose(result[0], data[0], atol=1e-7)
+ np.testing.assert_allclose(result[4, :3], result[0, :3], atol=1e-6)
+ self.assertAlmostEqual(abs(float(result[4, 3:7] @ result[0, 3:7])), 1.0, places=6)
+ np.testing.assert_allclose(result[4, 7:], result[0, 7:], atol=1e-6)
+ np.testing.assert_array_equal(result[5], data[5])
+ self.assertAlmostEqual(result[2, 2], data[0, 2] + 0.15, places=6)
+ self.assertAlmostEqual(result[2, 7], 0.2, places=6)
+ for count in (0, 1):
+ animation.num_frames = count
+ animation.make_loopable()
+ np.testing.assert_array_equal(animation.poses.numpy(), result)
+
+ def test_history_resamples_elapsed_time_and_root_rotation_at_30_hz(self):
+ reference = wp.array(_poses([0])[0], dtype=wp.float32)
+ history = MotionRecorder(reference, capacity=16)
+ token = DOFToken(1)
+ token.update_from_recorder(history)
+ np.testing.assert_allclose(token.poses.numpy(), _poses([0, 0, 0, 0]))
+ elapsed = 0.0
+ for dt in (0.017, 0.009, 0.032, 0.025, 0.041, 0.013, 0.027, 0.008, 0.03):
+ elapsed += dt
+ reference.assign(_poses([elapsed])[0])
+ history.record(dt, reference)
+ token.update_from_recorder(history)
+ np.testing.assert_allclose(token.poses.numpy(), _poses(elapsed + np.arange(-3, 1) / 30), atol=4e-6)
+ self.assertEqual(token.num_poses, 4)
+
+ def test_generated_player_uses_target_token_policy_and_valid_output(self):
+ engine = _Engine()
+ reference = wp.array(_poses([0])[0], dtype=wp.float32)
+ player = GeneratedDOFMotionPlayer(engine, reference)
+ player.seed_history_from_pose(reference)
+ target = wp.array(_poses([1, 1.03, 1.06, 1.1]), dtype=wp.float32)
+ # A target without its own token counts keeps those of the config.
+ config = MotionBricksInferenceConfig(allowed_token_counts=(9,))
+ player.generate(target, TargetPoseInferenceParams(4, 4), config=config)
+ self.assertEqual(engine.configs[-1].allowed_token_counts, (9,))
+ player.generate(target, TargetPoseInferenceParams(4, 4, allowed_token_counts=(6, 7)))
+ self.assertEqual(engine.configs[-1].allowed_token_counts, (6, 7))
+ self.assertAlmostEqual(player.time_to_transition, 21 / 30)
+ contacts = wp.empty(4, dtype=wp.float32)
+ player.sample(100.0, reference, contacts)
+ np.testing.assert_allclose(reference.numpy(), target.numpy()[0], atol=1e-6)
+ np.testing.assert_allclose(contacts.numpy(), 0.9, atol=1e-6)
+ np.testing.assert_allclose(player.current_root_position(), target.numpy()[0, :3])
+
+ def test_current_foot_contacts_follow_generated_motion_and_read_zero_during_clips(self):
+ character, _, _ = self._character()
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ character.step(0.03, LocomotionCommand(facing, None))
+ self.assertIs(character._playback_source, PlaybackSource.CLIP)
+ np.testing.assert_array_equal(character.current_foot_contacts.numpy(), 0.0)
+ idle_clip = character.current_clip
+ expected = wp.empty(4, dtype=wp.float32, device="cpu")
+
+ # Starting generated motion or a clip updates the contacts before the next step.
+ target = wp.array(_poses([1, 1.03, 1.06, 1.1]), dtype=wp.float32)
+ character.generate_to_target_poses(target, TargetPoseInferenceParams(4, 4))
+ character.player.output.sample_foot_contacts(character.player.playback_time, expected)
+ self.assertGreater(expected.numpy().min(), 0.0)
+ np.testing.assert_allclose(character.current_foot_contacts.numpy(), expected.numpy())
+ character.start_clip(idle_clip, loop=True)
+ np.testing.assert_array_equal(character.current_foot_contacts.numpy(), 0.0)
+
+ character.step(0.03, LocomotionCommand(facing, facing))
+ self.assertIs(character._playback_source, PlaybackSource.GENERATED)
+ character.player.output.sample_foot_contacts(character.player.playback_time, expected)
+ np.testing.assert_allclose(character.current_foot_contacts.numpy(), expected.numpy())
+
+ def test_idle_locomotion_stop_restart_and_clip_boundary_keep_played_history(self):
+ character, engine, storage = self._character()
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ idle = LocomotionCommand(facing, None)
+ moving = LocomotionCommand(facing, facing)
+ character.step(0.137, idle)
+ before = character.current_pose.numpy().copy()
+ character.step(0.02, moving)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ self.assertEqual(character.state_machine.state.name, "Locomotion")
+ for _ in range(8):
+ character.step(0.03, moving)
+ character.step(0.02, idle)
+ self.assertIs(character._playback_source, PlaybackSource.CLIP_TRANSITION)
+ character.step(0.03, idle)
+ before = character.current_pose.numpy().copy()
+ character.step(0.02, moving)
+ self.assertIs(character._playback_source, PlaybackSource.GENERATED)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ character.step(0.02, idle)
+ while character.time_to_transition() > 0.04:
+ character.step(0.031, idle)
+ character.step(0.05, idle)
+ # The transition ended at the idle clip's first pose, so the clip starts from zero.
+ self.assertIs(character._playback_source, PlaybackSource.CLIP)
+ self.assertAlmostEqual(character._clip_playback_time, 0.05)
+ expected = wp.empty(8, dtype=wp.float32)
+ clip = character.current_clip
+ clip.animation.sample(0.05, expected, root_offset=clip.root_offset)
+ np.testing.assert_allclose(character.current_pose.numpy(), expected.numpy(), atol=1e-6)
+ character._clip_playback_time = clip.duration - 0.005
+ character.step(0.012, idle)
+ self.assertAlmostEqual(character._clip_playback_time, 0.007)
+ before = character.current_pose.numpy().copy()
+ character.step(0.015, moving)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ np.testing.assert_array_equal(storage.numpy()[:5], -99.0)
+ np.testing.assert_array_equal(storage.numpy()[13:], -99.0)
+
+ def test_interaction_sequences_and_loop_continue_from_the_displayed_pose(self):
+ character, engine, storage = self._character()
+ machine = character.state_machine
+ state = machine.interaction_state
+ primitive = self.asset_pool.instantiate(self._save_interaction(), _SequenceLoop)
+ primitive.clip_paths = (self.idle_path,)
+ expected = wp.empty((12, 8), dtype=wp.float32)
+ primitive.get_world_target_poses_for_sequence(primitive.sequence_index("Entry"), expected[:8])
+ primitive.get_world_target_poses_for_sequence(primitive.sequence_index("Exit"), expected[8:])
+ expected = expected.numpy()
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ idle = LocomotionCommand(facing, None)
+ self._step(character, engine, idle)
+
+ before = character.current_pose.numpy().copy()
+ machine.start_interaction(character, primitive)
+ self.assertTrue(machine.is_interacting)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ np.testing.assert_allclose(engine.targets[-1], expected[:4], atol=1e-6)
+
+ reached = self._step_until(character, engine, idle, lambda: state.is_looping)
+ self.assertEqual(len(engine.targets), 2)
+ np.testing.assert_allclose(engine.targets[-1], expected[4:5], atol=1e-6)
+ # The loop starts from the reached root, including its height and turn.
+ clip = character.current_clip
+ loop_start = clip.animation.poses.numpy()[0]
+ self.assertGreater(abs(reached[2] - loop_start[2]), 0.01)
+ self.assertLess(abs(float(reached[3:7] @ loop_start[3:7])), 0.999)
+ first = wp.empty(8, dtype=wp.float32)
+ clip.animation.sample(0.0, first, root_offset=clip.root_offset)
+ first = first.numpy()
+ np.testing.assert_allclose(first[:3], reached[:3], atol=1e-5)
+ self.assertAlmostEqual(abs(float(first[3:7] @ reached[3:7])), 1.0, places=6)
+ self.assertAlmostEqual(character._clip_playback_time, 0.03)
+ sampled = wp.empty(8, dtype=wp.float32)
+ clip.animation.sample(0.03, sampled, root_offset=clip.root_offset)
+ np.testing.assert_allclose(character.current_pose.numpy(), sampled.numpy(), atol=1e-6)
+
+ # The loop keeps playing past its duration without generating.
+ generations = len(engine.contexts)
+ for _ in range(40):
+ self._step(character, engine, idle)
+ self.assertTrue(state.is_looping)
+ self.assertEqual(len(engine.contexts), generations)
+ self.assertLess(character._clip_playback_time, 0.5 * clip.duration)
+
+ before = character.current_pose.numpy().copy()
+ machine.interact()
+ self.assertFalse(state.is_looping)
+ np.testing.assert_allclose(engine.contexts[-1][-1], before, atol=1e-6)
+ np.testing.assert_allclose(engine.targets[-1], expected[8:], atol=1e-6)
+ self._step_until(character, engine, idle, lambda: not machine.is_interacting)
+ self.assertIs(machine.state, machine.standing_idle_state)
+ self.assertIs(character._playback_source, PlaybackSource.CLIP_TRANSITION)
+ self.assertIsNone(primitive._interaction_state)
+
+ self._step(character, engine, LocomotionCommand(facing, facing))
+ self.assertTrue(machine.is_locomoting)
+ self.assertEqual(engine.configs[-1].allowed_token_counts, tuple(range(8, 15)))
+ np.testing.assert_array_equal(storage.numpy()[:5], -99.0)
+ np.testing.assert_array_equal(storage.numpy()[13:], -99.0)
+
+ def test_clip_started_during_an_idle_transition_plays_once_from_its_first_frame(self):
+ character, engine, _ = self._character()
+ machine = character.state_machine
+ primitive = self.asset_pool.instantiate(self._save_interaction(), _PlayOnce)
+ primitive.clip_paths = (self.csv_path,)
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ idle = LocomotionCommand(facing, None)
+ for _ in range(5):
+ self._step(character, engine, LocomotionCommand(facing, facing))
+ self._step(character, engine, idle)
+ self.assertIs(character._playback_source, PlaybackSource.CLIP_TRANSITION)
+ self.assertGreater(character.time_to_transition(), 0.03)
+
+ machine.start_interaction(character, primitive)
+ self.assertEqual(character._clip_playback_time, 0.0)
+ self._step(character, engine, idle)
+ self.assertAlmostEqual(character._clip_playback_time, 0.03)
+ clip = character.current_clip
+ sampled = wp.empty(8, dtype=wp.float32)
+ clip.animation.sample(0.03, sampled, root_offset=clip.root_offset)
+ np.testing.assert_allclose(character.current_pose.numpy(), sampled.numpy(), atol=1e-6)
+
+ # The interaction ends during the step that reaches the clip's end.
+ self._step_until(character, engine, idle, lambda: character.clip_ends_within(0.03))
+ self.assertTrue(machine.is_interacting)
+ self._step(character, engine, idle)
+ self.assertFalse(machine.is_interacting)
+ self.assertIs(machine.state, machine.standing_idle_state)
+ self.assertIs(character._playback_source, PlaybackSource.CLIP_TRANSITION)
+
+ def test_initial_transform_places_and_turns_the_starting_idle(self):
+ yaw = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), 0.5 * np.pi)
+ character, engine, _ = self._character(
+ initial_transform=wp.transform(wp.vec3(3.0, -2.0, 0.4), yaw),
+ )
+ np.testing.assert_allclose(character.character_ground_position, [3.0, -2.0, 0.0], atol=1e-6)
+ np.testing.assert_allclose(character.movement.current_facing, [0.0, 1.0, 0.0], atol=1e-6)
+ self.assertAlmostEqual(character.movement.current_facing_angle, 0.5 * np.pi, places=6)
+ self.assertAlmostEqual(character.movement.desired_velocity_angle, 0.5 * np.pi, places=6)
+ pose = character.current_pose.numpy()
+ np.testing.assert_allclose(pose[:3], [3.0, -2.0, 0.8], atol=1e-5)
+ self.assertAlmostEqual(abs(float(pose[3:7] @ np.asarray(yaw))), 1.0, places=6)
+ near, _ = character.probe_segment
+ np.testing.assert_allclose(near, [3.0, -2.0 + character.interaction_probe.near_distance, 0.0], atol=1e-6)
+ self.assertEqual(len(engine.contexts), 0)
+
+ def test_interaction_box_follows_desired_velocity_and_crouch_height(self):
+ probe = InteractionProbe(
+ box_width=0.8, box_min_depth=0.6, box_height=1.25, near_distance=0.1, lookahead_time=1.0,
+ extra_lookahead_min_speed=1.5, extra_lookahead_time=0.25,
+ )
+ character, _, _ = self._character(interaction_probe=probe)
+ # Standing still, the box has its minimum depth.
+ box = character.probe_box.numpy()
+ np.testing.assert_allclose(box["transform"][0, :3], [0.4, 0.0, 0.625], atol=1e-6)
+ np.testing.assert_allclose(box["half_extents"][0], [0.4, 0.3, 0.625], atol=1e-6)
+
+ facing = np.array([1, 0, 0], dtype=np.float32)
+ character.step(0.03, LocomotionCommand(facing, None, requested_mode=CROUCH_LOCOMOTION.name))
+ self.assertEqual(character.state_machine.probe_box_height_scale, 0.6)
+ character.movement.desired_velocity[:] = (0.0, 2.0, 0.0)
+ character.movement.desired_velocity_direction[:] = (0.0, 1.0, 0.0)
+ character._update_probe_box()
+ ground = character.character_ground_position
+ near, far = character.probe_segment
+ np.testing.assert_allclose(near, ground + [0.0, 0.1, 0.0], atol=1e-6)
+ np.testing.assert_allclose(far, ground + [0.0, 2.125, 0.0], atol=1e-6)
+ box = character.probe_box.numpy()
+ np.testing.assert_allclose(box["transform"][0, :3], ground + [0.0, 1.1125, 0.375], atol=1e-6)
+ np.testing.assert_allclose(box["transform"][0, 3:], [0.0, 0.0, 0.0, 1.0], atol=1e-6)
+ np.testing.assert_allclose(box["half_extents"][0], [0.4, 1.0125, 0.375], atol=1e-6)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_import_boundaries.py b/tests/app/test_import_boundaries.py
new file mode 100644
index 0000000..ee773b2
--- /dev/null
+++ b/tests/app/test_import_boundaries.py
@@ -0,0 +1,107 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+
+class ImportBoundaryTests(unittest.TestCase):
+ def assert_imports_without(self, source: str, excluded: tuple[str, ...]) -> None:
+ # A fresh process prevents other test modules from hiding eager imports.
+ program = (
+ "import sys\n"
+ + source
+ + f"\nexcluded = {excluded!r}\n"
+ + "unexpected = sorted(name for name in sys.modules if any(\n"
+ + " name == prefix or name.startswith(prefix + '.')\n"
+ + " for prefix in excluded))\n"
+ + "assert not unexpected, unexpected\n"
+ )
+ result = subprocess.run(
+ [sys.executable, "-B", "-c", program],
+ cwd=Path(__file__).resolve().parents[2],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+ def test_model_contract_does_not_load_execution_backends(self) -> None:
+ self.assert_imports_without(
+ "from motionbricks.model.soma.contract import SOMA_N1_CONTRACT\n"
+ "from motionbricks.model.config import MotionBricksInferenceConfig\n"
+ "from motionbricks.inference.types import TensorMode, TensorSpec\n",
+ ("tensorrt", "newton", "warp", "motionbricks.inference.engine"),
+ )
+
+ def test_common_runtime_does_not_load_rig_specific_runtime_or_backends(self) -> None:
+ self.assert_imports_without(
+ "from motionbricks.runtime.target_pose import (\n"
+ " IKPin, TargetPoseInferenceParams, create_soma_target_pose_ik_rig)\n"
+ "from motionbricks.runtime.blend_spaces import BlendSpace\n"
+ "assert 'app' not in sys.modules, 'target poses or blend spaces loaded app'\n"
+ "from app.runtime.common.motion import (\n"
+ " AnimationClip, LocomotionCommand, LocomotionMode,\n"
+ " LocomotionModeRuntime, LocomotionSettings, PlaybackSource,\n"
+ " directional_blend_space_value, ground_direction)\n"
+ "from app.runtime.common.state_machine import StateMachine\n"
+ "from app.runtime.common.states import IdleState, InteractionState, LocomotionState, State\n"
+ "from app.runtime.common.target_pose_blender import BaseTargetPoseBlender\n"
+ "from app.runtime.common.interaction import InteractionProbe\n"
+ "from app.runtime.common.character import BaseCharacter\n",
+ (
+ "app.runtime.soma",
+ "app.runtime.unitree_g1",
+ "app.authoring",
+ "motionbricks.model.soma.engine",
+ "motionbricks.inference.engine",
+ "motionbricks.renderers",
+ "tensorrt",
+ "newton",
+ "imgui_bundle",
+ "pyglet",
+ ),
+ )
+
+ def test_shared_behaviors_and_documents_do_not_load_rig_specific_runtime_or_applications(self) -> None:
+ self.assert_imports_without(
+ "import app.runtime.common.smart_primitive_behaviors\n"
+ "import app.runtime.common.io.scene_document\n"
+ "import app.runtime.common.io.smart_primitive_document\n",
+ (
+ "tensorrt",
+ "imgui_bundle",
+ "pyglet",
+ "app.authoring",
+ "app.smart_primitive_editor",
+ "app.scene_editor",
+ "app.scene_preview",
+ "app.inbetweener_demo",
+ "app.runtime.soma",
+ "app.runtime.unitree_g1",
+ ),
+ )
+
+ def test_all_runtime_modules_import_without_authoring_or_ui(self) -> None:
+ self.assert_imports_without(
+ "import importlib\n"
+ "import pkgutil\n"
+ "import app.runtime\n"
+ "for module in pkgutil.walk_packages(app.runtime.__path__, 'app.runtime.'):\n"
+ " importlib.import_module(module.name)\n",
+ (
+ "app.authoring",
+ "app.smart_primitive_editor",
+ "app.scene_editor",
+ "app.scene_preview",
+ "app.inbetweener_demo",
+ "imgui_bundle",
+ "pyglet",
+ ),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_inbetweener_demo.py b/tests/app/test_inbetweener_demo.py
new file mode 100644
index 0000000..f0cb964
--- /dev/null
+++ b/tests/app/test_inbetweener_demo.py
@@ -0,0 +1,501 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from itertools import product
+from pathlib import Path
+import unittest
+from unittest.mock import Mock, patch
+
+import newton
+import numpy as np
+import warp as wp
+
+from app.inbetweener_demo import InbetweenerDemo, PoseEntry, sample_pose_window
+from app.authoring.common import InlineRename
+from app.runtime.common.clip_registry import ClipRegistry
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.contract import ModelRig
+from motionbricks.model.soma.buffers import PoseToken
+from motionbricks.model.unitree_g1.buffers import DOFToken
+from motionbricks.renderers.foot_contact_renderer import (
+ ContactOutline,
+ DOFFootContactRenderer,
+ SkeletonFootContactRenderer,
+)
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+from motionbricks.utils.space_conversion_utils import FacingDirectionType, SpaceConverter
+
+
+_G1_JOINTS = ("hip", "knee")
+
+
+class _RecordingEngine:
+ """Deterministic output with unused capacity to catch context carry-over errors."""
+
+ stream = None
+
+ def __init__(self):
+ self.calls = []
+ self.target_counts = []
+ self.token_counts = []
+
+ def generate_animation(self, context, target, output, *, config):
+ self.calls.append((context.poses.numpy().copy(), target.poses.numpy().copy()))
+ self.target_counts.append(target.num_poses)
+ self.token_counts.append(config.allowed_token_counts)
+ frames = np.repeat(context.poses.numpy()[-1:], output.capacity, axis=0)
+ # Both pose layouts start with the root position.
+ root_x = frames.reshape(output.capacity, -1)[:, 0]
+ root_x[:6] = np.linspace(root_x[0], target.poses.numpy()[0].reshape(-1)[0], 6)
+ root_x[6:] = 999.0
+ output.poses.assign(frames)
+ output.num_frames = 6
+
+
+class InbetweenerDemoTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+ reference = np.array([
+ [0, 1, 0, 0, 0, 0, 1],
+ [0, 0.2, 0, 0, 0, 0, 1],
+ ], dtype=np.float32)
+ cls.skeleton = Skeleton(["Hips", "Child"], [-1, 0], reference)
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def make_entry(self, sample_rate=60.0, sample_time=0.5):
+ num_frames = int(sample_rate) + 1
+ frames = np.repeat(self.skeleton.reference_local_transforms.numpy()[None], num_frames, axis=0)
+ times = np.arange(num_frames) / sample_rate
+ frames[:, 0, 0] = 10 + times * 3
+ frames[:, 0, 1] = 1 + times
+ frames[:, 0, 2] = 20 - times * 6
+ clip = AnimationBuffer(self.skeleton, sample_rate, wp.array(frames, dtype=wp.transform))
+ return PoseEntry(0, "Start", Path("test.bvh"), clip, sample_time, wp.transform_identity())
+
+ def make_dof_entry(self, sample_rate=120.0, sample_time=0.5):
+ # Z-up root motion and joint angles, like a G1 CSV clip.
+ num_frames = int(sample_rate) + 1
+ times = np.arange(num_frames) / sample_rate
+ frames = np.zeros((num_frames, 7 + len(_G1_JOINTS)), dtype=np.float32)
+ frames[:, :3] = np.array([10, 20, 1]) + times[:, None] * [3, -6, 1]
+ frames[:, 6] = 1.0
+ frames[:, 7:] = times[:, None] * [2, -1]
+ clip = DOFAnimationBuffer(_G1_JOINTS, sample_rate, wp.array(frames, dtype=wp.float32))
+ return PoseEntry(0, "Start", Path("test.csv"), clip, sample_time, wp.transform_identity())
+
+ def make_demo(self, g1=False):
+ # Exercise app behavior without opening a GL window or loading TensorRT.
+ demo = InbetweenerDemo.__new__(InbetweenerDemo)
+ demo.engine = _RecordingEngine()
+ demo.viewer = Mock()
+ demo.mesh_renderer = Mock()
+ demo.skeleton_renderer = Mock()
+ demo.playback_color = None if g1 else wp.vec3(0.7, 0.7, 0.7)
+ demo.velocity_renderer = Mock()
+ demo.foot_contact_renderer = Mock()
+ demo.show_foot_contacts = False
+ demo.state = Mock()
+ demo.selected_index = 0
+ demo._next_id = 1
+ demo._rename = InlineRename()
+ demo.error = None
+ if g1:
+ demo.clip_registry = ClipRegistry(ModelRig.UNITREE_G1, joint_names=_G1_JOINTS)
+ demo.model_to_runtime = wp.transform_identity()
+ demo.pose_entries = [self.make_dof_entry()]
+ demo.context = DOFToken(len(_G1_JOINTS))
+ demo.target = DOFToken(len(_G1_JOINTS))
+ demo.output = DOFAnimationBuffer(
+ _G1_JOINTS, 30.0, wp.empty((20, 7 + len(_G1_JOINTS)), dtype=wp.float32), num_frames=0,
+ )
+ else:
+ demo.clip_registry = ClipRegistry(ModelRig.SOMA, skeleton=self.skeleton)
+ converter = SpaceConverter(FacingDirectionType.MUJOCO)
+ demo.model_to_runtime = converter.convert_transform(wp.transform_identity())
+ demo.pose_entries = [self.make_entry()]
+ demo.context = PoseToken(2)
+ demo.target = PoseToken(2)
+ demo.output = AnimationBuffer(
+ self.skeleton, 30.0, wp.empty((20, self.skeleton.num_joints), dtype=wp.transform), num_frames=0,
+ )
+ demo.current_pose = wp.empty_like(demo.context.poses[0])
+ demo.refresh_poses()
+ return demo
+
+ def test_windows_resample_source_fps_on_each_side_of_visible_pose(self):
+ # The conversion moves BVH X, Y (height), and Z to scene Y, Z, and X.
+ conversion = SpaceConverter(FacingDirectionType.MAYA).convert_transform(wp.transform_identity())
+ for source_rate in (15, 30, 60):
+ for context in (True, False):
+ with self.subTest(source_rate=source_rate, context=context):
+ entry = self.make_entry(source_rate)
+ window = wp.empty((4, self.skeleton.num_joints), dtype=wp.transform)
+ sample_pose_window(entry, conversion, window, anchor=3 if context else 0)
+ poses = window.numpy()
+ offsets = (np.arange(4) - (3 if context else 0)) / 30
+ np.testing.assert_allclose(poses[:, 0, 0], offsets * -6, atol=1e-5)
+ np.testing.assert_allclose(poses[:, 0, 1], offsets * 3, atol=1e-5)
+ np.testing.assert_allclose(poses[:, 0, 2], 1.5 + offsets, atol=1e-5)
+ np.testing.assert_allclose(poses[:, 1, 1], 0.2)
+
+ def test_dof_windows_keep_height_rotation_and_joint_angles(self):
+ placement = wp.transform(wp.vec3(4, 5, 0), wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.4))
+ rotation = wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.7)
+ for source_rate, context in product((15, 30, 120), (True, False)):
+ with self.subTest(source_rate=source_rate, context=context):
+ entry = self.make_dof_entry(source_rate)
+ frames = entry.clip.poses.numpy()
+ frames[:, 3:7] = np.asarray(rotation)
+ entry.clip.poses.assign(frames)
+ entry.placement = placement
+ window = wp.empty((4, 7 + len(_G1_JOINTS)), dtype=wp.float32)
+ sample_pose_window(entry, wp.transform_identity(), window, anchor=3 if context else 0)
+ poses = window.numpy()
+ offsets = (np.arange(4) - (3 if context else 0)) / 30
+ for pose, offset in zip(poses, offsets):
+ # Ground motion is relative to the visible pose. Height and rotation are kept.
+ root = wp.transform(wp.vec3(3 * offset, -6 * offset, 1.5 + offset), rotation)
+ np.testing.assert_allclose(pose[:7], np.asarray(wp.mul(placement, root)), atol=3e-6)
+ np.testing.assert_allclose(poses[:, 7:], (0.5 + offsets[:, None]) * [2, -1], atol=1e-6)
+
+ def test_hips_constraint_preserves_rotation_height_and_local_children(self):
+ entry = self.make_entry()
+ frames = entry.clip.poses.numpy()
+ frames[:, 0, 3:] = np.asarray(wp.quat_from_axis_angle(wp.vec3(0, 1, 0), 0.7))
+ entry.clip.poses.assign(frames)
+ entry.placement = wp.transform(
+ wp.vec3(4, 5, 2), wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.4)
+ )
+ conversion = SpaceConverter(FacingDirectionType.MAYA).convert_transform(wp.transform_identity())
+ window = wp.empty((4, self.skeleton.num_joints), dtype=wp.transform)
+ sample_pose_window(entry, conversion, window, anchor=0)
+ poses = window.numpy()
+ root = wp.transform(wp.vec3(0, 1.5, 0), wp.quat(*frames[30, 0, 3:]))
+ expected = wp.mul(entry.placement, wp.mul(conversion, root))
+ np.testing.assert_allclose(poses[0, 0], np.asarray(expected), atol=3e-6)
+ np.testing.assert_allclose(poses[:, 1], frames[30:34, 1], atol=1e-6)
+ self.assertAlmostEqual(float(np.linalg.norm(poses[1, 0, :3] - poses[0, 0, :3])),
+ float(np.linalg.norm([3, 1, -6]) / 30), places=5)
+
+ def test_list_edits_keep_the_start_first_and_update_the_ground_route(self):
+ demo = self.make_demo()
+ for _ in range(3):
+ demo.add_target()
+ positions = np.array([[0, 0], [2, 1], [5, -1], [9, 2]])
+ for entry, (x, y) in zip(demo.pose_entries, positions):
+ entry.placement = wp.transform(wp.vec3(float(x), float(y), 0), wp.quat_identity())
+ # The start cannot be removed, moved or displaced.
+ demo.selected_index = 0
+ demo.remove_target()
+ demo.move_target(0, 1)
+ demo.move_target(1, 0)
+ self.assertEqual([entry.id for entry in demo.pose_entries], [0, 1, 2, 3])
+ demo.move_target(3, 1)
+ self.assertEqual([entry.id for entry in demo.pose_entries], [0, 3, 1, 2])
+ self.assertEqual(demo.selected_index, 1)
+ ordered_positions = positions[[0, 3, 1, 2]]
+ np.testing.assert_allclose(demo.order_starts.numpy()[:, :2], ordered_positions[:-1])
+ np.testing.assert_allclose(demo.order_ends.numpy()[:, :2], ordered_positions[1:])
+ rings = demo.ring_starts.numpy().reshape(len(demo.pose_entries), -1, 3)
+ np.testing.assert_allclose(rings[:, :, :2].mean(axis=1), ordered_positions, atol=1e-6)
+ demo.move_target(1, 3)
+ self.assertEqual([entry.id for entry in demo.pose_entries], [0, 1, 2, 3])
+ for _ in range(3):
+ demo.remove_target()
+ self.assertEqual(demo.order_starts.shape, (0,))
+ self.assertEqual(demo.order_ends.shape, (0,))
+
+ def test_generation_follows_list_and_carries_last_four_valid_output_frames(self):
+ demo = self.make_demo()
+ demo.add_target()
+ demo.add_target()
+ demo.move_target(2, 1)
+ demo.pose_entries[1].min_tokens, demo.pose_entries[1].max_tokens = 6, 8
+ demo.pose_entries[2].min_tokens = demo.pose_entries[2].max_tokens = 16
+ initial_context = demo.pose_entries[0].sampled_poses.numpy()
+ demo.play()
+ demo.step(0.0)
+ self.assertEqual(len(demo.engine.calls), 1)
+ np.testing.assert_allclose(demo.engine.calls[0][0], initial_context)
+ np.testing.assert_allclose(demo.engine.calls[0][1], demo.pose_entries[1].sampled_poses.numpy())
+ demo.step(demo.output.duration / 2)
+ self.assertEqual(len(demo.engine.calls), 1)
+ expected_context = demo.output.poses.numpy()[2:6].copy()
+ demo.step(demo.output.duration)
+ self.assertEqual(len(demo.engine.calls), 1)
+ demo.step(0.0)
+ self.assertEqual(len(demo.engine.calls), 2)
+ self.assertEqual(demo.engine.token_counts, [(6, 7, 8), (16,)])
+ np.testing.assert_allclose(demo.engine.calls[1][0], expected_context)
+ np.testing.assert_allclose(demo.engine.calls[1][1], demo.pose_entries[2].sampled_poses.numpy())
+ demo.step(demo.output.duration)
+ self.assertFalse(demo.playing)
+ self.assertFalse(demo.has_segment)
+ demo.step(10.0)
+ self.assertEqual(len(demo.engine.calls), 2)
+
+ def test_target_frame_count_controls_conditioning_and_stop_velocity(self):
+ for g1, count in product((False, True), (1, 4)):
+ with self.subTest(g1=g1, count=count):
+ demo = self.make_demo(g1)
+ demo.add_target()
+ demo.pose_entries[1].num_poses_to_use = count
+ demo.refresh_poses()
+ demo.play()
+ demo.step(0.0)
+ self.assertEqual(demo.engine.target_counts, [count])
+ self.assertEqual(demo.context.num_poses, 4)
+ expected = demo.pose_entries[1].sampled_poses.numpy()
+ expected[count:] = expected[count - 1]
+ np.testing.assert_allclose(demo.engine.calls[0][1], expected)
+ if count == 1:
+ np.testing.assert_array_equal(demo.pose_entries[1].velocity, [0, 0, 0])
+ else:
+ self.assertAlmostEqual(float(np.linalg.norm(demo.pose_entries[1].velocity)),
+ float(np.linalg.norm([3, 1, -6])), places=4)
+
+ def test_early_transition_still_plays_the_four_poses_of_the_next_context(self):
+ # The output has six frames, and a segment plays at least four of them.
+ cases = ((0, 5), (1, 4), (2, 3), (4, 3), (20, 3))
+ for g1, (early_frames, last_frame) in product((False, True), cases):
+ with self.subTest(g1=g1, early_frames=early_frames):
+ demo = self.make_demo(g1)
+ demo.add_target()
+ demo.add_target()
+ demo.pose_entries[1].transition_early_by_frames = early_frames
+ demo.play()
+ demo.step(0.0)
+ np.testing.assert_allclose(demo.engine.calls[0][0], demo.pose_entries[0].sampled_poses.numpy())
+ played = demo.output.poses.numpy()[:last_frame + 1].copy()
+ demo.step(10.0)
+ self.assertAlmostEqual(demo.playback_time, last_frame / 30.0)
+ np.testing.assert_allclose(demo.current_pose.numpy(), played[-1])
+ demo.step(0.0)
+ np.testing.assert_allclose(demo.engine.calls[1][0], played[-4:])
+
+ def test_pause_and_edit_reset_do_not_reuse_stale_motion(self):
+ demo = self.make_demo()
+ demo.add_target()
+ demo.play()
+ demo.step(0.0)
+ pose = demo.current_pose.numpy().copy()
+ demo.playing = False
+ demo.step(10.0)
+ np.testing.assert_allclose(demo.current_pose.numpy(), pose)
+ demo.playing = True
+ demo.step(demo.output.duration / 2)
+ self.assertGreater(demo.playback_time, 0)
+ demo.pose_entries[0].placement = wp.transform(wp.vec3(9, 0, 0), wp.quat_identity())
+ demo.refresh_poses()
+ self.assertFalse(demo.playing)
+ self.assertFalse(demo.has_segment)
+ self.assertEqual(demo.next_target_index, 1)
+ np.testing.assert_allclose(demo.current_pose.numpy(), demo.pose_entries[0].sampled_poses.numpy()[-1])
+ demo.play()
+ demo.step(0.0)
+ np.testing.assert_allclose(demo.engine.calls[-1][0], demo.pose_entries[0].sampled_poses.numpy())
+
+ def test_failed_clip_load_keeps_the_original_entry(self):
+ demo = self.make_demo()
+ demo._pending_clip = demo.pose_entries[0]
+ original = demo.pose_entries[0].clip
+ with patch("app.authoring.common.choose_file", return_value="bad.bvh"), \
+ patch.object(demo.clip_registry, "load", side_effect=ValueError("Invalid BVH")):
+ demo._choose_pending_clip()
+ self.assertIs(demo.pose_entries[0].clip, original)
+ self.assertEqual(demo.pose_entries[0].path, Path("test.bvh"))
+ self.assertIn("Invalid BVH", demo.error)
+
+ def test_mesh_colors_and_pose_ids_survive_reordering_and_removal(self):
+ demo = self.make_demo()
+ demo.add_target()
+ demo.add_target()
+ colors = {0: (0.2, 0.8, 0.4), 1: (0.7, 0.1, 0.2), 2: (0.3, 0.2, 0.9)}
+ for entry in demo.pose_entries:
+ entry.color = colors[entry.id]
+ demo.move_target(2, 1)
+ demo.render()
+ calls = demo.mesh_renderer.draw_pose.call_args_list
+ self.assertEqual([call.args[4] for call in calls], [0, 2, 1])
+ for index, call in enumerate(calls):
+ np.testing.assert_allclose(call.args[1].numpy(), demo.pose_entries[index].preview_pose.numpy())
+ np.testing.assert_allclose(np.asarray(call.args[3]), colors[call.args[4]])
+ demo.mesh_renderer.reset_mock()
+ demo.selected_index = 2
+ demo.remove_target()
+ demo.mesh_renderer.clear.assert_called_once_with(demo.viewer)
+ demo.render()
+ self.assertEqual([call.args[4] for call in demo.mesh_renderer.draw_pose.call_args_list], [0, 2])
+
+ def test_ground_rings_select_poses_with_hidden_meshes(self):
+ demo = self.make_demo()
+ demo.viewer.camera.far = 100.0
+ demo.add_target()
+ demo.add_target()
+ for entry in demo.pose_entries:
+ entry.show_mesh = False
+ demo.pose_entries[2].placement = wp.transform(4, 5, 0, 0, 0, 0, 1)
+ demo.refresh_poses()
+ down = wp.vec3(0, 0, -1)
+ demo.selected_index = 0
+ demo._select_pose(wp.vec3(4.3, 5, 2), down)
+ self.assertEqual(demo.pose_entries[demo.selected_index].id, 2)
+ # The empty center of a ring misses.
+ demo.selected_index = 0
+ demo._select_pose(wp.vec3(4, 5, 2), down)
+ self.assertEqual(demo.selected_index, 0)
+ demo.mesh_renderer.raycast_pose.assert_not_called()
+
+ def test_gizmo_edit_updates_placement_and_resets_playback(self):
+ demo = self.make_demo()
+ demo.add_target()
+ entry = demo.pose_entries[demo.selected_index]
+ entry.placement = wp.transform(wp.vec3(1, 2, 3), wp.quat_identity())
+ demo.refresh_poses()
+ demo.play()
+ demo.step(0.0)
+ rotation = wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.5)
+
+ def drag_gizmo():
+ gizmo = demo.viewer.log_gizmo.call_args.args[1]
+ gizmo[:] = wp.transform(wp.vec3(4, 5, 3), rotation)
+
+ demo.viewer.end_frame.side_effect = drag_gizmo
+ demo.render()
+
+ np.testing.assert_allclose(entry.placement.p, [4, 5, 3])
+ np.testing.assert_allclose(entry.placement.q, rotation)
+ self.assertFalse(demo.playing)
+ self.assertFalse(demo.has_segment)
+
+ def test_generate_survives_idle_gizmo_redraw_after_pose_rotation(self):
+ for angle in (90, 180, 270, -180, 360):
+ with self.subTest(angle=angle):
+ demo = self.make_demo()
+ demo.add_target()
+ entry = demo.pose_entries[demo.selected_index]
+ entry.placement = wp.transform(
+ wp.vec3(2, 1, 0), wp.quat_rpy(0.0, 0.0, wp.radians(float(angle))),
+ )
+ entry.euler_degrees = [0, 0, angle]
+ demo.refresh_poses()
+
+ def redraw_gizmo():
+ # Newton converts through a matrix even without a user edit.
+ # This can return -q, which is the same rotation as q.
+ gizmo = demo.viewer.log_gizmo.call_args.args[1]
+ gizmo[:] = wp.transform_from_matrix(wp.transform_to_matrix(gizmo))
+
+ demo.viewer.end_frame.side_effect = redraw_gizmo
+ demo.play()
+ for _ in range(3):
+ demo.render()
+ demo.step(1 / 60)
+
+ self.assertEqual(len(demo.engine.calls), 1)
+ self.assertTrue(demo.playing)
+ self.assertGreater(demo.playback_time, 0.0)
+
+ def test_playback_mesh_hides_only_where_a_visible_preview_shows_its_pose(self):
+ for early_frames, preview_visible in ((1, True), (2, True), (0, False), (0, True)):
+ with self.subTest(early_frames=early_frames, preview_visible=preview_visible):
+ demo = self.make_demo()
+ demo.add_target()
+ demo.add_target()
+ demo.pose_entries[1].transition_early_by_frames = early_frames
+ demo.pose_entries[1].show_mesh = preview_visible
+
+ def playback_drawn():
+ demo.mesh_renderer.reset_mock()
+ demo.render()
+ return -1 in [call.args[4] for call in demo.mesh_renderer.draw_pose.call_args_list]
+
+ # The visible Start mesh shows the first frame.
+ demo.play()
+ demo.step(0.0)
+ self.assertFalse(playback_drawn())
+ demo.step(demo.output.duration / 2)
+ self.assertTrue(playback_drawn())
+ demo.step(10.0)
+ boundary_pose = demo.current_pose.numpy().copy()
+
+ # The end of one segment and frame zero of the next must agree
+ # on visibility: a preview replaces only a reached target.
+ for generate_next in (False, True):
+ if generate_next:
+ demo.step(0.0)
+ self.assertEqual(playback_drawn(), early_frames > 0 or not preview_visible)
+ np.testing.assert_allclose(demo.current_pose.numpy(), boundary_pose)
+
+ def test_contacts_follow_the_final_pose_without_a_mesh_draw_and_respect_the_threshold(self):
+ demo = self.make_demo()
+ demo.rig = ModelRig.SOMA
+ points = np.array([[0, 0, 0], [0.1, 0, 0], [0, 0, 0.1]], dtype=np.float32)
+ demo.foot_contact_renderer = SkeletonFootContactRenderer(
+ "contacts", self.skeleton, [ContactOutline(0, 1, points)],
+ )
+ demo.foot_contacts = wp.empty(4, dtype=wp.float32)
+ demo.output.foot_contacts = wp.full((demo.output.capacity, 4), 0.75, dtype=wp.float32)
+ demo.show_foot_contacts = True
+ demo.foot_contact_threshold = 0.5
+ demo.add_target()
+ demo.play()
+ demo.step(0.0)
+ demo.step(demo.output.duration)
+
+ demo._draw_foot_contacts()
+
+ root, child = (wp.transform(*pose) for pose in demo.current_pose.numpy())
+ expected = np.array([wp.transform_point(wp.mul(root, child), wp.vec3(*point)) for point in points])
+ _, starts, ends, _ = demo.viewer.log_lines.call_args.args
+ np.testing.assert_allclose(starts.numpy(), expected, atol=1e-6)
+ np.testing.assert_allclose(ends.numpy(), np.roll(expected, -1, axis=0), atol=1e-6)
+ demo.foot_contact_threshold = 0.8
+ demo._draw_foot_contacts()
+ np.testing.assert_allclose(ends.numpy(), starts.numpy())
+ demo.reset()
+ demo._draw_foot_contacts()
+ self.assertTrue(demo.viewer.log_lines.call_args.kwargs["hidden"])
+
+ def test_g1_contacts_follow_the_final_pose_without_a_mesh_draw(self):
+ demo = self.make_demo(g1=True)
+ demo.rig = ModelRig.UNITREE_G1
+ # A free root, then the hip and knee hinges, matching the fixture's joint_q.
+ builder = newton.ModelBuilder()
+ pelvis, thigh, shin = (builder.add_link(mass=1.0, inertia=wp.mat33(np.eye(3))) for _ in range(3))
+ builder.add_articulation([
+ builder.add_joint_free(pelvis),
+ builder.add_joint_revolute(pelvis, thigh, axis=wp.vec3(0.0, 0.0, 1.0)),
+ builder.add_joint_revolute(thigh, shin, axis=wp.vec3(0.0, 0.0, 1.0)),
+ ])
+ model = builder.finalize()
+ points = np.array([[0, 0, 0], [0.1, 0, 0], [0, 0.1, 0]], dtype=np.float32)
+ demo.foot_contact_renderer = DOFFootContactRenderer("contacts", model, [ContactOutline(0, shin, points)])
+ demo.foot_contacts = wp.empty(4, dtype=wp.float32)
+ demo.output.foot_contacts = wp.full((demo.output.capacity, 4), 0.75, dtype=wp.float32)
+ demo.show_foot_contacts = True
+ demo.foot_contact_threshold = 0.5
+ demo.add_target()
+ demo.play()
+ demo.step(0.0)
+ demo.step(demo.output.duration)
+
+ demo._draw_foot_contacts()
+
+ pose = demo.current_pose.numpy()
+ root = wp.transform(wp.vec3(*pose[:3]), wp.quat(*pose[3:7]))
+ bend = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), float(pose[7] + pose[8]))
+ shin_transform = wp.mul(root, wp.transform(wp.vec3(0.0, 0.0, 0.0), bend))
+ expected = np.array([wp.transform_point(shin_transform, wp.vec3(*point)) for point in points])
+ np.testing.assert_allclose(demo.viewer.log_lines.call_args.args[1].numpy(), expected, atol=1e-5)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_input.py b/tests/app/test_input.py
new file mode 100644
index 0000000..aebe297
--- /dev/null
+++ b/tests/app/test_input.py
@@ -0,0 +1,252 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import math
+import unittest
+
+from app.runtime.common.motion import (
+ CROUCH_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE, LINEAR_LOCOMOTION_MODE,
+)
+from app.utils.input import InputManager, LocomotionModeInput, apply_radial_dead_zone
+
+
+class _Controller:
+ def __init__(self, name: str = "Test Controller") -> None:
+ self.name = name
+ self.leftx = 0.0
+ self.lefty = 0.0
+ self.rightx = 0.0
+ self.righty = 0.0
+ self.dpadx = 0.0
+ self.dpady = 0.0
+ self.a = False
+ self.x = False
+ self.y = False
+ self.b = False
+ self.open_count = 0
+ self.close_count = 0
+
+ def open(self) -> None:
+ self.open_count += 1
+
+ def close(self) -> None:
+ self.close_count += 1
+
+
+class _ControllerManager:
+ def __init__(self, controllers=()) -> None:
+ self.controllers = list(controllers)
+ self.handler = None
+
+ def get_controllers(self) -> list[_Controller]:
+ return self.controllers
+
+ def push_handlers(self, handler) -> None:
+ self.handler = handler
+
+ def remove_handlers(self, handler) -> None:
+ if self.handler is handler:
+ self.handler = None
+
+
+class InputTests(unittest.TestCase):
+ def test_radial_dead_zone_preserves_and_remaps_stick_magnitude(self) -> None:
+ self.assertEqual(
+ apply_radial_dead_zone(0.1, -0.1, 0.15),
+ (0.0, 0.0),
+ )
+ x, y = apply_radial_dead_zone(0.575, 0.0, 0.15)
+ self.assertAlmostEqual(x, 0.5)
+ self.assertEqual(y, 0.0)
+
+ def test_keyboard_movement_is_normalized_at_default_speed(self) -> None:
+ for held_keys in ({"w", "d"}, {"up", "right"}, {"w", "right"}):
+ with self.subTest(keys=sorted(held_keys)):
+ input_manager = InputManager(lambda key: key in held_keys)
+
+ frame = input_manager.poll()
+
+ self.assertAlmostEqual(frame.movement[0], 1.0 / math.sqrt(2.0))
+ self.assertAlmostEqual(frame.movement[1], 1.0 / math.sqrt(2.0))
+ self.assertEqual(frame.camera_orbit, (0.0, 0.0))
+ self.assertFalse(frame.use_max_speed)
+ self.assertAlmostEqual(math.hypot(*frame.movement), 1.0)
+
+ def test_arrow_keys_move_like_wasd(self) -> None:
+ for arrow, letter in (("up", "w"), ("down", "s"), ("left", "a"), ("right", "d")):
+ with self.subTest(key=arrow):
+ arrow_frame = InputManager(lambda key: key == arrow).poll()
+ letter_frame = InputManager(lambda key: key == letter).poll()
+ self.assertEqual(arrow_frame.movement, letter_frame.movement)
+ self.assertNotEqual(arrow_frame.movement, (0.0, 0.0))
+
+ def test_controller_sticks_override_keyboard_and_use_max_speed(self) -> None:
+ controller = _Controller()
+ controller.leftx = 0.0
+ controller.lefty = 0.5
+ controller.rightx = 0.25
+ controller.righty = -0.25
+ manager = _ControllerManager((controller,))
+ input_manager = InputManager(
+ lambda key: key in {"w", "space"},
+ manager,
+ movement_dead_zone=0.2,
+ camera_dead_zone=0.1,
+ )
+
+ frame = input_manager.poll()
+
+ expected_speed_fraction = (0.5 - 0.2) / (1.0 - 0.2)
+ self.assertEqual(frame.movement[0], 0.0)
+ self.assertAlmostEqual(frame.movement[1], expected_speed_fraction)
+ self.assertAlmostEqual(
+ math.hypot(*frame.movement),
+ expected_speed_fraction,
+ )
+ raw_camera_length = math.hypot(0.25, -0.25)
+ camera_magnitude = (raw_camera_length - 0.1) / (1.0 - 0.1)
+ expected_camera_component = camera_magnitude / math.sqrt(2.0)
+ self.assertAlmostEqual(frame.camera_orbit[0], expected_camera_component)
+ self.assertAlmostEqual(frame.camera_orbit[1], -expected_camera_component)
+ self.assertTrue(frame.use_max_speed)
+ self.assertEqual(controller.open_count, 1)
+
+ input_manager.close()
+
+ self.assertEqual(controller.close_count, 1)
+ self.assertIsNone(manager.handler)
+
+ def test_keyboard_remains_available_inside_controller_dead_zone(self) -> None:
+ controller = _Controller()
+ controller.leftx = 0.19
+ controller.rightx = 0.19
+ input_manager = InputManager(
+ lambda key: key == "a",
+ _ControllerManager((controller,)),
+ movement_dead_zone=0.2,
+ camera_dead_zone=0.2,
+ )
+
+ frame = input_manager.poll()
+
+ self.assertEqual(frame.movement, (-1.0, 0.0))
+ self.assertEqual(frame.camera_orbit, (0.0, 0.0))
+ self.assertFalse(frame.use_max_speed)
+ input_manager.close()
+
+ def test_controller_hot_plug_selects_first_available_device(self) -> None:
+ manager = _ControllerManager()
+ input_manager = InputManager(lambda _key: False, manager)
+ first = _Controller("First")
+ second = _Controller("Second")
+ first.leftx = 1.0
+ second.lefty = 1.0
+
+ manager.controllers.extend((first, second))
+ input_manager.on_connect(first)
+ input_manager.on_connect(second)
+ self.assertEqual(input_manager.poll().movement, (1.0, 0.0))
+ self.assertEqual(second.open_count, 0)
+
+ manager.controllers.remove(first)
+ input_manager.on_disconnect(first)
+
+ self.assertEqual(input_manager.poll().movement, (0.0, 1.0))
+ self.assertEqual(second.open_count, 1)
+ input_manager.close()
+
+ def test_i_key_or_x_button_interacts(self) -> None:
+ held_keys = {"v"}
+ controller = _Controller()
+ input_manager = InputManager(lambda key: key in held_keys)
+ input_manager._controller = controller
+ self.assertFalse(input_manager.is_interaction_down())
+ held_keys.add("i")
+ self.assertTrue(input_manager.is_interaction_down())
+ held_keys.clear()
+ controller.x = True
+ self.assertTrue(input_manager.is_interaction_down())
+
+
+class LocomotionModeInputTests(unittest.TestCase):
+ def test_keys_toggle_modes_like_their_buttons_once_per_press(self):
+ held_keys = set()
+ controller = _Controller()
+ input_manager = InputManager(lambda key: key in held_keys)
+ input_manager._controller = controller
+ selector = LocomotionModeInput()
+ current_mode = LINEAR_LOCOMOTION_MODE
+ for buttons, keys, expected in (
+ ("", "", None),
+ ("y", "", DIRECTIONAL_LOCOMOTION_MODE),
+ ("y", "", None),
+ ("", "", None),
+ ("", "o", LINEAR_LOCOMOTION_MODE),
+ # Holding the key and its button together is still one press.
+ ("y", "o", None),
+ ("", "", None),
+ ("b", "", CROUCH_LOCOMOTION_MODE),
+ ("b", "", None),
+ ("", "", None),
+ ("", "p", DIRECTIONAL_LOCOMOTION_MODE),
+ ("", "", None),
+ ("", "p", CROUCH_LOCOMOTION_MODE),
+ ("", "", None),
+ ("", "o", LINEAR_LOCOMOTION_MODE),
+ ):
+ with self.subTest(mode=current_mode, buttons=buttons, keys=keys):
+ controller.y, controller.b = "y" in buttons, "b" in buttons
+ held_keys.clear()
+ held_keys.update(keys)
+ requested = selector.poll(input_manager, current_mode)
+ self.assertEqual(requested, expected)
+ if requested is not None:
+ current_mode = requested
+ input_manager._controller = None
+ held_keys.clear()
+ self.assertIsNone(selector.poll(input_manager, current_mode))
+ held_keys.add("p")
+ self.assertEqual(selector.poll(input_manager, current_mode), CROUCH_LOCOMOTION_MODE)
+
+ def test_bracket_or_a_cycles_styles_and_resumes_the_last_one(self):
+ held_keys = set()
+ controller = _Controller()
+ input_manager = InputManager(lambda key: key in held_keys)
+ input_manager._controller = controller
+ selector = LocomotionModeInput(("skipping_1d", "vogue_1d", "zombie_1d"))
+ current_mode = LINEAR_LOCOMOTION_MODE
+ for button_a, keys, expected in (
+ (False, "[", "skipping_1d"),
+ (False, "[", None),
+ (False, "", None),
+ (True, "", "vogue_1d"),
+ (False, "", None),
+ (False, "[", "zombie_1d"),
+ (False, "", None),
+ (False, "[", "skipping_1d"),
+ (False, "", None),
+ (False, "[", "vogue_1d"),
+ (False, "", None),
+ (False, "o", LINEAR_LOCOMOTION_MODE),
+ (False, "", None),
+ (False, "p", CROUCH_LOCOMOTION_MODE),
+ (False, "", None),
+ # From any other mode, the last style used comes back.
+ (False, "[", "vogue_1d"),
+ ):
+ with self.subTest(mode=current_mode, button_a=button_a, keys=keys):
+ controller.a = button_a
+ held_keys.clear()
+ held_keys.update(keys)
+ requested = selector.poll(input_manager, current_mode)
+ self.assertEqual(requested, expected)
+ if requested is not None:
+ current_mode = requested
+ # Without style modes, the style key does nothing.
+ held_keys.clear()
+ held_keys.add("[")
+ self.assertIsNone(LocomotionModeInput().poll(input_manager, LINEAR_LOCOMOTION_MODE))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_locomotion_character_states.py b/tests/app/test_locomotion_character_states.py
new file mode 100644
index 0000000..06d0e91
--- /dev/null
+++ b/tests/app/test_locomotion_character_states.py
@@ -0,0 +1,499 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+from dataclasses import replace
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+import numpy as np
+import warp as wp
+
+from app.runtime.soma.character import SOMACharacter
+from app.runtime.common.clip_registry import ClipRegistry
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveAssetPool
+from app.runtime.common.motion import (
+ LocomotionCommand,
+ LocomotionMode,
+ LocomotionModeRuntime,
+ LocomotionSettings,
+ MovementControl,
+ PlaybackSource,
+ load_locomotion_mode,
+ ground_direction,
+)
+from app.runtime.common.states import IdleState, LocomotionState
+from app.runtime.soma.target_pose_blender import SOMATargetPoseBlender
+from app.runtime.unitree_g1.character import UnitreeG1Character
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.contract import ModelRig
+from motionbricks.runtime.blend_spaces import BlendSpace, BlendSpaceType
+from motionbricks.runtime.motion_player import GeneratedMotionPlayer
+from motionbricks.runtime.target_pose import IKPin, TargetPoseInferenceParams
+
+
+def _mode(
+ name: str,
+ blend_space_type: BlendSpaceType,
+ max_speed: float,
+ *,
+ default_speed: float = 2.3,
+ minimum_speed: float = 0.0,
+ transition_early_by_frames: int = 8,
+ allowed_token_counts: tuple[int, ...] = tuple(range(8, 15)),
+ velocity_scale: float = 1.0,
+ position_scale: float = 1.0,
+) -> LocomotionMode:
+ return LocomotionMode(
+ name=name,
+ smart_primitive_path=Path("unused.smart_primitive.json"),
+ blend_space_type=blend_space_type,
+ target_values=(("Idle", (0.0, 0.0)),),
+ max_speed=max_speed,
+ default_speed=default_speed,
+ minimum_speed=minimum_speed,
+ transition_early_by_frames=transition_early_by_frames,
+ allowed_token_counts=allowed_token_counts,
+ velocity_scale=velocity_scale,
+ position_scale=position_scale,
+ )
+
+
+def _locomotion_state(
+ mode: LocomotionMode,
+ settings: LocomotionSettings = LocomotionSettings(),
+ runtime=None,
+) -> LocomotionState:
+ runtime = runtime or SimpleNamespace(definition=mode, blend_space=Mock())
+ pose = wp.empty(2, dtype=wp.transform, device="cpu")
+ return LocomotionState("Locomotion", (runtime,), mode.name, pose, settings=settings)
+
+
+def _idle_state(*clips: object) -> IdleState:
+ return IdleState("Idle", clips)
+
+
+class CharacterStateTests(unittest.TestCase):
+ def test_idle_selection_excludes_the_previous_clip(self) -> None:
+ clips = (object(), object())
+ state = _idle_state(*clips)
+
+ self.assertIs(state.choose_clip(SimpleNamespace(current_clip=clips[0])), clips[1])
+ self.assertIs(state.choose_clip(SimpleNamespace(current_clip=clips[1])), clips[0])
+
+ def test_locomotion_generation_uses_active_mode_early_transition_and_token_counts(self) -> None:
+ state = _locomotion_state(
+ _mode(
+ "linear",
+ BlendSpaceType.LINEAR_1D,
+ 4.5,
+ transition_early_by_frames=5,
+ allowed_token_counts=(6, 7, 8),
+ )
+ )
+ state._blended_target_poses = object()
+ state._target_poses = object()
+ state.evaluate_current_target_poses = Mock()
+ character = SimpleNamespace(
+ movement=SimpleNamespace(desired_velocity=np.array([2.0, 0.0, 0.0], dtype=np.float32)),
+ generate_to_target_poses=Mock(),
+ )
+
+ state._generate(character)
+
+ target_poses, params = (
+ character.generate_to_target_poses.call_args.args
+ )
+ self.assertIs(target_poses, state._target_poses)
+ self.assertEqual(
+ params,
+ TargetPoseInferenceParams(
+ transition_early_by_frames=5,
+ num_poses_to_use=4,
+ allowed_token_counts=(6, 7, 8),
+ ),
+ )
+
+ def test_locomotion_mode_rejects_invalid_early_transition_token_counts_and_speeds(self) -> None:
+ for options, message in (
+ ({"transition_early_by_frames": -1}, "cannot be negative"),
+ ({"allowed_token_counts": ()}, "cannot be empty"),
+ ({"allowed_token_counts": (5, 6)}, "must be 6 to 16"),
+ ({"allowed_token_counts": (16, 17)}, "must be 6 to 16"),
+ ({"default_speed": 4.6}, "default_speed"),
+ ({"minimum_speed": -0.1}, "minimum_speed"),
+ ({"minimum_speed": 2.4}, "minimum_speed"),
+ ({"minimum_speed": 4.6}, "minimum_speed"),
+ ):
+ with self.subTest(**options):
+ with self.assertRaisesRegex(ValueError, message):
+ _mode("linear", BlendSpaceType.LINEAR_1D, 4.5, **options)
+
+
+class PoseFacingTests(unittest.TestCase):
+ def _character(self, character_type, current_pose):
+ character = character_type.__new__(character_type)
+ character.current_pose = current_pose
+ character.movement = MovementControl(np.array([1.0, 0.0, 0.0], dtype=np.float32))
+ character.movement.current_facing_rate = 0.4
+ return character
+
+ def test_soma_faces_along_the_hips_y_axis_on_the_ground(self) -> None:
+ # The hips turn 30 degrees and tilt forward, as when bending to stand up.
+ rotation = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), wp.pi / 6.0) * wp.quat_from_axis_angle(
+ wp.vec3(1.0, 0.0, 0.0), -0.4,
+ )
+ pose = wp.array([wp.transform(wp.vec3(1.0, 2.0, 0.9), rotation)], dtype=wp.transform, device="cpu")
+ character = self._character(SOMACharacter, pose)
+
+ np.testing.assert_allclose(character.pose_facing(), [-0.5, np.sqrt(0.75), 0.0], atol=1.0e-6)
+
+ def test_g1_faces_along_the_pelvis_x_axis_and_face_pose_updates_every_facing(self) -> None:
+ rotation = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), 2.0) * wp.quat_from_axis_angle(
+ wp.vec3(0.0, 1.0, 0.0), 0.3,
+ )
+ joint_q = np.zeros(36, dtype=np.float32)
+ joint_q[:7] = [0.0, 0.0, 0.75, *rotation]
+ character = self._character(UnitreeG1Character, wp.array(joint_q, dtype=wp.float32, device="cpu"))
+ movement = character.movement
+ current_facing = movement.current_facing
+
+ character.face_pose()
+
+ expected = [np.cos(2.0), np.sin(2.0), 0.0]
+ self.assertIs(movement.current_facing, current_facing)
+ for facing in (movement.current_facing, movement.desired_facing, movement.last_input_facing):
+ np.testing.assert_allclose(facing, expected, atol=1.0e-6)
+ self.assertAlmostEqual(movement.current_facing_angle, 2.0, places=6)
+ self.assertEqual(movement.current_facing_rate, 0.0)
+
+
+class GroundDirectionTests(unittest.TestCase):
+ def test_returns_a_unit_xy_direction_or_its_fallback(self) -> None:
+ for direction, fallback, expected in (
+ ((3.0, 4.0, 8.0), (1.0, 0.0, 0.0), (0.6, 0.8, 0.0)),
+ ((0.0, 0.0, 0.0), (0.0, -3.0, 4.0), (0.0, -1.0, 0.0)),
+ ):
+ with self.subTest(direction=direction, fallback=fallback):
+ result = ground_direction(np.array(direction, dtype=np.float32), np.array(fallback, dtype=np.float32))
+ np.testing.assert_allclose(result, expected)
+ with self.assertRaisesRegex(ValueError, "no valid ground direction"):
+ ground_direction(np.zeros(3, dtype=np.float32), np.zeros(3, dtype=np.float32))
+
+
+class LocomotionModeSwitchTests(unittest.TestCase):
+ def test_mode_switch_reduces_speed_only_when_the_new_mode_is_not_faster(self) -> None:
+ linear = _mode("linear", BlendSpaceType.LINEAR_1D, 4.5)
+ directional = _mode("directional", BlendSpaceType.DIRECTIONAL_2D, 4.5)
+ crouch = _mode("crouch", BlendSpaceType.DIRECTIONAL_2D, 3.6)
+ settings = LocomotionSettings(maximum_direction_change_speed_reduction=0.25)
+ for previous, current, speed, expected_speed in (
+ (linear, directional, 4.5, 3.375),
+ (directional, crouch, 4.5, 3.375),
+ (crouch, directional, 3.6, 3.6),
+ ):
+ with self.subTest(previous=previous.name, current=current.name):
+ movement = MovementControl(np.array([0.0, 1.0, 0.0], dtype=np.float32), settings)
+ movement.desired_facing = np.array([1.0, 0.0, 0.0], dtype=np.float32)
+ movement.desired_speed = speed
+
+ movement._ease_mode_switch(current, previous)
+
+ self.assertAlmostEqual(movement.desired_speed, expected_speed)
+ self.assertLessEqual(movement.desired_speed, current.max_speed)
+ np.testing.assert_array_equal(movement.current_facing, movement.desired_facing)
+
+
+class LocomotionTargetEvaluationTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def _targets(self):
+ poses = np.zeros((3, 4, 2, 7), dtype=np.float32)
+ poses[..., 6] = 1
+ poses[0, :, 0, 0] = np.arange(4) * 0.1
+ poses[1, :, 0, 0] = np.arange(4) * 0.3
+ poses[0, :, 0, 2] = 1
+ poses[1, :, 0, 2] = 3
+ poses[0, :, 1, 0] = 0.5
+ poses[1, :, 1, 0] = 1.5
+ return poses, Skeleton(["Hips", "Child"], [-1, 0], poses[0, 0])
+
+ def test_modes_blend_then_scale_speed_and_place_only_the_root(self):
+ for space_type, speed, facing, height, child_x in (
+ (BlendSpaceType.LINEAR_1D, 2.25, (0, 1, 0), 2, 1),
+ (BlendSpaceType.DIRECTIONAL_2D, 4.5, (1, 0, 0), 3, 1.5),
+ ):
+ with self.subTest(space_type=space_type):
+ poses, skeleton = self._targets()
+ mode = _mode("test", space_type, 4.5, velocity_scale=0.9, position_scale=0.8)
+ keys = ((0, 0), (1, 0)) if space_type is BlendSpaceType.LINEAR_1D else ((0, 0), (1, 0), (0, -1))
+ space = BlendSpace(space_type)
+ for index, key in enumerate(keys):
+ space.add_target(wp.vec2(*key), index)
+ space.compile()
+ runtime = LocomotionModeRuntime(
+ mode, space, wp.array(poses, dtype=wp.transform),
+ )
+ state = _locomotion_state(mode, runtime=runtime)
+ direction = np.asarray(facing, dtype=np.float32)
+ character = SimpleNamespace(
+ target_pose_blender=SOMATargetPoseBlender(skeleton.reference_local_transforms),
+ engine=SimpleNamespace(stream=None),
+ character_ground_position=np.array([10, 2, 0], dtype=np.float32),
+ movement=SimpleNamespace(current_facing=direction, desired_velocity=direction * speed),
+ )
+ blended = wp.empty((4, 2), dtype=wp.transform)
+ target = wp.empty_like(blended)
+
+ state.evaluate_current_target_poses(character, blended, target)
+
+ actual = target.numpy()
+ ground = character.character_ground_position + direction * speed * 0.9 * 0.8
+ expected_root = ground + [0, 0, height]
+ for frame in range(4):
+ np.testing.assert_allclose(actual[frame, 0, :3],
+ expected_root + direction * speed * 0.9 * frame / 30, atol=1e-6)
+ np.testing.assert_allclose(actual[:, 1, 0], child_x)
+ np.testing.assert_array_equal(actual[:, 1, 1:3], 0)
+ root_rotation = wp.quat(*actual[0, 0, 3:])
+ np.testing.assert_allclose(wp.quat_rotate(root_rotation, wp.vec3(1, 0, 0)), direction, atol=1e-6)
+ np.testing.assert_array_equal(runtime.target_poses.numpy(), poses)
+
+ def test_mode_loader_keeps_named_target_windows_in_caller_owned_storage(self):
+ poses, skeleton = self._targets()
+ poses[1, :, :, 3:] *= -1
+ source = wp.array(poses, dtype=wp.transform)
+ mode = LocomotionMode(
+ "test", Path("unused.smart_primitive.json"), BlendSpaceType.LINEAR_1D,
+ (("Fast", (1, 0)), ("Slow", (0, 0))), max_speed=4.5, default_speed=2.3,
+ )
+
+ def copy_target(node_index, output):
+ wp.copy(output, source[node_index])
+ return TargetPoseInferenceParams(0, 4)
+
+ primitive = SimpleNamespace(
+ rig=ModelRig.SOMA,
+ node_index=lambda name: {"Fast": 1, "Slow": 0}[name],
+ has_target_pose=lambda index: True,
+ get_local_target_poses=copy_target,
+ )
+ pool = SmartPrimitiveAssetPool(
+ ClipRegistry(ModelRig.SOMA, skeleton=skeleton),
+ skeleton.reference_local_transforms, wp.transform_identity(),
+ )
+ with patch.object(pool, "instantiate", return_value=primitive):
+ runtime = load_locomotion_mode(mode, pool)
+ directional = load_locomotion_mode(replace(mode, blend_space_type=BlendSpaceType.DIRECTIONAL_2D), pool)
+ source.zero_()
+
+ np.testing.assert_array_equal(runtime.target_poses.numpy(), poses[[1, 0]])
+ expected = poses[[1, 0]].copy()
+ expected[0, :, :, 3:] *= -1
+ np.testing.assert_array_equal(directional.target_poses.numpy(), expected)
+ np.testing.assert_array_equal(runtime.blend_space.data_indices.numpy(), [0, 1])
+ sample = runtime.blend_space.evaluate(wp.vec2(0.25, 0))
+ self.assertEqual(tuple(sample.indices)[:2], (1, 0))
+ np.testing.assert_allclose(tuple(sample.weights)[:2], [0.75, 0.25])
+
+
+class CharacterVelocityTests(unittest.TestCase):
+ def test_analog_movement_scales_the_mode_maximum_speed_with_a_floor(self) -> None:
+ for movement, minimum_speed, expected_speed in (
+ ((0.5, 0.0, 0.0), 0.0, 2.25),
+ ((0.05, 0.0, 0.0), 1.84, 1.84),
+ (None, 1.84, 0.0),
+ ):
+ with self.subTest(movement=movement, minimum_speed=minimum_speed):
+ mode = _mode("linear", BlendSpaceType.LINEAR_1D, 4.5, minimum_speed=minimum_speed)
+ control = MovementControl(np.array([1.0, 0.0, 0.0], dtype=np.float32))
+ control.input_speed = 1.0
+
+ control._read_input(LocomotionCommand(
+ facing_direction=np.array([1.0, 0.0, 0.0], dtype=np.float32),
+ movement=None if movement is None else np.array(movement, dtype=np.float32),
+ use_max_speed=True,
+ ), mode)
+
+ self.assertAlmostEqual(control.input_speed, expected_speed)
+ np.testing.assert_allclose(control.input_velocity_direction, [1.0, 0.0, 0.0])
+
+ def test_realign_uses_measured_velocity_and_preserves_input(self) -> None:
+ mode = _mode("linear", BlendSpaceType.LINEAR_1D, 4.5)
+ velocity = np.array([0.0, 3.0, 0.0], dtype=np.float32)
+ movement = MovementControl(np.array([1.0, 0.0, 0.0], dtype=np.float32))
+ movement.input_speed = movement.desired_speed = 4.5
+ movement.desired_speed_rate = movement.desired_velocity_direction_rate = movement.current_facing_rate = 1.0
+ movement.desired_velocity[:] = (4.5, 0.0, 0.0)
+
+ movement.realign(velocity, mode)
+
+ self.assertAlmostEqual(movement.desired_speed, 3.0)
+ np.testing.assert_allclose(movement.desired_velocity, velocity)
+ np.testing.assert_allclose(movement.current_facing, [0.0, 1.0, 0.0])
+ self.assertEqual(movement.input_speed, 4.5)
+ np.testing.assert_allclose(movement.input_velocity_direction, [1.0, 0.0, 0.0])
+
+
+class CharacterGeneratedMotionTests(unittest.TestCase):
+ def test_regeneration_happens_before_sampling_the_full_timestep(self) -> None:
+ delta_time = 1.0 / 64.0
+ for remaining_time, early_frames in ((0.003, 0), (delta_time, 0), (0.020, 0), (0.003, 20)):
+ with self.subTest(remaining_time=remaining_time, early_frames=early_frames):
+ player = GeneratedMotionPlayer.__new__(GeneratedMotionPlayer)
+ player.engine = SimpleNamespace(stream=None)
+ player.output = SimpleNamespace(
+ sample_rate=30.0, num_frames=31, sample=Mock(), sample_foot_contacts=Mock(),
+ )
+ player.transition_early_by_frames = 0
+ player.playback_time = 1.0 - remaining_time
+ trajectory = np.array(
+ [[0.0, frame / 10.0, 0.0] for frame in range(31)], dtype=np.float32,
+ )
+ player._generated_root_positions = trajectory.copy()
+ player.record_pose = Mock()
+ character = SOMACharacter.__new__(SOMACharacter)
+ character.engine = player.engine
+ character.player = player
+ character._playback_source = PlaybackSource.GENERATED
+ character.current_pose = object()
+ character.current_foot_contacts = object()
+ character.character_ground_position = player.current_root_position()
+ character.actual_velocity = np.array([0.0, 3.0, 0.0], dtype=np.float32)
+ character.movement = MovementControl(np.array([0.0, 1.0, 0.0], dtype=np.float32))
+ character.movement.input_speed = character.movement.desired_speed = 3.0
+ character._target_pose_ik_corrector = None
+ character._update_probe_box = Mock()
+ start_position = character.character_ground_position.copy()
+ locomotion = _locomotion_state(_mode("linear", BlendSpaceType.LINEAR_1D, 4.5))
+ locomotion._force_regeneration = False
+ locomotion._previous_generation_desired_velocity[:] = character.actual_velocity
+
+ def regenerate(current_character):
+ # Generation uses the current pose/velocity, not a clamped endpoint.
+ np.testing.assert_allclose(current_character.character_ground_position, start_position)
+ np.testing.assert_allclose(current_character.actual_velocity, [0.0, 3.0, 0.0])
+ player.record_pose.assert_not_called()
+ player.playback_time = 0.0
+ # Even a deadline at time zero leaves the generated frames available.
+ player.output.num_frames = 18
+ player.transition_early_by_frames = early_frames
+ player._generated_root_positions = trajectory[:18] + start_position
+
+ locomotion._generate = Mock(side_effect=regenerate)
+ character.state_machine = SimpleNamespace(
+ update=lambda current, dt, command: locomotion.update(current, None, dt),
+ )
+
+ character.step(delta_time, None)
+
+ self.assertEqual(locomotion._generate.call_count, int(remaining_time <= delta_time))
+ expected_time = delta_time if remaining_time <= delta_time else 1.0 - remaining_time + delta_time
+ self.assertAlmostEqual(player.playback_time, expected_time)
+ np.testing.assert_allclose(
+ character.character_ground_position, start_position + [0.0, 3.0 * delta_time, 0.0],
+ atol=1e-6,
+ )
+ np.testing.assert_allclose(character.actual_velocity, [0.0, 3.0, 0.0], atol=1e-4)
+ player.record_pose.assert_called_once_with(delta_time, character.current_pose)
+
+ def test_clip_transition_does_not_end_early(self) -> None:
+ character = SOMACharacter.__new__(SOMACharacter)
+ character.character_ground_position = np.zeros(3, dtype=np.float32)
+ character.actual_velocity = np.zeros(3, dtype=np.float32)
+ character.movement = MovementControl(np.array([1.0, 0.0, 0.0], dtype=np.float32))
+ character._align_clip = Mock()
+ character._clip_target_poses = np.zeros(
+ (4, 1, 7), dtype=np.float32
+ )
+ character.engine = SimpleNamespace(stream=None)
+ character.generate_to_target_poses = Mock()
+ clip = SimpleNamespace(animation=Mock(), root_offset=None)
+
+ character.generate_clip_transition(clip)
+
+ target_poses, params, source = (
+ character.generate_to_target_poses.call_args.args
+ )
+ self.assertIs(target_poses, character._clip_target_poses)
+ self.assertEqual(
+ params,
+ TargetPoseInferenceParams(
+ transition_early_by_frames=0,
+ num_poses_to_use=4,
+ ),
+ )
+ self.assertIs(source, PlaybackSource.CLIP_TRANSITION)
+
+ def test_target_generation_captures_ik_targets_from_the_first_target_pose(self) -> None:
+ character = SOMACharacter.__new__(SOMACharacter)
+ character.engine = SimpleNamespace(stream=None)
+ character._target_pose_ik_corrector = Mock()
+ character.player = Mock()
+ character.current_pose = object()
+ character.current_foot_contacts = object()
+ character._apply_target_pose_ik = Mock()
+ character._update_character_position = Mock()
+ target_poses = np.arange(4 * 77 * 7, dtype=np.float32).reshape(4, 77, 7)
+ inference_params = TargetPoseInferenceParams(
+ transition_early_by_frames=2, num_poses_to_use=2,
+ ik_pin_mask=IKPin.LEFT_HAND | IKPin.RIGHT_FOOT,
+ )
+
+ character.generate_to_target_poses(target_poses, inference_params)
+
+ captured_pose, captured_mask = (
+ character._target_pose_ik_corrector.capture_pins.call_args.args
+ )
+ np.testing.assert_array_equal(captured_pose, target_poses[0])
+ self.assertEqual(captured_mask, inference_params.ik_pin_mask)
+
+ def test_target_pose_ik_uses_a_late_smooth_ramp(self) -> None:
+ character = SOMACharacter.__new__(SOMACharacter)
+ character.player = SimpleNamespace(
+ playback_duration=1.0,
+ time_to_transition=0.5,
+ )
+ character._playback_source = PlaybackSource.GENERATED
+
+ self.assertEqual(character._target_pose_ik_weight(), 0.0)
+
+ character.player.time_to_transition = 0.25
+ self.assertAlmostEqual(character._target_pose_ik_weight(), 0.5)
+
+ character.player.time_to_transition = 0.0
+ self.assertEqual(character._target_pose_ik_weight(), 1.0)
+
+ def test_each_target_sets_the_pins_that_target_pose_ik_applies(self) -> None:
+ character = SOMACharacter.__new__(SOMACharacter)
+ character.engine = SimpleNamespace(stream=None)
+ character._target_pose_ik_corrector = Mock()
+ character.player = Mock(playback_duration=1.0, time_to_transition=0.0)
+ character.current_pose = object()
+ character.current_foot_contacts = object()
+ character._update_character_position = Mock()
+ target_poses = np.zeros((4, 1, 7), dtype=np.float32)
+
+ character.generate_to_target_poses(target_poses, TargetPoseInferenceParams(0, 4, ik_pin_mask=IKPin.LEFT_HAND))
+ # A clip transition pins nothing, so the earlier target's pins stop applying.
+ character.generate_to_target_poses(
+ target_poses, TargetPoseInferenceParams(0, 4), PlaybackSource.CLIP_TRANSITION,
+ )
+
+ corrector = character._target_pose_ik_corrector
+ masks = [call.args[1] for call in corrector.capture_pins.call_args_list]
+ self.assertEqual(masks, [IKPin.LEFT_HAND, IKPin.NONE])
+ corrector.apply.assert_called_with(character.current_pose, 1.0, stream=None)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_locomotion_styles.py b/tests/app/test_locomotion_styles.py
new file mode 100644
index 0000000..a03e9f3
--- /dev/null
+++ b/tests/app/test_locomotion_styles.py
@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Both rigs offer the same locomotion styles, each blending the standing Idle target into its style."""
+
+import unittest
+from pathlib import Path
+
+import warp as wp
+
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveAssetPool
+from app.runtime.common.motion import load_locomotion_mode, style_locomotion_mode
+from app.runtime.common.rig import load_rig_assets
+from app.runtime.soma.presets import DEFAULT_LOCOMOTION_MODES as SOMA_MODES
+from app.runtime.soma.presets import STYLE_LOCOMOTION_MODES as SOMA_STYLES
+from app.runtime.unitree_g1.presets import DEFAULT_LOCOMOTION_MODES as G1_MODES
+from app.runtime.unitree_g1.presets import STYLE_LOCOMOTION_MODES as G1_STYLES
+from motionbricks.model.contract import ModelRig
+
+
+class LocomotionStyleTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_both_rigs_offer_the_same_styles_at_their_top_speed(self):
+ labels = ["Skipping", "Vogue", "Injured Torso", "Injured Leg", "Zombie", "Combat"]
+ for modes, styles in ((SOMA_MODES, SOMA_STYLES), (G1_MODES, G1_STYLES)):
+ self.assertEqual([mode.label for mode in styles], labels)
+ self.assertEqual(modes[-len(styles):], styles)
+ self.assertEqual([mode.name for mode in SOMA_STYLES], [mode.name for mode in G1_STYLES])
+ for mode in (*SOMA_STYLES, *G1_STYLES):
+ with self.subTest(mode=mode.name):
+ self.assertEqual(mode.target_values, (("Idle", (0.0, 0.0)), (mode.label, (1.0, 0.0))))
+ self.assertEqual(mode.default_speed, mode.max_speed)
+ self.assertLess(mode.minimum_speed, mode.max_speed)
+
+ def test_style_helper_names_the_mode_and_passes_its_tuning_through(self):
+ mode = style_locomotion_mode(
+ "Injured Leg", Path("styles.smart_primitive.json"), minimum_speed=0.5, max_speed=0.75,
+ velocity_scale=0.9, position_scale=1.2, transition_early_by_frames=3, allowed_token_counts=(6, 7, 8),
+ )
+ self.assertEqual((mode.name, mode.label), ("injured_leg_1d", "Injured Leg"))
+ self.assertEqual((mode.velocity_scale, mode.position_scale, mode.transition_early_by_frames), (0.9, 1.2, 3))
+ self.assertEqual(mode.allowed_token_counts, (6, 7, 8))
+
+ def test_each_rig_loads_every_style_from_its_document(self):
+ for rig, styles in ((ModelRig.SOMA, SOMA_STYLES), (ModelRig.UNITREE_G1, G1_STYLES)):
+ assets = load_rig_assets(rig)
+ pool = SmartPrimitiveAssetPool(assets.clip_registry, assets.reference_pose, assets.model_to_runtime)
+ for mode in styles:
+ with self.subTest(rig=rig.name, mode=mode.name):
+ runtime = load_locomotion_mode(mode, pool)
+ self.assertEqual(runtime.target_poses.shape[:2], (2, 4))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_mesh_picking.py b/tests/app/test_mesh_picking.py
new file mode 100644
index 0000000..63e7bed
--- /dev/null
+++ b/tests/app/test_mesh_picking.py
@@ -0,0 +1,315 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from types import SimpleNamespace
+from pathlib import Path
+import unittest
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.io.scene_document import SceneDefinition
+from app.runtime.common.clip_registry import ClipAsset
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveDocument, build_runtime_smart_primitive_data
+from app.inbetweener_demo import InbetweenerDemo, PoseEntry
+from app.smart_primitive_editor import SmartPrimitiveEditor
+from app.scene_editor import SceneEditor, _CharacterStartRenderer, _SceneSmartPrimitiveView
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.mesh import SkeletalMesh, SkinnedMesh
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.renderers.skeletal_mesh_renderer import SkeletalMeshRenderer
+from motionbricks.renderers.solid_box_renderer import SolidBoxRenderer
+from motionbricks.renderers.wire_box_renderer import WireBoxRenderer
+from motionbricks.runtime.smart_primitive import SmartPrimitive, SmartPrimitiveAsset
+
+
+def _renderer():
+ reference = np.array([[0, 0, 0, 0, 0, 0, 1], [0, 1, 0, 0, 0, 0, 1]], dtype=np.float32)
+ skeleton = Skeleton(["Hips", "Child"], [-1, 0], reference)
+ parts = [
+ SkinnedMesh(
+ np.array([[0, 0, z], [1, 0, z], [0, 1, z]], dtype=np.float32),
+ np.array([0, 1, 2], dtype=np.int32),
+ np.ones(3, dtype=np.int32), np.ones(3, dtype=np.float32),
+ )
+ for z in (-2, 0)
+ ]
+ # Like the SOMA mesh, it has the relaxed-hands override pose and finger mask.
+ mesh = SkeletalMesh(
+ parts, skeleton, [wp.transform_identity(), wp.transform(0, -1, 0, 0, 0, 0, 1)],
+ override_poses={"RelaxedHands": wp.clone(skeleton.reference_local_transforms)},
+ override_pose_masks={"Fingers": wp.zeros(2, dtype=wp.float32)},
+ )
+ return SkeletalMeshRenderer(mesh)
+
+
+class MeshPickingTests(unittest.TestCase):
+ def test_scene_picks_instance_roots_and_cubes_by_depth_and_geometry_visibility(self):
+ with wp.ScopedDevice("cpu"):
+ mesh = _renderer().skeletal_mesh
+ authoring = SmartPrimitiveDocument(
+ "soma", mesh.skeleton.reference_local_transforms, wp.transform_identity(),
+ )
+ frames = np.repeat(mesh.skeleton.reference_local_transforms.numpy()[None], 4, axis=0)
+ animation = AnimationBuffer(mesh.skeleton, 30.0, wp.array(frames, dtype=wp.transform))
+ clip = ClipAsset(Path("selection.bvh"), animation)
+ first, second = authoring.add_node(), authoring.add_node()
+ second.local_xform = wp.transform(4, 0, 0, 0, 0, 0, 1)
+ for node in (first, second):
+ authoring.add_target_pose(node).set_clip(clip)
+ box_node = authoring.add_node()
+ box_node.local_xform = wp.transform(wp.vec3(-3, 0, 1), wp.quat_rpy(0.0, 0.0, 0.6))
+ authoring.add_interaction_box(box_node).set_dimensions(2, 4, 2)
+ sequence = authoring.add_sequence()
+ authoring.add_sequence_node(sequence, second)
+ asset = SmartPrimitiveAsset(build_runtime_smart_primitive_data(authoring), device="cpu")
+ editor = SceneEditor.__new__(SceneEditor)
+ editor.viewer = SimpleNamespace(camera=SimpleNamespace(far=100))
+ editor.scene = SceneDefinition()
+ editor.solid_box_renderer = SolidBoxRenderer()
+ editor.character_start_renderer = _CharacterStartRenderer()
+ editor._runtime_views = {}
+ instances = [editor.scene.add_smart_primitive(), editor.scene.add_smart_primitive()]
+ for index, instance in enumerate(instances):
+ instance.reference = Path("selection.smart_primitive.json")
+ instance.transform = wp.transform(index * 8, 0, 1, 0, 0, 0, 1)
+ runtime = SmartPrimitive(asset)
+ editor._runtime_views[instance.id] = _SceneSmartPrimitiveView(
+ instance, runtime, mesh, mesh.skeleton.reference_local_transforms, instance.transform,
+ )
+ editor.selected_item_id = editor.scene.character_start.id
+ direction = wp.vec3(0, 0, -1)
+ for x, owner in ((0.2, instances[0]), (4.2, instances[0]), (8.2, instances[1])):
+ editor._select_scene_item(wp.vec3(x, 0.2, 5), direction)
+ self.assertEqual(editor.selected_item_id, owner.id)
+ cube = editor.scene.add_solid_cube()
+ cube.transform = wp.transform(0.2, 0.2, 3, 0, 0, 0, 1)
+ editor._select_scene_item(wp.vec3(0.2, 0.2, 5), direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+ cube.transform = wp.transform(0.2, 0.2, -3, 0, 0, 0, 1)
+ editor._select_scene_item(wp.vec3(0.2, 0.2, 5), direction)
+ self.assertEqual(editor.selected_item_id, instances[0].id)
+ view = editor._runtime_views[instances[0].id]
+ view.target_pose_sequence_index = 0
+ editor._select_scene_item(wp.vec3(0.2, 0.2, 5), direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+ editor._select_scene_item(wp.vec3(4.2, 0.2, 5), direction)
+ self.assertEqual(editor.selected_item_id, instances[0].id)
+ instances[0].show_target_poses = False
+ editor.selected_item_id = editor.scene.character_start.id
+ editor._select_scene_item(wp.vec3(4.2, 0.2, 5), direction)
+ self.assertEqual(editor.selected_item_id, editor.scene.character_start.id)
+
+ # Wire boxes select their instance root even when its target poses are hidden.
+ box_world = instances[0].transform * box_node.local_xform
+ origin = wp.transform_point(box_world, wp.vec3(0, 2, 5))
+ direction = wp.transform_vector(box_world, wp.vec3(0, 0, -1))
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, instances[0].id)
+ instances[0].show_interaction_boxes = False
+ editor.selected_item_id = cube.id
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+
+ instances[0].show_interaction_boxes = True
+ instances[0].transform = wp.transform(wp.vec3(-5, 2, 4), wp.quat_rpy(0.4, -0.3, 0.7))
+ view.set_transform(instances[0].transform)
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+ box_world = instances[0].transform * box_node.local_xform
+ origin = wp.transform_point(box_world, wp.vec3(0, 2, 5))
+ direction = wp.transform_vector(box_world, wp.vec3(0, 0, -1))
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, instances[0].id)
+
+ def test_wire_box_picking_follows_transformed_resized_edges_and_leaves_faces_open(self):
+ placement = wp.transform(wp.vec3(3, 4, 5), wp.quat_rpy(0.3, -0.4, 0.9))
+ for origin, direction, limit, expected in (
+ ((0.25, 2, 8), (0, 0, -1), 12.3, 5.0),
+ ((1, 0.25, 8), (0, 0, -1), 12.3, 5.0),
+ ((6, 2, 0.25), (-1, 0, 0), 12.3, 5.0),
+ ((0, 0, 8), (0, 0, -1), 12.3, None),
+ ((1, 0.25, 8), (0, 0, 1), 12.3, None),
+ ((1, 0.25, 8), (0, 0, -1), 4.0, None),
+ ):
+ with self.subTest(origin=origin, direction=direction, limit=limit):
+ distance = WireBoxRenderer.raycast(
+ placement, wp.vec3(2, 4, 6), wp.transform_point(placement, wp.vec3(*origin)),
+ wp.transform_vector(placement, wp.vec3(*direction)), limit,
+ )
+ if expected is None:
+ self.assertEqual(distance, limit)
+ else:
+ self.assertAlmostEqual(distance, expected, delta=0.1)
+ origin = wp.transform_point(placement, wp.vec3(0.25, 2, 8))
+ direction = wp.transform_vector(placement, wp.vec3(0, 0, -1))
+ self.assertEqual(WireBoxRenderer.raycast(placement, wp.vec3(2, 3, 6), origin, direction, 12.3), 12.3)
+ # Authored boxes may be flat; collapsed edges must not create invalid rotations.
+ self.assertAlmostEqual(
+ WireBoxRenderer.raycast(placement, wp.vec3(2, 4, 0), origin, direction), 8.0, delta=0.1,
+ )
+
+ def test_scene_picks_transformed_start_lines_without_selecting_gaps_or_occluded_geometry(self):
+ with wp.ScopedDevice("cpu"):
+ editor = SceneEditor.__new__(SceneEditor)
+ editor.viewer = SimpleNamespace(camera=SimpleNamespace(far=100))
+ editor.scene = SceneDefinition()
+ editor._runtime_views = {}
+ editor.character_start_renderer = _CharacterStartRenderer()
+ editor.solid_box_renderer = SolidBoxRenderer()
+ start = editor.scene.character_start
+ placement = wp.transform(wp.vec3(3, -2, 1), wp.quat_rpy(0.3, 0.4, 0.9))
+ start.transform = placement
+ cube = editor.scene.add_solid_cube()
+ cube.width = cube.depth = 2.0
+ cube.transform = placement * wp.transform(0, 0, -2, 0, 0, 0, 1)
+ direction = wp.transform_vector(placement, wp.vec3(0, 0, -1))
+ # Circle, arrow shaft, and arrowhead select the marker ahead of a cube.
+ for x, y in ((0.0, 0.35), (0.5, 0.0), (0.71, 0.06)):
+ with self.subTest(x=x, y=y):
+ editor.selected_item_id = cube.id
+ origin = wp.transform_point(placement, wp.vec3(x, y, 5))
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, start.id)
+
+ cube.transform = placement * wp.transform(0, 0, 2, 0, 0, 0, 1)
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+
+ cube.transform = wp.transform(20, 0, 0, 0, 0, 0, 1)
+ for point in ((0, 0.15, 5), (0.5, 0.3, 5)):
+ editor._select_scene_item(wp.transform_point(placement, wp.vec3(*point)), direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+
+ # Picking uses the edited transform, not the marker's previous placement.
+ start.transform = wp.transform(10, 0, 0, 0, 0, 0, 1) * placement
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_item_id, cube.id)
+ editor._select_scene_item(origin + wp.vec3(10, 0, 0), direction)
+ self.assertEqual(editor.selected_item_id, start.id)
+
+ def test_raycast_follows_skinned_pose_placement_and_uses_nearest_mesh_part(self):
+ wp.init()
+ for device in wp.get_devices():
+ with self.subTest(device=device.alias), wp.ScopedDevice(device):
+ renderer = _renderer()
+ pose = renderer.skeletal_mesh.skeleton.reference_local_transforms.numpy().copy()
+ pose[1, 0] = 1
+ transforms = wp.array(pose, dtype=wp.transform)
+ placement = wp.transform(wp.vec3(3, 0, 0), wp.quat_rpy(0.0, 0.0, wp.pi / 2))
+ ray = wp.vec3(0, 0, -1)
+ self.assertAlmostEqual(renderer.raycast_pose(transforms, placement, wp.vec3(2.8, 1.2, 5), ray), 5)
+ # Moving a joint must invalidate the old surface, even though the picker reuses its mesh.
+ pose[1, 0] = 4
+ transforms.assign(pose)
+ self.assertEqual(renderer.raycast_pose(transforms, placement, wp.vec3(2.8, 1.2, 5), ray, 12.3), 12.3)
+ self.assertAlmostEqual(renderer.raycast_pose(transforms, placement, wp.vec3(2.8, 4.2, 5), ray), 5)
+ self.assertEqual(renderer.raycast_pose(transforms, placement, wp.vec3(2.8, 4.2, 5), ray, 4), 4)
+ # Inside the bounding box but outside the triangle is not a hit.
+ self.assertEqual(renderer.raycast_pose(transforms, placement, wp.vec3(2.1, 4.9, 5), ray, 10), 10)
+
+ def test_demo_selects_nearest_current_pose_after_reordering_and_preserves_selection_on_miss(self):
+ with wp.ScopedDevice("cpu"):
+ demo = InbetweenerDemo.__new__(InbetweenerDemo)
+ demo.viewer = SimpleNamespace(camera=SimpleNamespace(far=100))
+ demo.mesh_renderer = _renderer()
+ skeleton = demo.mesh_renderer.skeletal_mesh.skeleton
+ clip = AnimationBuffer(
+ skeleton, 30.0, wp.array(skeleton.reference_local_transforms.numpy()[None], dtype=wp.transform),
+ )
+ demo.pose_entries = [
+ PoseEntry(identifier, str(identifier), Path("synthetic.bvh"), clip,
+ 0.0, wp.transform_identity())
+ for identifier in (42, 8, 17)
+ ]
+ poses = np.repeat(
+ demo.mesh_renderer.skeletal_mesh.skeleton.reference_local_transforms.numpy()[None], 3, axis=0,
+ )
+ poses[:, 0, 2] = [0, 2, -2]
+ for index, (entry, pose) in enumerate(zip(demo.pose_entries, poses)):
+ entry.preview_pose = wp.array(pose, dtype=wp.transform)
+ # Keep the ground rings away from these rays. They have their own test.
+ entry.root_position = np.array([10 + 2 * index, 0, 0], dtype=np.float32)
+ demo._refresh_order_markers()
+ demo.selected_index = 0
+ origin, direction = wp.vec3(0.2, 0.2, 5), wp.vec3(0, 0, -1)
+ demo._select_pose(origin, direction)
+ self.assertEqual(demo.pose_entries[demo.selected_index].id, 8)
+ demo.pose_entries = [demo.pose_entries[i] for i in (0, 2, 1)]
+ demo._refresh_order_markers()
+ demo._select_pose(origin, direction)
+ self.assertEqual(demo.pose_entries[demo.selected_index].id, 8)
+ demo._select_pose(wp.vec3(5, 5, 5), direction)
+ self.assertEqual(demo.pose_entries[demo.selected_index].id, 8)
+ demo.pose_entries[demo.selected_index].show_mesh = False
+ demo._select_pose(origin, direction)
+ self.assertEqual(demo.pose_entries[demo.selected_index].id, 42)
+
+ def test_editor_selects_owning_node_and_ignores_hidden_meshes_and_ancestors(self):
+ with wp.ScopedDevice("cpu"):
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ renderer = _renderer()
+ editor.rig = SimpleNamespace(target_pose_renderers=SimpleNamespace(mesh=renderer))
+ editor.viewer = SimpleNamespace(camera=SimpleNamespace(far=100))
+ editor.authoring = SmartPrimitiveDocument(
+ "soma", renderer.skeletal_mesh.skeleton.reference_local_transforms, wp.transform(3, 0, 0, 0, 0, 0, 1),
+ )
+ parent = editor.authoring.add_node()
+ parent.local_xform = wp.transform(0, 4, 0, 0, 0, 0, 1)
+ far = editor.authoring.add_node(parent)
+ near = editor.authoring.add_node(parent)
+ near.local_xform = wp.transform(0, 0, 2, 0, 0, 0, 1)
+ editor.authoring.add_target_pose(far)
+ component = editor.authoring.add_target_pose(near)
+ editor.selected_id = editor.authoring.root.id
+ origin, direction = wp.vec3(3.2, 4.2, 5), wp.vec3(0, 0, -1)
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_id, near.id)
+ self.assertNotEqual(editor.selected_id, component.id)
+ component.show_mesh = False
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_id, far.id)
+ parent.visible = False
+ editor.selected_id = editor.authoring.root.id
+ editor._select_scene_item(origin, direction)
+ self.assertEqual(editor.selected_id, editor.authoring.root.id)
+
+ def test_editor_picks_wire_box_owner_with_hierarchy_visibility_and_mesh_clickthrough(self):
+ with wp.ScopedDevice("cpu"):
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ renderer = _renderer()
+ editor.rig = SimpleNamespace(target_pose_renderers=SimpleNamespace(mesh=renderer))
+ editor.interaction_box_renderer = WireBoxRenderer()
+ editor.viewer = SimpleNamespace(camera=SimpleNamespace(far=100))
+ editor.authoring = SmartPrimitiveDocument(
+ "soma", renderer.skeletal_mesh.skeleton.reference_local_transforms, wp.transform(3, 0, 0, 0, 0, 0, 1),
+ )
+ parent = editor.authoring.add_node()
+ parent.local_xform = wp.transform(wp.vec3(2, 4, 1), wp.quat_rpy(0.3, -0.2, 0.8))
+ pose_node = editor.authoring.add_node(parent)
+ editor.authoring.add_target_pose(pose_node)
+ box_node = editor.authoring.add_node(parent)
+ box_node.local_xform = wp.transform(3.2, 0.2, 1, 0, 0, 0, 1)
+ box = editor.authoring.add_interaction_box(box_node)
+ box.set_dimensions(0.4, 0.4, 2)
+ editor.selected_id = parent.id
+ direction = wp.transform_vector(parent.local_xform, wp.vec3(0, 0, -1))
+ interior = wp.transform_point(parent.local_xform, wp.vec3(3.2, 0.2, 5))
+ editor._select_scene_item(interior, direction)
+ self.assertEqual(editor.selected_id, pose_node.id)
+
+ edge = wp.transform_point(parent.local_xform, wp.vec3(3.2, 0.4, 5))
+ editor._select_scene_item(edge, direction)
+ self.assertEqual(editor.selected_id, box_node.id)
+ self.assertNotEqual(editor.selected_id, box.id)
+ box_node.visible = False
+ editor._select_scene_item(edge, direction)
+ self.assertEqual(editor.selected_id, pose_node.id)
+ box_node.visible = True
+ box_node.local_xform = wp.transform(3.2, 0.2, -4, 0, 0, 0, 1)
+ editor._select_scene_item(edge, direction)
+ self.assertEqual(editor.selected_id, pose_node.id)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_runtime_smart_primitive.py b/tests/app/test_runtime_smart_primitive.py
new file mode 100644
index 0000000..64f3e59
--- /dev/null
+++ b/tests/app/test_runtime_smart_primitive.py
@@ -0,0 +1,719 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import tempfile
+import unittest
+from dataclasses import replace
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.clip_registry import ClipAsset, ClipRegistry
+from app.runtime.common.io.smart_primitive_document import (
+ SmartPrimitiveDocumentError,
+ SmartPrimitiveAssetPool,
+ SmartPrimitiveDocument,
+ TargetPoseComponent,
+ build_runtime_smart_primitive_data,
+ save_smart_primitive_document,
+)
+from app.runtime.common.smart_primitive_behaviors import (
+ SittingBehavior,
+ SmartPrimitiveBehavior,
+ VelocityMatchingSequenceBehavior,
+ behavior_types,
+)
+from app.scene_preview import ScenePreview, _RuntimeSceneSmartPrimitive
+from app.runtime.common.io.scene_document import SceneDefinition, SmartPrimitiveInstance, save_scene_document
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.contract import MODEL_POSES_PER_TOKEN, ModelRig
+from motionbricks.runtime.pivot import Axis, ConeSide, ConstraintType
+from motionbricks.runtime.smart_primitive import (
+ CharacterProperties,
+ InteractionBox,
+ SmartPrimitive,
+ SmartPrimitiveAsset,
+ compute_interaction_box_overlaps,
+)
+from motionbricks.runtime.target_pose import (
+ IKPin,
+ TargetPoseInferenceParams,
+)
+
+
+def _transform(values) -> wp.transform:
+ return wp.transform(wp.vec3(*values[:3]), wp.quat(*values[3:]))
+
+
+def _transform_values(transform: wp.transform) -> np.ndarray:
+ return np.asarray(
+ [float(transform[index]) for index in range(7)],
+ dtype=np.float32,
+ )
+
+
+def _interaction_box_array(
+ position,
+ half_extents=(0.5, 0.5, 0.5),
+ rotation=None,
+) -> wp.array:
+ box = InteractionBox()
+ box.transform = wp.transform(
+ wp.vec3(*position),
+ rotation if rotation is not None else wp.quat(0.0, 0.0, 0.0, 1.0),
+ )
+ box.half_extents = wp.vec3(*half_extents)
+ return wp.array([box], dtype=InteractionBox, device="cpu")
+
+
+class RuntimeSmartPrimitiveTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def _build_authoring(self):
+ reference_pose = np.asarray(
+ [
+ [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
+ [0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0],
+ ],
+ dtype=np.float32,
+ )
+ skeleton = Skeleton(
+ ["Hips", "Chest"],
+ [-1, 0],
+ reference_pose,
+ )
+ self.skeleton = skeleton
+ clip_poses = np.repeat(reference_pose[None, ...], 10, axis=0)
+ clip_poses[:, 0, 0] = 2.0 + np.arange(10, dtype=np.float32)
+ clip_poses[:, 0, 1] = 0.5
+ clip_poses[:, 0, 2] = 4.0 + 0.5 * np.arange(10, dtype=np.float32)
+ animation = AnimationBuffer(skeleton, 30.0, wp.array(clip_poses, dtype=wp.transform))
+ clip = ClipAsset(Path("runtime_test.bvh"), animation)
+
+ model_to_runtime = wp.transform(
+ wp.vec3(0.0, 0.0, 0.0),
+ wp.quat_rpy(0.5 * wp.pi, 0.0, 0.0),
+ )
+ authoring = SmartPrimitiveDocument("soma", skeleton.reference_local_transforms, model_to_runtime)
+ authoring.root.local_xform = wp.transform(
+ wp.vec3(1.0, 2.0, 3.0),
+ wp.quat_rpy(0.0, 0.0, 0.2),
+ )
+
+ approach = authoring.add_node()
+ approach.name = "Approach"
+ approach.local_xform = wp.transform(
+ wp.vec3(4.0, 0.0, 0.0),
+ wp.quat_rpy(0.0, 0.1, 0.0),
+ )
+ approach_target = authoring.add_target_pose(approach)
+ approach_target.set_clip(clip)
+ approach_target.set_time(1 / 30.0)
+ approach_target.set_num_poses_to_use(3)
+ approach_target.transition_early_by_frames = 7
+ approach_target.ik_pin_mask = IKPin.LEFT_HAND | IKPin.RIGHT_FOOT
+
+ contact = authoring.add_node(approach)
+ contact.name = "Contact"
+ contact.local_xform = wp.transform(
+ wp.vec3(0.0, 5.0, 0.0),
+ wp.quat_rpy(0.1, 0.0, 0.0),
+ )
+ contact_target = authoring.add_target_pose(contact)
+ contact_target.set_clip(clip)
+ contact_target.set_time(2 / 30.0)
+ contact_target.constrain_hips(True)
+ contact_target.set_num_poses_to_use(2)
+ contact_target.transition_early_by_frames = 11
+ contact_target.set_token_range(7, 9)
+ contact_target.ik_pin_mask = IKPin.RIGHT_HAND | IKPin.LEFT_FOOT
+
+ box = authoring.add_interaction_box(contact)
+ box.set_dimensions(2.0, 4.0, 6.0)
+ sequence = authoring.add_sequence()
+ sequence.name = "Contact Then Approach"
+ authoring.add_sequence_node(sequence, contact)
+ authoring.add_sequence_node(sequence, approach)
+ return authoring, approach, approach_target, contact, contact_target
+
+ def _build_data(self):
+ authoring, approach, approach_target, contact, contact_target = self._build_authoring()
+ data = build_runtime_smart_primitive_data(authoring)
+ return data, authoring, approach, approach_target, contact, contact_target
+
+ def test_prepared_data_preserves_target_and_sequence_settings(self) -> None:
+ data, *_ = self._build_data()
+ self.assertEqual(data.rig, "soma")
+ self.assertEqual(data.target_poses.shape, (8, 2, 7))
+ self.assertEqual(data.target_inference_params, (
+ TargetPoseInferenceParams(
+ transition_early_by_frames=7, num_poses_to_use=3,
+ ik_pin_mask=int(IKPin.LEFT_HAND | IKPin.RIGHT_FOOT),
+ allowed_token_counts=tuple(range(6, 15)),
+ ),
+ TargetPoseInferenceParams(
+ transition_early_by_frames=11, num_poses_to_use=2,
+ ik_pin_mask=int(IKPin.RIGHT_HAND | IKPin.LEFT_FOOT),
+ allowed_token_counts=(7, 8, 9),
+ ),
+ ))
+ np.testing.assert_array_equal(data.node_parent_indices, [-1, 0, 1])
+ np.testing.assert_allclose(data.box_half_extents, [[1, 2, 3]])
+ self.assertEqual(len(data.sequences), 1)
+ sequence = data.sequences[0]
+ self.assertEqual(sequence.name, "Contact Then Approach")
+ self.assertEqual(sequence.node_indices, (2, 1))
+ self.assertAlmostEqual(sequence.start_speed, np.sqrt(30**2 + 15**2), places=4)
+
+ def test_runtime_retrieves_newton_local_and_world_target_poses(self) -> None:
+ data, authoring, approach, approach_target, contact, contact_target = (
+ self._build_data()
+ )
+ runtime = SmartPrimitive(SmartPrimitiveAsset(data, device="cpu"))
+ output = wp.empty((6, 2), dtype=wp.transform, device="cpu")
+ for node, component in ((approach, approach_target), (contact, contact_target)):
+ node_index = runtime.node_index(node.name)
+ sampled = component.sampled_poses.numpy()
+ if component.hips_constrained:
+ np.testing.assert_allclose(sampled[0, 0, [0, 2]], 0.0, atol=1.0e-6)
+
+ converted_hips = [
+ wp.mul(authoring.model_to_runtime, _transform(sampled[frame, 0]))
+ for frame in range(4)
+ ]
+ runtime.get_local_target_poses(node_index, output)
+ local_output = output.numpy()[:4]
+ for frame in range(4):
+ expected = wp.mul(node.local_xform, converted_hips[frame])
+ np.testing.assert_allclose(
+ local_output[frame, 0],
+ _transform_values(expected),
+ atol=1.0e-5,
+ )
+ np.testing.assert_allclose(local_output[:, 1], sampled[:, 1], atol=1.0e-6)
+
+ runtime.get_world_target_poses(node_index, output)
+ world_output = output.numpy()[:4]
+ node_world = authoring.world_xform(node)
+ for frame in range(4):
+ expected = wp.mul(node_world, converted_hips[frame])
+ np.testing.assert_allclose(
+ world_output[frame, 0],
+ _transform_values(expected),
+ atol=1.0e-5,
+ )
+ np.testing.assert_allclose(world_output[:, 1], sampled[:, 1], atol=1.0e-6)
+
+ def test_json_asset_pool_preserves_runtime_order_and_shares_clips(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ authoring, approach, approach_target, contact, contact_target = self._build_authoring()
+ clip_path = root / "source.bvh"
+ clip_path.write_text(
+ "HIERARCHY\nROOT Hips\n{\n OFFSET 0 0 0\n"
+ " CHANNELS 6 Xposition Yposition Zposition Xrotation Yrotation Zrotation\n"
+ " JOINT Chest\n {\n OFFSET 0 100 0\n"
+ " CHANNELS 3 Xrotation Yrotation Zrotation\n }\n}\n"
+ "MOTION\nFrames: 10\nFrame Time: 0.03333333333333333\n"
+ + "\n".join(f"{200 + 100*i} 50 {400 + 50*i} 0 0 0 0 0 0" for i in range(10))
+ + "\n",
+ encoding="utf-8",
+ )
+ clip = ClipAsset(clip_path, approach_target.clip.animation)
+ approach_target.clip = contact_target.clip = clip
+ approach_target.show_trajectory = True
+ # A parent created last must precede its children at runtime.
+ parent = authoring.add_node()
+ parent.name = "Late Parent"
+ parent.local_xform = wp.transform(
+ wp.vec3(-2.0, 3.0, 1.0), wp.quat_rpy(0.2, 0.0, -0.4),
+ )
+ authoring.reparent(approach, parent)
+ authoring.add_pivot(parent)
+ authoring.set_sequence_pivot(authoring.sequences[0], parent)
+ variation = authoring.add_sequence()
+ variation.name = "Return"
+ for node in (approach, contact, approach):
+ authoring.add_sequence_node(variation, node)
+ authoring.sequences.reverse()
+ camera = {
+ "pos": [1, 2, 3], "pivot": [0, 0, 0], "pitch": -20, "yaw": 45,
+ "fov": 45, "near": 0.01, "far": 1000,
+ }
+ document_path = save_smart_primitive_document(authoring, root / "first", approach.id, camera)
+ other_path = save_smart_primitive_document(authoring, root / "second", contact.id, camera)
+ expected_asset = SmartPrimitiveAsset(build_runtime_smart_primitive_data(authoring), device="cpu")
+ expected_runtime = SmartPrimitive(expected_asset)
+ registry = ClipRegistry(ModelRig.SOMA, skeleton=self.skeleton)
+ pool = SmartPrimitiveAssetPool(registry, authoring.reference_pose, authoring.model_to_runtime)
+
+ with patch.object(TargetPoseComponent, "_update_trajectory_samples") as sample_trajectory:
+ runtime = pool.instantiate(document_path)
+ second = pool.instantiate(document_path)
+ other = pool.instantiate(other_path)
+ sample_trajectory.assert_not_called()
+ self.assertIs(runtime.asset, second.asset)
+ self.assertIsNot(runtime.asset, other.asset)
+
+ self.assertEqual(
+ tuple(runtime.node_name(index) for index in range(runtime.node_count)),
+ ("Root", "Late Parent", "Approach", "Contact"),
+ )
+ np.testing.assert_array_equal(runtime.node_parent_indices.numpy(), [-1, 0, 1, 2])
+ np.testing.assert_allclose(
+ runtime.node_local_transforms.numpy(), expected_runtime.node_local_transforms.numpy(),
+ )
+ self.assertEqual(runtime.pivot_node_indices, expected_runtime.pivot_node_indices)
+ for node_index in runtime.pivot_node_indices:
+ self.assertEqual(runtime.pivot(node_index), expected_runtime.pivot(node_index))
+ self.assertEqual(
+ [runtime.sequence_name(index) for index in range(runtime.sequence_count)],
+ ["Return", "Contact Then Approach"],
+ )
+ output = wp.empty((12, 2), dtype=wp.transform, device="cpu")
+ expected_output = wp.empty_like(output)
+ for index in range(runtime.sequence_count):
+ self.assertEqual(
+ runtime.target_names_for_sequence(index), expected_runtime.target_names_for_sequence(index),
+ )
+ self.assertAlmostEqual(
+ runtime.sequence_start_speed(index), expected_runtime.sequence_start_speed(index), places=4,
+ )
+ self.assertEqual(
+ runtime.sequence_pivot_node_index(index), expected_runtime.sequence_pivot_node_index(index),
+ )
+ params = runtime.get_world_target_poses_for_sequence(index, output)
+ self.assertEqual(params, expected_runtime.get_world_target_poses_for_sequence(index, expected_output))
+ frames = len(params) * MODEL_POSES_PER_TOKEN
+ np.testing.assert_allclose(output.numpy()[:frames], expected_output.numpy()[:frames], atol=1.0e-5)
+ boxes = wp.empty(runtime.interaction_box_count, dtype=InteractionBox, device="cpu")
+ expected_boxes = wp.empty_like(boxes)
+ runtime.get_world_interaction_boxes(boxes)
+ expected_runtime.get_world_interaction_boxes(expected_boxes)
+ for field in ("transform", "half_extents"):
+ np.testing.assert_allclose(boxes.numpy()[field], expected_boxes.numpy()[field], atol=1.0e-5)
+
+ def test_velocity_matching_behavior_selects_the_closest_sequence_speed(
+ self,
+ ) -> None:
+ authoring, approach, _, _, contact_target = self._build_authoring()
+ contact_target.set_num_poses_to_use(1)
+ alternate = authoring.add_sequence()
+ alternate.name = "Approach Only"
+ authoring.add_sequence_node(alternate, approach)
+ data = build_runtime_smart_primitive_data(authoring)
+ runtime = VelocityMatchingSequenceBehavior(SmartPrimitiveAsset(data, device="cpu"))
+ output = wp.empty(
+ (
+ runtime.max_sequence_length * MODEL_POSES_PER_TOKEN,
+ runtime.pose_size,
+ ),
+ dtype=wp.transform,
+ device="cpu",
+ )
+ expected = wp.empty_like(output)
+ stopped = CharacterProperties(
+ position=np.zeros(3, dtype=np.float32),
+ velocity=np.zeros(3, dtype=np.float32),
+ facing=np.array([1.0, 0.0, 0.0], dtype=np.float32),
+ desired_velocity=np.zeros(3, dtype=np.float32),
+ probe_segment=(np.zeros(3), np.zeros(3)),
+ )
+ self.assertEqual(runtime.sequence_start_speed(0), 0.0)
+ alternate_speed = runtime.sequence_start_speed(1)
+
+ # Speeds above every sequence pick the fastest one. A tie keeps the first.
+ for speed, sequence in (
+ (0.0, 0), (alternate_speed, 1), (2.0 * alternate_speed, 1), (0.5 * alternate_speed, 0),
+ ):
+ with self.subTest(speed=speed):
+ properties = replace(stopped, velocity=np.array([speed, 0.0, 0.0]))
+ params = runtime.get_targets(properties, output)
+ self.assertEqual(params, runtime.get_world_target_poses_for_sequence(sequence, expected))
+ frames = len(params) * MODEL_POSES_PER_TOKEN
+ np.testing.assert_allclose(output.numpy()[:frames], expected.numpy()[:frames])
+
+ def test_every_behavior_subclass_is_found_by_class_name(self) -> None:
+ class _TestLeaningBehavior(SmartPrimitiveBehavior):
+ pass
+
+ class _TestLongSittingBehavior(SittingBehavior):
+ pass
+
+ types = behavior_types()
+ self.assertIs(types["SittingBehavior"], SittingBehavior)
+ self.assertIs(types["_TestLeaningBehavior"], _TestLeaningBehavior)
+ self.assertIs(types["_TestLongSittingBehavior"], _TestLongSittingBehavior)
+
+ def test_node_transforms_can_be_set_in_local_or_world_space(self) -> None:
+ data, _, approach, _, contact, _ = self._build_data()
+ runtime = SmartPrimitive(SmartPrimitiveAsset(data, device="cpu"))
+ world_transforms_output = wp.empty(
+ runtime.node_count + 2,
+ dtype=wp.transform,
+ device="cpu",
+ )
+
+ new_approach_local = wp.transform(
+ wp.vec3(-2.0, 3.0, 4.0),
+ wp.quat_rpy(0.2, -0.3, 0.4),
+ )
+ runtime.set_node_local_transform(
+ runtime.node_index(approach.name),
+ new_approach_local,
+ )
+ runtime.compute_world_transforms(world_transforms_output)
+ world_transforms_numpy = world_transforms_output.numpy()
+ root = _transform(runtime.node_local_transforms.numpy()[0])
+ expected_approach_world = wp.mul(root, new_approach_local)
+ np.testing.assert_allclose(
+ world_transforms_numpy[runtime.node_index(approach.name)],
+ _transform_values(expected_approach_world),
+ atol=1.0e-5,
+ )
+
+ desired_contact_world = wp.transform(
+ wp.vec3(8.0, 9.0, 10.0),
+ wp.quat_rpy(-0.1, 0.2, -0.3),
+ )
+ runtime.set_node_world_transform(
+ runtime.node_index(contact.name),
+ desired_contact_world,
+ )
+ runtime.compute_world_transforms(world_transforms_output)
+ np.testing.assert_allclose(
+ world_transforms_output.numpy()[runtime.node_index(contact.name)],
+ _transform_values(desired_contact_world),
+ atol=1.0e-5,
+ )
+
+ expected_local = wp.mul(
+ wp.transform_inverse(expected_approach_world),
+ desired_contact_world,
+ )
+ np.testing.assert_allclose(
+ runtime.node_local_transforms.numpy()[runtime.node_index(contact.name)],
+ _transform_values(expected_local),
+ atol=1.0e-5,
+ )
+
+ def test_interaction_box_returns_collision_ready_box(self) -> None:
+ data, authoring, _, _, contact, _ = self._build_data()
+ runtime = SmartPrimitive(SmartPrimitiveAsset(data, device="cpu"))
+ node_index = runtime.node_index(contact.name)
+ output_box = wp.empty(3, dtype=InteractionBox, device="cpu")
+
+ runtime.get_local_interaction_box(node_index, output_box)
+ local_box = output_box.numpy()
+ np.testing.assert_allclose(
+ local_box["transform"][0],
+ _transform_values(contact.local_xform),
+ atol=1.0e-6,
+ )
+ np.testing.assert_allclose(local_box["half_extents"][0], [1.0, 2.0, 3.0])
+
+ runtime.get_world_interaction_box(node_index, output_box)
+ world_box = output_box.numpy()
+ np.testing.assert_allclose(
+ world_box["transform"][0],
+ _transform_values(authoring.world_xform(contact)),
+ atol=1.0e-5,
+ )
+
+ runtime.get_world_interaction_boxes(output_box)
+ world_boxes = output_box.numpy()
+ np.testing.assert_allclose(
+ world_boxes["transform"][0],
+ _transform_values(authoring.world_xform(contact)),
+ atol=1.0e-5,
+ )
+ np.testing.assert_allclose(
+ world_boxes["half_extents"][0],
+ [1.0, 2.0, 3.0],
+ )
+
+ def test_interaction_box_overlap_helper_processes_one_batch(self) -> None:
+ near_box = InteractionBox()
+ near_box.transform = wp.transform_identity()
+ near_box.half_extents = wp.vec3(0.5, 0.5, 0.5)
+ far_box = InteractionBox()
+ far_box.transform = wp.transform(
+ wp.vec3(3.0, 0.0, 0.0),
+ wp.quat_identity(),
+ )
+ far_box.half_extents = wp.vec3(0.5, 0.5, 0.5)
+ boxes = wp.array(
+ [near_box, far_box],
+ dtype=InteractionBox,
+ device="cpu",
+ )
+ results = wp.empty(3, dtype=wp.int32, device="cpu")
+ for character_box, expected in (
+ (_interaction_box_array((0.0, 0.0, 0.0)), [1, 0]),
+ (_interaction_box_array((1.0, 0.0, 0.0)), [1, 0]), # Face contact.
+ (_interaction_box_array((2.0, 0.0, 0.0)), [0, 1]),
+ (_interaction_box_array((5.0, 0.0, 0.0)), [0, 0]),
+ (_interaction_box_array(
+ (0.0, 0.0, 0.0), half_extents=(0.75, 0.25, 0.5),
+ rotation=wp.quat_rpy(0.0, 0.0, 0.25 * wp.pi),
+ ), [1, 0]),
+ ):
+ compute_interaction_box_overlaps(boxes, character_box, results)
+ np.testing.assert_array_equal(results.numpy()[:2], expected)
+ with self.assertRaisesRegex(ValueError, "at least 2 results"):
+ compute_interaction_box_overlaps(
+ boxes,
+ character_box,
+ wp.empty(1, dtype=wp.int32, device="cpu"),
+ )
+
+ def test_interaction_box_overlap_is_exact_for_parallel_boxes_on_every_device(self) -> None:
+ # Walking along an axis keeps the probe box parallel to an overhead box.
+ overhead = InteractionBox()
+ overhead.transform = wp.transform(
+ wp.vec3(3.1405947, 12.562379, 1.5375934), wp.quat(0.0, 0.0, -0.70710677, 0.70710677),
+ )
+ overhead.half_extents = wp.vec3(0.19628717, 0.19628717, 0.39257434)
+ for device in wp.get_devices():
+ for half_height, expected in ((0.63, 1), (0.55, 0)):
+ with self.subTest(device=str(device), half_height=half_height):
+ probe = InteractionBox()
+ probe.transform = wp.transform(
+ wp.vec3(3.0434444, 12.853794, half_height), wp.quat(0.0, 0.0, -0.7071068, 0.70710677),
+ )
+ probe.half_extents = wp.vec3(0.395, 0.5872061, half_height)
+ results = wp.empty(1, dtype=wp.int32, device=device)
+ compute_interaction_box_overlaps(
+ wp.array([overhead], dtype=InteractionBox, device=device),
+ wp.array([probe], dtype=InteractionBox, device=device),
+ results,
+ )
+ self.assertEqual(results.numpy()[0], expected)
+
+ def test_scene_preview_checks_a_scene_before_building_its_engine(self) -> None:
+ camera = {
+ "pos": [1, 2, 3], "pivot": [0, 0, 0], "pitch": -20, "yaw": 45,
+ "fov": 45, "near": 0.01, "far": 1000,
+ }
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ authoring = SmartPrimitiveDocument(
+ ModelRig.SOMA, wp.array([wp.transform_identity()], dtype=wp.transform), wp.transform_identity(),
+ )
+ reference = save_smart_primitive_document(authoring, root / "soma", authoring.root.id, camera)
+ preview = ScenePreview.__new__(ScenePreview)
+ current = object()
+ preview._scene_session = current
+ preview._rig_for = Mock()
+ for reference_path, behavior, message in (
+ (
+ reference, "SittingBehavior",
+ "soma.smart_primitive.json was saved for the 'soma' rig, but this scene uses 'unitree_g1'",
+ ),
+ (reference, "unknown", "uses unknown behavior 'unknown'"),
+ (None, "SittingBehavior", "has no reference"),
+ ):
+ with self.subTest(message=message):
+ scene = SceneDefinition(rig=ModelRig.UNITREE_G1)
+ instance = scene.add_smart_primitive()
+ instance.reference, instance.behavior = reference_path, behavior
+ preview._pending_scene_path = save_scene_document(scene, root / "scene", 1, camera)
+ preview.scene_error = None
+ preview._load_pending_scene()
+ self.assertIn(message, preview.scene_error)
+ self.assertIs(preview._scene_session, current)
+ preview._rig_for.assert_not_called()
+
+ def test_scene_preview_draws_target_poses_in_the_instance_color(self) -> None:
+ data, *_ = self._build_data()
+ definition = SmartPrimitiveInstance(id=1, name="Primitive", target_pose_color=wp.vec3(0.2, 0.55, 1.0))
+ instance = _RuntimeSceneSmartPrimitive(
+ definition, SmartPrimitive(SmartPrimitiveAsset(data, device="cpu")), 0,
+ self.skeleton.reference_local_transforms, Mock(), None,
+ )
+ np.testing.assert_array_equal(instance.target_pose_colors.numpy(), [list(definition.target_pose_color)])
+
+ def test_scene_preview_interacts_with_the_nearest_overlapping_primitive(self) -> None:
+ data, *_ = self._build_data()
+ instances = tuple(
+ _RuntimeSceneSmartPrimitive(
+ SmartPrimitiveInstance(
+ id=index + 1,
+ name=f"Primitive {index}",
+ transform=wp.transform(wp.vec3(x, 0.0, 0.0), wp.quat_identity()),
+ ),
+ SmartPrimitive(SmartPrimitiveAsset(data, device="cpu")),
+ index,
+ self.skeleton.reference_local_transforms,
+ Mock(),
+ None,
+ )
+ for index, x in enumerate((0.0, 1.0, 10.0))
+ )
+ character = SimpleNamespace(
+ engine=SimpleNamespace(stream=None),
+ # The probe touches the first two interaction boxes but not the third.
+ probe_box=_interaction_box_array((4.5, 5.0, 0.0)),
+ character_ground_position=np.array([9.0, 0.0, 0.0], dtype=np.float32),
+ )
+ preview = ScenePreview.__new__(ScenePreview)
+ preview._active_interaction = None
+ preview._scene_session = SimpleNamespace(
+ character=character,
+ smart_primitives=instances,
+ interaction_boxes=wp.empty(3, dtype=InteractionBox),
+ interaction_overlap_results=wp.empty(3, dtype=wp.int32),
+ interaction_box_count=3,
+ )
+
+ # The third root is the closest, but only primitives whose boxes overlap the probe count.
+ preview._update_smart_primitive_interaction()
+ self.assertEqual([instance.interactable for instance in instances], [True, True, False])
+ self.assertIs(preview._nearest_interactable, instances[1])
+ character.character_ground_position = np.array([-1.0, 0.0, 0.0], dtype=np.float32)
+ preview._update_smart_primitive_interaction()
+ self.assertIs(preview._nearest_interactable, instances[0])
+
+ def test_prepared_pivot_rules_keep_limits_fixed(self) -> None:
+ authoring, approach, _, contact, _ = self._build_authoring()
+ approach.name = "Rail"
+ authoring.root.local_xform = approach.local_xform = wp.transform_identity()
+ rules = authoring.add_pivot(approach).pivot
+ rules.translation_axis = Axis.X
+ rules.translation_constraint = ConstraintType.LINE_PROJECTION
+ rules.line_min_offset, rules.line_max_offset = -1.0, 1.0
+ rules.rotation_axis = Axis.Z
+ rules.rotation_constraint = ConstraintType.CONE
+ rules.cone_side = ConeSide.BOTH
+ authoring.set_sequence_pivot(authoring.sequences[0], approach)
+ authoring.add_sequence_node(authoring.add_sequence(), contact) # No new alignment.
+
+ primitive = SmartPrimitive(SmartPrimitiveAsset(build_runtime_smart_primitive_data(authoring), device="cpu"))
+ node = primitive.sequence_pivot_node_index(0)
+ self.assertEqual(node, primitive.node_index("Rail"))
+ self.assertNotEqual(node, approach.id)
+ self.assertEqual(primitive.pivot_node_indices, (node,))
+ self.assertEqual(primitive.sequence_pivot_node_index(1), -1)
+ self.assertEqual(primitive.pivot(node), rules)
+ self.assertIsNot(primitive.pivot(node), rules)
+
+ properties = CharacterProperties(
+ position=np.zeros(3), velocity=np.zeros(3), facing=np.array([1, 0, 0]),
+ desired_velocity=np.array([0, 1, 0]),
+ probe_segment=(np.zeros(3), np.zeros(3)),
+ )
+ transforms = wp.empty(primitive.node_count, dtype=wp.transform, device="cpu")
+ for x, expected in ((0.75, 0.75), (-4.0, -1.0), (4.0, 1.0)):
+ properties.position[:] = (x, -3.0, 0.0)
+ properties.probe_segment[0][:] = (x, -2.85, 0.0)
+ properties.probe_segment[1][:] = (x, -2.0, 0.0)
+ primitive.align_sequence_pivot(0, properties)
+ primitive.compute_world_transforms(transforms)
+ np.testing.assert_allclose(transforms.numpy()[node, :3], [expected, 0, 0], atol=1e-6)
+
+ properties.desired_velocity[:] = (1, 0, 0)
+ primitive.align_sequence_pivot(0, properties)
+ primitive.compute_world_transforms(transforms)
+ aligned = transforms.numpy()[node].copy()
+ np.testing.assert_allclose(
+ wp.quat_rotate(wp.quat(*aligned[3:]), wp.vec3(0, 1, 0)),
+ [np.sqrt(0.5), np.sqrt(0.5), 0.0], atol=1e-6,
+ )
+ properties.desired_velocity[:] = (-1, 0, 0)
+ primitive.align_sequence_pivot(1, properties)
+ primitive.compute_world_transforms(transforms)
+ np.testing.assert_array_equal(transforms.numpy()[node], aligned)
+
+ def test_preparation_rejects_duplicate_names_and_targets_without_clips(self) -> None:
+ authoring, approach, _, contact, _ = self._build_authoring()
+ contact.name = approach.name
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ "must be unique",
+ ):
+ build_runtime_smart_primitive_data(authoring)
+
+ empty_authoring = SmartPrimitiveDocument(
+ authoring.rig,
+ authoring.reference_pose,
+ authoring.model_to_runtime,
+ )
+ node = empty_authoring.add_node()
+ empty_authoring.add_target_pose(node)
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ "has no clip",
+ ):
+ build_runtime_smart_primitive_data(empty_authoring)
+
+ sequence_authoring = SmartPrimitiveDocument(
+ authoring.rig,
+ authoring.reference_pose,
+ authoring.model_to_runtime,
+ )
+ sequence_authoring.add_sequence()
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ "must contain at least one Target Pose",
+ ):
+ build_runtime_smart_primitive_data(sequence_authoring)
+
+ def test_empty_primitive_keeps_its_pose_size_and_writes_no_boxes(self) -> None:
+ authoring, _, _, _, _ = self._build_authoring()
+ empty = SmartPrimitiveDocument(
+ authoring.rig,
+ authoring.reference_pose,
+ authoring.model_to_runtime,
+ )
+ data = build_runtime_smart_primitive_data(empty)
+ runtime = SmartPrimitive(SmartPrimitiveAsset(data, device="cpu"))
+
+ self.assertEqual(runtime.pose_size, self.skeleton.num_joints)
+ runtime.get_world_interaction_boxes(
+ wp.empty(0, dtype=InteractionBox, device="cpu")
+ )
+
+ def test_asset_pool_rejects_invalid_pivot_rules(self) -> None:
+ authoring, *_ = self._build_authoring()
+ pivot_only = SmartPrimitiveDocument(authoring.rig, authoring.reference_pose, authoring.model_to_runtime)
+ pivot_only.add_pivot(pivot_only.root)
+ camera = {
+ "pos": [1, 2, 3], "pivot": [0, 0, 0], "pitch": -20, "yaw": 45,
+ "fov": 45, "near": 0.01, "far": 1000,
+ }
+ pool = SmartPrimitiveAssetPool(
+ ClipRegistry(ModelRig.SOMA, skeleton=self.skeleton), authoring.reference_pose, authoring.model_to_runtime,
+ )
+ with tempfile.TemporaryDirectory() as directory:
+ path = save_smart_primitive_document(pivot_only, Path(directory) / "pivot", pivot_only.root.id, camera)
+ original = path.read_text("utf-8")
+ for field, value, message in (
+ ("motion_direction", [0, 0, 0], "non-zero"),
+ ("operation_order", "bad", "valid OperationOrder"),
+ ("translation_axis", "bad", "valid Axis"),
+ ("line_min_offset", 2.0, "Min Offset <= Max Offset"),
+ ("cone_half_angle_degrees", 181, "between 0 and 180"),
+ ):
+ with self.subTest(field=field):
+ document = json.loads(original)
+ document["root"]["components"][0][field] = value
+ path.write_text(json.dumps(document), encoding="utf-8")
+ with self.assertRaisesRegex(SmartPrimitiveDocumentError, message):
+ pool.load(path)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_scene.py b/tests/app/test_scene.py
new file mode 100644
index 0000000..5b627dc
--- /dev/null
+++ b/tests/app/test_scene.py
@@ -0,0 +1,356 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.io.document_io import DocumentError
+from app.runtime.common.io.scene_document import (
+ SCENE_DOCUMENT,
+ CharacterStart,
+ SceneDefinition,
+ SceneDocumentError,
+ check_reference_rigs,
+ load_scene_document,
+ save_scene_document,
+)
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveDocument, save_smart_primitive_document
+from motionbricks.model.contract import ModelRig
+
+
+def _camera_state() -> dict:
+ return {
+ "pos": [1.0, 2.0, 3.0],
+ "pivot": [4.0, 5.0, 6.0],
+ "pitch": -20.0,
+ "yaw": 45.0,
+ "fov": 60.0,
+ "near": 0.01,
+ "far": 1000.0,
+ }
+
+
+def _transform_values(transform: wp.transform) -> np.ndarray:
+ return np.asarray([float(transform[index]) for index in range(7)])
+
+
+def _turn(angle: float) -> wp.quat:
+ return wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), angle)
+
+
+def _assert_same_placement(test, actual: wp.transform, expected: wp.transform) -> None:
+ actual, expected = _transform_values(actual), _transform_values(expected)
+ np.testing.assert_allclose(actual[:3], expected[:3], atol=1.0e-5)
+ test.assertGreater(abs(float(np.dot(actual[3:], expected[3:]))), 1.0 - 1.0e-6)
+
+
+class SceneHierarchyTests(unittest.TestCase):
+ def test_parenting_keeps_placements_and_branches_follow_their_parent(self) -> None:
+ scene = SceneDefinition()
+ jump, platform, step = scene.add_smart_primitive(), scene.add_solid_cube(), scene.add_solid_cube()
+ jump.transform = wp.transform(wp.vec3(2.0, 0.0, 0.0), _turn(0.5 * wp.pi))
+ platform.transform = wp.transform(wp.vec3(3.0, 1.0, 0.5), _turn(0.3))
+ step.transform = wp.transform(wp.vec3(3.0, 2.0, 0.25), wp.quat_identity())
+ before = {item.id: scene.world_transform(item) for item in (jump, platform, step)}
+
+ self.assertTrue(scene.set_parent(platform, jump.id))
+ self.assertTrue(scene.set_parent(step, platform.id))
+ for item in (jump, platform, step):
+ _assert_same_placement(self, scene.world_transform(item), before[item.id])
+ np.testing.assert_allclose(_transform_values(platform.transform)[:3], [1.0, -1.0, 0.5], atol=1.0e-6)
+ self.assertEqual([item.id for item in scene.children(None)], [jump.id])
+ self.assertEqual([item.id for item in scene.subtree(jump)], [jump.id, platform.id, step.id])
+
+ # Moving and turning the root carries the whole branch through both levels.
+ jump.transform = wp.transform(wp.vec3(5.0, 0.0, 0.0), wp.quat_identity())
+ _assert_same_placement(
+ self, scene.world_transform(platform), wp.transform(wp.vec3(6.0, -1.0, 0.5), _turn(0.3 - 0.5 * wp.pi)),
+ )
+ _assert_same_placement(
+ self, scene.world_transform(step), wp.transform(wp.vec3(7.0, -1.0, 0.25), _turn(-0.5 * wp.pi)),
+ )
+
+ start = scene.character_start
+ for item, parent_id in (
+ (jump, step.id), (platform, platform.id), (start, jump.id),
+ (platform, start.id), (platform, 999), (platform, jump.id),
+ ):
+ with self.subTest(item=item.id, parent_id=parent_id):
+ self.assertFalse(scene.set_parent(item, parent_id))
+
+ world = scene.world_transform(step)
+ self.assertTrue(scene.set_parent(step, None))
+ self.assertIsNone(step.parent_id)
+ _assert_same_placement(self, step.transform, world)
+
+ def test_removing_an_item_removes_everything_under_it(self) -> None:
+ scene = SceneDefinition()
+ jump, other = scene.add_smart_primitive(), scene.add_smart_primitive()
+ platform, step = scene.add_solid_cube(), scene.add_solid_cube()
+ self.assertEqual(len({item.id for item in (scene.character_start, jump, other, platform, step)}), 5)
+ scene.set_parent(platform, jump.id)
+ scene.set_parent(step, platform.id)
+
+ self.assertEqual(scene.remove_item(scene.character_start.id), [])
+ self.assertEqual(scene.remove_item(jump.id), [jump.id, platform.id, step.id])
+ self.assertEqual(scene.smart_primitives, [other])
+ self.assertEqual(scene.solid_cubes, [])
+
+ def test_hierarchy_round_trips_and_flattens_into_world_transforms(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ scene = SceneDefinition()
+ jump, platform = scene.add_smart_primitive(), scene.add_solid_cube()
+ jump.transform = wp.transform(wp.vec3(2.0, 0.0, 0.0), _turn(0.5 * wp.pi))
+ platform.transform = wp.transform(wp.vec3(3.0, 1.0, 0.5), wp.quat_identity())
+ scene.set_parent(platform, jump.id)
+ path = save_scene_document(scene, Path(directory) / "nested", platform.id, _camera_state())
+
+ loaded, _, _ = load_scene_document(path)
+ loaded_platform = loaded.find_item(platform.id)
+ self.assertEqual(loaded_platform.parent_id, jump.id)
+ self.assertEqual([item.id for item in loaded.children(None)], [jump.id])
+ np.testing.assert_allclose(
+ _transform_values(loaded_platform.transform), _transform_values(platform.transform), atol=1.0e-6,
+ )
+ flat = loaded.flatten()
+ self.assertTrue(all(item.parent_id is None for item in (*flat.smart_primitives, *flat.solid_cubes)))
+ _assert_same_placement(self, flat.find_item(platform.id).transform, loaded.world_transform(loaded_platform))
+ self.assertEqual(loaded_platform.parent_id, jump.id)
+
+
+class SceneDocumentTests(unittest.TestCase):
+ def test_path_normalization_uses_scene_json_suffix(self) -> None:
+ for path in ("demo", "demo.json", "demo.scene"):
+ self.assertEqual(SCENE_DOCUMENT.normalize_path(path), Path("demo.scene.json"))
+
+ def test_round_trip_preserves_scene_and_editor_state(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ reference = root / "jump.smart_primitive.json"
+ reference.touch()
+ scene = SceneDefinition(
+ rig=ModelRig.UNITREE_G1,
+ character_start=CharacterStart(
+ transform=wp.transform(
+ wp.vec3(1.0, 2.0, 3.0),
+ wp.quat_rpy(0.1, 0.2, 0.3),
+ ),
+ euler_degrees=[5.0, 10.0, 15.0],
+ )
+ )
+ instance = scene.add_smart_primitive()
+ instance.name = "Jump"
+ instance.transform = wp.transform(
+ wp.vec3(5.0, 6.0, 0.0),
+ wp.quat_rpy(0.0, 0.0, 1.0),
+ )
+ instance.euler_degrees = [0.0, 0.0, 57.2958]
+ instance.reference = reference
+ instance.show_target_poses = False
+ instance.show_interaction_boxes = True
+ instance.target_pose_color = wp.vec3(0.2, 0.6, 0.9)
+ instance.behavior = "VelocityMatchingSequenceBehavior"
+ unassigned = scene.add_smart_primitive()
+ cube = scene.add_solid_cube()
+ cube.name = "Platform"
+ cube.transform = wp.transform(
+ wp.vec3(-2.0, 3.0, 1.0),
+ wp.quat_rpy(0.1, 0.0, -0.2),
+ )
+ cube.euler_degrees = [5.72958, 0.0, -11.45916]
+ cube.width = 4.0
+ cube.depth = 2.0
+ cube.height = 0.5
+ cube.color = wp.vec3(0.2, 0.4, 0.8)
+
+ document_path = save_scene_document(
+ scene,
+ root / "demo",
+ cube.id,
+ _camera_state(),
+ )
+ loaded, selected_item_id, camera = load_scene_document(document_path)
+
+ self.assertEqual(document_path.name, "demo.scene.json")
+ self.assertEqual(json.loads(document_path.read_text("utf-8"))["rig"], "unitree_g1")
+ self.assertIs(loaded.rig, ModelRig.UNITREE_G1)
+ self.assertEqual(selected_item_id, cube.id)
+ self.assertEqual(camera, _camera_state())
+ np.testing.assert_allclose(
+ _transform_values(loaded.character_start.transform),
+ _transform_values(scene.character_start.transform),
+ )
+ self.assertEqual(len(loaded.smart_primitives), 2)
+ self.assertIsNone(loaded.find_item(unassigned.id).reference)
+ loaded_instance = loaded.smart_primitives[0]
+ self.assertEqual(loaded_instance.name, "Jump")
+ self.assertEqual(loaded_instance.reference, reference.resolve())
+ self.assertFalse(loaded_instance.show_target_poses)
+ self.assertTrue(loaded_instance.show_interaction_boxes)
+ self.assertEqual(loaded_instance.target_pose_color, instance.target_pose_color)
+ self.assertEqual(
+ loaded_instance.behavior,
+ "VelocityMatchingSequenceBehavior",
+ )
+ np.testing.assert_allclose(
+ _transform_values(loaded_instance.transform),
+ _transform_values(instance.transform),
+ )
+ self.assertEqual(len(loaded.solid_cubes), 1)
+ loaded_cube = loaded.solid_cubes[0]
+ self.assertEqual(loaded_cube.name, "Platform")
+ self.assertEqual(
+ (loaded_cube.width, loaded_cube.depth, loaded_cube.height),
+ (4.0, 2.0, 0.5),
+ )
+ self.assertEqual(loaded_cube.color, cube.color)
+ np.testing.assert_allclose(
+ _transform_values(loaded_cube.transform),
+ _transform_values(cube.transform),
+ )
+
+ document = json.loads(document_path.read_text("utf-8"))
+ document["editor"]["selected_item_id"] = 9999
+ renamed_path = root / "renamed.scene.json"
+ renamed_path.write_text(json.dumps(document), encoding="utf-8")
+ renamed, selected_item_id, _ = load_scene_document(renamed_path)
+ self.assertEqual(selected_item_id, renamed.character_start.id)
+ self.assertEqual(renamed.smart_primitives[0].reference, reference.resolve())
+ self.assertEqual(renamed.solid_cubes[0].name, cube.name)
+
+ def test_every_reference_must_use_the_scene_rig(self) -> None:
+ with tempfile.TemporaryDirectory() as directory, wp.ScopedDevice("cpu"):
+ root = Path(directory)
+ references = {}
+ for rig, reference_pose in (
+ (ModelRig.SOMA, wp.array([wp.transform_identity()], dtype=wp.transform)),
+ (ModelRig.UNITREE_G1, wp.array([0, 0, 0, 0, 0, 0, 1, 0], dtype=wp.float32)),
+ ):
+ document = SmartPrimitiveDocument(rig, reference_pose, wp.transform_identity())
+ references[rig] = save_smart_primitive_document(
+ document, root / rig, document.root.id, _camera_state(),
+ )
+ scene = SceneDefinition(rig=ModelRig.UNITREE_G1)
+ scene.add_smart_primitive()
+ scene.add_smart_primitive().reference = references[ModelRig.UNITREE_G1]
+ check_reference_rigs(scene)
+
+ scene.add_smart_primitive().reference = references[ModelRig.SOMA]
+ with self.assertRaisesRegex(
+ SceneDocumentError,
+ r"soma\.smart_primitive\.json was saved for the 'soma' rig, but this scene uses 'unitree_g1'",
+ ):
+ check_reference_rigs(scene)
+
+ def test_scene_rejects_non_smart_primitive_references(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ scene = SceneDefinition()
+ reference = root / "unrelated.json"
+ reference.touch()
+ scene.add_smart_primitive().reference = reference
+ with self.assertRaisesRegex(SceneDocumentError, "must reference"):
+ save_scene_document(scene, root / "invalid", 1, _camera_state())
+
+ def test_references_are_relative_so_moved_folders_still_load(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ original = Path(directory) / "original"
+ reference = original / "smart_primitives" / "asset.smart_primitive.json"
+ reference.parent.mkdir(parents=True)
+ reference.touch()
+ scene = SceneDefinition()
+ instance = scene.add_smart_primitive()
+ instance.reference = reference
+ document_path = save_scene_document(
+ scene, original / "scenes" / "relative", instance.id, _camera_state(),
+ )
+ document = json.loads(document_path.read_text(encoding="utf-8"))
+ self.assertEqual(
+ document["smart_primitives"][0]["reference"],
+ "../smart_primitives/asset.smart_primitive.json",
+ )
+
+ moved = original.rename(Path(directory) / "moved")
+ loaded, _, _ = load_scene_document(moved / "scenes" / document_path.name)
+ self.assertEqual(
+ loaded.smart_primitives[0].reference,
+ (moved / "smart_primitives" / reference.name).resolve(),
+ )
+
+ def test_loader_and_saver_reject_invalid_documents(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ reference = root / "asset.smart_primitive.json"
+ reference.touch()
+ scene = SceneDefinition()
+ instance = scene.add_smart_primitive()
+ first, second = scene.add_solid_cube(), scene.add_solid_cube()
+ scene.set_parent(second, first.id)
+ path = save_scene_document(scene, root / "invalid", instance.id, _camera_state())
+ original = path.read_text(encoding="utf-8")
+
+ # A reference on another Windows drive is saved as an absolute path.
+ document = json.loads(original)
+ document["smart_primitives"][0]["reference"] = reference.resolve().as_posix()
+ path.write_text(json.dumps(document), encoding="utf-8")
+ loaded, _, _ = load_scene_document(path)
+ self.assertEqual(loaded.smart_primitives[0].reference, reference.resolve())
+
+ for location, value, message in (
+ (("rig",), "robot", "invalid.scene.json uses unknown rig 'robot'"),
+ (("unexpected",), True, "unexpected"),
+ (("editor", "camera", "far"), 0.001, "camera.far"),
+ (("character_start", "transform", "rotation_xyzw"), [0, 0, 0, 2], "non-unit quaternion"),
+ (("smart_primitives", 0, "target_pose_color"), [0, 0, 1.1], "target_pose_color"),
+ (("smart_primitives", 0, "reference"), "", "reference must be a non-empty string"),
+ (("smart_primitives", 0, "reference"), " ", "reference must be a non-empty string"),
+ (
+ ("smart_primitives", 0, "reference"), "missing.smart_primitive.json",
+ "Could not find the Smart Primitive",
+ ),
+ (("solid_cubes", 0, "parent_id"), 999, "as its parent"),
+ (("solid_cubes", 0, "parent_id"), scene.character_start.id, "as its parent"),
+ (("solid_cubes", 0, "parent_id"), first.id, "under itself"),
+ (("solid_cubes", 0, "parent_id"), second.id, "under itself"),
+ ):
+ with self.subTest(location=location, value=value):
+ document = json.loads(original)
+ *keys, field = location
+ container = document
+ for key in keys:
+ container = container[key]
+ container[field] = value
+ path.write_text(json.dumps(document), encoding="utf-8")
+ with self.assertRaisesRegex(DocumentError, message):
+ load_scene_document(path)
+
+ first.parent_id = second.id
+ with self.assertRaisesRegex(SceneDocumentError, "under itself"):
+ save_scene_document(scene, path, 1, _camera_state())
+
+ def test_save_rejects_items_the_loader_would_refuse(self) -> None:
+ with tempfile.TemporaryDirectory() as directory:
+ for add_item, field, value, message in (
+ (SceneDefinition.add_solid_cube, "height", 0.0, "height must be greater than zero"),
+ (SceneDefinition.add_solid_cube, "name", "", "name cannot be empty"),
+ (SceneDefinition.add_smart_primitive, "name", " ", "name cannot be empty"),
+ ):
+ with self.subTest(field=field, value=value):
+ scene = SceneDefinition()
+ item = add_item(scene)
+ saved = save_scene_document(scene, Path(directory) / "scene", item.id, _camera_state())
+ original = saved.read_bytes()
+ setattr(item, field, value)
+ with self.assertRaisesRegex(SceneDocumentError, message):
+ save_scene_document(scene, saved, item.id, _camera_state())
+ # A refused save leaves the existing file as it was.
+ self.assertEqual(saved.read_bytes(), original)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_scene_editor.py b/tests/app/test_scene_editor.py
new file mode 100644
index 0000000..b9022f7
--- /dev/null
+++ b/tests/app/test_scene_editor.py
@@ -0,0 +1,235 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+import unittest
+from unittest.mock import patch
+
+import newton
+import numpy as np
+import warp as wp
+
+from app.authoring.common import InlineRename
+from app.runtime.common.clip_registry import ClipRegistry
+from app.runtime.common.io.scene_document import SceneDefinition, load_scene_document, save_scene_document
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveDocument, save_smart_primitive_document
+from app.scene_editor import SceneEditor, _CharacterStartRenderer
+from motionbricks.animation.mesh import SkeletalMesh, SkinnedMesh
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.csv import save_csv
+from motionbricks.model.contract import ModelRig
+from motionbricks.renderers.dof_mesh_renderer import DOFMeshRenderer
+from motionbricks.renderers.skeletal_mesh_renderer import SkeletalMeshRenderer
+from motionbricks.renderers.solid_box_renderer import SolidBoxRenderer
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+
+_CAMERA = {"pos": [0, -3, 2], "pivot": [0, 0, 1], "pitch": -15, "yaw": 90,
+ "fov": 45, "near": 0.01, "far": 100}
+
+
+class SceneEditorRigTests(unittest.TestCase):
+ def setUp(self):
+ self.enterContext(wp.ScopedDevice("cpu"))
+ self.folder = Path(self.enterContext(TemporaryDirectory()))
+ skeleton = Skeleton(["Hips"], [-1], [wp.transform_identity()])
+ mesh = SkinnedMesh(
+ np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]], dtype=np.float32),
+ np.array([0, 1, 2], dtype=np.int32),
+ np.zeros(3, dtype=np.int32), np.ones(3, dtype=np.float32),
+ )
+ # Like the SOMA mesh, it has the relaxed-hands override pose and finger mask.
+ soma = SkeletalMesh(
+ [mesh], skeleton, [wp.transform_identity()],
+ override_poses={"RelaxedHands": wp.clone(skeleton.reference_local_transforms)},
+ override_pose_masks={"Fingers": wp.zeros(1, dtype=wp.float32)},
+ )
+ builder = newton.ModelBuilder()
+ root = builder.add_link(mass=1.0, inertia=wp.mat33(np.eye(3)))
+ arm = builder.add_link(mass=1.0, inertia=wp.mat33(np.eye(3)))
+ builder.add_articulation([
+ builder.add_joint_free(root),
+ builder.add_joint_revolute(root, arm, axis=wp.vec3(0, 0, 1)),
+ ])
+ builder.add_shape_box(root, hx=0.2, hy=0.2, hz=0.2)
+ self.robot = builder.finalize()
+ self.load_soma = self.enterContext(
+ patch("app.runtime.common.rig.io_utils.get_soma_human_model", return_value=soma),
+ )
+ self.load_g1 = self.enterContext(
+ patch("app.runtime.common.rig.io_utils.get_unitree_g1_model", return_value=self.robot),
+ )
+ self.enterContext(
+ patch("app.runtime.common.rig.UNITREE_G1_N1_CONTRACT", SimpleNamespace(joint_names=("hinge",))),
+ )
+
+ bvh = self.folder / "walk.bvh"
+ bvh.write_text(
+ "HIERARCHY\nROOT Hips\n{\n OFFSET 0 0 0\n"
+ " CHANNELS 6 Xposition Yposition Zposition Xrotation Yrotation Zrotation\n}\n"
+ "MOTION\nFrames: 2\nFrame Time: 0.03333333333333333\n"
+ "0 100 0 0 0 0\n10 100 0 0 0 0\n", encoding="utf-8",
+ )
+ self.soma_path = self._save_primitive(
+ ClipRegistry(ModelRig.SOMA, skeleton=skeleton), skeleton.reference_local_transforms, bvh,
+ )
+ csv = self.folder / "walk.csv"
+ frames = np.tile([0, 0, 1, 0, 0, 0, 1, 0.4], (4, 1)).astype(np.float32)
+ save_csv(csv, DOFAnimationBuffer(("hinge",), 120, wp.array(frames, dtype=wp.float32)))
+ self.g1_path = self._save_primitive(
+ ClipRegistry(ModelRig.UNITREE_G1, joint_names=("hinge",)),
+ self.robot.joint_q, csv,
+ )
+ self.editor = SceneEditor.__new__(SceneEditor)
+ self.editor.device = wp.get_device("cpu")
+ self.editor._rig_assets = None
+ self.editor._asset_pool = None
+ self.editor._runtime_views = {}
+ self.editor.scene = SceneDefinition()
+ self.editor.viewer = SimpleNamespace(objects={}, lines={})
+
+ def _save_primitive(self, registry, reference_pose, clip_path):
+ document = SmartPrimitiveDocument(registry.rig, reference_pose, wp.transform_identity())
+ document.add_target_pose(document.add_node()).set_clip(registry.load(clip_path))
+ return save_smart_primitive_document(document, self.folder / registry.rig, document.root.id, _CAMERA)
+
+ def _save_unknown_rig_primitive(self):
+ path = self.folder / "invalid.smart_primitive.json"
+ document = json.loads(self.g1_path.read_text(encoding="utf-8"))
+ document["rig"] = "robot"
+ path.write_text(json.dumps(document), encoding="utf-8")
+ return path
+
+ def test_children_follow_their_parent_in_previews_picking_and_deletion(self):
+ editor = self.editor
+ editor._gizmo_item_id = editor._gizmo_transform = editor._gizmo_source_transform = None
+ editor._transform_locks = {}
+ editor._rename = InlineRename()
+ editor.solid_box_renderer = SolidBoxRenderer()
+ editor.character_start_renderer = _CharacterStartRenderer()
+ editor.viewer.camera = SimpleNamespace(far=100.0)
+ jump, child = editor.scene.add_smart_primitive(), editor.scene.add_smart_primitive()
+ platform = editor.scene.add_solid_cube()
+ for instance in (jump, child):
+ editor._assign_reference(instance, self.soma_path)
+ editor._set_item_transform(child, wp.transform(wp.vec3(1.0, 0.0, 0.0), wp.quat_identity()))
+ editor._set_item_transform(platform, wp.transform(wp.vec3(0.0, 3.0, 0.5), wp.quat_identity()))
+ editor._set_parent(child.id, jump.id)
+ editor._set_parent(platform.id, jump.id)
+ self.assertEqual(editor.selected_item_id, platform.id)
+
+ editor._set_item_transform(jump, wp.transform(wp.vec3(10.0, 0.0, 0.0), wp.quat_identity()))
+ nodes = wp.empty(editor._runtime_views[child.id].runtime.node_count, dtype=wp.transform)
+ editor._runtime_views[child.id].runtime.compute_world_transforms(nodes)
+ np.testing.assert_allclose(nodes.numpy()[0][:3], [11.0, 0.0, 0.0], atol=1e-6)
+ editor.selected_item_id = editor.scene.character_start.id
+ editor._select_scene_item(wp.vec3(10.0, 3.0, 5.0), wp.vec3(0.0, 0.0, -1.0))
+ self.assertEqual(editor.selected_item_id, platform.id)
+ # Picking in the view opens the tree down to the picked child.
+ self.assertEqual(editor._reveal_item_ids, {platform.id, jump.id})
+
+ editor._delete_item(jump.id)
+ self.assertEqual(editor._runtime_views, {})
+ self.assertEqual((editor.scene.smart_primitives, editor.scene.solid_cubes), ([], []))
+ self.assertEqual(editor.selected_item_id, editor.scene.character_start.id)
+
+ def test_g1_scene_uses_dof_previews_shares_assets_and_never_loads_soma(self):
+ scene = SceneDefinition(rig=ModelRig.UNITREE_G1)
+ for _ in range(2):
+ scene.add_smart_primitive().reference = self.g1_path
+ scene_path = save_scene_document(scene, self.folder / "g1", 1, _CAMERA)
+ loaded, _, _ = load_scene_document(scene_path)
+ views = list(self.editor._create_runtime_views(loaded).values())
+ for view in views:
+ self.assertIsInstance(view.mesh_renderer, DOFMeshRenderer)
+ self.assertEqual(view.target_poses.dtype, wp.float32)
+ self.assertIs(views[0].runtime.asset, views[1].runtime.asset)
+
+ original_pose = self.robot.joint_q.numpy().copy()
+ views[0].set_transform(wp.transform(5, 0, 0, 0, 0, 0, 1))
+ views[0].runtime.get_world_target_poses(1, views[0].target_poses)
+ np.testing.assert_allclose(views[0].target_poses.numpy()[:, :3], [[5, 0, 1]] * 4)
+ np.testing.assert_allclose(views[0].target_poses.numpy()[:, 7], 0.4)
+ self.assertAlmostEqual(views[0].raycast(wp.vec3(5, 0, 3), wp.vec3(0, 0, -1), 100), 1.8, places=5)
+ views[1].runtime.get_world_target_poses(1, views[1].target_poses)
+ np.testing.assert_allclose(views[1].target_poses.numpy()[:, 0], 0)
+ np.testing.assert_array_equal(self.robot.joint_q.numpy(), original_pose)
+
+ reopened = list(self.editor._create_runtime_views(loaded).values())
+ for previous, current in zip(views, reopened):
+ self.assertIs(previous.runtime.asset, current.runtime.asset)
+ self.load_soma.assert_not_called()
+ self.load_g1.assert_called_once_with()
+
+ def test_a_reference_for_another_rig_is_rejected_and_the_previous_view_kept(self):
+ instance = self.editor.scene.add_smart_primitive()
+ self.editor._assign_reference(instance, self.soma_path)
+ self.assertIsNone(self.editor._status)
+ view = self.editor._runtime_views[instance.id]
+ self.assertIsInstance(view.mesh_renderer, SkeletalMeshRenderer)
+ self.assertEqual(view.target_poses.dtype, wp.transform)
+
+ for path, message in (
+ (self.g1_path, "was saved for the 'unitree_g1' rig, but this scene uses 'soma'"),
+ (self._save_unknown_rig_primitive(), "unknown rig 'robot'"),
+ ):
+ with self.subTest(reference=path.name):
+ self.editor._assign_reference(instance, path)
+ self.assertEqual(instance.reference, self.soma_path)
+ self.assertIs(self.editor._runtime_views[instance.id], view)
+ self.assertIn(message, self.editor._status)
+ self.load_g1.assert_not_called()
+
+ def test_the_first_reference_chooses_the_character(self):
+ first = self.editor.scene.add_smart_primitive()
+ second = self.editor.scene.add_smart_primitive()
+ self.editor._assign_reference(first, self._save_unknown_rig_primitive())
+ self.assertIn("unknown rig 'robot'", self.editor._status)
+ self.assertIsNone(first.reference)
+ self.assertIs(self.editor.scene.rig, ModelRig.SOMA)
+
+ self.editor._assign_reference(first, self.g1_path)
+ self.assertIsNone(self.editor._status)
+ self.assertIs(self.editor.scene.rig, ModelRig.UNITREE_G1)
+ self.assertIsInstance(self.editor._runtime_views[first.id].mesh_renderer, DOFMeshRenderer)
+
+ self.editor._assign_reference(second, self.soma_path)
+ self.assertIn("was saved for the 'soma' rig, but this scene uses 'unitree_g1'", self.editor._status)
+ self.assertIsNone(second.reference)
+ self.assertNotIn(second.id, self.editor._runtime_views)
+ self.assertIs(self.editor.scene.rig, ModelRig.UNITREE_G1)
+ self.load_soma.assert_not_called()
+
+ def test_loading_a_scene_with_another_rigs_reference_keeps_the_current_scene(self):
+ scene = SceneDefinition(rig=ModelRig.UNITREE_G1)
+ scene.add_smart_primitive().reference = self.g1_path
+ scene.add_smart_primitive().reference = self.soma_path
+ scene_path = save_scene_document(scene, self.folder / "mixed", 1, _CAMERA)
+ current = self.editor.scene
+
+ self.editor._open_document(scene_path)
+
+ self.assertIs(self.editor.scene, current)
+ self.assertIn(
+ "soma.smart_primitive.json was saved for the 'soma' rig, but this scene uses 'unitree_g1'",
+ self.editor._status,
+ )
+ self.load_soma.assert_not_called()
+ self.load_g1.assert_not_called()
+
+ def test_opening_a_file_without_the_scene_suffix_keeps_the_current_scene(self):
+ saved = save_scene_document(SceneDefinition(), self.folder / "renamed", 1, _CAMERA)
+ renamed = saved.rename(saved.with_name("renamed.json"))
+ current = self.editor.scene
+
+ self.editor._open_document(renamed)
+
+ self.assertIs(self.editor.scene, current)
+ self.assertIn("Scene documents must end in .scene.json", self.editor._status)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_smart_primitive_editor.py b/tests/app/test_smart_primitive_editor.py
new file mode 100644
index 0000000..ee6ae1d
--- /dev/null
+++ b/tests/app/test_smart_primitive_editor.py
@@ -0,0 +1,1409 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, call, patch
+
+import newton
+import numpy as np
+import warp as wp
+from imgui_bundle import imgui
+
+from app.authoring.common import InlineRename, draw_clip_scrubber
+from app.runtime.common.clip_registry import ClipAsset, ClipRegistry
+from app.runtime.common.io.document_io import DocumentError
+from app.runtime.common.io.smart_primitive_document import (
+ SmartPrimitiveAssetPool,
+ InteractionBoxComponent,
+ PivotComponent,
+ PlaybackMode,
+ SmartPrimitiveDocument,
+ SmartPrimitiveDocumentError,
+ TargetPoseComponent,
+ load_smart_primitive_document,
+ load_smart_primitive_rig,
+ save_smart_primitive_document,
+)
+from app.smart_primitive_editor import (
+ _PIVOT_ARROW_LIFT,
+ SmartPrimitiveEditor,
+ _HipsTrajectoryRenderer,
+ _IKPinRenderer,
+ _InteractionBoxRenderer,
+ _PivotRenderer,
+ _Rig,
+)
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.mesh import SkeletalMesh, SkinnedMesh
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.csv import save_csv
+from motionbricks.model.contract import ModelRig
+from motionbricks.renderers.skeletal_mesh_renderer import SkeletalMeshRenderer
+from motionbricks.renderers.vector_arrow_renderer import VectorArrowRenderer
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+from motionbricks.runtime.pivot import Axis, ConeSide, ConstraintType, OperationOrder
+from motionbricks.runtime.target_pose import IKPin, IK_PINS
+
+
+# BVH clips store height along Y.
+_BVH_UP_INDEX = 1
+
+
+def _hips_pose(x: float) -> np.ndarray:
+ return np.array(
+ [[x, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]],
+ dtype=np.float32,
+ )
+
+
+def _camera_state() -> dict:
+ return {
+ "pos": [1.0, 2.0, 3.0],
+ "pivot": [4.0, 5.0, 6.0],
+ "pitch": 7.0,
+ "yaw": 8.0,
+ "fov": 45.0,
+ "near": 0.01,
+ "far": 1000.0,
+ }
+
+
+class _ArrowViewer:
+ def __init__(self) -> None:
+ self.starts = None
+ self.ends = None
+ self.lines = {}
+
+ def log_arrows(self, name, starts, ends, colors, hidden=False) -> None:
+ self.starts = starts.numpy().copy()
+ self.ends = ends.numpy().copy()
+
+ def log_lines(self, name, starts, ends, colors, hidden=False) -> None:
+ self.lines[name] = (starts.numpy().copy(), ends.numpy().copy())
+
+
+class _MeshViewer:
+ def __init__(self) -> None:
+ self.points = {}
+
+ def log_mesh(self, name, points, indices, **options) -> None:
+ self.points[name] = points.numpy().copy()
+
+
+class _ShapeViewer:
+ def __init__(self) -> None:
+ self.shapes = {}
+
+ def log_shapes(
+ self,
+ name,
+ geo_type,
+ geo_scale,
+ xforms,
+ colors=None,
+ materials=None,
+ geo_thickness=0.0,
+ geo_is_solid=True,
+ geo_src=None,
+ hidden=False,
+ ) -> None:
+ self.shapes[name] = (geo_type, xforms.numpy().copy(), geo_is_solid)
+
+
+class _EmptyClipRegistry:
+ rig = ModelRig.SOMA
+
+
+class _TitleRenderer:
+ def set_title(self, title: str) -> None:
+ pass
+
+
+class _CameraVector(tuple):
+ def __new__(cls, x: float, y: float, z: float):
+ return super().__new__(cls, (x, y, z))
+
+
+class _Camera:
+ def __init__(self, state: dict) -> None:
+ self.pos = _CameraVector(*state["pos"])
+ self.pivot = _CameraVector(*state["pivot"])
+ self.pitch = state["pitch"]
+ self.yaw = state["yaw"]
+ self.fov = state["fov"]
+ self.near = state["near"]
+ self.far = state["far"]
+
+
+class _TitleViewer:
+ def __init__(self) -> None:
+ self.renderer = _TitleRenderer()
+ self.camera = _Camera(_camera_state())
+
+
+class _ClearableRenderers:
+ def __init__(self) -> None:
+ self.clear_count = 0
+
+ def clear(self, viewer) -> None:
+ self.clear_count += 1
+
+
+def _create_imgui_context():
+ """Create an ImGui context that draws editor windows without a display."""
+ context = imgui.create_context()
+ io = imgui.get_io()
+ io.set_ini_filename("")
+ io.display_size = (1000.0, 700.0)
+ io.delta_time = 1.0 / 60.0
+ io.backend_flags |= imgui.BackendFlags_.renderer_has_textures
+ return context
+
+
+def _loading_editor(rig) -> SmartPrimitiveEditor:
+ """An editor without a window, ready to open a document."""
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.viewer = _TitleViewer()
+ editor.interaction_box_renderer = _ClearableRenderers()
+ editor.pivot_renderer = _ClearableRenderers()
+ editor.rig = rig
+ editor.authoring = SmartPrimitiveDocument(rig.clip_registry.rig, rig.reference_pose, rig.model_to_runtime)
+ editor.selected_id = editor.authoring.root.id
+ editor._document_path = None
+ editor._status = object()
+ editor._node_rename = InlineRename()
+ editor._gizmo_item_id = None
+ editor._gizmo_xform = None
+ return editor
+
+
+class _InputIdRecordingUi:
+ def __init__(self, ui) -> None:
+ self._ui = ui
+ self.input_ids = {}
+
+ def __getattr__(self, name):
+ return getattr(self._ui, name)
+
+ def input_float(self, label, *args, **kwargs):
+ result = self._ui.input_float(label, *args, **kwargs)
+ self.input_ids[label] = self._ui.get_item_id()
+ return result
+
+
+class SmartPrimitiveUiIntegrationTests(unittest.TestCase):
+ def test_shared_scrubber_uses_source_frames_and_snaps_only_when_requested(self):
+ clip = SimpleNamespace(num_frames=61, sample_rate=60.0)
+ for animation, initial_time, show_frames, toggle, scrub_value, expected_time, expected_mode in (
+ (clip, 0.126, False, True, None, 8 / 60, True),
+ (clip, 0.126, False, False, None, 0.126, False),
+ (clip, 0.5, True, True, None, 0.5, False),
+ (clip, 0.0, True, False, 30, 0.5, True),
+ (clip, 0.0, False, False, 0.4, 0.4, False),
+ (None, 0.0, True, False, None, 0.0, True),
+ ):
+ with self.subTest(animation=animation, initial_time=initial_time, show_frames=show_frames, toggle=toggle):
+ ui = Mock()
+ ui.button.return_value = toggle
+ ui.slider_int.side_effect = ui.slider_float.side_effect = (
+ lambda _label, value, *_, **__: (
+ scrub_value is not None, value if scrub_value is None else scrub_value,
+ )
+ )
+ changed, sample_time, mode = draw_clip_scrubber(ui, animation, initial_time, show_frames, 1.0)
+ self.assertAlmostEqual(sample_time, expected_time)
+ self.assertEqual(mode, expected_mode)
+ self.assertEqual(changed, expected_time != initial_time)
+
+ def test_target_pose_ik_pins_turn_on_and_off_in_the_mask(self) -> None:
+ component = TargetPoseComponent.__new__(TargetPoseComponent)
+ component.ik_pin_mask = IKPin.NONE
+
+ for pin in IK_PINS:
+ component.set_ik_pin_enabled(pin, True)
+ self.assertEqual(component.ik_pin_mask, IKPin.ALL)
+
+ component.set_ik_pin_enabled(IKPin.RIGHT_HAND, False)
+ self.assertEqual(component.ik_pin_mask, IKPin.ALL & ~IKPin.RIGHT_HAND)
+
+ def test_target_pose_token_range_defaults_and_clamps(self) -> None:
+ component = TargetPoseComponent.__new__(TargetPoseComponent)
+ component.set_token_range(6, 14)
+ for requested, expected in (
+ ((7, 9), (7, 9)), ((2, 20), (6, 16)), ((10, 8), (10, 10)), ((17, 3), (16, 16)),
+ ):
+ with self.subTest(requested=requested):
+ component.set_token_range(*requested)
+ self.assertEqual((component.min_tokens, component.max_tokens), expected)
+
+ def test_transform_fields_have_node_specific_imgui_ids(self) -> None:
+ context = _create_imgui_context()
+ try:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ SimpleNamespace(),
+ wp.transform_identity(),
+ )
+ child = authoring.add_node()
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.authoring = authoring
+ editor.selected_id = authoring.root.id
+ editor._gizmo_item_id = None
+ editor._gizmo_xform = None
+ editor._status = None
+ ui = _InputIdRecordingUi(imgui)
+
+ field_ids = []
+ for selected in (authoring.root, child):
+ editor.selected_id = selected.id
+ ui.input_ids = {}
+ imgui.new_frame()
+ editor._draw_properties_window(ui, 1.0)
+ imgui.render()
+ field_ids.append(ui.input_ids.copy())
+
+ self.assertEqual(field_ids[0].keys(), field_ids[1].keys())
+ self.assertTrue(field_ids[0])
+ for label in field_ids[0]:
+ with self.subTest(label=label):
+ self.assertNotEqual(field_ids[0][label], field_ids[1][label])
+ finally:
+ imgui.destroy_context(context)
+
+
+class SmartPrimitiveEditorTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ if not wp.is_cuda_available():
+ raise unittest.SkipTest("CUDA is required for editor pose sampling.")
+ cls.previous_device = wp.get_device()
+ cls.device = wp.get_device("cuda:0")
+ wp.set_device(cls.device)
+
+ cls.skeleton = Skeleton(
+ ["Hips"],
+ [-1],
+ _hips_pose(0.0),
+ )
+ # Interval velocities are 1, 3, and 5 meters per second.
+ positions = (0.0, 1.0 / 30.0, 4.0 / 30.0, 9.0 / 30.0)
+ poses = wp.array(
+ np.stack([_hips_pose(position) for position in positions]),
+ dtype=wp.transform,
+ )
+ animation = AnimationBuffer(cls.skeleton, 30.0, poses)
+ cls.clip = ClipAsset(Path("velocity_test.bvh"), animation)
+
+ trajectory_positions = np.arange(61, dtype=np.float32) / 30.0
+ trajectory_poses = wp.array(
+ np.stack([_hips_pose(position) for position in trajectory_positions]),
+ dtype=wp.transform,
+ )
+ trajectory_animation = AnimationBuffer(cls.skeleton, 30.0, trajectory_poses)
+ cls.trajectory_clip = ClipAsset(
+ Path("trajectory_test.bvh"),
+ trajectory_animation,
+ )
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def setUp(self) -> None:
+ self.component = TargetPoseComponent(7, self.skeleton.reference_local_transforms, _BVH_UP_INDEX)
+ self.component.set_clip(self.clip)
+
+ def test_target_pose_velocity_requires_two_poses(self) -> None:
+ self.component.set_num_poses_to_use(1)
+ np.testing.assert_array_equal(
+ [float(self.component.velocity[index]) for index in range(3)],
+ np.zeros(3),
+ )
+ self.assertEqual(self.component.velocity_magnitude, 0.0)
+ self.assertFalse(self.component.has_velocity)
+
+ for frame, num_poses, expected in ((0, 2, 1.0), (0, 3, 1.0), (0, 4, 1.0), (1, 3, 3.0)):
+ with self.subTest(frame=frame, num_poses=num_poses):
+ self.component.set_time(frame / 30.0)
+ self.component.set_num_poses_to_use(num_poses)
+ self.assertAlmostEqual(
+ float(self.component.velocity[0]),
+ expected,
+ places=5,
+ )
+ self.assertAlmostEqual(
+ self.component.velocity_magnitude,
+ expected,
+ places=5,
+ )
+ self.assertTrue(self.component.has_velocity)
+
+ def test_trajectory_is_refreshed_after_edits(self) -> None:
+ self.component.set_clip(self.trajectory_clip)
+ self.component.set_time(30 / 30.0)
+ trajectory = self.component.trajectory_transforms
+ np.testing.assert_allclose(
+ trajectory.numpy()[:, 0], np.arange(10, 51, 2) / 30.0, atol=1.0e-6,
+ )
+
+ # The preview uses the latest settings after several edits.
+ self.component.set_time(45 / 30.0)
+ self.component.constrain_hips(True)
+ self.component.set_trajectory_scale(1.0)
+ self.assertIs(self.component.trajectory_transforms, trajectory)
+ np.testing.assert_allclose(
+ trajectory.numpy()[:, 0], np.arange(-10, 11) / 30.0, atol=1.0e-6,
+ )
+
+ def test_target_pose_trajectory_scale_controls_sample_interval(self) -> None:
+ self.component.set_clip(self.trajectory_clip)
+ self.component.set_time(30 / 30.0)
+ trajectory_buffer = self.component.trajectory_transforms
+ sample_offsets = np.arange(-10, 11, dtype=np.float32)
+
+ for scale in (1.0, 2.0, 3.0, 4.0):
+ with self.subTest(scale=scale):
+ self.component.set_trajectory_scale(scale)
+ expected_frames = np.clip(
+ 30.0 + sample_offsets * scale,
+ 0.0,
+ 60.0,
+ )
+ np.testing.assert_allclose(
+ self.component.trajectory_transforms.numpy()[:, 0],
+ expected_frames / 30.0,
+ atol=1.0e-6,
+ )
+ self.assertIs(
+ self.component.trajectory_transforms,
+ trajectory_buffer,
+ )
+
+ for invalid_scale in (0.99, 4.01, float("nan")):
+ with (
+ self.subTest(invalid_scale=invalid_scale),
+ self.assertRaisesRegex(
+ ValueError,
+ "Trajectory scale",
+ ),
+ ):
+ self.component.set_trajectory_scale(invalid_scale)
+
+ def test_sampling_reuses_allocated_pose_buffers(self) -> None:
+ display_pose = self.component.pose
+ sampled_poses = self.component.sampled_poses
+ trajectory = self.component.trajectory_transforms
+
+ self.component.set_time(1 / 30.0)
+ self.component.constrain_hips(True)
+ self.component.set_clip(self.trajectory_clip)
+
+ self.assertIs(self.component.pose, display_pose)
+ self.assertIs(self.component.sampled_poses, sampled_poses)
+ self.assertIs(self.component.trajectory_transforms, trajectory)
+
+ def test_velocity_arrow_uses_displayed_hips_and_node_world_transform(self) -> None:
+ self.component.set_num_poses_to_use(4)
+ renderer = VectorArrowRenderer("target_pose_velocity", wp.vec3(1.0, 0.0, 0.0))
+ viewer = _ArrowViewer()
+ world_xform = wp.transform(
+ wp.vec3(10.0, 20.0, 30.0),
+ wp.quat_rpy(0.0, 0.0, 0.5 * wp.pi),
+ )
+
+ renderer.draw(
+ viewer,
+ self.component.id,
+ world_xform,
+ self.component.hips_position,
+ self.component.velocity,
+ )
+
+ np.testing.assert_allclose(viewer.starts[0], [10.0, 20.0, 30.0], atol=1.0e-5)
+ np.testing.assert_allclose(viewer.ends[0], [10.0, 21.0, 30.0], atol=1.0e-5)
+
+ def test_interaction_box_renderer_draws_only_box_edges(self) -> None:
+ component = InteractionBoxComponent(12)
+ component.set_dimensions(2.0, 4.0, 6.0)
+ self.assertEqual(
+ (component.width, component.depth, component.height),
+ (2.0, 4.0, 6.0),
+ )
+ renderer = _InteractionBoxRenderer()
+ viewer = _ArrowViewer()
+ world_xform = wp.transform(
+ wp.vec3(1.0, 2.0, 3.0),
+ wp.quat_identity(),
+ )
+
+ renderer.draw(viewer, component, world_xform)
+
+ starts, ends = viewer.lines["/interaction_box_12"]
+ points = np.concatenate((starts, ends), axis=0)
+ self.assertEqual(starts.shape, (12, 3))
+ np.testing.assert_allclose(points.min(axis=0), [0.0, 0.0, 0.0])
+ np.testing.assert_allclose(points.max(axis=0), [2.0, 4.0, 6.0])
+ np.testing.assert_allclose(points.mean(axis=0), world_xform.p)
+
+ component.set_dimensions(8.0, 10.0, 12.0)
+ renderer.draw(viewer, component, world_xform)
+ resized_points = np.concatenate(viewer.lines["/interaction_box_12"], axis=0)
+ np.testing.assert_allclose(resized_points.mean(axis=0), world_xform.p)
+
+ def test_ik_pin_renderer_draws_selected_frame_zero_joints_as_spheres(
+ self,
+ ) -> None:
+ joint_names = [
+ "Hips",
+ "LeftArm",
+ "LeftForeArm",
+ "LeftHand",
+ "RightArm",
+ "RightForeArm",
+ "RightHand",
+ "LeftLeg",
+ "LeftShin",
+ "LeftFoot",
+ "RightLeg",
+ "RightShin",
+ "RightFoot",
+ ]
+ tip_positions = {
+ "LeftHand": (1.0, 0.0, 0.0),
+ "RightHand": (2.0, 0.0, 0.0),
+ "LeftFoot": (0.0, 3.0, 0.0),
+ "RightFoot": (0.0, 4.0, 0.0),
+ }
+ reference_pose = np.array(
+ [
+ [*tip_positions.get(name, (0.0, 0.0, 0.0)), 0.0, 0.0, 0.0, 1.0]
+ for name in joint_names
+ ],
+ dtype=np.float32,
+ )
+ skeleton = Skeleton(
+ joint_names,
+ [-1, 0, 1, 2, 0, 4, 5, 0, 7, 8, 0, 10, 11],
+ reference_pose,
+ )
+ component = TargetPoseComponent(19, skeleton.reference_local_transforms, _BVH_UP_INDEX)
+ component.set_ik_pin_enabled(IKPin.LEFT_HAND, True)
+ component.set_ik_pin_enabled(IKPin.RIGHT_FOOT, True)
+ renderer = _IKPinRenderer(skeleton)
+ viewer = _ShapeViewer()
+ world_xform = wp.transform(
+ wp.vec3(10.0, 20.0, 30.0),
+ wp.quat_identity(),
+ )
+
+ renderer.draw(viewer, component, world_xform)
+
+ geo_type, transforms, is_solid = viewer.shapes["/target_pose_ik_pins_19"]
+ self.assertEqual(geo_type, newton.GeoType.SPHERE)
+ self.assertTrue(is_solid)
+ np.testing.assert_allclose(
+ transforms[:, :3],
+ [[11.0, 20.0, 30.0], [10.0, 24.0, 30.0]],
+ atol=1.0e-5,
+ )
+
+ def test_trajectory_renderer_draws_path_and_coordinate_frames(self) -> None:
+ self.component.set_clip(self.trajectory_clip)
+ self.component.set_time(30 / 30.0)
+ renderer = _HipsTrajectoryRenderer()
+ viewer = _ArrowViewer()
+ world_xform = wp.transform(
+ wp.vec3(10.0, 20.0, 30.0),
+ wp.quat_rpy(0.0, 0.0, 0.5 * wp.pi),
+ )
+
+ renderer.draw(
+ viewer,
+ self.component.id,
+ world_xform,
+ self.component.trajectory_transforms,
+ )
+
+ path_starts, path_ends = viewer.lines["/target_pose_trajectory_7"]
+ expected_positions = np.arange(10, 51, 2, dtype=np.float32) / 30.0
+ self.assertEqual(path_starts.shape, (20, 3))
+ np.testing.assert_allclose(path_starts[:, 0], 10.0, atol=1.0e-5)
+ np.testing.assert_allclose(
+ path_starts[:, 1],
+ 20.0 + expected_positions[:-1],
+ atol=1.0e-5,
+ )
+ np.testing.assert_allclose(
+ path_ends[:, 1],
+ 20.0 + expected_positions[1:],
+ atol=1.0e-5,
+ )
+
+ frame_starts, frame_ends = viewer.lines["/target_pose_trajectory_frames_7"]
+ self.assertEqual(frame_starts.shape, (63, 3))
+ np.testing.assert_allclose(frame_starts[:3], [[10.0, 20.0 + 10.0 / 30.0, 30.0]] * 3, atol=1.0e-5)
+ # The X, Y and Z lines of each frame follow the node's turned axes.
+ axes = frame_ends[:3] - frame_starts[:3]
+ np.testing.assert_allclose(
+ axes / np.linalg.norm(axes, axis=1, keepdims=True),
+ [
+ [0.0, 1.0, 0.0],
+ [-1.0, 0.0, 0.0],
+ [0.0, 0.0, 1.0],
+ ],
+ atol=1.0e-5,
+ )
+
+ def test_mesh_renderer_uses_precomputed_inverse_bind_transforms(self) -> None:
+ skinned_mesh = SkinnedMesh(
+ np.array([[2.0, 0.0, 0.0]], dtype=np.float32),
+ np.array([0, 0, 0], dtype=np.int32),
+ np.array([0], dtype=np.int32),
+ np.array([1.0], dtype=np.float32),
+ )
+ inverse_bind_transform = wp.transform(
+ wp.vec3(-1.0, 0.0, 0.0),
+ wp.quat_identity(),
+ )
+ skeletal_mesh = SkeletalMesh(
+ [skinned_mesh],
+ self.skeleton,
+ [inverse_bind_transform],
+ )
+ renderer = SkeletalMeshRenderer(skeletal_mesh)
+ viewer = _MeshViewer()
+ posed_transforms = wp.array(_hips_pose(3.0), dtype=wp.transform)
+
+ renderer.draw_pose(
+ viewer,
+ posed_transforms,
+ wp.transform_identity(),
+ wp.vec3(0.2, 0.4, 0.6),
+ 11,
+ )
+
+ np.testing.assert_allclose(
+ skeletal_mesh.inverse_bind_transforms.numpy()[0, :3],
+ [-1.0, 0.0, 0.0],
+ atol=1.0e-6,
+ )
+ np.testing.assert_allclose(
+ viewer.points["/skeletal_mesh_11_0"],
+ [[4.0, 0.0, 0.0]],
+ atol=1.0e-6,
+ )
+
+ def test_hierarchy_traversal_drives_visibility_cycles_and_removal(self) -> None:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ branch = authoring.add_node()
+ sibling = authoring.add_node()
+ leaf = authoring.add_node(branch)
+
+ self.assertEqual(
+ list(authoring.iter_nodes()),
+ [authoring.root, branch, leaf, sibling],
+ )
+ self.assertEqual(
+ list(authoring.iter_ancestors(leaf)),
+ [leaf, branch, authoring.root],
+ )
+
+ branch.visible = False
+ self.assertFalse(authoring.is_visible(leaf))
+ self.assertFalse(authoring.can_reparent(branch, leaf))
+
+ authoring.remove_node(branch)
+ self.assertEqual(list(authoring.iter_nodes()), [authoring.root, sibling])
+ self.assertIsNone(authoring.find_node(branch.id))
+ self.assertIsNone(authoring.find_node(leaf.id))
+
+ def test_node_accepts_one_component_of_each_type(self) -> None:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ node = authoring.add_node()
+
+ box = authoring.add_interaction_box(node)
+ target_pose = authoring.add_target_pose(node)
+ pivot = authoring.add_pivot(node)
+
+ self.assertIs(authoring.add_interaction_box(node), box)
+ self.assertIs(authoring.add_target_pose(node), target_pose)
+ self.assertIs(authoring.add_pivot(node), pivot)
+ box.set_dimensions(0.0, 0.0, 0.0)
+ self.assertEqual((box.width, box.depth, box.height), (0.0, 0.0, 0.0))
+ # Components list in a fixed order, whatever order they were added in.
+ self.assertEqual(node.components, (target_pose, box, pivot))
+ self.assertEqual(list(authoring.iter_interaction_boxes()), [(node, box)])
+ self.assertEqual(list(authoring.iter_target_poses()), [(node, target_pose)])
+ self.assertEqual(list(authoring.iter_pivots()), [(node, pivot)])
+
+ def test_pivot_round_trip_and_reference_cleanup_preserve_target_steps(self) -> None:
+ authoring = SmartPrimitiveDocument("soma", self.skeleton.reference_local_transforms, wp.transform_identity())
+ parent = authoring.add_node()
+ node = authoring.add_node(parent)
+ component = authoring.add_pivot(node)
+ component.pivot.set_motion_direction((0.0, -4.0, 3.0))
+ component.pivot.operation_order = OperationOrder.ROTATION_THEN_TRANSLATION
+ component.pivot.translation_axis = Axis.Y
+ component.pivot.translation_constraint = ConstraintType.LINE_PROJECTION
+ component.pivot.line_min_offset = 1.25
+ component.pivot.line_max_offset = 2.5
+ component.pivot.rotation_axis = Axis.X
+ component.pivot.rotation_constraint = ConstraintType.CONE
+ component.pivot.cone_half_angle_degrees = 32.5
+ component.pivot.cone_side = ConeSide.BOTH
+ component.show_motion_direction = component.show_rotation_constraint = False
+ target = authoring.add_node()
+ authoring.add_target_pose(target)
+ first, second = authoring.add_sequence(), authoring.add_sequence()
+ for sequence in (first, second):
+ authoring.add_sequence_node(sequence, target)
+ authoring.set_sequence_pivot(sequence, node)
+ without_pivot = authoring.add_sequence()
+ node.name = "Renamed approach guide"
+
+ with tempfile.TemporaryDirectory() as directory:
+ path = save_smart_primitive_document(
+ authoring, Path(directory) / "pivot", node.id, _camera_state(),
+ )
+ loaded, _, _ = load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ path,
+ )
+ loaded_node = loaded.find_node(node.id)
+ loaded_component = loaded_node.pivot
+ self.assertIsInstance(loaded_component, PivotComponent)
+ np.testing.assert_allclose(loaded_component.pivot.motion_direction, (0.0, -0.8, 0.6))
+ self.assertIs(loaded_component.pivot.operation_order, OperationOrder.ROTATION_THEN_TRANSLATION)
+ self.assertIs(loaded_component.pivot.translation_axis, Axis.Y)
+ self.assertIs(loaded_component.pivot.rotation_axis, Axis.X)
+ self.assertIs(loaded_component.pivot.translation_constraint, ConstraintType.LINE_PROJECTION)
+ self.assertEqual(loaded_component.pivot.line_min_offset, 1.25)
+ self.assertEqual(loaded_component.pivot.line_max_offset, 2.5)
+ self.assertIs(loaded_component.pivot.rotation_constraint, ConstraintType.CONE)
+ self.assertEqual(loaded_component.pivot.cone_half_angle_degrees, 32.5)
+ self.assertIs(loaded_component.pivot.cone_side, ConeSide.BOTH)
+ self.assertEqual((
+ loaded_component.show_motion_direction,
+ loaded_component.show_translation_constraint,
+ loaded_component.show_rotation_constraint,
+ ), (False, True, False))
+ self.assertEqual(loaded_node.name, node.name)
+ self.assertEqual([s.pivot_node_id for s in loaded.sequences], [node.id, node.id, None])
+ self.assertEqual([s.node_ids for s in loaded.sequences], [[target.id], [target.id], []])
+
+ # Removing the component clears references but leaves target steps alone.
+ loaded.remove_component(loaded_node, loaded_component)
+ self.assertEqual([s.pivot_node_id for s in loaded.sequences], [None, None, None])
+ self.assertEqual(loaded.sequences[0].node_ids, [target.id])
+ # Removing an ancestor must clear references to its descendant pivots too.
+ loaded.add_pivot(loaded_node)
+ loaded.set_sequence_pivot(loaded.sequences[0], loaded_node)
+ loaded.set_sequence_pivot(loaded.sequences[1], loaded_node)
+ loaded.remove_node(loaded.find_node(parent.id))
+ self.assertEqual([s.pivot_node_id for s in loaded.sequences], [None, None, None])
+ self.assertEqual(loaded.sequences[1].node_ids, [target.id])
+ self.assertIsNone(without_pivot.pivot_node_id)
+
+ def test_pivot_preview_uses_node_space_and_selected_local_axis(self) -> None:
+ # The preview must not inherit the model coordinate conversion.
+ model_conversion = wp.transform(wp.vec3(0.0), wp.quat_rpy(wp.pi / 2, 0.0, 0.0))
+ authoring = SmartPrimitiveDocument("soma", self.skeleton.reference_local_transforms, model_conversion)
+ parent = authoring.add_node()
+ parent.local_xform = wp.transform(wp.vec3(2.0, 3.0, 1.0), wp.quat_rpy(0.0, 0.0, wp.pi / 2))
+ node = authoring.add_node(parent)
+ node.local_xform = wp.transform(wp.vec3(0.0), wp.quat_rpy(0.0, float(np.arcsin(0.6)), 0.0))
+ component = authoring.add_pivot(node)
+ pivot = component.pivot
+ pivot.translation_constraint = ConstraintType.LINE_PROJECTION
+ pivot.line_min_offset, pivot.line_max_offset = -2.0, 0.75
+ pivot.rotation_constraint = ConstraintType.CONE
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.authoring = authoring
+ editor.viewer = _ArrowViewer()
+ editor.pivot_renderer = _PivotRenderer()
+ line_name = f"/pivot_translation_constraint_{component.id}"
+ cone_name = f"/pivot_rotation_constraint_{component.id}"
+ origin = np.array([2.0, 3.0, 1.0])
+ # The 45 degree cone boundaries lie in the plane across the selected axis.
+ edge = 1.5 / np.sqrt(2.0)
+ for axis, motion, arrow_end, line, normal, forward in (
+ (
+ Axis.X, (0, 1, 0), (1, 3, 1), [(2, 1.4, 2.2), (2, 3.6, 0.55)], (0, 0.8, -0.6),
+ [(-edge, 0.6 * edge, 0.8 * edge), (-edge, -0.6 * edge, -0.8 * edge)],
+ ),
+ (
+ Axis.Y, (0, 0, 1), (2, 3.6, 1.8), [(4, 3, 1), (1.25, 3, 1)], (-1, 0, 0),
+ [(0, 1.4 * edge, 0.2 * edge), (0, -0.2 * edge, 1.4 * edge)],
+ ),
+ (
+ Axis.Z, (1, 0, 0), (2, 3.8, 0.4), [(2, 1.8, -0.6), (2, 3.45, 1.6)], (0, 0.6, 0.8),
+ [(-edge, 0.8 * edge, -0.6 * edge), (edge, 0.8 * edge, -0.6 * edge)],
+ ),
+ ):
+ pivot.translation_axis = pivot.rotation_axis = axis
+ pivot.set_motion_direction(motion)
+ mirrored = [tuple(-value for value in boundary) for boundary in forward]
+ for side, expected in (
+ (ConeSide.BOTH, forward + mirrored),
+ (ConeSide.FORWARD, forward),
+ (ConeSide.MIRRORED, mirrored),
+ ):
+ with self.subTest(axis=axis, side=side):
+ pivot.cone_side = side
+ editor._draw_pivots()
+ # The arrow sits just above its pivot, clear of the ground plane.
+ lift = np.array([0.0, 0.0, _PIVOT_ARROW_LIFT])
+ np.testing.assert_allclose(editor.viewer.starts[0], origin + lift, atol=1e-6)
+ np.testing.assert_allclose(editor.viewer.ends[0], np.add(arrow_end, lift), atol=1e-6)
+ line_starts, line_ends = editor.viewer.lines[line_name]
+ np.testing.assert_allclose([line_starts[0], line_ends[0]], line, atol=1e-6)
+ starts, ends = editor.viewer.lines[cone_name]
+ rays = np.all(np.isclose(starts, origin), axis=1)
+ actual = ends[rays] - origin
+ # Compare each expected boundary without depending on draw order.
+ self.assertEqual(len(actual), len(expected))
+ for boundary in expected:
+ self.assertTrue(np.any(np.all(np.isclose(actual, boundary, atol=1e-6), axis=1)))
+ np.testing.assert_allclose((ends - origin) @ normal, 0.0, atol=1e-6)
+
+ previous_direction = pivot.motion_direction
+ for invalid in ((0.0, 0.0, 0.0), (float("nan"), 1.0, 0.0), (0.0, float("inf"), 0.0)):
+ with self.assertRaisesRegex(ValueError, "finite and non-zero"):
+ pivot.set_motion_direction(invalid)
+ self.assertEqual(pivot.motion_direction, previous_direction)
+
+ def test_sequences_order_reuse_and_clean_up_target_pose_nodes(self) -> None:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ entry = authoring.add_node()
+ action = authoring.add_node()
+ unused = authoring.add_node()
+ entry_target = authoring.add_target_pose(entry)
+ authoring.add_target_pose(action)
+
+ primary = authoring.add_sequence()
+ variation = authoring.add_sequence()
+ authoring.add_sequence_node(primary, entry)
+ authoring.add_sequence_node(primary, action)
+ authoring.add_sequence_node(variation, entry)
+ authoring.add_sequence_node(variation, action)
+ authoring.add_sequence_node(variation, entry)
+ authoring.move_sequence_node(variation, 2, 0)
+
+ self.assertEqual(primary.node_ids, [entry.id, action.id])
+ self.assertEqual(variation.node_ids, [entry.id, entry.id, action.id])
+ self.assertEqual(
+ list(authoring.sequences_referencing(entry)),
+ [primary, variation],
+ )
+ with self.assertRaisesRegex(ValueError, "must own a Target Pose"):
+ authoring.add_sequence_node(primary, unused)
+
+ authoring.remove_component(entry, entry_target)
+ self.assertEqual(primary.node_ids, [action.id])
+ self.assertEqual(variation.node_ids, [action.id])
+
+ authoring.remove_node(action)
+ self.assertEqual(primary.node_ids, [])
+ self.assertEqual(variation.node_ids, [])
+
+ authoring.remove_sequence(primary)
+ self.assertNotIn(primary, authoring.sequences)
+
+ def _build_authored_scene(self, clip: ClipAsset):
+ model_to_runtime = wp.transform(
+ wp.vec3(0.0, 0.0, 0.0),
+ wp.quat_rpy(0.5 * wp.pi, 0.0, 0.0),
+ )
+ authoring = SmartPrimitiveDocument("soma", self.skeleton.reference_local_transforms, model_to_runtime)
+ authoring.root.name = "Authored Root"
+ authoring.root.local_xform = wp.transform(
+ wp.vec3(1.0, 2.0, 3.0),
+ wp.quat_rpy(0.1, 0.2, 0.3),
+ )
+ authoring.root.euler_degrees = [5.0, 10.0, 15.0]
+ authoring.root.translation_locks = [True, False, True]
+
+ branch = authoring.add_node()
+ branch.name = "Approach"
+ branch.visible = False
+ branch.rotation_locks = [False, True, False]
+ branch.local_xform = wp.transform(
+ wp.vec3(4.0, 5.0, 6.0),
+ wp.quat_rpy(-0.2, 0.4, -0.6),
+ )
+ sibling = authoring.add_node()
+ sibling.name = "Exit"
+ leaf = authoring.add_node(branch)
+ leaf.name = "Contact"
+ leaf.euler_degrees = [-20.0, 30.0, 220.0]
+
+ first_target = authoring.add_target_pose(branch)
+ first_target.set_clip(clip)
+ first_target.playback_mode = PlaybackMode.FRAMES
+ first_target.set_time(2 / clip.animation.sample_rate)
+ first_target.constrain_hips(True)
+ first_target.set_num_poses_to_use(3)
+ first_target.transition_early_by_frames = 7
+ first_target.ik_pin_mask = IKPin.LEFT_HAND | IKPin.RIGHT_FOOT
+ first_target.show_velocity = True
+ first_target.show_trajectory = True
+ first_target.set_trajectory_scale(3.5)
+ first_target.show_mesh = False
+ first_target.show_skeletons = True
+ first_target.color = wp.vec3(0.1, 0.2, 0.3)
+
+ interaction_box = authoring.add_interaction_box(branch)
+ interaction_box.set_dimensions(2.5, 3.5, 4.5)
+ interaction_box.color = wp.vec3(0.4, 0.5, 0.6)
+
+ second_target = authoring.add_target_pose(leaf)
+ second_target.set_clip(clip)
+ second_target.playback_mode = PlaybackMode.TIME
+ second_target.set_time(1.0 / 30.0)
+ second_target.set_num_poses_to_use(2)
+ second_target.transition_early_by_frames = 11
+ second_target.set_token_range(9, 9)
+ second_target.ik_pin_mask = IKPin.RIGHT_HAND
+ second_target.color = wp.vec3(0.7, 0.8, 0.9)
+
+ primary_sequence = authoring.add_sequence()
+ primary_sequence.name = "Primary"
+ authoring.add_sequence_node(primary_sequence, branch)
+ authoring.add_sequence_node(primary_sequence, leaf)
+ variation_sequence = authoring.add_sequence()
+ variation_sequence.name = "Variation"
+ authoring.add_sequence_node(variation_sequence, leaf)
+ authoring.add_sequence_node(variation_sequence, branch)
+
+ return authoring, leaf.id
+
+ def test_authoring_document_round_trip_preserves_complete_scene(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ temporary_path = Path(temporary_directory)
+ clip_path = temporary_path / "clips" / "shared.bvh"
+ clip_path.parent.mkdir()
+ clip_path.touch()
+ clip = ClipAsset(clip_path.resolve(), self.clip.animation)
+ authoring, selected_id = self._build_authored_scene(clip)
+
+ document_path = save_smart_primitive_document(
+ authoring,
+ temporary_path / "documents" / "locomotion",
+ selected_id,
+ _camera_state(),
+ )
+ self.assertEqual(
+ document_path.name,
+ "locomotion.smart_primitive.json",
+ )
+ saved_document = json.loads(document_path.read_text("utf-8"))
+ self.assertEqual(
+ saved_document["format"],
+ "motionbricks.smart_primitive.authoring",
+ )
+ self.assertEqual(saved_document["schema_version"], 1)
+ self.assertEqual(saved_document["name"], "locomotion")
+ self.assertEqual(saved_document["rig"], "soma")
+ self.assertEqual(
+ saved_document["root"]["children"][0]["components"][0]["clip"],
+ "../clips/shared.bvh",
+ )
+
+ registry = ClipRegistry(ModelRig.SOMA, skeleton=self.skeleton)
+ with patch(
+ "app.runtime.common.clip_registry.bvh_utils.load_bvh",
+ return_value=clip.animation,
+ ) as load_bvh:
+ loaded, loaded_selected_id, loaded_camera_state = (
+ load_smart_primitive_document(
+ registry,
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+ )
+ load_bvh.assert_called_once_with(clip.path, self.skeleton)
+ loaded_targets = [component for _, component in loaded.iter_target_poses()]
+ self.assertIs(loaded_targets[0].clip, loaded_targets[1].clip)
+ self.assertIs(loaded_targets[0].clip.animation, clip.animation)
+ round_trip_path = save_smart_primitive_document(
+ loaded,
+ document_path.parent / "round_trip.smart_primitive.json",
+ loaded_selected_id,
+ loaded_camera_state,
+ )
+ round_trip_document = json.loads(round_trip_path.read_text("utf-8"))
+ self.assertEqual(saved_document["editor"], round_trip_document["editor"])
+ self.assertEqual(
+ saved_document["sequences"],
+ round_trip_document["sequences"],
+ )
+ self.assertEqual(saved_document["root"], round_trip_document["root"])
+
+ existing_ids = {
+ item_id
+ for node in loaded.iter_nodes()
+ for item_id in [node.id, *[item.id for item in node.components]]
+ }
+ existing_ids.update(sequence.id for sequence in loaded.sequences)
+ added_node = loaded.add_node()
+ self.assertEqual(added_node.id, max(existing_ids) + 1)
+
+ saved_document["editor"]["selected_node_id"] = 9999
+ renamed_path = document_path.with_name("renamed.smart_primitive.json")
+ renamed_path.write_text(json.dumps(saved_document), encoding="utf-8")
+ renamed, selected_id, _ = load_smart_primitive_document(
+ registry,
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ renamed_path,
+ )
+ self.assertEqual(selected_id, renamed.root.id)
+ self.assertEqual(len(list(renamed.iter_target_poses())), 2)
+ self.assertEqual(renamed.sequences, authoring.sequences)
+
+ def test_authoring_document_rejects_invalid_sequence_metadata(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ temporary_path = Path(temporary_directory)
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ node = authoring.add_node()
+ authoring.add_target_pose(node)
+ sequence = authoring.add_sequence()
+ authoring.add_sequence_node(sequence, node)
+ document_path = save_smart_primitive_document(
+ authoring,
+ temporary_path / "sequences",
+ node.id,
+ _camera_state(),
+ )
+ document = json.loads(document_path.read_text("utf-8"))
+
+ invalid_documents = (
+ (
+ "must identify a node with a Pivot component",
+ lambda value: value["sequences"][0].__setitem__("pivot_node_id", 999),
+ ),
+ (
+ "must identify a node with a Pivot component",
+ lambda value: value["sequences"][0].__setitem__("pivot_node_id", node.id),
+ ),
+ (
+ "does not identify a hierarchy node",
+ lambda value: value["sequences"][0]["node_ids"].__setitem__(
+ 0, 999
+ ),
+ ),
+ (
+ "Duplicate ID",
+ lambda value: value["sequences"][0].__setitem__(
+ "id", value["root"]["id"]
+ ),
+ ),
+ )
+ for message, mutate in invalid_documents:
+ with self.subTest(message=message):
+ invalid_document = json.loads(json.dumps(document))
+ mutate(invalid_document)
+ document_path.write_text(
+ json.dumps(invalid_document),
+ encoding="utf-8",
+ )
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ message,
+ ):
+ load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+
+ def test_authoring_document_requires_valid_trajectory_scale(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ authoring.add_target_pose(authoring.root)
+ document_path = save_smart_primitive_document(
+ authoring,
+ Path(temporary_directory) / "trajectory_scale",
+ authoring.root.id,
+ _camera_state(),
+ )
+ document = json.loads(document_path.read_text("utf-8"))
+ document["root"]["components"][0]["trajectory_scale"] = 4.1
+ document_path.write_text(json.dumps(document), encoding="utf-8")
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ r"\.trajectory_scale must be 1\.0 to 4\.0",
+ ):
+ load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+
+ def test_authoring_document_requires_valid_ik_pin_mask(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ authoring.add_target_pose(authoring.root)
+ document_path = save_smart_primitive_document(
+ authoring,
+ Path(temporary_directory) / "ik_pin_mask",
+ authoring.root.id,
+ _camera_state(),
+ )
+ document = json.loads(document_path.read_text("utf-8"))
+ document["root"]["components"][0]["ik_pin_mask"] = 1 << 4
+ document_path.write_text(json.dumps(document), encoding="utf-8")
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ r"\.ik_pin_mask contains unsupported bits",
+ ):
+ load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+
+ def test_authoring_document_requires_valid_token_range(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ component = authoring.add_target_pose(authoring.root)
+ self.assertEqual((component.min_tokens, component.max_tokens), (6, 14))
+ document_path = save_smart_primitive_document(
+ authoring,
+ Path(temporary_directory) / "tokens",
+ authoring.root.id,
+ _camera_state(),
+ )
+ saved = json.loads(document_path.read_text("utf-8"))
+ for tokens, message in (
+ ((5, 14), r"\.min_tokens must be at least 6"),
+ ((6, 17), r"\.max_tokens must be at most 16"),
+ ((10, 9), r"\.max_tokens must be at least 10"),
+ ):
+ with self.subTest(tokens=tokens):
+ document = json.loads(json.dumps(saved))
+ target = document["root"]["components"][0]
+ target["min_tokens"], target["max_tokens"] = tokens
+ document_path.write_text(json.dumps(document), encoding="utf-8")
+ with self.assertRaisesRegex(DocumentError, message):
+ load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+
+ def test_authoring_document_rejects_multiple_interaction_boxes(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ authoring.add_interaction_box(authoring.root)
+ document_path = save_smart_primitive_document(
+ authoring,
+ Path(temporary_directory) / "duplicate_box",
+ authoring.root.id,
+ _camera_state(),
+ )
+ document = json.loads(document_path.read_text("utf-8"))
+ duplicate_document = json.loads(json.dumps(document))
+ duplicate = duplicate_document["root"]["components"][0].copy()
+ duplicate["id"] += 1
+ duplicate_document["root"]["components"].append(duplicate)
+ document_path.write_text(
+ json.dumps(duplicate_document),
+ encoding="utf-8",
+ )
+
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ "more than one Interaction Box",
+ ):
+ load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+
+ document["root"]["components"][0]["width"] = -0.1
+ document_path.write_text(json.dumps(document), encoding="utf-8")
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ r"\.width cannot be negative",
+ ):
+ load_smart_primitive_document(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ authoring.model_to_runtime,
+ document_path,
+ )
+
+ def test_new_scene_resets_authoring_document_and_interaction_state(self) -> None:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ selected = authoring.add_node()
+ authoring.add_target_pose(selected)
+
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.viewer = _TitleViewer()
+ editor.rig = SimpleNamespace(target_pose_renderers=_ClearableRenderers())
+ editor.interaction_box_renderer = _ClearableRenderers()
+ editor.pivot_renderer = _ClearableRenderers()
+ editor.authoring = authoring
+ editor.selected_id = selected.id
+ editor._document_path = Path("existing.smart_primitive.json")
+ editor._status = object()
+
+ editor._new_document()
+
+ self.assertIsNot(editor.authoring, authoring)
+ self.assertEqual(list(editor.authoring.iter_nodes()), [editor.authoring.root])
+ self.assertEqual(editor.selected_id, editor.authoring.root.id)
+ self.assertIsNone(editor._document_path)
+ self.assertIsNone(editor._status)
+
+ def test_save_as_chooses_new_current_document(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ temporary_path = Path(temporary_directory)
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ original_path = save_smart_primitive_document(
+ authoring,
+ temporary_path / "original.smart_primitive.json",
+ authoring.root.id,
+ _camera_state(),
+ )
+ requested_path = temporary_path / "copy"
+
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.viewer = _TitleViewer()
+ editor.authoring = authoring
+ editor.selected_id = authoring.root.id
+ editor._document_path = original_path
+ editor._status = object()
+
+ with patch("app.authoring.common.choose_file", return_value=str(requested_path)) as chooser:
+ editor._save_as()
+
+ copy_path = requested_path.with_name("copy.smart_primitive.json").resolve()
+ self.assertEqual(
+ chooser.call_args,
+ call(
+ "Save Smart Primitive", "Smart Primitive documents", ".smart_primitive.json",
+ original_path, save=True,
+ ),
+ )
+ self.assertTrue(original_path.is_file())
+ self.assertTrue(copy_path.is_file())
+ self.assertEqual(editor._document_path, copy_path)
+ self.assertIsNone(editor._status)
+
+ def test_successful_load_replaces_scene_without_persistent_status(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ authoring = SmartPrimitiveDocument(
+ "soma",
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ )
+ selected = authoring.add_node()
+ selected.name = "Loaded Node"
+ document_path = save_smart_primitive_document(
+ authoring,
+ Path(temporary_directory) / "loaded.smart_primitive.json",
+ selected.id,
+ _camera_state(),
+ )
+
+ rig = _Rig(
+ _EmptyClipRegistry(),
+ self.skeleton.reference_local_transforms,
+ wp.transform_identity(),
+ _ClearableRenderers(),
+ )
+ editor = _loading_editor(rig)
+ other_camera_state = _camera_state()
+ other_camera_state["pos"] = [-10.0, -20.0, -30.0]
+ editor.viewer.camera = _Camera(other_camera_state)
+
+ editor._open_document(document_path)
+
+ self.assertEqual(editor.selected.name, "Loaded Node")
+ self.assertEqual(editor._document_path, document_path.resolve())
+ self.assertIsNone(editor._status)
+ # Opening with the same character reuses its rig resources.
+ self.assertIs(editor.rig, rig)
+ self.assertEqual(editor._capture_camera_state(), _camera_state())
+
+ def _bvh_rig(self) -> _Rig:
+ # BVH clips are Y-up; a quarter turn about X makes them Z-up.
+ y_up_to_z_up = wp.transform(wp.vec3(0.0), wp.quat_rpy(0.5 * wp.pi, 0.0, 0.0))
+ return _Rig(
+ ClipRegistry(ModelRig.SOMA, skeleton=self.skeleton),
+ self.skeleton.reference_local_transforms,
+ y_up_to_z_up,
+ _ClearableRenderers(),
+ )
+
+ @staticmethod
+ def _csv_rig(folder: Path) -> tuple[_Rig, Path]:
+ """A one-hinge robot and a CSV clip that walks it forward."""
+ frames = np.zeros((31, 8), dtype=np.float32)
+ frames[:, 0] = np.arange(31) / 120.0
+ frames[:, 2] = 0.8
+ frames[:, 6] = 1.0
+ clip_path = folder / "walk.csv"
+ save_csv(str(clip_path), DOFAnimationBuffer(("hinge",), 120.0, wp.array(frames, dtype=wp.float32)))
+ rig = _Rig(
+ ClipRegistry(ModelRig.UNITREE_G1, joint_names=("hinge",)),
+ wp.array(frames[0], dtype=wp.float32),
+ wp.transform_identity(),
+ _ClearableRenderers(),
+ )
+ return rig, clip_path
+
+ def test_clips_must_match_the_character_and_then_fix_it(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ csv_rig, csv_path = self._csv_rig(Path(temporary_directory))
+ bvh_rig = self._bvh_rig()
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.viewer = SimpleNamespace()
+ editor._load_rig = Mock(return_value=csv_rig)
+ editor.rig = bvh_rig
+ editor.authoring = SmartPrimitiveDocument(
+ bvh_rig.clip_registry.rig, bvh_rig.reference_pose, bvh_rig.model_to_runtime,
+ )
+ editor._status = None
+ editor._choose_clip = lambda: str(csv_path)
+ target = editor.authoring.add_target_pose(editor.authoring.add_node())
+
+ # SOMA loads only BVH clips, and refusing a CSV clip builds no other rig.
+ with patch("app.smart_primitive_editor.draw_clip_selector", return_value=True):
+ editor._draw_clip_selector(None, target)
+ self.assertIn("loads .bvh clips", editor._status)
+ self.assertIsNone(target.clip)
+ editor._load_rig.assert_not_called()
+
+ # Without clips, another character re-lays out every target pose.
+ editor._use_rig(editor._rig_for(ModelRig.UNITREE_G1))
+ editor._load_rig.assert_called_once_with(ModelRig.UNITREE_G1)
+ self.assertIs(editor.rig, csv_rig)
+ self.assertEqual(editor.authoring.rig, "unitree_g1")
+ self.assertEqual(bvh_rig.target_pose_renderers.clear_count, 1)
+ self.assertEqual(editor.authoring.up_index, 2)
+ np.testing.assert_array_equal(target.pose.numpy(), csv_rig.reference_pose.numpy())
+ with patch("app.smart_primitive_editor.draw_clip_selector", return_value=True):
+ editor._draw_clip_selector(None, target)
+ self.assertEqual(target.clip.path, csv_path.resolve())
+
+ # A clip fixes the character, so the document refuses another one.
+ with self.assertRaisesRegex(ValueError, "Cannot change the rig"):
+ editor._use_rig(bvh_rig)
+ self.assertIs(editor.rig, csv_rig)
+
+ def test_load_selects_the_saved_rig_even_without_clips(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ folder = Path(temporary_directory)
+ csv_rig, _ = self._csv_rig(folder)
+ authoring = SmartPrimitiveDocument(
+ csv_rig.clip_registry.rig, csv_rig.reference_pose, csv_rig.model_to_runtime,
+ )
+ authoring.add_target_pose(authoring.add_node())
+ document_path = save_smart_primitive_document(
+ authoring, folder / "empty", authoring.root.id, _camera_state(),
+ )
+ bvh_rig = self._bvh_rig()
+ editor = _loading_editor(bvh_rig)
+ editor._load_rig = Mock(return_value=csv_rig)
+
+ editor._open_document(document_path)
+
+ editor._load_rig.assert_called_once_with(ModelRig.UNITREE_G1)
+
+ self.assertEqual(load_smart_primitive_rig(document_path), "unitree_g1")
+ self.assertIsNone(editor._status)
+ self.assertIs(editor.rig, csv_rig)
+ self.assertEqual(editor.authoring.rig, "unitree_g1")
+ self.assertEqual(bvh_rig.target_pose_renderers.clear_count, 1)
+ [(_, target)] = editor.authoring.iter_target_poses()
+ self.assertIsNone(target.clip)
+ np.testing.assert_array_equal(target.pose.numpy(), csv_rig.reference_pose.numpy())
+
+ def test_asset_pool_uses_registry_rig_before_loading_clips(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ temporary_path = Path(temporary_directory)
+ clip_path = temporary_path / "clip.bvh"
+ clip_path.touch()
+ clip = ClipAsset(clip_path.resolve(), self.clip.animation)
+ authoring = SmartPrimitiveDocument(
+ "soma", self.skeleton.reference_local_transforms, wp.transform_identity(),
+ )
+ authoring.add_target_pose(authoring.root).set_clip(clip)
+ document_path = save_smart_primitive_document(
+ authoring, temporary_path / "jump", authoring.root.id, _camera_state(),
+ )
+ clip_registry = ClipRegistry(
+ ModelRig.UNITREE_G1, joint_names=("hinge",),
+ )
+ pool = SmartPrimitiveAssetPool(
+ clip_registry, wp.array([0, 0, 0, 0, 0, 0, 1, 0], dtype=wp.float32), wp.transform_identity(),
+ )
+
+ with patch.object(clip_registry, "load") as load_clip:
+ with self.assertRaisesRegex(
+ SmartPrimitiveDocumentError,
+ r"jump\.smart_primitive\.json was saved for the 'soma' rig, but this app uses 'unitree_g1'",
+ ):
+ pool.load(document_path)
+ load_clip.assert_not_called()
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_smart_primitive_interactions.py b/tests/app/test_smart_primitive_interactions.py
new file mode 100644
index 0000000..59e9f50
--- /dev/null
+++ b/tests/app/test_smart_primitive_interactions.py
@@ -0,0 +1,521 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+from dataclasses import replace
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.clip_registry import ClipAsset, ClipRegistry
+from app.runtime.common.io.smart_primitive_document import (
+ SmartPrimitiveDocument,
+ build_runtime_smart_primitive_data,
+)
+from app.runtime.soma.character import SOMACharacter
+from app.runtime.common.motion import AnimationClip
+from app.runtime.soma.presets import DEFAULT_LOCOMOTION_MODES
+from app.runtime.common.state_machine import StateMachine
+from app.runtime.common.smart_primitive_behaviors import (
+ SmartPrimitiveBehavior,
+ VelocityMatchingSequenceBehavior,
+)
+from app.scene_preview import ScenePreview
+from app.utils.input import InputManager
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.runtime.motion_recorder import MotionRecorder
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.contract import ModelRig
+from motionbricks.runtime.motion_player import GeneratedMotionPlayer
+from motionbricks.runtime.pivot import Axis
+from motionbricks.runtime.smart_primitive import SmartPrimitiveAsset
+
+
+class _SequenceClipCycle(SmartPrimitiveBehavior):
+ """Drive the real interaction state through sequences and baked playback."""
+
+ required_sequences = ("Entry", "Exit")
+ clip_paths = (Path("synthetic_loop.bvh"),)
+
+ def enter(self):
+ self.interaction_state.play_target_pose_sequence("Entry", on_complete=self._play_loop)
+
+ def _play_loop(self):
+ self.interaction_state.play_clip(self.clip_paths[0], loop=True)
+
+ def interact(self):
+ if self.interaction_state.is_looping:
+ self.interaction_state.play_target_pose_sequence("Exit")
+
+
+class _OrderedTargets(SmartPrimitiveBehavior):
+ """Exercise a multi-target selection, independent of hierarchy order."""
+
+ def get_targets(self, properties, output, stream=None):
+ first = self.get_world_target_poses_for_sequence(
+ self.sequence_index("Exit"), output[:4], stream,
+ )[0]
+ second = self.get_world_target_poses_for_sequence(
+ self.sequence_index("Entry"), output[4:12], stream,
+ )
+ return replace(first, transition_early_by_frames=7), *second
+
+
+class SmartPrimitiveInteractionTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+ reference = np.array([
+ [0, 0, 1, 0, 0, 0, 1],
+ [0, 0.5, 0, 0, 0, 0, 1],
+ ], dtype=np.float32)
+ cls.skeleton = Skeleton(["Hips", "Child"], [-1, 0], reference)
+ poses = np.repeat(reference[None], 12, axis=0)
+ poses[:4, 0, 0] = np.arange(4, dtype=np.float32) / 30.0
+ poses[4:8, 0, 0] = 1.0
+ poses[8:, 0, 0] = 2.0
+ clip = ClipAsset(
+ Path("synthetic_targets.bvh"), AnimationBuffer(cls.skeleton, 30.0, wp.array(poses, dtype=wp.transform)),
+ )
+ authoring = SmartPrimitiveDocument("soma", cls.skeleton.reference_local_transforms, wp.transform_identity())
+ guide = authoring.add_node()
+ guide.name = "Guide"
+ pivot = authoring.add_pivot(guide).pivot
+ pivot.motion_direction = (-1.0, 0.0, 0.0)
+ pivot.rotation_axis = Axis.Z
+ unrelated = authoring.add_node()
+ unrelated.name = "Unrelated"
+
+ targets = []
+ # Approach keeps the default token range.
+ for name, frame, poses_to_use, early_frames, tokens in (
+ ("Approach", 0, 4, 3, (6, 14)), ("Hold", 4, 1, 0, (8, 8)), ("Depart", 8, 4, 0, (7, 12)),
+ ):
+ node = authoring.add_node(guide)
+ node.name = name
+ target = authoring.add_target_pose(node)
+ target.set_clip(clip)
+ target.set_time(frame / clip.animation.sample_rate)
+ target.set_num_poses_to_use(poses_to_use)
+ target.transition_early_by_frames = early_frames
+ target.set_token_range(*tokens)
+ targets.append(node)
+ entry = authoring.add_sequence()
+ entry.name = "Entry"
+ for node in targets[:2]:
+ authoring.add_sequence_node(entry, node)
+ authoring.set_sequence_pivot(entry, guide)
+ exit_sequence = authoring.add_sequence()
+ exit_sequence.name = "Exit"
+ authoring.add_sequence_node(exit_sequence, targets[2])
+ cls.asset = SmartPrimitiveAsset(build_runtime_smart_primitive_data(authoring), device="cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def setUp(self):
+ self.machine = StateMachine(
+ tuple(SimpleNamespace(definition=mode) for mode in DEFAULT_LOCOMOTION_MODES),
+ standing_idle_clips=(object(),),
+ crouching_idle_clips=(object(),),
+ pose=self.skeleton.reference_local_transforms,
+ )
+ self.machine.standing_idle_state.enter = Mock()
+ self.machine.standing_locomotion_state.enter = Mock()
+ self.generated = []
+ self.character = SimpleNamespace(
+ skeleton=self.skeleton,
+ clip_registry=ClipRegistry(ModelRig.SOMA, skeleton=self.skeleton),
+ current_pose=wp.empty_like(self.skeleton.reference_local_transforms),
+ engine=SimpleNamespace(device=wp.get_device("cpu"), stream=None),
+ movement=SimpleNamespace(
+ input_speed=0.0,
+ current_facing=np.array([1.0, 0.0, 0.0], dtype=np.float32),
+ desired_velocity=np.zeros(3, dtype=np.float32),
+ ),
+ character_ground_position=np.zeros(3, dtype=np.float32),
+ actual_velocity=np.zeros(3, dtype=np.float32),
+ probe_segment=(np.zeros(3), np.zeros(3)),
+ clear_ik_pins=Mock(),
+ face_pose=Mock(),
+ time_to_transition=Mock(return_value=0.5),
+ start_clip=Mock(),
+ clip_ends_within=Mock(return_value=False),
+ generate_to_target_poses=Mock(side_effect=self._record_generated_target),
+ )
+ self.cycle = _SequenceClipCycle(self.asset)
+ self.state = self.machine.interaction_state
+ poses = np.repeat(self.skeleton.reference_local_transforms.numpy()[None], 3, axis=0)
+ poses[1, 1, 2] = 0.2
+ self.baked_clip = AnimationClip(
+ animation=AnimationBuffer(self.skeleton, 30.0, wp.array(poses, dtype=wp.transform)),
+ source_ground=wp.transform_identity(),
+ duration=2.0 / 30.0,
+ root_offset=wp.transform_identity(),
+ root_positions=poses[:, 0, :3].copy(),
+ )
+ # Supply a real buffer without reading a BVH or any bundled motion assets.
+ self.character.load_clip = Mock(return_value=self.baked_clip)
+
+ def _record_generated_target(self, poses, params):
+ self.generated.append((poses.numpy().copy(), params))
+ self.character.time_to_transition.return_value = 0.5
+
+ def reach_target(self):
+ self.character.time_to_transition.return_value = 0.003
+ self.state.update(self.character, self.machine, 0.016)
+
+ def test_sequence_alignment_survives_clip_and_unaligned_followup(self):
+ primitive = _SequenceClipCycle(self.asset)
+ self.character.movement.current_facing[:] = (0.0, 1.0, 0.0)
+ self.character.movement.desired_velocity[:] = (1.0, 0.0, 0.0)
+ pivot = primitive.sequence_pivot_node_index(primitive.sequence_index("Entry"))
+ primitive.set_node_world_transform(
+ 0, wp.transform(wp.vec3(3.0, -2.0, 0.4), wp.quat_rpy(0.0, 0.0, 0.6)),
+ )
+ primitive.set_node_local_transform(
+ pivot, wp.transform(wp.vec3(0.3, -0.1, 0.2), wp.quat_rpy(0.0, 0.0, 0.4)),
+ )
+ transforms = wp.empty(primitive.node_count, dtype=wp.transform, device="cpu")
+ primitive.compute_world_transforms(transforms)
+ before = transforms.numpy().copy()
+
+ self.machine.start_interaction(self.character, primitive)
+
+ primitive.compute_world_transforms(transforms)
+ aligned = transforms.numpy().copy()
+ np.testing.assert_allclose(
+ wp.quat_rotate(wp.quat(*aligned[pivot, 3:]), wp.vec3(1.0, 0.0, 0.0)),
+ [-1.0, 0.0, 0.0], atol=1e-6,
+ )
+ np.testing.assert_allclose(aligned[pivot, :3], before[pivot, :3], atol=1e-6)
+ for node in (0, primitive.node_index("Unrelated")):
+ np.testing.assert_allclose(aligned[node], before[node], atol=1e-6)
+ expected = wp.empty((8, self.skeleton.num_joints), dtype=wp.transform, device="cpu")
+ primitive.get_world_target_poses_for_sequence(
+ primitive.sequence_index("Entry"), expected,
+ )
+ np.testing.assert_allclose(self.generated[0][0], expected.numpy()[:4])
+
+ self.reach_target()
+ np.testing.assert_allclose(self.generated[1][0], expected.numpy()[4:])
+ self.reach_target()
+ self.assertTrue(self.state.is_looping)
+ self.character.movement.current_facing[:] = (1.0, 0.0, 0.0)
+ self.character.movement.desired_velocity[:] = (0.0, 1.0, 0.0)
+ self.machine.interact()
+ primitive.compute_world_transforms(transforms)
+ np.testing.assert_allclose(transforms.numpy()[pivot], aligned[pivot], atol=1e-6)
+ primitive.get_world_target_poses_for_sequence(
+ primitive.sequence_index("Exit"), expected[:4],
+ )
+ np.testing.assert_allclose(self.generated[2][0], expected.numpy()[:4])
+
+ self.reach_target()
+ self.machine.start_interaction(self.character, primitive)
+ primitive.compute_world_transforms(transforms)
+ realigned = transforms.numpy()[pivot]
+ np.testing.assert_allclose(
+ wp.quat_rotate(wp.quat(*realigned[3:]), wp.vec3(1.0, 0.0, 0.0)),
+ [0.0, -1.0, 0.0], atol=1e-6,
+ )
+ np.testing.assert_allclose(realigned[:3], before[pivot, :3], atol=1e-6)
+
+ def test_velocity_matching_uses_the_authored_motion_direction(self):
+ primitive = VelocityMatchingSequenceBehavior(self.asset)
+ primitive.set_node_world_transform(
+ 0, wp.transform(wp.vec3(3.0, -2.0, 0.4), wp.quat_rpy(0.0, 0.0, 0.6)),
+ )
+ # Measured speed selects the moving Entry sequence; desired velocity
+ # independently determines how its authored -X direction aligns.
+ self.character.actual_velocity[:] = (1.0, 0.0, 0.0)
+ self.character.movement.desired_velocity[:] = (3.0, 4.0, 0.0)
+ self.machine.start_interaction(self.character, primitive)
+ transforms = wp.empty(primitive.node_count, dtype=wp.transform, device="cpu")
+ primitive.compute_world_transforms(transforms)
+ pivot = transforms.numpy()[primitive.sequence_pivot_node_index(primitive.sequence_index("Entry"))]
+ np.testing.assert_allclose(
+ wp.quat_rotate(wp.quat(*pivot[3:]), wp.vec3(-1.0, 0.0, 0.0)),
+ [0.6, 0.8, 0.0], atol=1e-6,
+ )
+
+ def test_sequence_to_looping_clip_to_sequence_waits_for_each_boundary(self):
+ self.machine.start_interaction(self.character, self.cycle)
+ self.machine.interact() # Input during the entry sequence is not queued.
+ self.state.update(self.character, self.machine, 0.016)
+ self.assertFalse(self.state.is_looping)
+ self.assertEqual(self.generated[0][1].num_poses_to_use, 4)
+ self.assertEqual(self.generated[0][1].allowed_token_counts, tuple(range(6, 15)))
+ self.character.start_clip.assert_not_called()
+
+ self.reach_target()
+ self.assertEqual(self.generated[1][1].num_poses_to_use, 1)
+ self.assertEqual(self.generated[1][1].allowed_token_counts, (8,))
+ self.assertFalse(self.state.is_looping)
+ self.character.start_clip.assert_not_called()
+ self.reach_target()
+ self.assertTrue(self.state.is_looping)
+ self.character.clear_ik_pins.assert_called()
+ self.character.start_clip.assert_called_once_with(
+ self.baked_clip,
+ loop=True, align_to_current_pose=True,
+ )
+ self.character.movement.input_speed = 2.0
+ for _ in range(3):
+ self.reach_target()
+ self.assertTrue(self.machine.is_interacting)
+ self.assertEqual(len(self.generated), 2)
+
+ self.machine.interact()
+ self.machine.interact() # Repeated input during the exit sequence is ignored.
+ self.assertFalse(self.state.is_looping)
+ self.assertEqual(len(self.generated), 3)
+ self.assertEqual(self.generated[2][1].num_poses_to_use, 4)
+ self.assertEqual(self.generated[2][1].allowed_token_counts, tuple(range(7, 13)))
+ self.reach_target()
+ self.reach_target() # No stale completion callback may run again.
+ self.assertIs(self.machine.state, self.machine.standing_locomotion_state)
+ self.machine.standing_locomotion_state.enter.assert_called_once()
+ self.assertIsNone(self.cycle._interaction_state)
+ self.character.clear_ik_pins.assert_called()
+
+ def test_default_behavior_preserves_target_order_and_inference_settings(self):
+ primitive = _OrderedTargets(self.asset)
+ self.machine.start_interaction(self.character, primitive)
+ self.state.update(self.character, self.machine, 0.016)
+ self.assertEqual(len(self.generated), 1)
+ self.reach_target()
+ self.assertEqual(len(self.generated), 2)
+ self.assertTrue(self.machine.is_interacting)
+ self.reach_target()
+ self.assertEqual(len(self.generated), 3)
+ self.assertTrue(self.machine.is_interacting)
+ self.assertEqual(
+ [(params.num_poses_to_use, params.transition_early_by_frames, params.allowed_token_counts)
+ for _, params in self.generated],
+ [(4, 7, tuple(range(7, 13))), (4, 3, tuple(range(6, 15))), (1, 0, (8,))],
+ )
+ expected = wp.empty((12, self.skeleton.num_joints), dtype=wp.transform, device="cpu")
+ primitive.get_world_target_poses_for_sequence(primitive.sequence_index("Exit"), expected[:4])
+ primitive.get_world_target_poses_for_sequence(primitive.sequence_index("Entry"), expected[4:])
+ for index, (poses, _) in enumerate(self.generated):
+ np.testing.assert_allclose(poses, expected.numpy()[index * 4 : (index + 1) * 4])
+ self.reach_target()
+ self.assertIs(self.machine.state, self.machine.standing_idle_state)
+ self.machine.standing_idle_state.enter.assert_called_once()
+
+ def test_non_looping_clip_returns_to_idle_when_its_end_is_within_the_step(self):
+ self.machine.start_interaction(self.character, self.cycle)
+ self.cycle.interaction_state.play_clip(self.cycle.clip_paths[0], loop=False)
+ self.assertFalse(self.state.is_looping)
+ self.character.clear_ik_pins.assert_called()
+ for _ in range(3):
+ self.reach_target() # A generated target's deadline cannot end this clip.
+ self.assertTrue(self.machine.is_interacting)
+ self.assertEqual(len(self.generated), 1)
+
+ self.character.clip_ends_within.return_value = True
+ self.state.update(self.character, self.machine, 0.016)
+ self.state.update(self.character, self.machine, 0.016)
+ self.assertIs(self.machine.state, self.machine.standing_idle_state)
+ self.machine.standing_idle_state.enter.assert_called_once()
+ self.character.face_pose.assert_called_once_with()
+ self.assertIsNone(self.cycle._interaction_state)
+
+ def test_sequence_to_one_shot_clip_to_sequence_preserves_callbacks(self):
+ completed = Mock()
+ self.cycle.enter = lambda: self.state.play_target_pose_sequence(
+ "Entry", on_complete=lambda: self.state.play_clip(
+ self.cycle.clip_paths[0], loop=False,
+ on_complete=lambda: self.state.play_target_pose_sequence("Exit", on_complete=completed),
+ ),
+ )
+ self.machine.start_interaction(self.character, self.cycle)
+ self.reach_target()
+ self.character.start_clip.assert_not_called()
+ self.reach_target()
+ self.character.start_clip.assert_called_once_with(
+ self.baked_clip, loop=False, align_to_current_pose=True,
+ )
+ self.character.clear_ik_pins.assert_called()
+ completed.assert_not_called()
+ self.state.update(self.character, self.machine, 0.016)
+ self.assertEqual(len(self.generated), 2)
+ self.character.clip_ends_within.return_value = True
+ self.state.update(self.character, self.machine, 0.016)
+ self.assertEqual(self.generated[-1][1].num_poses_to_use, 4)
+ self.assertEqual(len(self.generated), 3)
+ self.state.update(self.character, self.machine, 0.016)
+ completed.assert_not_called()
+ self.reach_target()
+ self.reach_target()
+ completed.assert_called_once_with()
+
+ def test_exit_cancels_pending_callbacks_and_allows_reusing_the_primitive(self):
+ self.machine.start_interaction(self.character, self.cycle)
+ with self.assertRaisesRegex(RuntimeError, "another is active"):
+ self.machine.start_interaction(self.character, self.cycle)
+ self.machine.resume_movement(self.character)
+ self.reach_target()
+ self.character.start_clip.assert_not_called()
+ self.assertIsNone(self.cycle._interaction_state)
+ self.assertIsNone(self.state.primitive)
+ self.character.clear_ik_pins.assert_called()
+ self.machine.start_interaction(self.character, self.cycle)
+ self.reach_target()
+ self.reach_target()
+ self.assertTrue(self.state.is_looping)
+ completed = Mock()
+ self.state.play_clip(self.cycle.clip_paths[0], loop=False, on_complete=completed)
+ self.machine.resume_movement(self.character)
+ self.character.clip_ends_within.return_value = True
+ self.reach_target()
+ completed.assert_not_called()
+ self.assertIsNone(self.cycle._interaction_state)
+ self.assertIsNone(self.state.primitive)
+
+ def test_failed_entry_releases_the_primitive_and_restores_movement(self):
+ self.character.generate_to_target_poses.side_effect = RuntimeError("inference failed")
+ with self.assertRaisesRegex(RuntimeError, "inference failed"):
+ self.machine.start_interaction(self.character, self.cycle)
+ self.assertIsNone(self.cycle._interaction_state)
+ self.assertFalse(self.machine.is_interacting)
+ self.character.clear_ik_pins.assert_called()
+ self.assertIs(self.machine.state, self.machine.standing_idle_state)
+
+ def test_viewer_routes_v_and_controller_x_once_and_rearms_auto_on_exit(self):
+ instance = SimpleNamespace(
+ definition=SimpleNamespace(id=10, name="TestInteraction"),
+ runtime=self.cycle,
+ interactable=True,
+ )
+ preview = ScenePreview.__new__(ScenePreview)
+ preview._scene_session = SimpleNamespace(
+ state_machine=self.machine, character=self.character,
+ smart_primitives=(instance,),
+ )
+ key = SimpleNamespace(down=False)
+ controller = SimpleNamespace(a=False, x=False, y=False, b=False)
+ preview._input = InputManager(lambda _: key.down)
+ preview._input._controller = controller
+ preview._interaction_down = False
+ preview._active_interaction = None
+ preview._nearest_interactable = instance
+ preview._auto_interaction_blocked = set()
+ preview.auto_interaction = True
+ preview._dispatch_interaction_input()
+ key.down = True
+ preview._dispatch_interaction_input() # A press during entry must not skip the loop.
+ self.reach_target()
+ self.reach_target()
+ for _ in range(3):
+ preview._dispatch_interaction_input()
+ self.assertTrue(self.state.is_looping)
+ preview._nearest_interactable = None # Manual input still reaches the active primitive.
+ controller.x = True
+ key.down = False
+ preview._dispatch_interaction_input() # Changing devices while held is not a new press.
+ self.assertTrue(self.state.is_looping)
+ controller.x = False
+ preview._dispatch_interaction_input()
+ controller.x = True
+ preview._dispatch_interaction_input()
+ self.assertFalse(self.state.is_looping)
+ self.assertEqual(len(self.generated), 3)
+ self.reach_target()
+ preview._nearest_interactable = instance
+ for _ in range(3):
+ preview._dispatch_interaction_input()
+ self.assertFalse(self.machine.is_interacting)
+ self.assertIs(self.machine.state, self.machine.standing_idle_state)
+ self.assertIsNone(preview._active_interaction)
+ instance.interactable = False
+ preview._nearest_interactable = None
+ preview._dispatch_interaction_input()
+ instance.interactable = True
+ preview._nearest_interactable = instance
+ preview._dispatch_interaction_input()
+ self.assertTrue(self.machine.is_interacting)
+ self.assertEqual(len(self.generated), 4)
+
+ def test_clip_playback_preserves_alignment_history_and_the_correct_ending(self):
+ source = wp.transform(wp.vec3(2.0, 1.0, -3.0), wp.quat_rpy(0.4, 0.2, 0.5))
+ reached = wp.transform(wp.vec3(8.0, -2.0, 1.7), wp.quat_rpy(0.1, 0.0, 1.9))
+ child = wp.transform(wp.vec3(0.5, 0.0, 0.0), wp.quat_identity())
+ local = np.array([[list(source), list(child)]] * 3, dtype=np.float32)
+ local[1, 0, 0] += 0.3
+ local[1, 1, 2] += 0.25
+ local[2, 0, 0] += 0.6
+ local[2, 1, 2] += 0.2
+ skeleton = SimpleNamespace(
+ num_joints=2,
+ reference_local_transforms=wp.array(local[0], dtype=wp.transform),
+ )
+ for loop in (False, True):
+ with self.subTest(loop=loop):
+ animation = AnimationBuffer(skeleton, 30.0, wp.array(local, dtype=wp.transform))
+ character = SOMACharacter.__new__(SOMACharacter)
+ character.engine = SimpleNamespace(stream=None)
+ character.clip_registry = ClipRegistry(ModelRig.SOMA, skeleton=skeleton)
+ character.model_to_runtime = wp.transform_identity()
+ with patch.object(character.clip_registry, "load", return_value=ClipAsset(Path("test.bvh"), animation)):
+ clip = character.load_clip(Path("test.bvh"), loop=loop)
+ prepared = clip.animation.poses.numpy().copy()
+ if loop:
+ np.testing.assert_allclose(prepared[-1], prepared[0], atol=1e-6)
+ else:
+ np.testing.assert_array_equal(prepared, local)
+
+ character.current_pose = wp.array([reached, child], dtype=wp.transform)
+ character.current_foot_contacts = wp.full(4, 0.5, dtype=wp.float32)
+ character.character_ground_position = np.array([8.0, -2.0, 0.0], dtype=np.float32)
+ character.actual_velocity = np.zeros(3, dtype=np.float32)
+ character.state_machine = SimpleNamespace(update=Mock())
+ character._update_probe_box = Mock()
+ player = GeneratedMotionPlayer.__new__(GeneratedMotionPlayer)
+ player.engine = character.engine
+ player.motion_history = MotionRecorder(skeleton.reference_local_transforms, capacity=8)
+ player.record_pose(1.0 / 30.0, character.current_pose)
+ character.player = player
+ history_before = player.motion_history.poses.numpy().copy()
+ times_before = player.motion_history.delta_times.copy()
+
+ character.start_clip(clip, loop=loop, align_to_current_pose=True)
+
+ np.testing.assert_allclose(character.current_pose.numpy()[0], list(reached), atol=1e-6)
+ np.testing.assert_allclose(character.current_pose.numpy()[1], list(child), atol=1e-6)
+ np.testing.assert_array_equal(player.motion_history.poses.numpy(), history_before)
+ np.testing.assert_array_equal(player.motion_history.delta_times, times_before)
+ self.assertFalse(character.clip_ends_within(0.0))
+ character.step(1.0 / 30.0, None)
+ self.assertGreater(float(character.current_pose.numpy()[1, 2]), 0.1)
+ # Baked clips have no predicted contacts.
+ np.testing.assert_array_equal(character.current_foot_contacts.numpy(), 0.0)
+ self.assertFalse(character.clip_ends_within(0.0))
+
+ character.step(1.0 / 30.0, None)
+ self.assertEqual(character.clip_ends_within(0.0), not loop)
+ end_frame = 0 if loop else -1
+ expected_hips = wp.mul(
+ clip.root_offset, wp.transform(*prepared[end_frame, 0]),
+ )
+ for _ in range(2):
+ np.testing.assert_allclose(
+ character.current_pose.numpy()[0], list(expected_hips), atol=1e-6,
+ )
+ np.testing.assert_allclose(
+ character.current_pose.numpy()[1], prepared[end_frame, 1], atol=1e-6,
+ )
+ # Looping wraps; one-shot playback holds its original final pose.
+ character.step(clip.duration, None)
+ np.testing.assert_array_equal(animation.poses.numpy(), local)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_state_machine.py b/tests/app/test_state_machine.py
new file mode 100644
index 0000000..ca475b1
--- /dev/null
+++ b/tests/app/test_state_machine.py
@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import numpy as np
+import warp as wp
+
+from app.runtime.common.motion import (
+ CROUCH_LOCOMOTION_MODE,
+ DIRECTIONAL_LOCOMOTION_MODE,
+ LINEAR_LOCOMOTION_MODE,
+ LocomotionCommand,
+ LocomotionMode,
+)
+from app.runtime.common.state_machine import StateMachine
+from app.runtime.common.states import State
+from motionbricks.runtime.blend_spaces import BlendSpaceType
+
+
+def _command(requested_mode: str | None = None) -> LocomotionCommand:
+ return LocomotionCommand(
+ facing_direction=np.array([1.0, 0.0, 0.0], dtype=np.float32),
+ movement=None,
+ requested_mode=requested_mode,
+ )
+
+
+class StateMachineTests(unittest.TestCase):
+ def setUp(self) -> None:
+ self.modes = tuple(LocomotionMode(
+ name, Path("unused.smart_primitive.json"), blend_type, (("Idle", (0, 0)),),
+ max_speed=1., default_speed=1.,
+ ) for name, blend_type in (
+ (LINEAR_LOCOMOTION_MODE, BlendSpaceType.LINEAR_1D),
+ (DIRECTIONAL_LOCOMOTION_MODE, BlendSpaceType.DIRECTIONAL_2D),
+ (CROUCH_LOCOMOTION_MODE, BlendSpaceType.DIRECTIONAL_2D),
+ ("zombie_1d", BlendSpaceType.LINEAR_1D),
+ ("skipping_1d", BlendSpaceType.LINEAR_1D),
+ ))
+ self.machine = self._machine()
+
+ def _machine(self, initial_mode: str = LINEAR_LOCOMOTION_MODE) -> StateMachine:
+ return StateMachine(
+ tuple(SimpleNamespace(definition=mode) for mode in self.modes),
+ initial_mode,
+ standing_idle_clips=(object(),),
+ crouching_idle_clips=(object(),),
+ pose=wp.empty(1, dtype=wp.transform, device="cpu"),
+ )
+
+ def test_transition_calls_exit_before_enter_and_skips_the_active_state(self) -> None:
+ events = []
+ character = object()
+ previous = Mock(spec=State)
+ next_state = Mock(spec=State)
+ previous.exit.side_effect = lambda *_: events.append("exit")
+ next_state.enter.side_effect = lambda *_: events.append("enter")
+ self.machine._state = previous
+
+ self.machine.transition_to(character, next_state)
+ self.assertEqual(events, ["exit", "enter"])
+ self.assertIs(self.machine.state, next_state)
+
+ self.machine.transition_to(character, next_state)
+ next_state.exit.assert_not_called()
+ next_state.enter.assert_called_once()
+
+ def test_mode_request_does_not_interrupt_interaction_and_selects_the_resume_pair(self) -> None:
+ standing_mode, crouch_mode = self.modes[0], self.modes[2]
+ character = SimpleNamespace(movement=Mock(input_speed=0.0))
+ interaction = self.machine.interaction_state
+ crouching = self.machine.crouching_locomotion_state
+ crouching.enter = Mock()
+ interaction.update = Mock()
+ interaction.exit = Mock()
+ self.machine._state = interaction
+ command = _command(CROUCH_LOCOMOTION_MODE)
+
+ self.machine.update(character, 0.1, command)
+
+ self.assertIs(self.machine.state, interaction)
+ self.assertIs(self.machine.active_locomotion_state, crouching)
+ interaction.update.assert_called_once_with(character, self.machine, 0.1)
+ # Movement keeps smoothing during the interaction, easing from the standing mode into Crouching.
+ character.movement.update.assert_called_once_with(command, crouch_mode, 0.1, standing_mode)
+
+ character.movement.input_speed = 2.0
+ self.machine.resume_movement(character)
+
+ self.assertIs(self.machine.state, crouching)
+ interaction.exit.assert_called_once_with(character, self.machine)
+ crouching.enter.assert_called_once_with(character, self.machine)
+
+ def test_extra_modes_are_standing_styles_that_share_the_standing_idle(self) -> None:
+ machine = self._machine(CROUCH_LOCOMOTION_MODE)
+ standing = machine.standing_locomotion_state
+ self.assertEqual(machine.style_modes, ("zombie_1d", "skipping_1d"))
+ self.assertEqual(
+ list(standing.mode_runtimes),
+ [LINEAR_LOCOMOTION_MODE, DIRECTIONAL_LOCOMOTION_MODE, "zombie_1d", "skipping_1d"],
+ )
+
+ # Picking a style while crouched stands the character up into the standing idle.
+ character = SimpleNamespace(movement=Mock(input_speed=0.0))
+ machine.crouching_idle_state.exit = Mock()
+ machine.standing_idle_state.enter = Mock()
+ machine.standing_idle_state.update = Mock()
+ self.assertIs(machine.state, machine.crouching_idle_state)
+
+ machine.update(character, 0.1, _command("zombie_1d"))
+
+ self.assertEqual(standing.active_mode.name, "zombie_1d")
+ self.assertIs(machine.active_locomotion_state, standing)
+ self.assertIs(machine.state, machine.standing_idle_state)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/app/test_viewer_gizmos.py b/tests/app/test_viewer_gizmos.py
new file mode 100644
index 0000000..a24863b
--- /dev/null
+++ b/tests/app/test_viewer_gizmos.py
@@ -0,0 +1,200 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from collections import defaultdict
+from functools import partial
+from types import SimpleNamespace
+import unittest
+
+import newton
+import numpy as np
+import warp as wp
+from imgui_bundle import imgui, imguizmo
+from newton._src.viewer.viewer_gui import ViewerGui
+from pyglet.math import Mat4, Vec3
+
+from app.authoring.common import NewtonViewerUIBridge, log_transform_gizmo
+from app.runtime.common.io.scene_document import SceneDefinition
+from app.runtime.common.io.smart_primitive_document import SmartPrimitiveDocument
+from app.scene_editor import SceneEditor
+from app.smart_primitive_editor import SmartPrimitiveEditor
+
+
+class ViewerGizmoTests(unittest.TestCase):
+ """Exercise native ImGuizmo drawing/input without a GL window or model engine."""
+
+ def setUp(self):
+ self.context = imgui.create_context()
+ self.io = imgui.get_io()
+ self.io.set_ini_filename("")
+ self.io.display_size = (1920, 1080)
+ self.io.delta_time = 1 / 60
+ self.io.mouse_double_click_time = 0.001
+ self.io.backend_flags |= imgui.BackendFlags_.renderer_has_textures
+ view = np.array(Mat4.look_at(Vec3(4, -7, 8), Vec3(0, 0, 0), Vec3(0, 0, 1)))
+ projection = np.array(Mat4.perspective_projection(1920 / 1080, 0.01, 100, 45))
+ self.viewer = SimpleNamespace(
+ camera=SimpleNamespace(get_view_matrix=lambda: view, get_projection_matrix=lambda: projection),
+ _gizmo_log={},
+ gizmo_is_using=False,
+ )
+ self.viewer.log_gizmo = partial(newton.viewer.ViewerGL.log_gizmo, self.viewer)
+ gui = ViewerGui.__new__(ViewerGui)
+ gui._viewer = self.viewer
+ gui._gizmo_active = {}
+ gui.ui = SimpleNamespace(imgui=imgui, giz=imguizmo.im_guizmo, io=self.io, is_available=True)
+ self.viewer.gui = gui
+ self.bridge = NewtonViewerUIBridge(self.viewer)
+ self.bridge.install(imgui)
+
+ def tearDown(self):
+ self.io.add_mouse_button_event(0, False)
+ self.draw()
+ self.viewer._gizmo_log.clear()
+ self.draw()
+ imgui.destroy_context(self.context)
+
+ def draw(self):
+ imgui.new_frame()
+ imguizmo.im_guizmo.begin_frame()
+ imguizmo.im_guizmo.set_drawlist(imgui.get_background_draw_list())
+ self.bridge._render_gizmos()
+ vertices = defaultdict(list)
+ for vertex in imgui.get_background_draw_list().vtx_buffer:
+ vertices[vertex.col].append((vertex.pos.x, vertex.pos.y))
+ imgui.render()
+ return vertices
+
+ def drag(self, start, end):
+ for position, down in ((start, False), (start, True), (end, True), (end, False)):
+ self.io.add_mouse_pos_event(*position)
+ self.io.add_mouse_button_event(0, down)
+ for _ in range(2):
+ self.draw()
+ self.assertEqual(self.viewer.gizmo_is_using, down)
+
+ def test_editor_locks_show_only_available_planes_and_keep_rotation_independent(self):
+ editor = SmartPrimitiveEditor.__new__(SmartPrimitiveEditor)
+ editor.viewer = self.viewer
+ editor.authoring = SmartPrimitiveDocument("soma", SimpleNamespace(), wp.transform_identity())
+ editor.selected_id = editor.authoring.root.id
+ # ImGuizmo's default plane fills and axis/ring colors, ordered by normal X/Y/Z.
+ plane_colors = (0x610000AA, 0x6100AA00, 0x61AA0000)
+ axis_colors = (0xFF0000AA, 0xFF00AA00, 0xFFAA0000)
+ for translation_locks, rotation_locks in (
+ ((False, False, False), (False, False, False)),
+ ((True, False, False), (False, True, False)),
+ ((False, True, True), (True, False, True)),
+ ((True, True, True), (False, False, False)),
+ ):
+ with self.subTest(translation=translation_locks, rotation=rotation_locks):
+ editor.selected.translation_locks = list(translation_locks)
+ editor.selected.rotation_locks = list(rotation_locks)
+ editor._draw_selection_gizmo()
+ vertices = self.draw()
+ for normal in range(3):
+ available = not any(translation_locks[axis] for axis in range(3) if axis != normal)
+ self.assertEqual(len(vertices[plane_colors[normal]]), 4 if available else 0)
+ # A ring has many more vertices than the arrow and square outlines.
+ self.assertEqual(len(vertices[axis_colors[normal]]) >= 64, not rotation_locks[normal])
+
+ def test_plane_and_center_drags_preserve_the_locked_coordinate(self):
+ for normal, plane_color in enumerate((0x610000AA, 0x6100AA00, 0x61AA0000)):
+ for handle in ("plane", "center"):
+ with self.subTest(normal=normal, handle=handle):
+ transform = wp.transform(wp.vec3(0.2, 0.3, 0.4), wp.quat_identity())
+ self.viewer._gizmo_log.clear()
+ log_transform_gizmo(
+ self.viewer, "pose", transform,
+ translation_locks=[axis == normal for axis in range(3)],
+ rotation_locks=[True, True, True],
+ )
+ self.io.add_mouse_pos_event(10, 1000)
+ vertices = self.draw()
+ color = plane_color if handle == "plane" else 0xFFFFFFFF
+ cursor = np.mean(vertices[color], axis=0)
+ before = np.asarray(transform).copy()
+ self.drag(cursor, cursor + [35, 15])
+ after = np.asarray(transform)
+ self.assertEqual(after[normal], before[normal])
+ for axis in range(3):
+ if axis != normal:
+ self.assertGreater(abs(after[axis] - before[axis]), 1e-4)
+ np.testing.assert_allclose(after[3:], before[3:], atol=1e-6)
+
+ def scene_editor_child(self, translation_locks, rotation_locks):
+ """Select a cube under a Smart Primitive that is turned 90 degrees, and draw its gizmo."""
+ editor = SceneEditor.__new__(SceneEditor)
+ editor.viewer = self.viewer
+ editor.scene = SceneDefinition()
+ editor._runtime_views = {}
+ editor._gizmo_item_id = editor._gizmo_transform = editor._gizmo_source_transform = None
+ parent, child = editor.scene.add_smart_primitive(), editor.scene.add_solid_cube()
+ parent.transform = wp.transform(
+ wp.vec3(0.5, 0.0, 0.0), wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), 0.5 * wp.pi),
+ )
+ child.parent_id = parent.id
+ child.transform = wp.transform(wp.vec3(0.3, 0.0, 0.2), wp.quat_identity())
+ editor.selected_item_id = child.id
+ editor._transform_locks = {child.id: (translation_locks, rotation_locks)}
+ editor._draw_selection_gizmo()
+ self.io.add_mouse_pos_event(10, 1000)
+ return editor, child, self.draw()
+
+ def test_child_handles_follow_a_rotated_parent_and_keep_its_locked_axis(self):
+ editor, child, vertices = self.scene_editor_child([True, False, False], [True, True, True])
+ # With local X locked, only the plane across the parent's Y and Z axes remains.
+ self.assertEqual(len(vertices[0x610000AA]), 4)
+ self.assertEqual(len(vertices[0x6100AA00]) + len(vertices[0x61AA0000]), 0)
+ before = np.asarray(child.transform).copy()
+ world_before = np.asarray(editor.scene.world_transform(child)).copy()
+ cursor = np.mean(vertices[0x610000AA], axis=0)
+ self.drag(cursor, cursor + [35, 15])
+ editor._apply_selection_gizmo()
+ after = np.asarray(child.transform)
+ world_after = np.asarray(editor.scene.world_transform(child))
+ self.assertEqual(after[0], before[0])
+ self.assertGreater(abs(after[1] - before[1]), 1e-2)
+ # The parent's X axis points along the scene's Y axis and its Y axis along -X.
+ self.assertAlmostEqual(world_after[1], world_before[1], places=5)
+ self.assertGreater(abs(world_after[0] - world_before[0]), 1e-2)
+ np.testing.assert_allclose(after[3:], before[3:], atol=1e-6)
+
+ def test_child_rotation_ring_turns_about_the_parent_axis(self):
+ editor, child, vertices = self.scene_editor_child([True, True, True], [False, True, True])
+ ring = np.asarray(vertices[0xFF0000AA])
+ self.assertGreaterEqual(len(ring), 64)
+ start = ring[np.argmax(ring[:, 0])]
+ self.drag(start, start + [0, 40])
+ editor._apply_selection_gizmo()
+ roll, pitch, yaw = (float(value) for value in wp.quat_to_rpy(wp.quat(*np.asarray(child.transform)[3:])))
+ self.assertGreater(abs(roll), np.radians(1.0))
+ self.assertAlmostEqual(pitch, 0.0, places=5)
+ self.assertAlmostEqual(yaw, 0.0, places=5)
+
+ def test_masks_do_not_leak_between_gizmos_or_outside_the_bridge(self):
+ for name, position, translation_locks in (
+ ("xy", (-1, 0, 0), [False, False, True]),
+ ("yz", (1, 0, 0), [True, False, False]),
+ ):
+ log_transform_gizmo(
+ self.viewer, name, wp.transform(wp.vec3(*position), wp.quat_identity()),
+ translation_locks=translation_locks, rotation_locks=[True, True, True],
+ )
+ vertices = self.draw()
+ self.assertEqual(len(vertices[0x610000AA]), 4)
+ self.assertEqual(len(vertices[0x6100AA00]), 0)
+ self.assertEqual(len(vertices[0x61AA0000]), 4)
+ self.assertIs(self.viewer.gui.ui.giz, imguizmo.im_guizmo)
+
+ self.viewer._gizmo_log.clear()
+ self.viewer.log_gizmo("unlocked", wp.transform_identity(), rotate=())
+ # Bypass the bridge to verify that native global mask state was restored.
+ self.bridge._render_gizmos = self.bridge._gizmos_callback
+ vertices = self.draw()
+ for color in (0x610000AA, 0x6100AA00, 0x61AA0000):
+ self.assertEqual(len(vertices[color]), 4)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/examples/test_examples.py b/tests/examples/test_examples.py
new file mode 100644
index 0000000..477b970
--- /dev/null
+++ b/tests/examples/test_examples.py
@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""The example scripts compile, and with a GPU they run for both rigs.
+
+Running them loads the real engines, so it needs an NVIDIA GPU. The first run builds the engines
+into .trt-cache, which takes several minutes. Set the MOTIONBRICKS_ENGINE_TESTS environment
+variable to 1 to run them.
+"""
+
+import os
+import re
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[2]
+_EXAMPLES = _REPO / "docs" / "examples"
+
+
+class ExampleSourceTests(unittest.TestCase):
+ def test_every_example_compiles(self):
+ for path in sorted(_EXAMPLES.glob("*.py")):
+ with self.subTest(example=path.name):
+ compile(path.read_text(encoding="utf-8"), str(path), "exec")
+
+
[email protected](os.environ.get("MOTIONBRICKS_ENGINE_TESTS") == "1", "set MOTIONBRICKS_ENGINE_TESTS=1 to run")
+class ExampleRunTests(unittest.TestCase):
+ def run_example(self, name, model):
+ result = subprocess.run(
+ [sys.executable, "-u", str(_EXAMPLES / name), "--model", model],
+ cwd=_REPO, capture_output=True, text=True, timeout=1800,
+ )
+ self.assertEqual(result.returncode, 0, result.stderr)
+ return result.stdout
+
+ def test_generate_once_chains_two_generations(self):
+ for model in ("soma", "unitree_g1"):
+ with self.subTest(model=model):
+ lines = re.findall(r"generated (\d+) frames", self.run_example("generate_once.py", model))
+ self.assertEqual(len(lines), 2)
+ for frames in lines:
+ # One generation makes 18 to 58 valid frames.
+ self.assertTrue(18 <= int(frames) <= 58)
+
+ def test_locomotion_loop_turns_left(self):
+ for model in ("soma", "unitree_g1"):
+ with self.subTest(model=model):
+ output = self.run_example("locomotion_loop.py", model)
+ roots = [
+ [float(value) for value in match]
+ for match in re.findall(r"root \[\s*(-?[\d.]+)\s+(-?[\d.]+)\s*\]", output)
+ ]
+ # It walks along +X first, then bends toward +Y.
+ self.assertGreater(roots[3][0], 1.5)
+ self.assertGreater(roots[-1][1], 3.0)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_animation_blending.py b/tests/motionbricks/test_animation_blending.py
new file mode 100644
index 0000000..459ea6d
--- /dev/null
+++ b/tests/motionbricks/test_animation_blending.py
@@ -0,0 +1,256 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Indexed pose/DOF blending on synthetic data, independent of models and clips."""
+
+import itertools
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.runtime.blend_spaces import (
+ BlendSample,
+ BlendSpace,
+ BlendSpaceType,
+ directional_2d_dof_blend,
+ directional_2d_pose_blend,
+ linear_1d_dof_blend,
+ linear_1d_pose_blend,
+ prepare_directional_poses,
+)
+
+
+def _space(space_type, values, *, data_indices=None, device=None):
+ space = BlendSpace(space_type, device=device)
+ indices = range(len(values)) if data_indices is None else data_indices
+ for value, index in zip(values, indices):
+ space.add_target(wp.vec2(*value), index)
+ space.compile()
+ return space
+
+
+def _rotation(degrees):
+ half_angle = np.deg2rad(degrees) * 0.5
+ return np.array([0, 0, np.sin(half_angle), np.cos(half_angle)], dtype=np.float32)
+
+
+def _sources(frame_count=3):
+ # Unregistered entries deliberately have invalid data; zero weights must skip them.
+ poses = np.full((5, frame_count, 2, 7), np.nan, dtype=np.float32)
+ dofs = np.full((5, frame_count, 9), np.nan, dtype=np.float32)
+ for target, position, angle, hinges in ((1, 2, 0, (-2.8, 1.2)), (4, 10, 120, (2.8, -0.4))):
+ for frame in range(frame_count):
+ for joint in range(2):
+ poses[target, frame, joint, :3] = [position + frame + joint, 2 * frame, 1 + joint]
+ poses[target, frame, joint, 3:] = _rotation(angle + frame * 10 + joint * 20)
+ dofs[target, frame, :7] = poses[target, frame, 0]
+ dofs[target, frame, 7:] = np.asarray(hinges) + frame * 0.1
+ return poses, dofs
+
+
+def _sample(indices, weights):
+ sample = BlendSample()
+ sample.data_indices = wp.array(indices, dtype=wp.int32)
+ sample.indices = wp.vec3i(*(list(range(len(indices))) + [0] * (3 - len(indices))))
+ sample.weights = wp.vec3(*(list(weights) + [0.0] * (3 - len(weights))))
+ sample.uniform_weight = 0.0
+ return sample
+
+
+def _assert_rotations(actual, expected):
+ np.testing.assert_allclose(np.linalg.norm(actual, axis=-1), 1, atol=2e-6)
+ np.testing.assert_allclose(np.abs(np.sum(actual * expected, axis=-1)), 1, atol=2e-6)
+
+
+class AnimationBlendingTests(unittest.TestCase):
+ device = "cpu"
+
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ if cls.device == "cuda:0" and not wp.is_cuda_available():
+ raise unittest.SkipTest("CUDA is not available.")
+ cls.previous_device = wp.get_device()
+ wp.set_device(cls.device)
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_same_linear_weights_blend_pose_and_dof_windows_with_slerp(self):
+ poses, dofs = _sources()
+ pose_data = wp.array(poses, dtype=wp.transform)
+ dof_data = wp.array(dofs, dtype=wp.float32)
+ # Registration order is deliberately different from the parameter order.
+ space = _space(BlendSpaceType.LINEAR_1D, ((1, 0), (0, 0), (2, 0)), data_indices=(4, 1, 3))
+ pose_output = wp.array(np.full((5, 2, 7), 99, dtype=np.float32), dtype=wp.transform)
+ dof_output = wp.full((5, 9), 99.0, dtype=wp.float32)
+
+ for blend in (0.25, 0.0, 0.75, 1.0):
+ sample = space.evaluate(wp.vec2(blend, 0))
+ linear_1d_pose_blend(pose_data, sample, pose_output)
+ linear_1d_dof_blend(dof_data, sample, dof_output)
+ expected_poses = poses[1] * (1 - blend) + poses[4] * blend
+ for frame in range(3):
+ for joint in range(2):
+ expected_poses[frame, joint, 3:] = _rotation(blend * 120 + frame * 10 + joint * 20)
+ actual_poses = pose_output.numpy()
+ actual_dofs = dof_output.numpy()
+ np.testing.assert_allclose(actual_poses[:3, :, :3], expected_poses[:, :, :3], atol=1e-6)
+ _assert_rotations(actual_poses[:3, :, 3:], expected_poses[:, :, 3:])
+ np.testing.assert_allclose(actual_dofs[:3, :3], expected_poses[:, 0, :3], atol=1e-6)
+ _assert_rotations(actual_dofs[:3, 3:7], expected_poses[:, 0, 3:])
+ expected_hinges = dofs[1, :, 7:] * (1 - blend) + dofs[4, :, 7:] * blend
+ np.testing.assert_allclose(actual_dofs[:3, 7:], expected_hinges, atol=1e-6)
+ np.testing.assert_array_equal(actual_poses[3:], 99)
+ np.testing.assert_array_equal(actual_dofs[3:], 99)
+ np.testing.assert_array_equal(pose_data.numpy(), poses)
+ np.testing.assert_array_equal(dof_data.numpy(), dofs)
+
+ def test_additive_blending_preserves_quaternion_accumulation_and_reference_fallback(self):
+ poses, dofs = _sources()
+ poses[4, ..., 3:] *= -1
+ dofs[4, :, 3:7] *= -1
+ pose_reference = np.zeros((2, 7), dtype=np.float32)
+ pose_reference[:, 0] = 4
+ pose_reference[:, 3:] = _rotation(40)
+ dof_reference = np.concatenate([pose_reference[0], [0.3, -0.5]]).astype(np.float32)
+ pose_output = wp.array(np.full((5, 2, 7), 99, dtype=np.float32), dtype=wp.transform)
+ dof_output = wp.full((5, 9), 99.0, dtype=wp.float32)
+
+ prepared = wp.array(poses, dtype=wp.transform)
+ reference = wp.array(pose_reference, dtype=wp.transform)
+ prepare_directional_poses(prepared, reference)
+ for first, second in ((0.75, 0.25), (0.25, 0.25), (0.0, 0.0)):
+ sample = _sample([1, 3, 4], [first, 0, second])
+ directional_2d_pose_blend(prepared, sample, reference, pose_output)
+ directional_2d_dof_blend(wp.array(dofs, dtype=wp.float32), sample,
+ wp.array(dof_reference, dtype=wp.float32), dof_output)
+
+ missing = 1 - first - second
+ expected = poses[1] * first + poses[4] * second + pose_reference * missing
+ rotations = poses[1, ..., 3:] * first - poses[4, ..., 3:] * second + pose_reference[:, 3:] * missing
+ rotations /= np.linalg.norm(rotations, axis=-1, keepdims=True)
+ actual_poses = pose_output.numpy()
+ actual_dofs = dof_output.numpy()
+ np.testing.assert_allclose(actual_poses[:3, :, :3], expected[..., :3], atol=1e-6)
+ _assert_rotations(actual_poses[:3, :, 3:], rotations)
+ np.testing.assert_allclose(actual_dofs[:3, :3], expected[:, 0, :3], atol=1e-6)
+ _assert_rotations(actual_dofs[:3, 3:7], rotations[:, 0])
+ expected_hinges = dofs[1, :, 7:] * first + dofs[4, :, 7:] * second + dof_reference[7:] * missing
+ np.testing.assert_allclose(actual_dofs[:3, 7:], expected_hinges, atol=1e-6)
+ np.testing.assert_array_equal(actual_poses[3:], 99)
+ np.testing.assert_array_equal(actual_dofs[3:], 99)
+
+ # Three far apart root rotations align each sign with the running sum.
+ # The 120 degree target comes last and flips.
+ data = np.zeros((3, 1, 8), dtype=np.float32)
+ data[:, 0, 3:7] = [_rotation(angle) for angle in (0, 120, -120)]
+ data[:, 0, 7] = [0, 1, 2]
+ source = wp.array(data, dtype=wp.float32)
+ output = wp.empty((1, 8), dtype=wp.float32)
+ directional_2d_dof_blend(source, _sample([0, 2, 1], [0.2, 0.5, 0.3]), source[0][0], output)
+ expected = data[0, 0, 3:7] * 0.2 + data[2, 0, 3:7] * 0.5 - data[1, 0, 3:7] * 0.3
+ _assert_rotations(output.numpy()[0, 3:7], expected / np.linalg.norm(expected))
+ self.assertAlmostEqual(float(output.numpy()[0, 7]), 1.3, places=6)
+
+ def test_more_than_three_targets_share_the_same_pose_and_dof_root_math(self):
+ space = _space(
+ BlendSpaceType.DIRECTIONAL_2D, ((1, 0), (0, 1), (-1, 0), (0, -1)),
+ data_indices=(5, 0, 4, 2),
+ )
+ poses = np.zeros((7, 2, 1, 7), dtype=np.float32)
+ poses[..., 6] = 1
+ dofs = np.zeros((7, 2, 8), dtype=np.float32)
+ samples = zip((5, 0, 4, 2), ((1, 0), (0, 1), (-1, 0), (0, -1)), (0, 30, -45, 60))
+ for target, (index, key, angle) in enumerate(samples):
+ poses[index, :, 0, 0] = target * 4
+ poses[index, :, 0, 3:] = _rotation(angle)
+ dofs[index, :, :7] = poses[index, :, 0]
+ dofs[index, :, 7] = target
+ pose_output = wp.empty((2, 1), dtype=wp.transform)
+ dof_output = wp.empty((2, 8), dtype=wp.float32)
+ sample = space.evaluate(wp.vec2(0.25, 0.25))
+
+ prepared = wp.array(poses, dtype=wp.transform)
+ reference = wp.array(poses[0, 0], dtype=wp.transform)
+ prepare_directional_poses(prepared, reference)
+ directional_2d_pose_blend(prepared, sample, reference, pose_output)
+ directional_2d_dof_blend(wp.array(dofs, dtype=wp.float32), sample,
+ wp.array(dofs[0, 0], dtype=wp.float32), dof_output)
+
+ expected_weights = np.array([0.375, 0.375, 0.125, 0.125])
+ expected_position = expected_weights @ [0, 4, 8, 12]
+ expected_rotation = expected_weights @ np.array([_rotation(angle) for angle in (0, 30, -45, 60)])
+ expected_rotation /= np.linalg.norm(expected_rotation)
+ np.testing.assert_allclose(pose_output.numpy()[:, 0, 0], expected_position)
+ _assert_rotations(pose_output.numpy()[:, 0, 3:], expected_rotation)
+ np.testing.assert_allclose(dof_output.numpy()[:, :7], pose_output.numpy()[:, 0], atol=1e-6)
+ np.testing.assert_allclose(dof_output.numpy()[:, 7], expected_weights @ [0, 1, 2, 3])
+
+ def test_skeletal_directional_signs_use_each_default_joint_and_ignore_sample_order(self):
+ poses = np.zeros((3, 1, 2, 7), dtype=np.float32)
+ rotations = np.array([_rotation(angle) for angle in (0, 120, -120)])
+ poses[:, 0, :, 3:] = rotations[:, None]
+ poses[1, ..., 3:] *= -1
+ poses[:, 0, :, 0] = np.arange(3)[:, None]
+ reference = np.zeros((2, 7), dtype=np.float32)
+ reference[:, 3:] = [_rotation(0), _rotation(80)]
+ prepared = wp.array(poses, dtype=wp.transform)
+ reference_array = wp.array(reference, dtype=wp.transform)
+ prepare_directional_poses(prepared, reference_array)
+ expected_rotations = []
+ for joint in range(2):
+ signed = rotations.copy()
+ signed[signed @ reference[joint, 3:] < 0] *= -1
+ total = np.array([0.2, 0.3, 0.5]) @ signed
+ expected_rotations.append(total / np.linalg.norm(total))
+ keys = ((0, 0), (1, 0), (0, 1))
+ output = wp.empty((1, 2), dtype=wp.transform)
+ for order in itertools.permutations(range(3)):
+ space = _space(
+ BlendSpaceType.DIRECTIONAL_2D, [keys[index] for index in order],
+ data_indices=order,
+ )
+ directional_2d_pose_blend(prepared, space.evaluate(wp.vec2(0.3, 0.5)), reference_array, output)
+ _assert_rotations(output.numpy()[0, :, 3:], np.asarray(expected_rotations))
+ np.testing.assert_allclose(output.numpy()[0, :, 0], 1.3)
+ np.testing.assert_array_equal(prepared.numpy()[..., :3], poses[..., :3])
+ _assert_rotations(prepared.numpy()[..., 3:], poses[..., 3:])
+
+ def test_output_layout_errors_are_reported_before_launch(self):
+ poses, dofs = _sources()
+ sample = _sample([1], [1])
+ with self.assertRaisesRegex(ValueError, "capacity"):
+ linear_1d_pose_blend(wp.array(poses, dtype=wp.transform), sample,
+ wp.empty((2, 2), dtype=wp.transform))
+ with self.assertRaisesRegex(ValueError, "components"):
+ linear_1d_dof_blend(wp.array(dofs, dtype=wp.float32), sample,
+ wp.empty((3, 8), dtype=wp.float32))
+
+
+class CUDAAnimationBlendingTests(AnimationBlendingTests):
+ device = "cuda:0"
+
+ def test_compilation_and_both_blenders_use_the_data_device(self):
+ with wp.ScopedDevice("cpu"):
+ device = wp.get_device(self.device)
+ poses, dofs = _sources(frame_count=1)
+ pose_data = wp.array(poses, dtype=wp.transform, device=device)
+ dof_data = wp.array(dofs, dtype=wp.float32, device=device)
+ pose_output = wp.empty((1, 2), dtype=wp.transform, device=device)
+ dof_output = wp.empty((1, 9), dtype=wp.float32, device=device)
+ pose_reference = wp.array(poses[1, 0], dtype=wp.transform, device=device)
+ dof_reference = wp.array(dofs[1, 0], dtype=wp.float32, device=device)
+ space = _space(BlendSpaceType.DIRECTIONAL_2D, ((1, 0), (0, 1)), data_indices=(1, 4), device=device)
+ sample = space.evaluate(wp.vec2(0, 0))
+ prepare_directional_poses(pose_data, pose_reference)
+ directional_2d_pose_blend(pose_data, sample, pose_reference, pose_output)
+ directional_2d_dof_blend(dof_data, sample, dof_reference, dof_output)
+ np.testing.assert_allclose(pose_output.numpy()[0, 0, 0], 6.0)
+ np.testing.assert_allclose(dof_output.numpy()[0, :7], pose_output.numpy()[0, 0], atol=1e-6)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_blend_spaces.py b/tests/motionbricks/test_blend_spaces.py
new file mode 100644
index 0000000..f5c3222
--- /dev/null
+++ b/tests/motionbricks/test_blend_spaces.py
@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.runtime.blend_spaces import BlendSpace, BlendSpaceType
+
+
+def _space(space_type, values, *, data_indices=None):
+ space = BlendSpace(space_type)
+ indices = range(len(values)) if data_indices is None else data_indices
+ for value, index in zip(values, indices):
+ space.add_target(wp.vec2(*value), index)
+ space.compile()
+ return space
+
+
+def _weights(sample):
+ result = np.full(sample.data_indices.size, sample.uniform_weight)
+ for index, weight in zip(sample.indices, sample.weights):
+ result[index] += weight
+ return result
+
+
+class BlendSpaceTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_linear_sorts_keys_and_selects_the_ordered_pair(self):
+ space = _space(
+ BlendSpaceType.LINEAR_1D, ((2, 100), (0, -100), (10, 0)),
+ data_indices=(7, 4, 1),
+ )
+ pointer = space.data_indices.ptr
+ for value, expected in (
+ (-1.0, [0.0, 1.0, 0.0]),
+ (0.5, [0.25, 0.75, 0.0]),
+ (2.0, [1.0, 0.0, 0.0]),
+ (4.0, [0.75, 0.0, 0.25]),
+ (20.0, [0.0, 0.0, 1.0]),
+ ):
+ np.testing.assert_allclose(_weights(space.evaluate(wp.vec2(value, 999))), expected)
+ sample = space.evaluate(wp.vec2(0.5, 0))
+ self.assertEqual(tuple(sample.indices)[:2], (1, 0))
+ np.testing.assert_allclose(tuple(sample.weights)[:2], (0.75, 0.25))
+ np.testing.assert_array_equal(space.data_indices.numpy(), [7, 4, 1])
+ self.assertEqual(space.data_indices.ptr, pointer)
+ self.assertEqual(space.data_indices.device, wp.get_device("cpu"))
+
+ def test_directional_uses_center_surrounding_targets_and_clamps(self):
+ space = _space(
+ BlendSpaceType.DIRECTIONAL_2D, ((0, 0), (1, 0), (0, 1), (-1, 0), (0, -1)),
+ data_indices=(0, 2, 4, 6, 8),
+ )
+ for value, expected in (
+ ((0.0, 0.0), [1, 0, 0, 0, 0]),
+ ((0.25, 0.25), [0.5, 0.25, 0.25, 0, 0]),
+ ((2.0, 2.0), [0, 0.5, 0.5, 0, 0]),
+ ((1.0, 0.0), [0, 1, 0, 0, 0]),
+ ((0.0, -1.0), [0, 0, 0, 0, 1]),
+ ((-1.0, -0.0), [0, 0, 0, 1, 0]),
+ ((-0.25, -0.5), [0.25, 0, 0, 0.25, 0.5]),
+ ):
+ np.testing.assert_allclose(_weights(space.evaluate(wp.vec2(*value))), expected)
+ np.testing.assert_array_equal(space.data_indices.numpy(), [0, 2, 4, 6, 8])
+
+ def test_directional_preparation_handles_unequal_radii_and_unsorted_keys(self):
+ space = _space(
+ BlendSpaceType.DIRECTIONAL_2D, ((0, -0.5), (0, 3), (-1, 0), (2, 0), (0, 0)),
+ )
+ for value, expected in (
+ ((0.5, 0.75), [0, 0.25, 0, 0.25, 0.5]),
+ ((4, 6), [0, 0.5, 0, 0.5, 0]),
+ ((-0.25, -0.125), [0.25, 0, 0.25, 0, 0.5]),
+ ):
+ sample = space.evaluate(wp.vec2(*value))
+ np.testing.assert_allclose(_weights(sample), expected)
+ self.assertEqual(tuple(sample.indices), tuple(sorted(sample.indices)))
+
+ def test_directional_falls_back_for_open_and_collinear_sectors(self):
+ for keys in (((0, 0), (1, 0)), ((0, 0), (1, 0), (-1, 0))):
+ space = _space(BlendSpaceType.DIRECTIONAL_2D, keys)
+ for value in ((0, 1), (0, -1)):
+ np.testing.assert_array_equal(_weights(space.evaluate(wp.vec2(*value))), [1] + [0] * (len(keys) - 1))
+ space = _space(BlendSpaceType.DIRECTIONAL_2D, ((1, 0), (-1, 0)))
+ np.testing.assert_allclose(_weights(space.evaluate(wp.vec2(0, 1))), [0.5, 0.5])
+
+ def test_evaluation_requires_compiling_all_registered_targets(self):
+ space = BlendSpace(BlendSpaceType.LINEAR_1D)
+ space.add_target(wp.vec2(0, 0), 4)
+ with self.assertRaisesRegex(RuntimeError, "compile"):
+ space.evaluate(wp.vec2(0, 0))
+ space.compile()
+ np.testing.assert_array_equal(_weights(space.evaluate(wp.vec2(0, 0))), [1])
+ space.add_target(wp.vec2(1, 0), 8)
+ with self.assertRaisesRegex(RuntimeError, "compile"):
+ space.evaluate(wp.vec2(0.25, 0))
+ space.compile()
+ np.testing.assert_allclose(_weights(space.evaluate(wp.vec2(0.25, 0))), [0.75, 0.25])
+
+ def test_invalid_layouts_are_rejected_during_preparation(self):
+ for space_type, values, indices, message in (
+ (BlendSpaceType.LINEAR_1D, (), None, "without targets"),
+ (BlendSpaceType.LINEAR_1D, ((0, 0),), (-1,), "non-negative"),
+ (BlendSpaceType.LINEAR_1D, ((0, 0), (0, 1)), None, "must be unique"),
+ (BlendSpaceType.DIRECTIONAL_2D, ((0, 0), (0, 0)), None, "only one center"),
+ (BlendSpaceType.DIRECTIONAL_2D, ((1, 0), (2, 0)), None, "distinct directions"),
+ (BlendSpaceType.DIRECTIONAL_2D, ((1, float("nan")),), None, "finite"),
+ ):
+ with self.subTest(message=message), self.assertRaisesRegex(ValueError, message):
+ _space(space_type, values, data_indices=indices)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_bvh.py b/tests/motionbricks/test_bvh.py
new file mode 100644
index 0000000..31ef1eb
--- /dev/null
+++ b/tests/motionbricks/test_bvh.py
@@ -0,0 +1,338 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""BVH loading contracts, including channel order and downstream consumers."""
+
+import itertools
+from pathlib import Path
+import tempfile
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.bvh import load_bvh, load_skeleton_from_bvh
+
+
+def _write_motion(directory, order="ZXY", frames=2, root_angles=None):
+ # Position channels are deliberately interleaved and out of XYZ order.
+ # End Site offsets must not overwrite the preceding joint's offset.
+ hierarchy = f"""HIERARCHY
+ROOT actor:rig:Root
+{{
+ OFFSET 1 2 3
+ CHANNELS 6 Zposition {order[0]}rotation Xposition {order[1]}rotation Yposition {order[2]}rotation
+ JOINT actor:rig:Spine
+ {{
+ OFFSET 0 50 0
+ CHANNELS 3 Yrotation Zrotation Xrotation
+ JOINT actor:rig:Tip
+ {{
+ OFFSET 0 25 0
+ CHANNELS 0
+ End Site
+ {{
+ OFFSET 100 200 300
+ }}
+ }}
+ }}
+ JOINT actor:rig:Sibling
+ {{
+ OFFSET -10 0 0
+ CHANNELS 3 Xposition Yposition Zposition
+ }}
+}}
+MOTION
+Frames: {frames}
+Frame Time: 0.008333333333333333
+"""
+ samples = np.array([
+ [300, 20, 100, -35, -200, 65, 15, 25, -40, -10, 5, 7],
+ [-600, 55, -400, -10, 500, -15, -65, 10, 35, -12, 6, 8],
+ ], dtype=np.float32)[:frames]
+ if root_angles is not None:
+ samples[:, [1, 3, 5]] = root_angles[:frames]
+ path = directory / "motion.BVH"
+ with path.open("w", encoding="utf-8") as target:
+ target.write(hierarchy)
+ np.savetxt(target, samples, fmt="%.6f")
+ return path
+
+
+class _BVHTestCase(unittest.TestCase):
+ device = "cpu"
+
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ if cls.device == "cuda:0" and not wp.is_cuda_available():
+ raise unittest.SkipTest("CUDA is not available.")
+ cls.previous_device = wp.get_device()
+ wp.set_device(cls.device)
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def setUp(self) -> None:
+ directory = tempfile.TemporaryDirectory()
+ self.addCleanup(directory.cleanup)
+ self.directory = Path(directory.name)
+
+
+class BVHTests(_BVHTestCase):
+ def test_authored_channels_and_world_poses(self) -> None:
+ angle_cases = {
+ "ordinary": [(20, -35, 65), (55, -10, -15)],
+ "zero": [(0, 0, 0), (0, 0, 0)],
+ "gimbal": [(30, 90, -45), (-120, -90, 15)],
+ "multi_turn": [(180, -180, 360), (-360, 720, -720)],
+ }
+ for axes, (case, root_angles) in itertools.product(
+ itertools.permutations("XYZ"), angle_cases.items()
+ ):
+ order = "".join(axes)
+ with self.subTest(order=order, angles=case):
+ path = _write_motion(self.directory, order, root_angles=root_angles)
+ animation = load_bvh(path)
+ skeleton = animation.skeleton
+ self.assertEqual(skeleton.joint_names, ["Root", "Spine", "Tip", "Sibling"])
+ np.testing.assert_array_equal(skeleton.parent_indices.numpy(), [-1, 0, 1, 0])
+ self.assertEqual(animation.num_frames, 2)
+ self.assertEqual(animation.sample_rate, 120.0)
+ self.assertEqual(animation.poses.dtype, wp.transform)
+ self.assertEqual(animation.poses.shape, (2, 4))
+ self.assertEqual(animation.poses.device, wp.get_device(self.device))
+ reference = skeleton.reference_local_transforms.numpy()
+ np.testing.assert_allclose(reference[:, :3], [
+ [.01, .02, .03], [0, .5, 0], [0, .25, 0], [-.1, 0, 0],
+ ], atol=1e-7)
+ np.testing.assert_array_equal(reference[:, 3:], np.tile([0, 0, 0, 1], (4, 1)))
+
+ positions = [
+ [[1, -2, 3], [0, .5, 0], [0, .25, 0], [-.1, .05, .07]],
+ [[-4, 5, -6], [0, .5, 0], [0, .25, 0], [-.12, .06, .08]],
+ ]
+ spine_angles = [(15, 25, -40), (-65, 10, 35)]
+ local = animation.poses.numpy()
+ world_transforms = wp.empty_like(animation.poses)
+ for frame in range(animation.num_frames):
+ animation.skeleton.compute_world_transforms(animation.poses[frame], world_transforms[frame])
+ actual_world = world_transforms.numpy()
+
+ for frame, angles in enumerate(root_angles):
+ # Compose the authored order with fixed-convention RPY calls,
+ # independently of the loader's axis-angle conversion.
+ angles_by_axis = dict(zip(order, angles))
+ x = wp.quat_rpy(wp.radians(float(angles_by_axis["X"])), 0.0, 0.0)
+ y = wp.quat_rpy(0.0, wp.radians(float(angles_by_axis["Y"])), 0.0)
+ z = wp.quat_rpy(0.0, 0.0, wp.radians(float(angles_by_axis["Z"])))
+ root_rotation = {
+ "XYZ": x * y * z,
+ "XZY": x * z * y,
+ "YXZ": y * x * z,
+ "YZX": y * z * x,
+ "ZXY": z * x * y,
+ "ZYX": z * y * x,
+ }[order]
+ sy, sz, sx = (wp.radians(float(angle)) for angle in spine_angles[frame])
+ spine_rotation = (
+ wp.quat_rpy(0.0, sy, 0.0)
+ * wp.quat_rpy(0.0, 0.0, sz)
+ * wp.quat_rpy(sx, 0.0, 0.0)
+ )
+ rotations = [
+ root_rotation, spine_rotation, wp.quat_identity(), wp.quat_identity()
+ ]
+ expected_local = [
+ wp.transform(position, rotation)
+ for position, rotation in zip(positions[frame], rotations, strict=True)
+ ]
+
+ # Compose the known hierarchy, including the separate root child.
+ root, spine, tip, sibling = expected_local
+ world_spine = wp.transform_multiply(root, spine)
+ expected_world = [
+ root,
+ world_spine,
+ wp.transform_multiply(world_spine, tip),
+ wp.transform_multiply(root, sibling),
+ ]
+ for actual_pose, expected_pose in (
+ (local[frame], expected_local),
+ (actual_world[frame], expected_world),
+ ):
+ for actual, expected in zip(actual_pose, expected_pose, strict=True):
+ rotation = wp.quat(actual[3:])
+ self.assertAlmostEqual(wp.length(rotation), 1.0, delta=1e-6)
+ np.testing.assert_allclose(actual[:3], expected.p, rtol=0, atol=1e-6)
+ np.testing.assert_allclose(
+ wp.quat_to_matrix(rotation),
+ wp.quat_to_matrix(expected.q),
+ atol=1e-6,
+ )
+
+ def test_skeleton_only_load(self) -> None:
+ path = _write_motion(self.directory)
+ expected = load_bvh(path).skeleton
+ hierarchy = path.read_text(encoding="utf-8").split("MOTION", 1)[0]
+ path.write_text(
+ hierarchy + "MOTION\nFrames: invalid\nFrame Time: invalid\nnot motion data\n",
+ encoding="utf-8",
+ )
+
+ skeleton = load_skeleton_from_bvh(path)
+ self.assertEqual(skeleton.joint_names, expected.joint_names)
+ np.testing.assert_array_equal(
+ skeleton.parent_indices.numpy(), expected.parent_indices.numpy()
+ )
+ np.testing.assert_array_equal(
+ skeleton.reference_local_transforms.numpy(),
+ expected.reference_local_transforms.numpy(),
+ )
+
+ def test_single_frame_motion(self) -> None:
+ animation = load_bvh(_write_motion(self.directory, frames=1))
+ self.assertEqual(animation.num_frames, 1)
+ self.assertEqual(animation.poses.shape, (1, 4))
+
+ def test_namespace_preservation_and_remapping(self) -> None:
+ path = _write_motion(self.directory)
+ stripped = load_bvh(path)
+ stripped_skeleton = stripped.skeleton
+ animation = load_bvh(path, remove_namespace=False)
+ skeleton = animation.skeleton
+ self.assertEqual(skeleton.joint_names, [
+ "actor:rig:Root", "actor:rig:Spine", "actor:rig:Tip", "actor:rig:Sibling",
+ ])
+ np.testing.assert_array_equal(
+ skeleton.parent_indices.numpy(), stripped_skeleton.parent_indices.numpy()
+ )
+ np.testing.assert_array_equal(
+ skeleton.reference_local_transforms.numpy(),
+ stripped_skeleton.reference_local_transforms.numpy(),
+ )
+ poses = animation.poses.numpy()
+ np.testing.assert_array_equal(poses, stripped.poses.numpy())
+
+ reference = skeleton.reference_local_transforms.numpy()[[0, 3, 1]]
+ target = Skeleton(
+ ["actor:rig:Root", "actor:rig:Extra", "actor:rig:Spine"], [-1, 0, 0], reference
+ )
+ remapped = load_bvh(path, target, remove_namespace=False)
+ self.assertIs(remapped.skeleton, target)
+ remapped_poses = remapped.poses.numpy()
+ np.testing.assert_array_equal(remapped_poses[:, 0], poses[:, 0])
+ np.testing.assert_array_equal(remapped_poses[:, 2], poses[:, 1])
+ np.testing.assert_array_equal(remapped_poses[:, 1], np.tile(reference[1], (2, 1)))
+
+ def test_channel_names_are_case_insensitive(self) -> None:
+ for case in ("lower", "mixed"):
+ with self.subTest(case=case):
+ path = _write_motion(self.directory)
+ expected = load_bvh(path)
+ lines = path.read_text(encoding="utf-8").splitlines()
+ for index, line in enumerate(lines):
+ tokens = line.split()
+ if tokens and tokens[0] == "CHANNELS":
+ tokens[2:] = [
+ channel.lower() if case == "lower" or channel_index % 2 == 0
+ else channel.upper()
+ for channel_index, channel in enumerate(tokens[2:])
+ ]
+ lines[index] = " ".join(tokens)
+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+ animation = load_bvh(path)
+ np.testing.assert_array_equal(
+ animation.poses.numpy(), expected.poses.numpy()
+ )
+
+ def test_unsupported_channels_are_ignored(self) -> None:
+ path = _write_motion(self.directory)
+ expected = load_bvh(path)
+ expected_skeleton = expected.skeleton
+ text = path.read_text(encoding="utf-8").replace(
+ "CHANNELS 6 Zposition Zrotation Xposition Xrotation Yposition Yrotation",
+ "CHANNELS 9 Scale Zposition Zrotation Xposition Confidence Xrotation Yposition Yrotation Xscale",
+ ).replace("CHANNELS 0", "CHANNELS 1 UserData")
+ header, frame_time, motion = text.partition("Frame Time: 0.008333333333333333\n")
+ rows = []
+ for line in motion.splitlines():
+ values = line.split()
+ # Extra values surround the root channels and belong to the tip as well.
+ rows.append(" ".join([
+ "101", *values[:3], "202", *values[3:6], "303",
+ *values[6:9], "404", *values[9:],
+ ]))
+ path.write_text(header + frame_time + "\n".join(rows) + "\n", encoding="utf-8")
+
+ animation = load_bvh(path)
+ skeleton = animation.skeleton
+ self.assertEqual(skeleton.joint_names, expected_skeleton.joint_names)
+ np.testing.assert_array_equal(
+ skeleton.parent_indices.numpy(), expected_skeleton.parent_indices.numpy()
+ )
+ np.testing.assert_array_equal(
+ skeleton.reference_local_transforms.numpy(),
+ expected_skeleton.reference_local_transforms.numpy(),
+ )
+ np.testing.assert_array_equal(
+ animation.poses.numpy(), expected.poses.numpy()
+ )
+
+ def test_utf8_joint_names(self) -> None:
+ path = _write_motion(self.directory)
+ expected = load_bvh(path)
+ root_name = "Racine_\u00e9_\u9aa8"
+ text = path.read_text(encoding="utf-8").replace("actor:rig:Root", f"actor:rig:{root_name}")
+ path.write_text(text, encoding="utf-8")
+ animation = load_bvh(path, remove_namespace=False)
+ skeleton = animation.skeleton
+ self.assertEqual(skeleton.joint_names, [
+ f"actor:rig:{root_name}", "actor:rig:Spine", "actor:rig:Tip", "actor:rig:Sibling",
+ ])
+ np.testing.assert_array_equal(
+ animation.poses.numpy(), expected.poses.numpy()
+ )
+
+ def test_mismatched_channel_count_is_rejected(self) -> None:
+ path = _write_motion(self.directory)
+ text = path.read_text(encoding="utf-8").replace(
+ "CHANNELS 3 Xposition Yposition Zposition",
+ "CHANNELS 2 Xposition Yposition Zposition",
+ )
+ path.write_text(text, encoding="utf-8")
+ with self.assertRaisesRegex(ValueError, "BVH joint 'Sibling' declares 2 channels but lists 3"):
+ load_bvh(path)
+
+ def test_malformed_motion_is_rejected(self) -> None:
+ for invalid in ("frames", "channels", "frame_time"):
+ with self.subTest(invalid=invalid):
+ path = _write_motion(self.directory)
+ text = path.read_text(encoding="utf-8")
+ if invalid == "frames":
+ text = text.replace("Frames: 2", "Frames: 3")
+ message = "Expected 3 frames and 12 channels"
+ elif invalid == "channels":
+ text = text.replace(
+ "CHANNELS 3 Xposition Yposition Zposition", "CHANNELS 2 Xposition Yposition"
+ )
+ message = "Expected 2 frames and 11 channels"
+ else:
+ text = text.replace("Frame Time: 0.008333333333333333\n", "")
+ message = "BVH frame time is missing"
+ path.write_text(text, encoding="utf-8")
+ with self.assertRaisesRegex(ValueError, message):
+ load_bvh(path)
+
+
+class BVHCUDATests(_BVHTestCase):
+ """Run the Warp pose conversion on CUDA."""
+
+ device = "cuda:0"
+ test_authored_channels_and_world_poses = BVHTests.test_authored_channels_and_world_poses
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_csv.py b/tests/motionbricks/test_csv.py
new file mode 100644
index 0000000..ff31823
--- /dev/null
+++ b/tests/motionbricks/test_csv.py
@@ -0,0 +1,85 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import csv
+from pathlib import Path
+import tempfile
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.io.csv import load_csv, save_csv
+
+
+_ROOT_FIELDS = ["Frame", "root_translateX", "root_translateY", "root_translateZ",
+ "root_rotateX", "root_rotateY", "root_rotateZ"]
+
+
+class CSVTests(unittest.TestCase):
+ def setUp(self):
+ directory = tempfile.TemporaryDirectory()
+ self.addCleanup(directory.cleanup)
+ self.directory = Path(directory.name)
+
+ def write_clip(self, *, single=False):
+ path = self.directory / "clip.csv"
+ rows = [[10, 100, -250, 80, 20, -35, 65, 90, -45],
+ [11, 200, -200, 90, 0, 0, 90, 60, -30]]
+ with path.open("w", encoding="utf-8-sig", newline="") as stream:
+ writer = csv.writer(stream)
+ writer.writerow(_ROOT_FIELDS + ["elbow", "knee"])
+ writer.writerows(rows[:1] if single else rows)
+ return path
+
+ def test_converts_units_and_root_euler_in_file_order(self):
+ clip = load_csv(self.write_clip(), sample_rate=60, device="cpu")
+ values = clip.poses.numpy()
+ self.assertEqual(clip.joint_names, ("elbow", "knee"))
+ self.assertEqual(clip.sample_rate, 60)
+ np.testing.assert_allclose(values[:, :3], [[1, -2.5, 0.8], [2, -2, 0.9]], atol=1e-6)
+ np.testing.assert_allclose(values[:, 7:], np.deg2rad([[90, -45], [60, -30]]), atol=1e-6)
+ expected = np.array(wp.quat_rpy(*np.deg2rad([20, -35, 65])))
+ self.assertAlmostEqual(abs(float(values[0, 3:7] @ expected)), 1.0, places=6)
+
+ def test_single_frame(self):
+ clip = load_csv(self.write_clip(single=True), device="cpu")
+ self.assertEqual(clip.num_frames, 1)
+ self.assertEqual(clip.duration, 0)
+
+ def test_rejects_non_finite_coordinates(self):
+ path = self.directory / "invalid.csv"
+ with path.open("w", encoding="utf-8", newline="") as stream:
+ writer = csv.writer(stream)
+ writer.writerow(_ROOT_FIELDS + ["hinge"])
+ writer.writerow([0.0] * 7 + [float("nan")])
+ with self.assertRaisesRegex(ValueError, "coordinates must be finite"):
+ load_csv(path, device="cpu")
+
+ def test_existing_writer_round_trip_preserves_coordinate_order(self):
+ original = load_csv(self.write_clip(), device="cpu")
+ path = self.directory / "saved.csv"
+ save_csv(path, original)
+ loaded = load_csv(path, device="cpu")
+ self.assertEqual(loaded.joint_names, original.joint_names)
+ a, b = original.poses.numpy(), loaded.poses.numpy()
+ np.testing.assert_allclose(a[:, :3], b[:, :3], atol=1e-6)
+ np.testing.assert_allclose(a[:, 7:], b[:, 7:], atol=1e-6)
+ np.testing.assert_allclose(np.abs(np.sum(a[:, 3:7] * b[:, 3:7], axis=1)), 1, atol=1e-6)
+
+ def test_writer_exports_only_valid_frames(self):
+ clip = load_csv(self.write_clip(), device="cpu")
+ clip.num_frames = 1
+ clip.poses[1:].fill_(float("nan"))
+ path = self.directory / "valid.csv"
+ save_csv(path, clip)
+ loaded = load_csv(path, device="cpu")
+ self.assertEqual(loaded.num_frames, 1)
+ np.testing.assert_allclose(loaded.poses.numpy(), clip.poses.numpy()[:1], atol=1e-6)
+ clip.num_frames = 0
+ with self.assertRaisesRegex(ValueError, "at least one frame in use"):
+ save_csv(path, clip)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_dof_buffers.py b/tests/motionbricks/test_dof_buffers.py
new file mode 100644
index 0000000..72610fd
--- /dev/null
+++ b/tests/motionbricks/test_dof_buffers.py
@@ -0,0 +1,192 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""DOF clip sampling, DOF tokens and Newton playback on synthetic data."""
+
+import unittest
+
+import newton
+import numpy as np
+import warp as wp
+
+from motionbricks.model.unitree_g1.buffers import DOFToken
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+
+def _poses(count):
+ poses = np.zeros((count, 9), dtype=np.float32)
+ poses[:, 0] = np.arange(count)
+ poses[:, 6] = 1.0
+ poses[:, 7] = np.arange(count) * 0.25
+ poses[:, 8] = -poses[:, 7]
+ return poses
+
+
+def _assert_transform(test, actual, expected):
+ actual, expected = np.asarray(actual), np.asarray(expected)
+ np.testing.assert_allclose(actual[:3], expected[:3], atol=2e-6)
+ test.assertAlmostEqual(abs(float(actual[3:] @ expected[3:])), 1.0, places=5)
+
+
+class DOFBufferTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_token_reuses_storage_and_replaces_padding_on_each_update(self):
+ poses = _poses(4)
+ source = wp.array(poses, dtype=wp.float32)
+ token = DOFToken(2)
+ pointer = token.poses.ptr
+ self.assertEqual(token.num_poses, 0)
+ for count in (4, 2, 1, 3):
+ with self.subTest(count=count):
+ token.update_from_poses(source[0] if count == 1 else source[:count])
+ self.assertEqual(token.num_poses, count)
+ self.assertEqual(token.poses.ptr, pointer)
+ expected = np.concatenate((poses[:count], np.repeat(poses[count - 1:count], 4 - count, axis=0)))
+ np.testing.assert_array_equal(token.poses.numpy(), expected)
+ np.testing.assert_array_equal(source.numpy(), poses)
+
+ def test_sampling_places_the_root_clamps_time_and_writes_only_the_robot_view(self):
+ poses = np.full((6, 9), np.nan, dtype=np.float32)
+ poses[:2, :3] = [[1, 2, 3], [5, 6, 7]]
+ poses[:2, 3:7] = [
+ wp.quat_from_axis_angle(wp.vec3(0, 0, 1), float(np.deg2rad(170))),
+ wp.quat_from_axis_angle(wp.vec3(0, 0, 1), float(np.deg2rad(-170))),
+ ]
+ poses[:2, 7:] = [[-2.8, 1.2], [2.8, -0.4]]
+ source = wp.array(poses, dtype=wp.float32)
+ animation = DOFAnimationBuffer(("a", "b"), 2, source, num_frames=2)
+ joint_q = wp.full(27, -100.0, dtype=wp.float32)
+ robot_view = joint_q[9:18]
+ offset = wp.transform(wp.vec3(10, -4, 0), wp.quat_from_axis_angle(wp.vec3(0, 1, 0), 0.3))
+
+ animation.sample(0.25, robot_view, root_offset=offset)
+ actual = robot_view.numpy()
+ expected_root = offset * wp.transform(wp.vec3(3, 4, 5), wp.quat_from_axis_angle(wp.vec3(0, 0, 1), np.pi))
+ _assert_transform(self, actual[:7], expected_root)
+ np.testing.assert_allclose(actual[7:], [0, 0.4], atol=1e-6)
+ for num_frames, time, frame in ((2, -1.0, 0), (2, 10.0, 1), (1, -1.0, 0), (1, 10.0, 0)):
+ animation.num_frames = num_frames
+ animation.sample(time, robot_view)
+ np.testing.assert_allclose(robot_view.numpy(), poses[frame], atol=1e-6)
+
+ window = _poses(13)
+ clip = DOFAnimationBuffer(("a", "b"), 120, wp.array(window, dtype=wp.float32))
+ for frame in range(4):
+ clip.sample(frame / 30, robot_view)
+ np.testing.assert_allclose(robot_view.numpy(), window[frame * 4], atol=1e-6)
+
+ np.testing.assert_array_equal(joint_q.numpy()[:9], -100)
+ np.testing.assert_array_equal(joint_q.numpy()[18:], -100)
+ self.assertEqual(animation.poses.ptr, source.ptr)
+ np.testing.assert_array_equal(source.numpy(), poses)
+
+ def test_make_loopable_moves_the_root_along_a_straight_line(self):
+ # The root makes a quarter turn and ends 0.3 m from its start.
+ poses = _poses(3)
+ poses[:, 0] = (0.0, 1.0, 0.3)
+ for frame, angle in enumerate((0.0, 0.25 * np.pi, 0.5 * np.pi)):
+ poses[frame, 3:7] = wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), angle)
+ animation = DOFAnimationBuffer(("a", "b"), 30, wp.array(poses, dtype=wp.float32))
+
+ animation.make_loopable()
+
+ corrected = animation.poses.numpy()
+ # The middle frame moves by half the end gap, in the same direction as the gap.
+ np.testing.assert_allclose(corrected[1, :3], [0.85, 0.0, 0.0], atol=1e-6)
+ _assert_transform(self, corrected[2, :7], corrected[0, :7])
+
+ def test_copy_keeps_the_frames_in_use_in_new_storage(self):
+ poses = wp.array(_poses(3), dtype=wp.float32)
+ contacts = wp.array(np.arange(12, dtype=np.float32).reshape(3, 4), dtype=wp.float32)
+ animation = DOFAnimationBuffer(("a", "b"), 30, poses, num_frames=2, foot_contacts=contacts)
+
+ copy = animation.copy()
+
+ self.assertEqual(copy.joint_names, ("a", "b"))
+ self.assertEqual((copy.capacity, copy.num_frames, copy.sample_rate), (2, 2, 30.0))
+ self.assertNotEqual(copy.poses.ptr, poses.ptr)
+ np.testing.assert_array_equal(copy.poses.numpy(), poses.numpy()[:2])
+ np.testing.assert_array_equal(copy.foot_contacts.numpy(), contacts.numpy()[:2])
+ self.assertIsNone(DOFAnimationBuffer(("a", "b"), 30, poses).copy().foot_contacts)
+
+ def test_valid_count_controls_duration_and_hides_stale_frames(self):
+ animation = DOFAnimationBuffer(
+ ("a", "b"), 30, wp.empty((6, 9), dtype=wp.float32), num_frames=0,
+ )
+ pointer = animation.poses.ptr
+ self.assertEqual(animation.capacity, 6)
+ output = wp.empty(9, dtype=wp.float32)
+ self.assertEqual(animation.num_frames, 0)
+ self.assertEqual(animation.duration, 0)
+ with self.assertRaisesRegex(ValueError, "empty"):
+ animation.sample(0, output)
+ poses = _poses(6)
+ animation.poses.assign(poses)
+ for count in (6, 2, 1):
+ animation.num_frames = count
+ self.assertEqual(animation.poses.ptr, pointer)
+ self.assertAlmostEqual(animation.duration, (count - 1) / 30)
+ animation.sample(100, output)
+ np.testing.assert_array_equal(output.numpy(), poses[count - 1])
+ animation.num_frames = 0
+ with self.assertRaisesRegex(ValueError, "empty"):
+ animation.sample(0, output)
+ for invalid in (-1, animation.capacity + 1):
+ with self.assertRaises(ValueError):
+ animation.num_frames = invalid
+ self.assertEqual(animation.num_frames, 0)
+
+ def test_samples_directly_into_newton_joint_q_and_evaluates_fk(self):
+ builder = newton.ModelBuilder(up_axis=newton.Axis.Z)
+ root = builder.add_link(label="root", mass=1, inertia=wp.mat33(1.0))
+ arm = builder.add_link(label="arm", mass=1, inertia=wp.mat33(1.0))
+ leg = builder.add_link(label="leg", mass=1, inertia=wp.mat33(1.0))
+ joints = [builder.add_joint_free(root, label="free")]
+ joints.append(builder.add_joint_revolute(
+ root, arm, axis=wp.vec3(0, 0, 1),
+ parent_xform=wp.transform(wp.vec3(1, 0, 0), wp.quat_identity()), label="robot/elbow",
+ ))
+ joints.append(builder.add_joint_revolute(
+ root, leg, axis=wp.vec3(0, 1, 0),
+ parent_xform=wp.transform(wp.vec3(0, 0, -1), wp.quat_identity()), label="robot/knee",
+ ))
+ builder.add_articulation(joints)
+ model = builder.finalize()
+ state = model.state()
+ poses = _poses(2)
+ poses[:, :3] = [[4, -2, 1], [6, 2, 3]]
+ poses[:, 3:7] = wp.quat_rpy(0.2, -0.3, 0.7)
+ poses[:, 7:] = [[0.25, -0.75], [0.75, -0.25]]
+ clip = DOFAnimationBuffer(("elbow", "knee"), 2, wp.array(poses, dtype=wp.float32))
+ offset = wp.transform(wp.vec3(3, -1, 0.6), wp.quat_rpy(0.0, 0.0, 0.3))
+
+ clip.sample(0.25, model.joint_q, root_offset=offset)
+ newton.eval_fk(model, model.joint_q, model.joint_qd, state)
+
+ position = poses[:, :3].mean(axis=0)
+ hinges = poses[:, 7:].mean(axis=0)
+ root_transform = offset * wp.transform(wp.vec3(*position), wp.quat(*poses[0, 3:7]))
+ sample = model.joint_q.numpy()
+ _assert_transform(self, sample[:7], root_transform)
+ np.testing.assert_allclose(sample[7:], hinges, atol=1e-6)
+ body_transforms = state.body_q.numpy()
+ _assert_transform(self, body_transforms[root], root_transform)
+ _assert_transform(self, body_transforms[arm], root_transform * wp.transform(
+ wp.vec3(1, 0, 0), wp.quat_from_axis_angle(wp.vec3(0, 0, 1), float(hinges[0])),
+ ))
+ _assert_transform(self, body_transforms[leg], root_transform * wp.transform(
+ wp.vec3(0, 0, -1), wp.quat_from_axis_angle(wp.vec3(0, 1, 0), float(hinges[1])),
+ ))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_dof_endpoint_correction.py b/tests/motionbricks/test_dof_endpoint_correction.py
new file mode 100644
index 0000000..69abe8f
--- /dev/null
+++ b/tests/motionbricks/test_dof_endpoint_correction.py
@@ -0,0 +1,145 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Endpoint correction mathematics, independent of motions and robot assets."""
+
+import unittest
+
+import numpy as np
+from scipy.spatial.transform import Rotation
+import warp as wp
+
+from motionbricks.model.unitree_g1 import kernels
+
+
+def _motion(count):
+ t = np.linspace(0, 1, count)
+ poses = np.zeros((count, 9), dtype=np.float32)
+ poses[:, :3] = np.column_stack((t, t * -.2, .8 + np.sin(t) * .02))
+ poses[:, 3:7] = Rotation.from_euler("xyz", np.column_stack((t * .2, t * -.15, t * .3 + 3.))).as_quat()
+ poses[:, 7:] = np.column_stack((2.8 + t * .1, np.sin(t * 3)))
+ return poses
+
+
+def _reference(raw, start, end, fade_frames=6.0):
+ weights = np.linspace(0, 1, len(raw))[:, None]
+ expected = raw.astype(np.float64)
+ expected[:, :3] += (1 - weights) * (start[:3] - raw[0, :3])
+ expected[:, :3] += weights * (end[:3] - raw[-1, :3])
+ distance = np.arange(len(raw), dtype=np.float64)[:, None]
+ phase = np.clip(distance / min(fade_frames, (len(raw) - 1) / 2), 0, 1)
+ falloff = np.where(phase < .5, 1 - 2*phase**2, 2*(1 - phase)**2)
+ expected[:, 7:] += falloff * (start[7:] - raw[0, 7:])
+ expected[:, 7:] += falloff[::-1] * (end[7:] - raw[-1, 7:])
+ rotations = Rotation.from_quat(raw[:, 3:7])
+ start_delta = rotations[0].inv() * Rotation.from_quat(start[3:7])
+ end_delta = rotations[-1].inv() * Rotation.from_quat(end[3:7])
+ expected[:, 3:7] = (
+ rotations * Rotation.from_rotvec((1 - weights) * start_delta.as_rotvec())
+ * Rotation.from_rotvec(weights * end_delta.as_rotvec())
+ ).as_quat()
+ return expected
+
+
+class DOFEndpointCorrectionTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def _correct(self, source, context, target, count, fade_frames=6.0):
+ generated = wp.array(source, dtype=wp.float32)
+ context_device = wp.array(context, dtype=wp.float32)
+ target_device = wp.array(target, dtype=wp.float32)
+ frame_count = wp.array([count], dtype=wp.int32)
+ deltas = wp.empty((2, source.shape[1]), dtype=wp.float32)
+ wp.launch(kernels.compute_endpoint_deltas_kernel, dim=2,
+ inputs=[frame_count, context_device, target_device, generated], outputs=[deltas])
+ wp.launch(kernels.apply_endpoint_deltas_kernel, dim=len(source),
+ inputs=[frame_count, deltas, fade_frames], outputs=[generated])
+ np.testing.assert_array_equal(context_device.numpy(), context)
+ np.testing.assert_array_equal(target_device.numpy(), target)
+ return generated.numpy()
+
+ def _assert_poses(self, actual, expected):
+ np.testing.assert_allclose(actual[:, :3], expected[:, :3], atol=3e-6)
+ np.testing.assert_allclose(actual[:, 7:], expected[:, 7:], atol=3e-6)
+ error = Rotation.from_quat(actual[:, 3:7]).inv() * Rotation.from_quat(expected[:, 3:7])
+ self.assertLess(float(error.magnitude().max()), 3e-6)
+ np.testing.assert_allclose(np.linalg.norm(actual[:, 3:7], axis=1), 1, atol=2e-7)
+
+ def test_matches_endpoints_and_localizes_deltas_without_wrapping_hinges(self):
+ for count in (18, 58):
+ with self.subTest(count=count):
+ raw = _motion(count)
+ context, target = _motion(4), _motion(4)
+ context[-1, :3] += [.1, -.2, .03]
+ target[0, :3] += [1.5, .1, -.04]
+ context[-1, 3:7] = -Rotation.from_euler("xyz", [.4, .3, -3.0]).as_quat()
+ target[0, 3:7] = Rotation.from_euler("xyz", [-.5, .2, 3.1]).as_quat()
+ context[-1, 7:] = [-2.8, 1.5]
+ target[0, 7:] = [-2.6, .3]
+ # Other guide rows and the spare output capacity must not affect correction.
+ context[:-1] = np.nan
+ target[1:] = np.nan
+ source = np.concatenate((raw, np.full((3, 9), np.nan, dtype=np.float32)))
+ actual = self._correct(source, context, target, count)
+ expected = _reference(raw, context[-1], target[0])
+ self._assert_poses(actual[:count], expected)
+ self._assert_poses(actual[[0, count - 1]], np.stack((context[-1], target[0])))
+ # Crossing +/-pi uses a scalar offset, not an angle wrap. The
+ # unmodified interior keeps the predictor's positive hinge.
+ np.testing.assert_array_equal(actual[6:count - 6, 7:], raw[6:count - 6, 7:])
+ self.assertAlmostEqual(actual[3, 7], (raw[3, 7] + .5*(context[-1, 7] - raw[0, 7])), places=6)
+ np.testing.assert_array_equal(actual[count:], source[count:])
+
+ def test_fade_duration_sets_the_corrected_region(self):
+ raw, context, target = _motion(26), _motion(4), _motion(4)
+ context[-1, 7:] = raw[0, 7:] + [1.0, -2.0]
+ target[0, 7:] = raw[-1, 7:] + [3.0, -4.0]
+ for fade_frames in (3.0, 6.0, 9.0, 12.0):
+ with self.subTest(fade_frames=fade_frames):
+ actual = self._correct(raw, context, target, len(raw), fade_frames)
+ self._assert_poses(actual, _reference(raw, context[-1], target[0], fade_frames))
+ span = int(fade_frames)
+ np.testing.assert_array_equal(actual[span:-span, 7:], raw[span:-span, 7:])
+ start_offsets = actual[:span + 1, 7] - raw[:span + 1, 7]
+ self.assertTrue(np.all(np.diff(start_offsets) <= 0))
+ self.assertAlmostEqual(float(start_offsets[0]), 1.0, places=6)
+ self.assertEqual(float(start_offsets[-1]), 0.0)
+ np.testing.assert_allclose(start_offsets + start_offsets[::-1], 1.0, atol=3e-7)
+
+ def test_short_clips_keep_both_endpoints_without_overlapping_fades(self):
+ for count in (2, 3, 8, 13):
+ with self.subTest(count=count):
+ raw, context, target = _motion(count), _motion(4), _motion(4)
+ context[-1, 7:] -= [2, 3]
+ target[0, 7:] += [4, 5]
+ actual = self._correct(raw, context, target, count)
+ self._assert_poses(actual, _reference(raw, context[-1], target[0]))
+ self._assert_poses(actual[[0, -1]], np.stack((context[-1], target[0])))
+ if count % 2 == 1:
+ np.testing.assert_array_equal(actual[count // 2, 7:], raw[count // 2, 7:])
+
+ def test_quaternion_signs_do_not_change_the_corrected_motion(self):
+ source, context, target = _motion(18), _motion(4), _motion(4)
+ source[:, 3:7] = Rotation.from_euler("z", np.deg2rad(179)).as_quat()
+ context[-1, 3:7] = Rotation.from_euler("z", np.deg2rad(-179)).as_quat()
+ target[0, 3:7] = Rotation.from_euler("z", np.deg2rad(177)).as_quat()
+ expected = self._correct(source, context, target, len(source))
+ source[::2, 3:7] *= -1
+ context[:, 3:7] *= -1
+ target[:, 3:7] *= -1
+ actual = self._correct(source, context, target, len(source))
+ self._assert_poses(actual, expected)
+ step_angles = (Rotation.from_quat(actual[1:, 3:7]) * Rotation.from_quat(actual[:-1, 3:7]).inv()).magnitude()
+ self.assertLess(float(step_angles.max()), np.deg2rad(1))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_dof_mesh_renderer.py b/tests/motionbricks/test_dof_mesh_renderer.py
new file mode 100644
index 0000000..585baf7
--- /dev/null
+++ b/tests/motionbricks/test_dof_mesh_renderer.py
@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Robot previews and picking must share geometry and leave playback untouched."""
+
+import unittest
+from unittest.mock import Mock
+
+import newton
+import numpy as np
+import warp as wp
+
+from motionbricks.renderers.dof_mesh_renderer import DOFMeshRenderer
+
+
+class DOFMeshRendererTests(unittest.TestCase):
+ def test_fk_mesh_scale_and_picking_leave_playback_untouched(self):
+ with wp.ScopedDevice("cpu"):
+ builder = newton.ModelBuilder()
+ root = builder.add_link(mass=1.0, inertia=wp.mat33(np.eye(3)))
+ arm = builder.add_link(mass=1.0, inertia=wp.mat33(np.eye(3)))
+ builder.add_articulation([
+ builder.add_joint_free(root),
+ builder.add_joint_revolute(
+ root, arm, axis=wp.vec3(0, 0, 1),
+ parent_xform=wp.transform(0, 2, 0, 0, 0, 0, 1),
+ ),
+ ])
+ mesh = newton.Mesh(
+ np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]], dtype=np.float32),
+ np.array([0, 1, 2], dtype=np.int32), compute_inertia=False,
+ )
+ builder.add_shape_mesh(
+ arm, mesh=mesh, scale=(2, 3, 1), xform=wp.transform(1, 0, 0, 0, 0, 0, 1),
+ )
+ builder.add_shape_box(root, xform=wp.transform(0, 0, 2, 0, 0, 0, 1))
+ # An invisible collision shape sits closer to the picking rays.
+ builder.add_shape_box(
+ root, xform=wp.transform(0, 0, 3, 0, 0, 0, 1), hx=3, hy=3, hz=0.2,
+ cfg=newton.ModelBuilder.ShapeConfig(is_visible=False),
+ )
+ model = builder.finalize()
+ playback = model.state()
+ newton.eval_fk(model, model.joint_q, model.joint_qd, playback)
+ original_q = model.joint_q.numpy().copy()
+ original_bodies = playback.body_q.numpy().copy()
+ original_scales = model.shape_scale.numpy().copy()
+ pose = wp.array([3, 4, 1, 0, 0, np.sqrt(0.5), np.sqrt(0.5), -np.pi / 2], dtype=wp.float32)
+ renderer = DOFMeshRenderer(model)
+ viewer = Mock()
+
+ # Mesh instances carry the mesh scale. Box sizes live in the shared geometry.
+ renderer.draw_pose(viewer, pose, wp.transform_identity(), wp.vec3(0.2, 0.8, 0.4), "start")
+ scales = [call.args[3].numpy() for call in viewer.log_instances.call_args_list]
+ np.testing.assert_allclose(scales, [[[2, 3, 1]], [[1, 1, 1]]])
+
+ placement = wp.transform(wp.vec3(10, -1, 2), wp.quat_rpy(0.2, -0.3, 0.7))
+ for origin, limit, expected in (
+ ((2.4, 4.6, 5), 20.0, 4.0), # Scaled, articulated triangle.
+ ((3, 4, 10), 20.0, 6.5), # Visible box, ignoring the nearer collision shape.
+ ((3.8, 6.7, 5), 20.0, 20.0), # Inside the triangle's bounds but outside its surface.
+ ((2.4, 4.6, 5), 2.0, 2.0), # Hit beyond the requested distance.
+ ):
+ with self.subTest(origin=origin, limit=limit):
+ distance = renderer.raycast_pose(
+ pose, placement, wp.transform_point(placement, wp.vec3(*origin)),
+ wp.transform_vector(placement, wp.vec3(0, 0, -1)), limit,
+ )
+ self.assertAlmostEqual(distance, expected, places=5)
+
+ np.testing.assert_array_equal(model.joint_q.numpy(), original_q)
+ np.testing.assert_array_equal(playback.body_q.numpy(), original_bodies)
+ np.testing.assert_array_equal(model.shape_scale.numpy(), original_scales)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_dof_skeleton_renderer.py b/tests/motionbricks/test_dof_skeleton_renderer.py
new file mode 100644
index 0000000..cd965c3
--- /dev/null
+++ b/tests/motionbricks/test_dof_skeleton_renderer.py
@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Debug FK must honor valid pose counts without changing the animated model."""
+
+import unittest
+from unittest.mock import Mock
+
+import newton
+import numpy as np
+import warp as wp
+
+from motionbricks.renderers.skeleton_renderer import DOFSkeletonRenderer
+
+
+def _model():
+ """A free root, a revolute arm, and a tip fixed one metre along the arm."""
+ builder = newton.ModelBuilder()
+ root = builder.add_link(mass=1, inertia=wp.mat33(np.eye(3)))
+ arm = builder.add_link(mass=1, inertia=wp.mat33(np.eye(3)))
+ tip = builder.add_link(mass=1, inertia=wp.mat33(np.eye(3)))
+ joints = [builder.add_joint_free(root)]
+ # Co-located joint origins are common on robots and must draw finite lines.
+ joints.append(builder.add_joint_revolute(root, arm, axis=wp.vec3(0, 0, 1)))
+ joints.append(builder.add_joint_fixed(
+ arm, tip, parent_xform=wp.transform(wp.vec3(1, 0, 0), wp.quat_identity()),
+ ))
+ builder.add_articulation(joints)
+ return builder.finalize(), root, tip
+
+
+class DOFSkeletonRendererTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_batch_fk_preserves_playback_grows_storage_and_hides_zero_poses(self):
+ model, root, tip = _model()
+ playback = model.state()
+ newton.eval_fk(model, model.joint_q, model.joint_qd, playback)
+ original_q = model.joint_q.numpy().copy()
+ original_body_q = playback.body_q.numpy().copy()
+ poses = np.full((4, model.joint_coord_count), np.nan, dtype=np.float32)
+ poses[:2] = 0
+ poses[0, :7] = [0, 0, 1, 0, 0, 0, 1]
+ poses[1, :7] = [2, 3, 1, 0, 0, np.sqrt(0.5), np.sqrt(0.5)]
+ poses[1, 7] = -np.pi / 2
+ joint_q = wp.array(poses, dtype=wp.float32)
+ placement = wp.transform(wp.vec3(10, 0, 0), wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.5 * np.pi))
+ renderer = DOFSkeletonRenderer(model, max_instances=1)
+ viewer = Mock()
+ colors = wp.array([wp.vec3(0.2, 0.75, 1.0), wp.vec3(1.0, 0.5, 0.2)], dtype=wp.vec3)
+ renderer.draw_batch(viewer, joint_q, 2, placement, colors, "target")
+ bodies = renderer.world_poses.numpy()
+ np.testing.assert_allclose(bodies[:2, root, :3], [[10, 0, 1], [7, 2, 1]], atol=1e-6)
+ np.testing.assert_allclose(bodies[:2, tip, :3], [[10, 1, 1], [7, 3, 1]], atol=1e-6)
+ _, starts, ends, line_colors = viewer.log_lines.call_args.args
+ self.assertTrue(np.isfinite(starts.numpy()).all())
+ self.assertTrue(np.isfinite(ends.numpy()).all())
+ # Each pose's bones use that pose's color.
+ half = len(line_colors) // 2
+ np.testing.assert_allclose(line_colors.numpy()[:half], np.tile([0.2, 0.75, 1.0], (half, 1)))
+ np.testing.assert_allclose(line_colors.numpy()[half:], np.tile([1.0, 0.5, 0.2], (half, 1)))
+ np.testing.assert_array_equal(model.joint_q.numpy(), original_q)
+ np.testing.assert_array_equal(playback.body_q.numpy(), original_body_q)
+ np.testing.assert_array_equal(joint_q.numpy(), poses)
+ renderer.draw_batch(viewer, joint_q, 0, placement, colors, "target")
+ self.assertTrue(viewer.log_lines.call_args.kwargs["hidden"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_foot_contacts.py b/tests/motionbricks/test_foot_contacts.py
new file mode 100644
index 0000000..5993d86
--- /dev/null
+++ b/tests/motionbricks/test_foot_contacts.py
@@ -0,0 +1,226 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Foot contact buffers, outline builders, and the outline renderer."""
+
+import unittest
+from unittest.mock import Mock
+
+import newton
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.mesh import SkeletalMesh, SkinnedMesh
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.utils import get_soma_human_model, get_unitree_g1_model
+from motionbricks.model.soma.contract import SOMA_N1_FOOT_CONTACT_JOINTS
+from motionbricks.model.unitree_g1.contract import (
+ UNITREE_G1_N1_FOOT_CONTACT_BODIES,
+ UNITREE_G1_N1_FOOT_CONTACT_OFFSETS,
+)
+from motionbricks.renderers.foot_contact_renderer import (
+ ContactOutline,
+ FootContactRenderer,
+ body_sole_outlines,
+ skeletal_mesh_sole_outlines,
+)
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+
+def _slab(forwards, sides, heights):
+ """Return the vertices (forward, side, height) and triangles of a box sliced at each forward position."""
+ vertices = np.array([[f, s, h] for f in forwards for s in sides for h in heights], dtype=np.float32)
+ triangles = []
+ for slice_index in range(len(forwards) - 1):
+ a, b = 4 * slice_index, 4 * (slice_index + 1)
+ for h in (0, 1):
+ triangles += [a + h, b + h, b + 2 + h, a + h, b + 2 + h, a + 2 + h]
+ return vertices, np.array(triangles, dtype=np.int32)
+
+
+class FootContactTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_buffers_validate_their_contacts_and_blend_them_within_the_valid_frames(self):
+ contacts = np.array([[0.0, 0.2, 0.4, 0.6], [1.0, 0.8, 0.6, 0.4], [0.5, 0.5, 0.5, 0.5]], dtype=np.float32)
+ skeleton = Skeleton(["Root"], [-1], np.array([[0, 0, 0, 0, 0, 0, 1]], dtype=np.float32))
+ buffers = (
+ AnimationBuffer(
+ skeleton, 30.0, wp.zeros((3, 1), dtype=wp.transform),
+ foot_contacts=wp.array(contacts, dtype=wp.float32),
+ ),
+ DOFAnimationBuffer(
+ ("hinge",), 30.0, wp.zeros((3, 8), dtype=wp.float32),
+ foot_contacts=wp.array(contacts, dtype=wp.float32),
+ ),
+ )
+ output = wp.empty(4, dtype=wp.float32)
+ for buffer in buffers:
+ with self.subTest(buffer=type(buffer).__name__):
+ buffer.num_frames = 2
+ buffer.sample_foot_contacts(0.5 / 30.0, output)
+ np.testing.assert_allclose(output.numpy(), [0.5, 0.5, 0.5, 0.5], atol=1e-6)
+ # Sampling stops at the last valid frame, not at the end of the storage.
+ buffer.sample_foot_contacts(10.0, output)
+ np.testing.assert_allclose(output.numpy(), contacts[1])
+
+ with self.assertRaisesRegex(ValueError, "foot_contacts"):
+ AnimationBuffer(
+ skeleton, 30.0, wp.zeros((3, 1), dtype=wp.transform), foot_contacts=wp.zeros((2, 4), dtype=wp.float32),
+ )
+ with self.assertRaisesRegex(ValueError, "foot_contacts"):
+ DOFAnimationBuffer(
+ ("hinge",), 30.0, wp.zeros((3, 8), dtype=wp.float32), foot_contacts=wp.zeros((3, 3), dtype=wp.float32),
+ )
+ clip = DOFAnimationBuffer(("hinge",), 30.0, wp.zeros((3, 8), dtype=wp.float32))
+ with self.assertRaisesRegex(ValueError, "Cannot sample foot contacts"):
+ clip.sample_foot_contacts(0.0, output)
+
+ def test_outlines_close_each_loop_and_show_contacts_above_the_threshold(self):
+ square = np.array([[0, 0, 0], [0.1, 0, 0], [0.1, 0.1, 0], [0, 0.1, 0]], dtype=np.float32)
+ outlines = [
+ ContactOutline(0, 0, square),
+ ContactOutline(1, 0, square - [0, 0, 0.1]),
+ ContactOutline(2, 1, square),
+ ContactOutline(3, 1, square),
+ ]
+ transforms = wp.array(
+ [wp.transform_identity(), wp.transform(wp.vec3(1.0, 0.0, 0.5), wp.quat_identity())], dtype=wp.transform,
+ )
+ renderer = FootContactRenderer("outlines", outlines)
+ self.assertEqual(renderer.threshold, FootContactRenderer.DEFAULT_THRESHOLD)
+ viewer = Mock()
+
+ renderer.draw(viewer, transforms, wp.array([0.0, 0.6, 0.3, 1.0], dtype=wp.float32))
+
+ _, starts, ends, colors = viewer.log_lines.call_args.args
+ starts, ends, colors = (array.numpy().reshape(4, 4, 3) for array in (starts, ends, colors))
+ # Contacts at or below the threshold collapse their segments.
+ np.testing.assert_allclose(ends[0], starts[0])
+ np.testing.assert_allclose(ends[2], starts[2])
+ # A drawn outline is closed and follows its transform.
+ np.testing.assert_allclose(starts[3], square + [1.0, 0.0, 0.5], atol=1e-6)
+ np.testing.assert_allclose(ends[3], np.roll(square, -1, axis=0) + [1.0, 0.0, 0.5], atol=1e-6)
+ # Points below the floor rise to just above it.
+ np.testing.assert_allclose(starts[1][:, 2], 0.003, atol=1e-6)
+ np.testing.assert_allclose(colors[1], [[1.0, 0.4, 0.0]] * 4, atol=1e-6)
+ np.testing.assert_allclose(colors[3], [[1.0, 0.0, 0.0]] * 4, atol=1e-6)
+ self.assertIs(viewer.log_lines.call_args.kwargs["hidden"], False)
+
+ # A negative threshold still hides a contact of 0.
+ renderer.threshold = -1.0
+ renderer.draw(viewer, transforms, wp.array([0.0, 0.05, -0.2, 1.0], dtype=wp.float32))
+ starts, ends, _ = (array.numpy().reshape(4, 4, 3) for array in viewer.log_lines.call_args.args[1:])
+ drawn = [bool(np.any(ends[contact] != starts[contact])) for contact in range(4)]
+ self.assertEqual(drawn, [False, True, False, True])
+
+ renderer.hide(viewer)
+ renderer.hide(viewer)
+ hidden = [call for call in viewer.log_lines.call_args_list if call.kwargs["hidden"]]
+ self.assertEqual(len(hidden), 1)
+
+ def test_body_outlines_surround_the_foot_mesh_and_grow_away_from_the_split(self):
+ builder = newton.ModelBuilder()
+ vertices, triangles = _slab(np.linspace(-0.05, 0.15, 9), (-0.04, 0.04), (-0.03, 0.02))
+ for name in ("left_foot", "right_foot"):
+ body = builder.add_body(label=name, mass=1.0)
+ builder.add_shape_mesh(body, mesh=newton.Mesh(vertices, triangles, compute_inertia=False))
+ model = builder.finalize(device="cpu")
+
+ heel_and_toe = ((0.0, 0.0, 0.0), (0.1, 0.0, 0.0))
+ outlines = body_sole_outlines(
+ model, ("left_foot",) * 2 + ("right_foot",) * 2, heel_and_toe * 2, margin=0.008, rings=1,
+ )
+
+ self.assertEqual(
+ [(outline.contact, outline.transform) for outline in outlines], [(0, 0), (1, 0), (2, 1), (3, 1)],
+ )
+ heel, toe = outlines[0].points, outlines[1].points
+ # The outline grows 8 mm at its ends and sides. It splits halfway to the toe point, at x = 0.05.
+ np.testing.assert_allclose([heel[:, 0].min(), heel[:, 0].max()], [-0.058, 0.05], atol=1e-6)
+ np.testing.assert_allclose([toe[:, 0].min(), toe[:, 0].max()], [0.05, 0.158], atol=1e-6)
+ np.testing.assert_allclose([heel[:, 1].min(), heel[:, 1].max()], [-0.048, 0.048], atol=1e-6)
+ # It sits 4 mm above the sole.
+ np.testing.assert_allclose(np.concatenate([heel, toe])[:, 2], -0.026, atol=1e-6)
+
+ # The second ring runs 5 mm beyond the first.
+ rings = body_sole_outlines(model, ("left_foot",) * 2, heel_and_toe, margin=0.01, rings=2, spacing=0.005)
+ self.assertEqual([outline.contact for outline in rings], [0, 1, 0, 1])
+ np.testing.assert_allclose(
+ [rings[0].points[:, 0].min(), rings[2].points[:, 0].min()], [-0.06, -0.065], atol=1e-6,
+ )
+
+ def test_skinned_outlines_split_at_the_toe_joint_in_the_bind_pose(self):
+ # The bind pose is Y up and faces +Z. Its joint frames are rotated, so outline points must change frame.
+ positions = {"Hips": (0.0, 1.0, 0.0), "LeftFoot": (0.1, 0.08, -0.05), "LeftToeBase": (0.1, 0.02, 0.05)}
+ skeleton = Skeleton(list(positions), [-1, 0, 1], np.tile([0, 0, 0, 0, 0, 0, 1], (3, 1)).astype(np.float32))
+ bind = [wp.transform(wp.vec3(*position), wp.quat_rpy(0.2, -0.3, 0.4)) for position in positions.values()]
+ inverse_bind = [wp.transform_inverse(transform) for transform in bind]
+ foot, foot_triangles = _slab(np.linspace(-0.15, 0.10, 6), (0.05, 0.15), (0.0, 0.06))
+ leg, leg_triangles = _slab((-0.3, 0.3), (0.0, 0.2), (0.5, 1.0))
+ # Slab coordinates (forward, side, height) become (Z, X, Y) in the bind pose.
+ points = np.concatenate([foot, leg])[:, [1, 2, 0]]
+ # The toe joint moves the front of the foot. The hips move the leg, which no outline includes.
+ joints = np.concatenate([np.where(foot[:, 0] < 0.025, 1, 2), np.zeros(len(leg), dtype=int)]).astype(np.int32)
+ # The foot part stores one influence per vertex. The leg part stores two.
+ foot_mesh = SkinnedMesh(
+ points[:len(foot)], foot_triangles, joints[:len(foot)], np.ones(len(foot), dtype=np.float32),
+ )
+ leg_joints = np.tile([0, 2], len(leg)).astype(np.int32)
+ leg_weights = np.tile([0.7, 0.3], len(leg)).astype(np.float32)
+ leg_mesh = SkinnedMesh(points[len(foot):], leg_triangles, leg_joints, leg_weights)
+ skinned = SkeletalMesh([foot_mesh, leg_mesh], skeleton, inverse_bind)
+
+ outlines = skeletal_mesh_sole_outlines(skinned, ["LeftFoot", "LeftToeBase"], margin=0.008, rings=1)
+
+ self.assertEqual([(outline.contact, outline.transform) for outline in outlines], [(0, 1), (1, 2)])
+ renderer = FootContactRenderer("foot", outlines)
+ viewer = Mock()
+ # The pose stands 1 m above the floor, so no outline point is raised to it.
+ lift = wp.transform(wp.vec3(0.0, 0.0, 1.0), wp.quat_identity())
+ lifted = wp.array([wp.mul(lift, joint) for joint in bind], dtype=wp.transform)
+ renderer.draw(viewer, lifted, wp.ones(4, dtype=wp.float32))
+ # World joint transforms place the local outlines back around the original foot.
+ starts = viewer.log_lines.call_args.args[1].numpy()
+ heel, toe = np.split(starts, [len(outlines[0].points)])
+ np.testing.assert_allclose([heel[:, 2].min(), heel[:, 2].max()], [0.842, 1.05], atol=1e-6)
+ np.testing.assert_allclose([toe[:, 2].min(), toe[:, 2].max()], [1.05, 1.108], atol=1e-6)
+ np.testing.assert_allclose([heel[:, 0].min(), heel[:, 0].max()], [0.042, 0.158], atol=1e-6)
+ np.testing.assert_allclose(np.concatenate([heel, toe])[:, 1], 0.004, atol=1e-6)
+
+ def test_contract_contact_points_outline_both_shipped_rigs(self):
+ soma = skeletal_mesh_sole_outlines(get_soma_human_model(), SOMA_N1_FOOT_CONTACT_JOINTS, rings=1)
+ g1 = body_sole_outlines(
+ get_unitree_g1_model(), UNITREE_G1_N1_FOOT_CONTACT_BODIES, UNITREE_G1_N1_FOOT_CONTACT_OFFSETS, rings=1,
+ )
+ for outlines in (soma, g1):
+ self.assertEqual([outline.contact for outline in outlines], [0, 1, 2, 3])
+ # G1 splits halfway between its ankle roll joint and the toe point 14 cm ahead.
+ np.testing.assert_allclose([g1[0].points[:, 0].max(), g1[1].points[:, 0].min()], [0.07, 0.07], atol=1e-6)
+
+ def test_contacts_and_samples_stay_on_the_pose_device(self):
+ if not wp.is_cuda_available():
+ self.skipTest("A second device needs CUDA.")
+ skeleton = Skeleton(["Root"], [-1], np.array([[0, 0, 0, 0, 0, 0, 1]], dtype=np.float32))
+ on_gpu = wp.zeros((3, 4), dtype=wp.float32, device="cuda:0")
+ with self.assertRaisesRegex(ValueError, "device"):
+ AnimationBuffer(skeleton, 30.0, wp.zeros((3, 1), dtype=wp.transform), foot_contacts=on_gpu)
+ with self.assertRaisesRegex(ValueError, "device"):
+ DOFAnimationBuffer(("hinge",), 30.0, wp.zeros((3, 8), dtype=wp.float32), foot_contacts=on_gpu)
+ contacts = wp.zeros((3, 4), dtype=wp.float32)
+ buffer = DOFAnimationBuffer(("hinge",), 30.0, wp.zeros((3, 8), dtype=wp.float32), foot_contacts=contacts)
+ with self.assertRaisesRegex(ValueError, "device"):
+ buffer.sample_foot_contacts(0.0, wp.empty(4, dtype=wp.float32, device="cuda:0"))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_inference_engine.py b/tests/motionbricks/test_inference_engine.py
new file mode 100644
index 0000000..7c966b1
--- /dev/null
+++ b/tests/motionbricks/test_inference_engine.py
@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+import unittest
+from types import SimpleNamespace
+
+import numpy as np
+import tensorrt as trt
+
+from motionbricks.inference.types import TensorMode, TensorSpec
+from motionbricks.inference.builder import TensorRTBuildOptions, _specialize_batch_dimension, create_logger
+from motionbricks.inference.errors import EngineBuildError
+from motionbricks.inference.progress import TensorRTBuildProgressMonitor
+
+
+class InferenceEngineTests(unittest.TestCase):
+ def test_static_tensor_metadata(self) -> None:
+ spec = TensorSpec("input", TensorMode.INPUT, (1, 8, 5), np.dtype(np.float32))
+
+ self.assertEqual(spec.element_count, 40)
+ self.assertEqual(spec.nbytes, 160)
+
+ def test_tensorrt_messages_go_to_python_logging(self) -> None:
+ warnings_and_up = create_logger("warning")
+ with self.assertLogs("motionbricks.inference.tensorrt", level="DEBUG") as logs:
+ warnings_and_up.log(trt.Logger.ERROR, "failed")
+ warnings_and_up.log(trt.Logger.WARNING, "careful")
+ warnings_and_up.log(trt.Logger.INFO, "below the minimum severity")
+ create_logger("INFO").log(trt.Logger.INFO, "detail")
+ self.assertEqual(
+ [(record.levelno, record.getMessage()) for record in logs.records],
+ [(logging.ERROR, "failed"), (logging.WARNING, "careful"), (logging.DEBUG, "detail")],
+ )
+ with self.assertRaisesRegex(ValueError, "Unknown TensorRT log severity"):
+ create_logger("loud")
+
+ def test_cache_payload_omits_default_precision_and_keeps_batch_size(self) -> None:
+ defaults = TensorRTBuildOptions()
+ self.assertNotIn("enable_fp16", defaults.cache_payload())
+ self.assertTrue(
+ TensorRTBuildOptions(enable_fp16=True).cache_payload()["enable_fp16"]
+ )
+ self.assertNotIn("enable_tf32", defaults.cache_payload())
+ self.assertNotIn("enable_tf32", TensorRTBuildOptions(enable_tf32=True).cache_payload())
+ self.assertIs(TensorRTBuildOptions(enable_tf32=False).cache_payload()["enable_tf32"], False)
+ self.assertEqual(TensorRTBuildOptions(batch_size=3).cache_payload()["batch_size"], 3)
+
+ def test_batch_specialization_keeps_nonbatch_dimensions(self) -> None:
+ inputs = [SimpleNamespace(name="poses", shape=(-1, 8, 267)),
+ SimpleNamespace(name="mask", shape=(-1, 8)),
+ SimpleNamespace(name="constant", shape=(11,))]
+ network = SimpleNamespace(num_inputs=len(inputs), get_input=inputs.__getitem__)
+ _specialize_batch_dimension(network, 3)
+ self.assertEqual([tensor.shape for tensor in inputs], [(3, 8, 267), (3, 8), (11,)])
+ inputs[0].shape = (-1, -1, 267)
+ with self.assertRaisesRegex(EngineBuildError, "Only the leading batch"):
+ _specialize_batch_dimension(network, 1)
+
+ def test_build_progress_monitor_tracks_phases_and_cancellation(self) -> None:
+ monitor = TensorRTBuildProgressMonitor()
+
+ monitor.phase_start("parent", None, 4)
+ self.assertEqual(monitor.snapshot().phase_name, "parent")
+ self.assertTrue(monitor.step_complete("parent", 0))
+ self.assertEqual(monitor.snapshot().fraction, 0.25)
+
+ monitor.phase_start("child", "parent", 2)
+ self.assertTrue(monitor.step_complete("child", 0))
+ self.assertEqual(monitor.snapshot().phase_name, "parent")
+ self.assertEqual(monitor.snapshot().fraction, 0.25)
+ monitor.phase_finish("child")
+ self.assertEqual(monitor.snapshot().phase_name, "parent")
+
+ monitor.request_cancel()
+ self.assertFalse(monitor.step_complete("parent", 1))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_math_utils.py b/tests/motionbricks/test_math_utils.py
new file mode 100644
index 0000000..c9fa9aa
--- /dev/null
+++ b/tests/motionbricks/test_math_utils.py
@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import math
+import unittest
+
+import numpy as np
+
+from motionbricks.utils.math_utils import (
+ critical_spring_angle,
+ critical_spring_damper_exact,
+ wrap_angle,
+)
+
+
+class MathUtilsTests(unittest.TestCase):
+ def test_critical_spring_converges_to_goal(self) -> None:
+ current = 0.0
+ rate = 0.0
+ for _ in range(240):
+ current, rate = critical_spring_damper_exact(
+ current,
+ rate,
+ goal=3.0,
+ halflife=0.4,
+ delta_time=1.0 / 60.0,
+ )
+
+ self.assertAlmostEqual(current, 3.0, delta=2.0e-4)
+ self.assertAlmostEqual(rate, 0.0, delta=2.0e-4)
+
+ def test_angle_spring_uses_the_shortest_arc(self) -> None:
+ current_angle = math.radians(179.0)
+ desired_angle = math.radians(-179.0)
+ desired_direction = np.array(
+ [math.cos(desired_angle), math.sin(desired_angle), 0.0],
+ dtype=np.float32,
+ )
+
+ next_angle, _next_rate = critical_spring_angle(
+ current_angle,
+ current_rate=0.0,
+ desired_direction=desired_direction,
+ halflife=0.2,
+ delta_time=1.0 / 60.0,
+ )
+
+ angular_step = wrap_angle(next_angle - current_angle)
+ self.assertGreater(angular_step, 0.0)
+ self.assertLess(angular_step, math.radians(2.0))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_motion_bricks_contract.py b/tests/motionbricks/test_motion_bricks_contract.py
new file mode 100644
index 0000000..5135bc7
--- /dev/null
+++ b/tests/motionbricks/test_motion_bricks_contract.py
@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+from pathlib import Path
+import tempfile
+import unittest
+
+import numpy as np
+
+from motionbricks.inference.errors import TensorContractError
+from motionbricks.inference.types import TensorMode, TensorSpec
+from motionbricks.model.config import MotionBricksInferenceConfig
+from motionbricks.model.contract import (
+ MODEL_CONTEXT_AND_TARGET_POSES,
+ MODEL_MAX_TOKEN_COUNT,
+ MODEL_MAX_VALID_FRAMES,
+ MODEL_MIN_TOKEN_COUNT,
+ MODEL_POSES_PER_TOKEN,
+ load_model_manifest,
+ valid_frame_count,
+)
+from motionbricks.model.soma.contract import (
+ SOMA_N1_CONTRACT,
+ SOMA_N1_FP16_ONNX_PATH,
+ SOMA_N1_FP32_ONNX_PATH,
+ SOMA_N1_MANIFEST_PATH,
+)
+from motionbricks.model.unitree_g1.contract import UNITREE_G1_N1_CONTRACT
+
+
+class MotionBricksContractTests(unittest.TestCase):
+ def test_tensor_layouts_follow_the_joint_counts(self) -> None:
+ predicted_frames = MODEL_MAX_TOKEN_COUNT * MODEL_POSES_PER_TOKEN
+ shapes = {spec.name: spec.shape for spec in SOMA_N1_CONTRACT.tensor_specs}
+ joints = len(SOMA_N1_CONTRACT.joint_names)
+ self.assertEqual(shapes["local_poses"], (1, MODEL_CONTEXT_AND_TARGET_POSES, 3 * (joints - 1) + 6 * joints))
+ self.assertEqual(
+ shapes["pred_global_motions"],
+ (1, predicted_frames, 5 + 3 * (joints - 1) + 6 * joints + 3 * joints + 4),
+ )
+
+ shapes = {spec.name: spec.shape for spec in UNITREE_G1_N1_CONTRACT.tensor_specs}
+ coordinates = 7 + len(UNITREE_G1_N1_CONTRACT.joint_names)
+ self.assertEqual(shapes["context_qpos"], (1, MODEL_POSES_PER_TOKEN, coordinates))
+ self.assertEqual(shapes["target_qpos"], (1, MODEL_POSES_PER_TOKEN, coordinates))
+ self.assertEqual(shapes["pred_qpos"], (1, predicted_frames, coordinates))
+ self.assertEqual(shapes["pred_foot_contacts"], (1, predicted_frames, 4))
+
+ def test_contract_reports_mismatched_tensor(self) -> None:
+ specs = {spec.name: spec for spec in SOMA_N1_CONTRACT.tensor_specs}
+ specs["pred_num_tokens"] = TensorSpec(
+ "pred_num_tokens",
+ TensorMode.OUTPUT,
+ (2,),
+ np.dtype(np.int32),
+ )
+ with self.assertRaisesRegex(TensorContractError, "expected shape"):
+ SOMA_N1_CONTRACT.validate_tensor_specs(specs)
+
+ def test_token_range_is_enforced(self) -> None:
+ MotionBricksInferenceConfig(allowed_token_counts=(MODEL_MIN_TOKEN_COUNT, MODEL_MAX_TOKEN_COUNT))
+ for invalid in (MODEL_MIN_TOKEN_COUNT - 1, MODEL_MAX_TOKEN_COUNT + 1):
+ with self.subTest(invalid=invalid):
+ with self.assertRaises(ValueError):
+ MotionBricksInferenceConfig(allowed_token_counts=(invalid,))
+ with self.assertRaises(ValueError):
+ valid_frame_count(invalid)
+
+ def test_valid_frames_drop_three_boundary_frames_at_each_end(self) -> None:
+ self.assertEqual(valid_frame_count(MODEL_MIN_TOKEN_COUNT), 18)
+ self.assertEqual(MODEL_MAX_VALID_FRAMES, 58)
+
+ def test_manifest_timing_must_match_the_model_constants(self) -> None:
+ manifest = json.loads(SOMA_N1_MANIFEST_PATH.read_text(encoding="utf-8"))
+ for field, value in (("min_pred_tokens", 8), ("max_pred_tokens", 14), ("sample_rate", 60.0)):
+ with self.subTest(field=field), tempfile.TemporaryDirectory() as folder:
+ path = Path(folder) / "manifest.json"
+ path.write_text(json.dumps(dict(manifest, **{field: value})), encoding="utf-8")
+ with self.assertRaisesRegex(ValueError, f"{field} must be"):
+ load_model_manifest(path)
+
+ def test_manifest_names_both_precisions_next_to_it(self) -> None:
+ self.assertEqual(SOMA_N1_FP32_ONNX_PATH, SOMA_N1_MANIFEST_PATH.with_name("mmm_v6_soma_fp32.onnx"))
+ self.assertEqual(SOMA_N1_FP16_ONNX_PATH, SOMA_N1_MANIFEST_PATH.with_name("mmm_v6_soma_fp16.onnx"))
+ self.assertTrue(SOMA_N1_FP16_ONNX_PATH.is_file())
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_motion_player.py b/tests/motionbricks/test_motion_player.py
new file mode 100644
index 0000000..6107e12
--- /dev/null
+++ b/tests/motionbricks/test_motion_player.py
@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+from types import SimpleNamespace
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.model.soma.buffers import PoseToken
+from motionbricks.runtime.motion_player import GeneratedMotionPlayer
+from motionbricks.runtime.motion_recorder import MotionRecorder
+
+
+def _pose(x: float = 0.0) -> np.ndarray:
+ return np.array([x, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0], dtype=np.float32)
+
+
+class GeneratedMotionPlayerTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def test_transition_deadline_does_not_limit_sampling_to_trimmed_frames(self) -> None:
+ player = GeneratedMotionPlayer.__new__(GeneratedMotionPlayer)
+ player.engine = SimpleNamespace(stream=None)
+ skeleton = Skeleton(["Hips"], [-1], np.stack([_pose()]))
+ contacts = np.repeat(np.arange(8, dtype=np.float32)[:, None] / 10.0, 4, axis=1)
+ player.output = AnimationBuffer(
+ skeleton, 30.0, wp.empty((8, skeleton.num_joints), dtype=wp.transform),
+ num_frames=0, foot_contacts=wp.array(contacts, dtype=wp.float32),
+ )
+ frames = np.stack([_pose(float(x)) for x in (0, 1, 2, 3, 4, 5, 999, 999)])[:, None]
+ player.output.poses.assign(frames)
+ player.output.num_frames = 6
+ destination_pose = wp.empty(1, dtype=wp.transform)
+ destination_contacts = wp.empty(4, dtype=wp.float32)
+
+ for early_frames, last_frame in ((0, 5), (1, 4), (2, 3), (5, 0), (20, 0)):
+ with self.subTest(early_frames=early_frames):
+ player.transition_early_by_frames = early_frames
+ player.playback_time = 0.0
+ self.assertAlmostEqual(player.time_to_transition, last_frame / 30.0)
+
+ player.sample(4.5 / 30.0, destination_pose, destination_contacts)
+ np.testing.assert_allclose(destination_pose.numpy()[0], _pose(4.5))
+ np.testing.assert_allclose(destination_contacts.numpy(), 0.45, atol=1e-6)
+ self.assertAlmostEqual(player.playback_time, 4.5 / 30.0)
+ self.assertAlmostEqual(player.time_to_transition, max(0.0, (last_frame - 4.5) / 30.0))
+
+ # Sampling is still bounded by valid data, never unused buffer capacity.
+ player.sample(10.0, destination_pose, destination_contacts)
+ np.testing.assert_allclose(destination_pose.numpy()[0], frames[5, 0])
+ np.testing.assert_allclose(destination_contacts.numpy(), 0.5, atol=1e-6)
+ self.assertEqual(player.time_to_transition, 0.0)
+
+ def test_seed_history_uses_supplied_pose_and_refreshes_context(self) -> None:
+ player = GeneratedMotionPlayer.__new__(GeneratedMotionPlayer)
+ player.engine = SimpleNamespace(stream=None)
+ skeleton = Skeleton(["Hips"], [-1], np.stack([_pose()]))
+ player.motion_history = MotionRecorder(skeleton.reference_local_transforms, capacity=3)
+ player.context = PoseToken(skeleton.num_joints)
+ player.record_pose(1.0 / 30.0, wp.array(np.stack([_pose(1.0)]), dtype=wp.transform))
+ player.refresh_context()
+ seed = np.stack([_pose(2.0)])
+
+ player.seed_history_from_pose(wp.array(seed, dtype=wp.transform))
+
+ np.testing.assert_array_equal(player.motion_history.poses.numpy(), np.repeat(seed[None], 3, axis=0))
+ np.testing.assert_array_equal(player.motion_history.delta_times, np.zeros(3, dtype=np.float32))
+ np.testing.assert_array_equal(player.context.poses.numpy(), np.repeat(seed[None], 4, axis=0))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_override_poses.py b/tests/motionbricks/test_override_poses.py
new file mode 100644
index 0000000..395785c
--- /dev/null
+++ b/tests/motionbricks/test_override_poses.py
@@ -0,0 +1,166 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Override poses load from USD and only change the drawn mesh, never the poses passed in."""
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import Mock
+
+import numpy as np
+import warp as wp
+from pxr import Gf, Usd, UsdGeom, UsdSkel
+
+from motionbricks.animation.mesh import SkeletalMesh, SkinnedMesh
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.io.usd import load_skeletal_mesh_with_skeleton_from_usd
+from motionbricks.renderers.skeletal_mesh_renderer import SkeletalMeshRenderer
+
+
+def _drawn_points(renderer, pose):
+ viewer = Mock()
+ renderer.draw_pose(viewer, pose, wp.transform_identity(), wp.vec3(1, 1, 1), "pose")
+ return viewer.log_mesh.call_args.args[1].numpy()
+
+
+def _finger_mesh():
+ """Return a two joint mesh with a Curled override pose and Finger and HalfFinger masks."""
+ reference = np.array([[0, 0, 0, 0, 0, 0, 1], [0, 1, 0, 0, 0, 0, 1]], dtype=np.float32)
+ skeleton = Skeleton(["Hips", "Finger"], [-1, 0], reference)
+ # One vertex follows the finger, which is bound one unit above the hips.
+ part = SkinnedMesh(
+ np.array([[1, 1, 0]], dtype=np.float32), np.array([0, 0, 0], dtype=np.int32),
+ np.array([1], dtype=np.int32), np.array([1], dtype=np.float32),
+ )
+ inverse_binds = [wp.transform_identity(), wp.transform(0, -1, 0, 0, 0, 0, 1)]
+ # The override pose curls the finger a quarter turn. Its hips are far away, but no mask selects them.
+ turn = wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.5 * np.pi)
+ curled = wp.array([[9, 9, 9, 0, 0, 0, 1], [0, 1, 0, *turn]], dtype=wp.transform)
+ masks = {"Finger": skeleton.joint_mask(["Finger"]), "HalfFinger": skeleton.joint_mask(["Finger"], 0.5)}
+ return SkeletalMesh([part], skeleton, inverse_binds, override_poses={"Curled": curled}, override_pose_masks=masks)
+
+
+def _write_character(path, frame=None):
+ """Write a three joint character in centimeters with one partial SkelAnimation.
+
+ The animation holds default values, or only time samples at frame on a single frame stage.
+ """
+ stage = Usd.Stage.CreateNew(str(path))
+ UsdGeom.SetStageMetersPerUnit(stage, 0.01)
+ time = Usd.TimeCode.Default()
+ if frame is not None:
+ stage.SetStartTimeCode(frame)
+ stage.SetEndTimeCode(frame)
+ time = Usd.TimeCode(frame)
+ UsdSkel.Root.Define(stage, "/Character")
+ skeleton = UsdSkel.Skeleton.Define(stage, "/Character/Skeleton")
+ skeleton.CreateJointsAttr(["Hips", "Hips/Finger", "Hips/Finger/Tip"])
+ # The joints stack up from the hips, 10 cm and then 5 cm apart.
+ rest_heights, bind_heights = (100, 10, 5), (100, 110, 115)
+ skeleton.CreateRestTransformsAttr([Gf.Matrix4d().SetTranslate(Gf.Vec3d(0, y, 0)) for y in rest_heights])
+ skeleton.CreateBindTransformsAttr([Gf.Matrix4d().SetTranslate(Gf.Vec3d(0, y, 0)) for y in bind_heights])
+ curled = UsdSkel.Animation.Define(stage, "/Character/Skeleton/Curled")
+ curled.CreateJointsAttr(["Hips/Finger"])
+ curled.CreateTranslationsAttr().Set([Gf.Vec3f(0, 8, 0)], time)
+ curled.CreateRotationsAttr().Set([Gf.Quatf(np.sqrt(0.5), 0, 0, np.sqrt(0.5))], time)
+ curled.CreateScalesAttr().Set([Gf.Vec3h(1, 1, 1)], time)
+ mesh = UsdGeom.Mesh.Define(stage, "/Character/Mesh")
+ mesh.CreatePointsAttr([(0, 110, 0), (1, 110, 0), (0, 111, 0)])
+ mesh.CreateFaceVertexCountsAttr([3])
+ mesh.CreateFaceVertexIndicesAttr([0, 1, 2])
+ binding = UsdSkel.BindingAPI.Apply(mesh.GetPrim())
+ binding.CreateSkeletonRel().SetTargets([skeleton.GetPath()])
+ binding.CreateJointIndicesPrimvar(False, 1).Set([1, 1, 1])
+ binding.CreateJointWeightsPrimvar(False, 1).Set([1, 1, 1])
+ stage.Save()
+
+
+class OverridePoseTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_joint_mask_weights_only_the_named_joints(self):
+ skeleton = Skeleton(["Hips", "Hand", "Finger"], [-1, 0, 1], np.tile([0, 0, 0, 0, 0, 0, 1], (3, 1)))
+ np.testing.assert_allclose(skeleton.joint_mask(["Finger", "Hips"], 0.25).numpy(), [0.25, 0, 0.25])
+ np.testing.assert_allclose(skeleton.joint_mask(["Toe", "Hand"]).numpy(), [0, 1, 0])
+ np.testing.assert_allclose(skeleton.joint_mask(["Hand"], 1.5).numpy(), [0, 1, 0])
+ np.testing.assert_allclose(skeleton.joint_mask(["Hand"], -0.5).numpy(), [0, 0, 0])
+ if wp.is_cuda_available():
+ # The mask lives with the skeleton, whatever the current device is.
+ with wp.ScopedDevice("cuda:0"):
+ self.assertEqual(skeleton.joint_mask(["Hand"]).device, skeleton.reference_local_transforms.device)
+
+ def test_override_pose_blends_each_joint_by_its_mask_weight(self):
+ mesh = _finger_mesh()
+ renderer = SkeletalMeshRenderer(mesh)
+ # The animated pose moves the hips and stretches the finger.
+ pose = wp.array([[5, 0, 0, 0, 0, 0, 1], [0, 3, 0, 0, 0, 0, 1]], dtype=wp.transform)
+ animated = pose.numpy().copy()
+ np.testing.assert_allclose(_drawn_points(renderer, pose), [[6, 3, 0]], atol=1e-6)
+
+ renderer.set_override_pose("Curled", mask="Finger")
+ np.testing.assert_allclose(_drawn_points(renderer, pose), [[5, 2, 0]], atol=1e-6)
+ # Half weight puts the finger halfway up and turns it an eighth of a turn.
+ renderer.set_override_pose("Curled", mask="HalfFinger")
+ np.testing.assert_allclose(_drawn_points(renderer, pose), [[5 + np.sqrt(0.5), 2 + np.sqrt(0.5), 0]], atol=1e-6)
+ # Weights outside 0 to 1 are clamped, and a NaN weight counts as 0.
+ for weight, expected in ((1.5, [5, 2, 0]), (-0.5, [6, 3, 0]), (np.nan, [6, 3, 0])):
+ with self.subTest(weight=weight):
+ mesh.override_pose_masks["Odd"] = wp.array([0.0, weight], dtype=wp.float32)
+ renderer.set_override_pose("Curled", mask="Odd")
+ np.testing.assert_allclose(_drawn_points(renderer, pose), [expected], atol=1e-6)
+ renderer.set_override_pose(None)
+ np.testing.assert_allclose(_drawn_points(renderer, pose), [[6, 3, 0]], atol=1e-6)
+ np.testing.assert_array_equal(pose.numpy(), animated)
+
+ def test_override_pose_selection_rejects_masks_that_do_not_fit(self):
+ mesh = _finger_mesh()
+ masks = mesh.override_pose_masks
+ masks["Short"] = wp.zeros(1, dtype=wp.float32)
+ masks["Double"] = wp.zeros(2, dtype=wp.float64)
+ renderer = SkeletalMeshRenderer(mesh)
+ renderer.set_override_pose("Curled", mask="Finger")
+ for name in ("Short", "Double"):
+ with self.subTest(mask=name), self.assertRaises(ValueError):
+ renderer.set_override_pose("Curled", mask=name)
+ with self.assertRaises(ValueError):
+ renderer.set_override_pose("Curled")
+ with self.assertRaises(KeyError):
+ renderer.set_override_pose("Missing", mask="Finger")
+
+ # A rejected selection keeps the previous one.
+ pose = wp.array([[5, 0, 0, 0, 0, 0, 1], [0, 3, 0, 0, 0, 0, 1]], dtype=wp.transform)
+ np.testing.assert_allclose(_drawn_points(renderer, pose), [[5, 2, 0]], atol=1e-6)
+ if wp.is_cuda_available():
+ # Drawing with a mask on another device would crash, so selection rejects it.
+ masks["Elsewhere"] = wp.zeros(2, dtype=wp.float32, device="cuda:0")
+ with self.assertRaises(ValueError):
+ renderer.set_override_pose("Curled", mask="Elsewhere")
+
+ def test_usd_skel_animations_load_as_full_override_poses_in_meters(self):
+ # Exporters write a pose as default values or as a single time sample.
+ for frame in (None, 1):
+ with self.subTest(frame=frame), tempfile.TemporaryDirectory() as folder:
+ path = Path(folder) / "character.usda"
+ _write_character(path, frame)
+ mesh = load_skeletal_mesh_with_skeleton_from_usd(path, "/Character/Mesh", "/Character/Skeleton")
+
+ self.assertEqual(list(mesh.override_poses), ["Curled"])
+ pose = mesh.override_poses["Curled"].numpy()
+ rest = mesh.skeleton.reference_local_transforms.numpy()
+ np.testing.assert_allclose(pose[1], [0, 0.08, 0, 0, 0, np.sqrt(0.5), np.sqrt(0.5)], atol=1e-6)
+ # Joints the animation does not list keep their rest transforms.
+ np.testing.assert_allclose(pose[[0, 2]], rest[[0, 2]])
+ np.testing.assert_allclose(rest[:, :3], [[0, 1, 0], [0, 0.1, 0], [0, 0.05, 0]], atol=1e-6)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_pivot.py b/tests/motionbricks/test_pivot.py
new file mode 100644
index 0000000..2064d40
--- /dev/null
+++ b/tests/motionbricks/test_pivot.py
@@ -0,0 +1,222 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import math
+import unittest
+from types import SimpleNamespace
+
+import numpy as np
+import warp as wp
+
+from motionbricks.runtime.pivot import Axis, ConeSide, ConstraintType, OperationOrder, Pivot
+
+
+def _character(desired, position=(0.0, 0.0, 0.0)):
+ start = wp.vec3(*position)
+ end = start + wp.vec3(*desired) if math.isfinite(math.hypot(*desired)) else start
+ return SimpleNamespace(position=position, desired_velocity=desired, probe_segment=(start, end))
+
+
+class PivotAlignmentTests(unittest.TestCase):
+ def test_local_z_alignment_preserves_position_and_authored_axis(self):
+ parent = wp.transform(wp.vec3(3.0, -2.0, 1.0), wp.quat_rpy(0.3, -0.4, 0.6))
+ local = wp.transform(wp.vec3(0.5, 0.1, 0.2), wp.quat_rpy(-0.2, 0.1, 0.5))
+ upright = wp.transform(wp.vec3(1.0, 2.0, 3.0), wp.quat_rpy(0.0, 0.0, 0.7))
+ for world in (upright, wp.mul(parent, local)):
+ # A world-space approach with a known heading in the authored frame.
+ # Its local-Z component should not affect the chosen turn.
+ desired = wp.quat_rotate(world.q, wp.vec3(3.0, 4.0, 5.0))
+ for motion in ((0.0, 1.0, 0.0), (-1.0, 0.0, 0.0), (0.0, 0.6, 0.8)):
+ with self.subTest(world=world, motion=motion):
+ pivot = Pivot(motion_direction=motion, rotation_axis=Axis.Z)
+ aligned = pivot.aligned_transform(world, world, _character(desired))
+ result_direction = np.asarray(wp.quat_rotate(
+ wp.quat_inverse(world.q), wp.quat_rotate(aligned.q, wp.vec3(*motion)),
+ ))
+ np.testing.assert_allclose(
+ result_direction[:2] / np.linalg.norm(result_direction[:2]), [0.6, 0.8], atol=1e-6,
+ )
+ np.testing.assert_allclose(result_direction[2], motion[2], atol=1e-6, rtol=0.0)
+ np.testing.assert_array_equal(aligned.p, world.p)
+ # The relative rotation must use local Z only, even with a tilted parent.
+ delta = wp.mul(wp.quat_inverse(world.q), aligned.q)
+ np.testing.assert_allclose(np.asarray(delta)[:2], [0.0, 0.0], atol=1e-6)
+
+ def test_no_rotation_or_undefined_heading_keeps_the_current_transform(self):
+ for rotation in (wp.quat_rpy(0.0, 0.0, 0.7), wp.quat_rpy(0.4, -0.6, 0.7)):
+ world = wp.transform(wp.vec3(3.0, 2.0, 1.0), rotation)
+ for axis, motion, local_desired in (
+ (Axis.NONE, (0, 1, 0), (1, 0, 0)),
+ (Axis.X, (0, 1, 0), (1, 0, 0)),
+ (Axis.X, (1, 0, 0), (0, 1, 0)),
+ (Axis.Y, (1, 0, 0), (0, 1, 0)),
+ (Axis.Y, (0, 1, 0), (1, 0, 0)),
+ (Axis.Z, (0, 1, 0), (0, 0, 0)),
+ (Axis.Z, (0, 1, 0), (0, 0, 1)),
+ (Axis.Z, (0, 0, 1), (1, 0, 0)),
+ (Axis.Z, (0, 1, 0), (float("nan"), 0, 0)),
+ ):
+ with self.subTest(rotation=rotation, axis=axis, motion=motion, desired=local_desired):
+ pivot = Pivot(motion_direction=motion, rotation_axis=axis)
+ desired = wp.quat_rotate(rotation, wp.vec3(*local_desired))
+ np.testing.assert_array_equal(pivot.aligned_transform(world, world, _character(desired)), world)
+ np.testing.assert_array_equal(
+ Pivot().aligned_transform(wp.transform_identity(), world, _character((1, 0, 0))), world,
+ )
+
+ def test_line_projection_uses_a_finite_approach_and_fixed_limits(self):
+ reference = wp.transform(wp.vec3(2.0, 3.0, 4.0), wp.quat_rpy(0.3, -0.4, 0.5))
+ current = wp.transform(wp.vec3(7.0, 8.0, 9.0), wp.quat_rpy(0.2, 0.1, 0.8))
+ pivot = Pivot(
+ translation_axis=Axis.X, translation_constraint=ConstraintType.LINE_PROJECTION,
+ line_min_offset=-1.0, line_max_offset=1.0,
+ )
+ for position, velocity, expected_offset in (
+ ((0.25, -2, 0), (0, 1, 0), 0.25),
+ ((0, -2, 0), (0.5, 1, 0), 0.5), # Stops short of the line.
+ ((0, -2, 0), (1, 2, 0), 1.0), # Same direction, enough speed to reach it.
+ ((0, -2, 0), (2, 1, 0), 1.0),
+ ((2, -2, 0), (-2, 1, 0), 0.0),
+ ((0.25, 2, 0), (0, 1, 0), 0.25),
+ ((0.25, -2, 1), (0, 1, 0), 0.25),
+ ((0.25, -2, 0), (0, 0, 0), 0.25),
+ ((0.25, -2, 0), (float("nan"), 0, 0), 0.25),
+ ):
+ with self.subTest(position=position, velocity=velocity):
+ character = _character(
+ wp.quat_rotate(reference.q, wp.vec3(*velocity)),
+ wp.transform_point(reference, wp.vec3(*position)),
+ )
+ result = pivot.aligned_transform(reference, current, character)
+ expected = wp.transform_point(reference, wp.vec3(expected_offset, 0.0, 0.0))
+ np.testing.assert_allclose(result.p, expected, atol=1e-6)
+ np.testing.assert_array_equal(result.q, current.q)
+ current = result # Limits must not follow previous adjustments.
+
+ # The caller's interaction probe can extend beyond one second of motion.
+ character = _character((0.25, 0.5, 0.0), (0.0, -2.0, 0.0))
+ character.probe_segment = (wp.vec3(0.0, -2.0, 0.0), wp.vec3(1.0, 0.0, 0.0))
+ result = pivot.aligned_transform(wp.transform_identity(), wp.transform_identity(), character)
+ np.testing.assert_allclose(result.p, [1.0, 0.0, 0.0], atol=1e-6)
+
+ # Parallel segments can have several equally close points.
+ result = pivot.aligned_transform(reference, current, _character(
+ wp.quat_rotate(reference.q, wp.vec3(1.0, 0.0, 0.0)),
+ wp.transform_point(reference, wp.vec3(0.25, -2.0, 0.0)),
+ ))
+ local_point = wp.transform_point(wp.transform_inverse(reference), result.p)
+ self.assertGreaterEqual(local_point[0], 0.25 - 1e-6)
+ self.assertLessEqual(local_point[0], 1.0 + 1e-6)
+ np.testing.assert_allclose(np.asarray(local_point)[1:], [0.0, 0.0], atol=1e-6)
+
+ pivot.line_min_offset = pivot.line_max_offset = 0.4
+ result = pivot.aligned_transform(reference, current, _character((1, 0, 0)))
+ np.testing.assert_allclose(result.p, wp.transform_point(reference, wp.vec3(0.4, 0.0, 0.0)), atol=1e-6)
+
+ pivot.translation_constraint = ConstraintType.UNCONSTRAINED
+ result = pivot.aligned_transform(reference, current, _character(
+ wp.quat_rotate(reference.q, wp.vec3(2.0, 1.0, 0.0)),
+ wp.transform_point(reference, wp.vec3(0.0, -2.0, 0.0)),
+ ))
+ np.testing.assert_allclose(result.p, wp.transform_point(reference, wp.vec3(4.0, 0.0, 0.0)), atol=1e-5)
+
+ def test_operation_order_projects_onto_the_authored_or_rotated_line_without_drift(self):
+ for reference in (
+ wp.transform_identity(),
+ wp.transform(wp.vec3(2.0, 3.0, 4.0), wp.quat_rpy(0.3, -0.4, 0.5)),
+ ):
+ # In the authored frame, this approach crosses y = 0 at x = -0.5.
+ character = _character(
+ wp.quat_rotate(reference.q, wp.vec3(2.0, 2.0, 0.0)),
+ wp.transform_point(reference, wp.vec3(-1.5, -1.0, 0.0)),
+ )
+ for constraint, rotated_position, heading in (
+ (ConstraintType.UNCONSTRAINED, (-0.25, 0.25, 0.0), (math.sqrt(0.5), math.sqrt(0.5), 0.0)),
+ (ConstraintType.CONE, (-0.3169873, 0.1830127, 0.0), (0.5, math.sqrt(0.75), 0.0)),
+ ):
+ for order, expected_position in (
+ (OperationOrder.TRANSLATION_THEN_ROTATION, (-0.5, 0.0, 0.0)),
+ (OperationOrder.ROTATION_THEN_TRANSLATION, rotated_position),
+ ):
+ with self.subTest(reference=reference, constraint=constraint, order=order):
+ pivot = Pivot(
+ operation_order=order,
+ translation_axis=Axis.X,
+ translation_constraint=ConstraintType.LINE_PROJECTION,
+ line_min_offset=-1.0, line_max_offset=1.0,
+ rotation_axis=Axis.Z, rotation_constraint=constraint,
+ cone_half_angle_degrees=30.0,
+ )
+ current = wp.transform(wp.vec3(7.0, 8.0, 9.0), wp.quat_rpy(0.2, 0.1, 0.8))
+ for _ in range(3):
+ current = pivot.aligned_transform(reference, current, character)
+ np.testing.assert_allclose(
+ current.p, wp.transform_point(reference, wp.vec3(*expected_position)), atol=1e-6,
+ )
+ np.testing.assert_allclose(
+ wp.quat_rotate(current.q, wp.vec3(0, 1, 0)),
+ wp.quat_rotate(reference.q, wp.vec3(*heading)), atol=1e-6,
+ )
+
+ def test_rotation_first_still_translates_when_rotation_is_disabled_or_heading_is_undefined(self):
+ reference = wp.transform_identity()
+ current = wp.transform(wp.vec3(7.0, 8.0, 9.0), wp.quat_rpy(0.0, 0.0, -math.pi / 2))
+ character = _character((0.0, 0.0, 0.0), (0.4, -0.25, 0.0))
+ for axis, expected in (
+ (Axis.NONE, (0.4, 0.0, 0.0)),
+ (Axis.Z, (0.0, -0.25, 0.0)),
+ ):
+ with self.subTest(axis=axis):
+ pivot = Pivot(
+ operation_order=OperationOrder.ROTATION_THEN_TRANSLATION,
+ translation_axis=Axis.X,
+ translation_constraint=ConstraintType.LINE_PROJECTION,
+ rotation_axis=axis,
+ )
+ result = pivot.aligned_transform(reference, current, character)
+ np.testing.assert_allclose(result.p, expected, atol=1e-6)
+ np.testing.assert_array_equal(result.q, current.q)
+
+ def test_cone_limits_forward_mirrored_and_both_without_drifting(self):
+ reference = wp.transform(wp.vec3(2.0, 3.0, 4.0), wp.quat_rpy(0.3, -0.4, 0.5))
+ for axis, motion, sideways, normal in (
+ (Axis.X, wp.vec3(0, 1, 0), wp.vec3(0, 0, 1), wp.vec3(1, 0, 0)),
+ (Axis.Y, wp.vec3(0, 0, 1), wp.vec3(1, 0, 0), wp.vec3(0, 1, 0)),
+ (Axis.Z, wp.vec3(1, 0, 0), wp.vec3(0, 1, 0), wp.vec3(0, 0, 1)),
+ ):
+ current = wp.transform(wp.vec3(7.0, 8.0, 9.0), reference.q)
+ pivot = Pivot(motion_direction=tuple(motion), rotation_axis=axis, rotation_constraint=ConstraintType.CONE)
+ for side, half_angle, approach, expected in (
+ (ConeSide.FORWARD, 45, 20, 20),
+ (ConeSide.FORWARD, 45, 100, 45),
+ (ConeSide.FORWARD, 45, -100, -45),
+ (ConeSide.MIRRORED, 45, 170, 170),
+ (ConeSide.MIRRORED, 45, 10, 135),
+ (ConeSide.MIRRORED, 45, -10, -135),
+ (ConeSide.BOTH, 45, 100, 135),
+ (ConeSide.BOTH, 45, -100, -135),
+ (ConeSide.BOTH, 45, 70, 45),
+ (ConeSide.BOTH, 0, 179, 180),
+ (ConeSide.FORWARD, 180, -175, -175),
+ ):
+ with self.subTest(axis=axis, side=side, half_angle=half_angle, approach=approach):
+ pivot.cone_side, pivot.cone_half_angle_degrees = side, half_angle
+ approach, expected = math.radians(approach), math.radians(expected)
+ desired = wp.quat_rotate(
+ reference.q, math.cos(approach) * motion + math.sin(approach) * sideways + 0.4 * normal,
+ )
+ result = pivot.aligned_transform(reference, current, _character(desired))
+ np.testing.assert_allclose(
+ wp.quat_rotate(result.q, motion),
+ wp.quat_rotate(reference.q, math.cos(expected) * motion + math.sin(expected) * sideways),
+ atol=1e-6,
+ )
+ np.testing.assert_allclose(
+ wp.quat_rotate(result.q, normal), wp.quat_rotate(reference.q, normal), atol=1e-6,
+ )
+ np.testing.assert_array_equal(result.p, current.p)
+ current = result
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_pose_buffers.py b/tests/motionbricks/test_pose_buffers.py
new file mode 100644
index 0000000..30d9b10
--- /dev/null
+++ b/tests/motionbricks/test_pose_buffers.py
@@ -0,0 +1,233 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.runtime.motion_recorder import MotionRecorder
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.model.soma.buffers import PoseToken
+from motionbricks.utils import pose_utils
+
+
+def _pose(x: float) -> np.ndarray:
+ return np.array([[x, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]], dtype=np.float32)
+
+
+class PoseBufferTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ if not wp.is_cuda_available():
+ raise unittest.SkipTest("CUDA is required for MotionBricks pose buffers.")
+ cls.previous_device = wp.get_device()
+ cls.device = wp.get_device("cuda:0")
+ wp.set_device(cls.device)
+ cls.skeleton = Skeleton(
+ ["Root"],
+ [-1],
+ _pose(0.0),
+ )
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def test_pose_token_reuses_storage(self) -> None:
+ token = PoseToken(1)
+ storage_ptr = token.poses.ptr
+ self.assertEqual(token.num_poses, 0)
+
+ token.update_from_poses(wp.array(np.stack([_pose(2.0)]), dtype=wp.transform))
+ wp.synchronize_device(self.device)
+ self.assertEqual(token.num_poses, 1)
+ np.testing.assert_allclose(token.poses.numpy()[:, 0, 0], 2.0)
+
+ token.update_from_poses(wp.array(np.stack([_pose(1.0), _pose(3.0)]), dtype=wp.transform))
+ wp.synchronize_device(self.device)
+ self.assertEqual(token.poses.ptr, storage_ptr)
+ self.assertEqual(token.num_poses, 2)
+ np.testing.assert_allclose(token.poses.numpy()[:, 0, 0], [1.0, 3.0, 3.0, 3.0])
+
+ with self.assertRaisesRegex(ValueError, "requires 1 to 4 poses"):
+ token.update_from_poses(wp.array(np.stack([_pose(0.0)] * 5), dtype=wp.transform))
+
+ def test_runtime_root_offset_moves_only_the_root_joint(self) -> None:
+ skeleton = Skeleton(["Root", "Child"], [-1, 0], np.concatenate([_pose(0.0), _pose(0.0)]))
+ frames = np.stack([
+ np.concatenate([_pose(1.0), _pose(5.0)]),
+ np.concatenate([_pose(3.0), _pose(7.0)]),
+ ])
+ animation = AnimationBuffer(skeleton, 30.0, wp.array(frames, dtype=wp.transform))
+ output_pose = wp.empty(2, dtype=wp.transform)
+ root_offset = wp.transform(
+ wp.vec3(10.0, 20.0, 0.0),
+ wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), 0.5 * np.pi),
+ )
+
+ animation.sample(1.0 / 60.0, output_pose, root_offset=root_offset)
+ wp.synchronize_device(self.device)
+
+ expected_root = wp.mul(root_offset, wp.transform(wp.vec3(2.0, 0.0, 0.0), wp.quat_identity()))
+ np.testing.assert_allclose(output_pose.numpy()[0], np.asarray(expected_root), atol=1.0e-6)
+ np.testing.assert_allclose(output_pose.numpy()[1], _pose(6.0)[0], atol=1.0e-6)
+
+ def test_make_loopable_distributes_end_to_start_delta(self) -> None:
+ frames = wp.array(
+ np.stack([_pose(0.0), _pose(1.0), _pose(3.0), _pose(100.0), _pose(200.0)]),
+ dtype=wp.transform,
+ )
+ animation = AnimationBuffer(self.skeleton, 30.0, frames, num_frames=3)
+
+ animation.make_loopable()
+ wp.synchronize_device(self.device)
+
+ corrected = animation.poses.numpy()
+ np.testing.assert_allclose(corrected[0], _pose(0.0))
+ np.testing.assert_allclose(corrected[1], _pose(-0.5))
+ np.testing.assert_allclose(corrected[2], _pose(0.0))
+ np.testing.assert_array_equal(corrected[3:], np.stack([_pose(100.0), _pose(200.0)]))
+
+ animation.num_frames = 1
+ animation.make_loopable()
+ np.testing.assert_allclose(animation.poses.numpy()[0], _pose(0.0))
+
+ def test_make_loopable_moves_the_root_along_a_straight_line(self) -> None:
+ # The root makes a quarter turn and ends 0.3 m from its start.
+ frames = np.array([
+ [[x, 0.0, 0.0, *wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), angle)]]
+ for x, angle in ((0.0, 0.0), (1.0, 0.25 * np.pi), (0.3, 0.5 * np.pi))
+ ], dtype=np.float32)
+ animation = AnimationBuffer(self.skeleton, 30.0, wp.array(frames, dtype=wp.transform))
+
+ animation.make_loopable()
+
+ corrected = animation.poses.numpy()[:, 0]
+ # The middle frame moves by half the end gap, in the same direction as the gap.
+ np.testing.assert_allclose(corrected[1, :3], [0.85, 0.0, 0.0], atol=1e-6)
+ np.testing.assert_allclose(corrected[2, :3], corrected[0, :3], atol=1e-6)
+ self.assertAlmostEqual(abs(float(corrected[2, 3:] @ corrected[0, 3:])), 1.0, places=6)
+
+ def test_copy_keeps_the_frames_in_use_in_new_storage(self) -> None:
+ frames = wp.array(np.stack([_pose(0.0), _pose(1.0), _pose(9.0)]), dtype=wp.transform)
+ contacts = wp.array(np.arange(12, dtype=np.float32).reshape(3, 4), dtype=wp.float32)
+ animation = AnimationBuffer(self.skeleton, 30.0, frames, num_frames=2, foot_contacts=contacts)
+
+ copy = animation.copy()
+
+ self.assertIs(copy.skeleton, self.skeleton)
+ self.assertEqual((copy.capacity, copy.num_frames, copy.sample_rate), (2, 2, 30.0))
+ self.assertNotEqual(copy.poses.ptr, frames.ptr)
+ np.testing.assert_array_equal(copy.poses.numpy(), frames.numpy()[:2])
+ np.testing.assert_array_equal(copy.foot_contacts.numpy(), contacts.numpy()[:2])
+ self.assertIsNone(AnimationBuffer(self.skeleton, 30.0, frames).copy().foot_contacts)
+
+ def test_delta_pose_is_right_multiplicative(self) -> None:
+ transform = wp.transform(
+ wp.vec3(1.0, 2.0, 3.0),
+ wp.quat_from_axis_angle(wp.vec3(0.0, 0.0, 1.0), 0.5),
+ )
+ target_transform = wp.transform(
+ wp.vec3(4.0, 2.0, 1.0),
+ wp.quat_from_axis_angle(wp.vec3(0.0, 1.0, 0.0), -0.25),
+ )
+ pose = wp.array([transform], dtype=wp.transform)
+ target_pose = wp.array([target_transform], dtype=wp.transform)
+ delta_pose = wp.empty_like(pose)
+
+ pose_utils.compute_delta_pose(pose, target_pose, delta_pose)
+ pose_utils.apply_delta_pose(pose, delta_pose, 1.0)
+ wp.synchronize_device(self.device)
+
+ expected_delta = wp.mul(
+ wp.transform_inverse(transform),
+ target_transform,
+ )
+ np.testing.assert_allclose(
+ delta_pose.numpy()[0],
+ np.asarray(expected_delta),
+ atol=1.0e-5,
+ )
+ np.testing.assert_allclose(
+ pose.numpy()[0],
+ np.asarray(target_transform),
+ atol=1.0e-5,
+ )
+
+ def test_history_keeps_latest_pose_at_active_end(self) -> None:
+ motion_history = MotionRecorder(self.skeleton.reference_local_transforms, capacity=3)
+ device_poses = []
+ for frame in range(4):
+ device_poses.append(
+ wp.array(_pose(float(frame)), dtype=wp.transform)
+ )
+ motion_history.record(float(frame + 1), device_poses[-1])
+ wp.synchronize_device(self.device)
+
+ np.testing.assert_allclose(motion_history.delta_times, [3.0, 4.0, 0.0])
+ np.testing.assert_allclose(
+ motion_history.poses.numpy()[:, 0, 0],
+ [1.0, 2.0, 3.0],
+ )
+
+ def test_history_resamples_variable_frame_deltas_at_model_rate(self) -> None:
+ motion_history = MotionRecorder(self.skeleton.reference_local_transforms, capacity=16)
+ timestamp = 0.0
+ device_poses = []
+ for delta_time in (0.020, 0.015, 0.030, 0.025, 0.020):
+ timestamp += delta_time
+ device_poses.append(
+ wp.array(_pose(timestamp), dtype=wp.transform)
+ )
+ motion_history.record(delta_time, device_poses[-1])
+
+ token = PoseToken(1)
+ token.update_from_recorder(motion_history)
+ wp.synchronize_device(self.device)
+
+ expected = timestamp + np.arange(-3, 1, dtype=np.float32) / 30.0
+ np.testing.assert_allclose(
+ token.poses.numpy()[:, 0, 0],
+ expected,
+ atol=1.0e-6,
+ )
+
+ def test_animation_buffer_tracks_valid_frames_in_reusable_storage(self) -> None:
+ frames = wp.array(
+ np.stack([_pose(0.0), _pose(1.0), _pose(2.0), _pose(999.0)]),
+ dtype=wp.transform,
+ )
+ output = AnimationBuffer(self.skeleton, 30.0, frames, num_frames=0)
+ self.assertEqual(output.capacity, 4)
+ self.assertEqual(output.duration, 0)
+ sampled = wp.empty(1, dtype=wp.transform)
+ with self.assertRaisesRegex(ValueError, "empty"):
+ output.sample(0, sampled)
+ for count in (3, 2, 1):
+ output.num_frames = count
+ self.assertEqual(output.poses.ptr, frames.ptr)
+ self.assertAlmostEqual(output.duration, (count - 1) / 30)
+ output.sample(10, sampled)
+ np.testing.assert_array_equal(sampled.numpy(), _pose(float(count - 1)))
+ output.num_frames = 3
+
+ output.sample(1.0 / 60.0, sampled)
+ wp.synchronize_device(self.device)
+
+ self.assertEqual(output.num_frames, 3)
+ self.assertTrue(output.poses.device.is_cuda)
+ self.assertAlmostEqual(float(sampled.numpy()[0, 0]), 0.5, places=6)
+ for invalid in (-1, output.capacity + 1):
+ with self.assertRaises(ValueError):
+ output.num_frames = invalid
+ self.assertEqual(output.num_frames, 3)
+ output.num_frames = 0
+ with self.assertRaisesRegex(ValueError, "empty"):
+ output.sample(0, sampled)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_real_engines.py b/tests/motionbricks/test_real_engines.py
new file mode 100644
index 0000000..4b9d261
--- /dev/null
+++ b/tests/motionbricks/test_real_engines.py
@@ -0,0 +1,184 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""The real TensorRT engines generate sane motion from the bundled models.
+
+Each generation's length must come from the token counts its config allows.
+
+These tests load the SOMA and G1 engines in FP32 and FP16. They need an NVIDIA GPU.
+The first run builds the engines into .trt-cache, which takes several minutes.
+Set the MOTIONBRICKS_ENGINE_TESTS environment variable to 1 to run them.
+Run them after changing the ONNX models, the decode kernels or TensorRT.
+"""
+
+import os
+from pathlib import Path
+import unittest
+
+import numpy as np
+from scipy.spatial.transform import Rotation
+import warp as wp
+
+from motionbricks.inference.builder import TensorRTBuildOptions
+from motionbricks.io.bvh import load_bvh
+from motionbricks.io.csv import load_csv
+from motionbricks.io.usd import load_skeleton_from_usd
+from motionbricks.io.utils import SOMA_SKELETON_PRIM_PATH, get_asset_file
+from motionbricks.model.config import MotionBricksInferenceConfig
+from motionbricks.model.contract import valid_frame_count
+from motionbricks.model.soma.contract import SOMA_N1_CONTRACT, SOMA_N1_FP16_ONNX_PATH, SOMA_N1_FP32_ONNX_PATH
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.model.unitree_g1.contract import UNITREE_G1_N1_FP16_ONNX_PATH, UNITREE_G1_N1_FP32_ONNX_PATH
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+from motionbricks.utils.space_conversion_utils import FacingDirectionType, SpaceConverter
+
+
+_REPO = Path(__file__).resolve().parents[2]
+_WALK = "locomotion/bs_1d_linear/Neutral_walk_forward_002__A057"
+# The first context ends 1 s into the walk. Each generation targets the walk poses at the next time.
+_CONTEXT_END = 1.0
+_TARGET_TIMES = (1.6, 3.2)
+
+
+def _clip_window(clip, poses, start, to_runtime):
+ """Sample four clip poses at 30 Hz from start, into an array shaped like poses."""
+ window = wp.empty((4, poses.shape[1]), dtype=poses.dtype, device=poses.device)
+ for index in range(4):
+ clip.sample(start + index / 30.0, window[index], root_offset=to_runtime)
+ return window
+
+
+def _degrees_between(a, b):
+ return np.degrees((Rotation.from_quat(a).inv() * Rotation.from_quat(b)).magnitude())
+
+
[email protected](os.environ.get("MOTIONBRICKS_ENGINE_TESTS") == "1", "set MOTIONBRICKS_ENGINE_TESTS=1 to run")
+class RealEngineTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cuda:0")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def check_walk(self, engine, clip, to_runtime, context, target, output, poses, errors):
+ """Generate along the walk without endpoint correction.
+
+ The first generation starts from clip poses. Each later one starts from the last four
+ generated poses, the way the demos chain them. poses is the output's pose array.
+ Each foot's contacts must reach high and low values along the walk.
+ """
+ config = MotionBricksInferenceConfig(correct_generated_diff=False)
+ contacts = []
+ with wp.ScopedStream(engine.stream):
+ context_poses = _clip_window(clip, poses, _CONTEXT_END - 3 / 30.0, to_runtime)
+ for target_time in _TARGET_TIMES:
+ target_poses = _clip_window(clip, poses, target_time, to_runtime)
+ context.update_from_poses(context_poses, stream=engine.stream)
+ target.update_from_poses(target_poses, stream=engine.stream)
+ engine.generate_animation(context, target, output, config=config)
+ raw = poses.numpy()[:output.num_frames]
+ self.assert_walk(raw, context_poses.numpy()[-1], target_poses.numpy()[0], errors)
+ contacts.append(output.foot_contacts.numpy()[:output.num_frames])
+ context_poses = wp.clone(poses[output.num_frames - 4:output.num_frames])
+ contacts = np.concatenate(contacts)
+ self.assertTrue(((contacts >= 0.0) & (contacts <= 1.0)).all())
+ for side in (contacts[:, :2], contacts[:, 2:]):
+ self.assertGreater(side.max(), 0.8)
+ self.assertLess(side.min(), 0.2)
+
+ def assert_walk(self, raw, last_context, first_target, errors):
+ """errors(a, b) gives the root distance in meters and each joint's turn in degrees between two poses."""
+ self.assertTrue(np.isfinite(raw).all())
+ # A wrong decode would leave the raw motion far from the poses it was generated from.
+ for pose, end in ((raw[0], last_context), (raw[-1], first_target)):
+ distance, turns = errors(pose, end)
+ self.assertLess(distance, 0.05)
+ self.assertLess(turns.mean(), 10.0)
+ for previous, pose in zip(raw[:-1], raw[1:]):
+ distance, turns = errors(previous, pose)
+ self.assertLess(distance, 0.15)
+ self.assertLess(turns.max(), 45.0)
+
+ def check_token_counts(self, engine, clip, to_runtime, context, target, output, poses):
+ """Each generation's length must come from the allowed token counts in its config.
+
+ One allowed count forces the length. Several let the model choose among them.
+ """
+ with wp.ScopedStream(engine.stream):
+ context_poses = _clip_window(clip, poses, _CONTEXT_END - 3 / 30.0, to_runtime)
+ context.update_from_poses(context_poses, stream=engine.stream)
+ target.update_from_poses(_clip_window(clip, poses, _TARGET_TIMES[0], to_runtime), stream=engine.stream)
+ for allowed in ((6,), (11,), (16,), (12, 13), (7, 15)):
+ with self.subTest(allowed=allowed):
+ config = MotionBricksInferenceConfig(allowed_token_counts=allowed)
+ engine.generate_animation(context, target, output, config=config)
+ lengths = [valid_frame_count(count) for count in allowed]
+ self.assertIn(output.num_frames, lengths)
+
+ def soma_engine(self, fp16):
+ """Return the SOMA engine, followed by the other arguments of check_walk."""
+ skeleton = load_skeleton_from_usd(
+ get_asset_file("human", "soma_base_skel_minimal_no_root.usd"), SOMA_SKELETON_PRIM_PATH,
+ )
+ clip = load_bvh(str(_REPO / f"assets/motions/soma/{_WALK}.bvh"), skeleton)
+ to_runtime = SpaceConverter(FacingDirectionType.MUJOCO).convert_transform(wp.transform_identity())
+ # The skeleton also has finger joints, which the model does not predict.
+ joints = [skeleton.joint_names.index(name) for name in SOMA_N1_CONTRACT.joint_names]
+
+ def errors(a, b):
+ return np.linalg.norm(a[0, :3] - b[0, :3]), _degrees_between(a[joints, 3:], b[joints, 3:])
+
+ engine = MotionBricksSOMAEngine(
+ SOMA_N1_FP16_ONNX_PATH if fp16 else SOMA_N1_FP32_ONNX_PATH, model_to_runtime=to_runtime,
+ build_options=TensorRTBuildOptions(enable_fp16=fp16), cache_dir=_REPO / ".trt-cache",
+ )
+ self.addCleanup(engine.close)
+ context, target = engine.create_input(skeleton), engine.create_input(skeleton)
+ output = engine.create_output(skeleton)
+ return engine, clip, to_runtime, context, target, output, output.poses, errors
+
+ def g1_engine(self, fp16):
+ """Return the G1 engine, followed by the other arguments of check_walk."""
+ clip = load_csv(_REPO / f"assets/motions/unitree_g1/{_WALK}.csv", device="cuda:0")
+ to_runtime = wp.transform_identity()
+
+ def errors(a, b):
+ # A G1 pose holds the root position and XYZW rotation, then one hinge angle per joint.
+ turns = np.append(_degrees_between(a[3:7], b[3:7]), np.degrees(np.abs(a[7:] - b[7:])))
+ return np.linalg.norm(a[:3] - b[:3]), turns
+
+ engine = MotionBricksUnitreeG1Engine(
+ UNITREE_G1_N1_FP16_ONNX_PATH if fp16 else UNITREE_G1_N1_FP32_ONNX_PATH,
+ build_options=TensorRTBuildOptions(enable_fp16=fp16), cache_dir=_REPO / ".trt-cache",
+ )
+ self.addCleanup(engine.close)
+ context, target, output = engine.create_input(), engine.create_input(), engine.create_output()
+ return engine, clip, to_runtime, context, target, output, output.poses, errors
+
+ def test_soma_chains_walks_between_clip_poses(self):
+ for fp16 in (False, True):
+ with self.subTest(fp16=fp16):
+ self.check_walk(*self.soma_engine(fp16))
+
+ def test_g1_chains_walks_between_clip_poses(self):
+ for fp16 in (False, True):
+ with self.subTest(fp16=fp16):
+ self.check_walk(*self.g1_engine(fp16))
+
+ def test_soma_generates_only_allowed_token_counts(self):
+ for fp16 in (False, True):
+ with self.subTest(fp16=fp16):
+ self.check_token_counts(*self.soma_engine(fp16)[:-1])
+
+ def test_g1_generates_only_allowed_token_counts(self):
+ for fp16 in (False, True):
+ with self.subTest(fp16=fp16):
+ self.check_token_counts(*self.g1_engine(fp16)[:-1])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_skeleton_renderer.py b/tests/motionbricks/test_skeleton_renderer.py
new file mode 100644
index 0000000..b667d58
--- /dev/null
+++ b/tests/motionbricks/test_skeleton_renderer.py
@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Skeleton previews draw each bone between a joint and its parent for every active pose."""
+
+import unittest
+from unittest.mock import Mock
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.renderers.skeleton_renderer import SkeletonRenderer
+
+
+def _local(position, angle=0.0):
+ return [*position, *wp.quat_from_axis_angle(wp.vec3(0, 0, 1), angle)]
+
+
+class SkeletonRendererTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_batch_draws_placed_bones_and_hides_zero_poses(self):
+ skeleton = Skeleton(["Hips", "Spine", "Head"], [-1, 0, 1], np.tile(_local((0, 0, 0)), (3, 1)))
+ poses = np.full((3, 3, 7), np.nan, dtype=np.float32)
+ poses[0] = [_local((0, 0, 1)), _local((0, 0, 0.5)), _local((0, 0, 0.3))]
+ poses[1] = [_local((2, 3, 1), 0.5 * np.pi), _local((0.5, 0, 0)), _local((0.3, 0, 0))]
+ local_poses = wp.array(poses, dtype=wp.transform)
+ placement = wp.transform(wp.vec3(10, 0, 0), wp.quat_from_axis_angle(wp.vec3(0, 0, 1), 0.5 * np.pi))
+ colors = wp.array([wp.vec3(0.2, 0.75, 1.0), wp.vec3(1.0, 0.5, 0.2)], dtype=wp.vec3)
+ renderer = SkeletonRenderer(skeleton, max_instances=1)
+ viewer = Mock()
+
+ renderer.draw_batch(viewer, local_poses, 2, placement, colors, "target")
+
+ joints = [[[10, 0, 1], [10, 0, 1.5], [10, 0, 1.8]], [[7, 2, 1], [6.5, 2, 1], [6.2, 2, 1]]]
+ np.testing.assert_allclose(renderer.world_poses.numpy()[:2, :3, :3], joints, atol=1e-6)
+ _, starts, ends, line_colors = viewer.log_lines.call_args.args
+ # Each bone draws 16 lines, one pyramid from the joint and one from its parent.
+ self.assertEqual(starts.shape, (2 * 2 * 16,))
+ starts = starts.numpy().reshape(2, 2, 16, 3)
+ for pose in range(2):
+ for bone, (parent, child) in enumerate(((0, 1), (1, 2))):
+ np.testing.assert_allclose(starts[pose, bone, 0], joints[pose][child], atol=1e-6)
+ np.testing.assert_allclose(starts[pose, bone, 8], joints[pose][parent], atol=1e-6)
+ self.assertTrue(np.isfinite(ends.numpy()).all())
+ pose_colors = np.repeat(colors.numpy()[:, None], 32, axis=1)
+ np.testing.assert_allclose(line_colors.numpy().reshape(2, 32, 3), pose_colors)
+ np.testing.assert_array_equal(local_poses.numpy(), poses)
+ renderer.draw_batch(viewer, local_poses, 0, placement, colors, "target")
+ self.assertTrue(viewer.log_lines.call_args.kwargs["hidden"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_solid_box_renderer.py b/tests/motionbricks/test_solid_box_renderer.py
new file mode 100644
index 0000000..4418a69
--- /dev/null
+++ b/tests/motionbricks/test_solid_box_renderer.py
@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import unittest
+from unittest.mock import Mock
+
+import numpy as np
+import warp as wp
+
+from motionbricks.renderers.solid_box_renderer import SolidBoxRenderer
+
+
+class SolidBoxRendererTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def test_box_picking_uses_rotation_full_dimensions_and_positive_ray_distances(self):
+ size = wp.vec3(2, 4, 6)
+ for rotation, origin, direction, limit, expected in (
+ (0.0, (3, 4, 10), (0, 0, -1), 100, 2),
+ (0.0, (3, 4, 10), (0, 0, 1), 100, 100),
+ (0.0, (5, 4, 10), (0, 0, -1), 100, 100),
+ (0.0, (3, 4, 10), (0, 0, -1), 1, 1),
+ (0.0, (3, 4, 5), (0, 1, 0), 100, 2),
+ (wp.pi / 2, (10, 4, 5), (-1, 0, 0), 100, 5),
+ (wp.pi / 2, (3, 5.5, 10), (0, 0, -1), 100, 100),
+ ):
+ with self.subTest(rotation=rotation, origin=origin, direction=direction, limit=limit):
+ transform = wp.transform(wp.vec3(3, 4, 5), wp.quat_rpy(0.0, 0.0, rotation))
+ distance = SolidBoxRenderer.raycast(transform, size, wp.vec3(*origin), wp.vec3(*direction), limit)
+ self.assertAlmostEqual(distance, expected, places=5)
+
+ def test_drawn_box_matches_the_pick_volume(self) -> None:
+ renderer = SolidBoxRenderer(device="cpu")
+ viewer = Mock()
+ size = wp.vec3(2.0, 3.0, 4.0)
+
+ renderer.draw_batch(viewer, [wp.transform_identity()], [size], [wp.vec3(0.2, 0.4, 0.8)], "scene")
+
+ half_extents = viewer.log_geo.call_args.args[2]
+ scales = viewer.log_instances.call_args.args[3].numpy()
+ np.testing.assert_allclose(2.0 * np.asarray(half_extents) * scales, [size])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_soma_generation.py b/tests/motionbricks/test_soma_generation.py
new file mode 100644
index 0000000..2645078
--- /dev/null
+++ b/tests/motionbricks/test_soma_generation.py
@@ -0,0 +1,163 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""SOMA generation with a controlled predictor in place of TensorRT."""
+
+import unittest
+
+import numpy as np
+from scipy.spatial.transform import Rotation
+import warp as wp
+
+from motionbricks.animation.animation_buffer import AnimationBuffer
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.inference.errors import TensorContractError
+from motionbricks.io.usd import load_skeleton_from_usd
+from motionbricks.io.utils import SOMA_SKELETON_PRIM_PATH, get_asset_file
+from motionbricks.model.config import MotionBricksInferenceConfig
+from motionbricks.model.soma.engine import MotionBricksSOMAEngine
+from motionbricks.utils.space_conversion_utils import FacingDirectionType, SpaceConverter
+
+
+def _transform(values) -> wp.transform:
+ return wp.transform(wp.vec3(*values[:3]), wp.quat(*values[3:7]))
+
+
+def _config(tokens: int, correct: bool) -> MotionBricksInferenceConfig:
+ return MotionBricksInferenceConfig(allowed_token_counts=(tokens,), correct_generated_diff=correct)
+
+
+class _ControlledSOMAEngine(MotionBricksSOMAEngine):
+ """Exercise the real generation path, replacing only the TensorRT backend."""
+
+ def _initialize(self, build_options, *, cache_dir, force_rebuild, progress_monitor):
+ self._tensor_specs = {spec.name: spec for spec in self.contract.tensor_specs}
+ self._buffers = {
+ spec.name: wp.zeros(
+ spec.shape, dtype=wp.float32 if spec.dtype == np.dtype(np.float32) else wp.int32, device=self.device,
+ )
+ for spec in self.contract.tensor_specs
+ }
+ self.tokens = 8
+
+ def _enqueue_tensorrt(self):
+ with wp.ScopedStream(self.stream):
+ wp.copy(self.device_tensor("pred_global_motions"), self.prediction)
+ self.device_tensor("pred_num_tokens").assign([self.tokens])
+
+
+class SOMAGenerationEngineTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ if not wp.is_cuda_available():
+ raise unittest.SkipTest("CUDA is unavailable")
+ cls.previous_device = wp.get_device()
+ wp.set_device("cuda:0")
+ cls.skeleton = load_skeleton_from_usd(
+ get_asset_file("human", "soma_base_skel_minimal_no_root.usd"), SOMA_SKELETON_PRIM_PATH,
+ )
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def setUp(self):
+ self.model_to_runtime = SpaceConverter(FacingDirectionType.MUJOCO).convert_transform(wp.transform_identity())
+ self.engine = _ControlledSOMAEngine(
+ "controlled.onnx", model_to_runtime=self.model_to_runtime, bake_cuda_graph=False,
+ )
+ self.addCleanup(self.engine.close)
+ # Hips move forward in the aligned model space. Every joint keeps an identity global rotation.
+ prediction = np.zeros((1, 64, 366), dtype=np.float32)
+ prediction[0, :, 0:3] = np.column_stack((0.02 * np.arange(64), np.full(64, 0.9), 0.05 * np.arange(64)))
+ rotations = 5 + 3 * (len(self.engine.contract.joint_names) - 1)
+ for joint in range(len(self.engine.contract.joint_names)):
+ prediction[0, :, rotations + 6 * joint: rotations + 6 * joint + 6] = [1, 0, 0, 0, 1, 0]
+ self.prediction = prediction
+ self.engine.prediction = wp.array(prediction, dtype=wp.float32)
+
+ self.output = self.engine.create_output(self.skeleton)
+ self.context = self.engine.create_input(self.skeleton)
+ self.target = self.engine.create_input(self.skeleton)
+ reference = self.skeleton.reference_local_transforms.numpy()
+ hips = _transform(reference[0])
+ poses = np.repeat(reference[None], 8, axis=0)
+ for frame in range(8):
+ # Walk along the model's forward axis, with the target poses 1.5 m further ahead.
+ step = wp.vec3(0.0, 0.0, 0.04 * frame + (1.5 if frame >= 4 else 0.0))
+ moved = wp.transform(wp.add(hips.p, step), hips.q)
+ poses[frame, 0] = np.asarray(wp.mul(self.model_to_runtime, moved))
+ with wp.ScopedStream(self.engine.stream):
+ self.context.update_from_poses(wp.array(poses[:4], dtype=wp.transform), stream=self.engine.stream)
+ self.target.update_from_poses(wp.array(poses[4:], dtype=wp.transform), stream=self.engine.stream)
+ self.poses = poses
+
+ def generate(self, tokens: int, correct: bool, context=None) -> np.ndarray:
+ self.engine.tokens = tokens
+ self.engine.generate_animation(
+ context or self.context, self.target, self.output, config=_config(tokens, correct),
+ )
+ return self.output.poses.numpy()[:self.output.num_frames].copy()
+
+ def test_generation_trims_padding_and_places_the_hips_in_runtime_space(self):
+ pointer = self.output.poses.ptr
+ for tokens in (16, 6, 8):
+ with self.subTest(tokens=tokens):
+ frames = self.generate(tokens, correct=False)
+ self.assertEqual(self.output.num_frames, tokens * 4 - 6)
+ self.assertEqual(self.output.poses.ptr, pointer)
+ # The first output frame is the raw frame after the three padding frames.
+ to_runtime = wp.mul(self.model_to_runtime, _transform(self.engine._alignment.numpy()[0]))
+ expected = [wp.transform_point(to_runtime, wp.vec3(*self.prediction[0, 3 + frame, :3]))
+ for frame in range(len(frames))]
+ np.testing.assert_allclose(frames[:, 0, :3], expected, atol=1e-5)
+
+ def test_generation_copies_each_output_frames_foot_contacts_clamped(self):
+ contacts = np.arange(64 * 4, dtype=np.float32).reshape(64, 4) / 128.0 - 0.5
+ self.prediction[0, :, -4:] = contacts
+ self.engine.prediction = wp.array(self.prediction, dtype=wp.float32)
+ self.generate(8, correct=False)
+ frames = self.output.num_frames
+ # Output frame 0 is the raw frame after the three padding frames.
+ np.testing.assert_array_equal(self.output.foot_contacts.numpy()[:frames], np.clip(contacts[3:3 + frames], 0, 1))
+
+ def test_correction_meets_context_and_target_poses_and_can_be_turned_off(self):
+ raw = self.generate(8, correct=False)
+ corrected = self.generate(8, correct=True)
+ for frame, pose in ((corrected[0], self.poses[3]), (corrected[-1], self.poses[4])):
+ np.testing.assert_allclose(frame[:, :3], pose[:, :3], atol=1e-4)
+ angles = (Rotation.from_quat(frame[:, 3:]).inv() * Rotation.from_quat(pose[:, 3:])).magnitude()
+ self.assertLess(float(angles.max()), 1e-3)
+ self.assertGreater(float(np.abs(raw[0, 0, :3] - self.poses[3, 0, :3]).max()), 1e-2)
+ np.testing.assert_array_equal(self.generate(8, correct=False), raw)
+ self.assertEqual(self.engine.timer.milliseconds["post_process"], 0.0)
+
+ def test_invalid_model_lengths_raise_without_publishing_frames(self):
+ for tokens in (5, 17, 7):
+ with self.subTest(tokens=tokens):
+ self.generate(8, correct=False)
+ self.engine.tokens = tokens
+ with self.assertRaises(TensorContractError):
+ self.engine.generate_animation(self.context, self.target, self.output, config=_config(8, False))
+ self.assertEqual(self.output.num_frames, 0)
+
+ def test_buffers_must_match_the_model(self):
+ for create in (self.engine.create_input, self.engine.create_output):
+ with self.subTest(create=create.__name__), self.assertRaisesRegex(ValueError, "missing model joints"):
+ create(Skeleton(["Hips"], [-1], [wp.transform_identity()]))
+ short_context = self.engine.create_input(self.skeleton)
+ with wp.ScopedStream(self.engine.stream):
+ short_context.update_from_poses(wp.array(self.poses[:2], dtype=wp.transform), stream=self.engine.stream)
+ with self.assertRaisesRegex(ValueError, "Context token must contain 4 poses"):
+ self.generate(8, correct=False, context=short_context)
+ empty_target = self.engine.create_input(self.skeleton)
+ with self.assertRaisesRegex(ValueError, "Target token must contain 1 to 4 poses"):
+ self.engine.generate_animation(self.context, empty_target, self.output)
+ no_contacts = AnimationBuffer(self.skeleton, 30.0, wp.empty_like(self.output.poses), num_frames=0)
+ with self.assertRaisesRegex(ValueError, "foot_contacts"):
+ self.engine.generate_animation(self.context, self.target, no_contacts)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_soma_pose_pipeline.py b/tests/motionbricks/test_soma_pose_pipeline.py
new file mode 100644
index 0000000..f365e73
--- /dev/null
+++ b/tests/motionbricks/test_soma_pose_pipeline.py
@@ -0,0 +1,242 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.io.usd import load_skeleton_from_usd
+from motionbricks.io.utils import SOMA_SKELETON_PRIM_PATH, get_asset_file, get_soma_human_model
+from motionbricks.model.contract import MODEL_CONTEXT_AND_TARGET_POSES, MODEL_POSES_PER_TOKEN, valid_frame_count
+from motionbricks.model.soma import kernels
+from motionbricks.model.soma.contract import SOMA_N1_CONTRACT
+from motionbricks.runtime.target_pose import IKPin, TargetPoseIKCorrector, create_soma_target_pose_ik_rig
+from motionbricks.utils import pose_utils
+from motionbricks.utils.space_conversion_utils import FacingDirectionType, SpaceConverter
+
+
+def _as_transform(values: np.ndarray) -> wp.transform:
+ return wp.transform(wp.vec3(*values[:3]), wp.quat(*values[3:]))
+
+
+class SOMAPosePipelineTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+ cls.skeleton = load_skeleton_from_usd(
+ get_asset_file("human", "soma_base_skel_minimal_no_root.usd"),
+ SOMA_SKELETON_PRIM_PATH,
+ )
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def test_usd_rest_pose_defines_the_runtime_skeleton_and_model_joints(self) -> None:
+ skeleton = self.skeleton
+
+ self.assertEqual(skeleton.num_joints, 77)
+ self.assertEqual(skeleton.joint_names[:3], ["Hips", "Spine1", "Spine2"])
+ np.testing.assert_array_equal(skeleton.parent_indices.numpy()[:3], [-1, 0, 1])
+ np.testing.assert_allclose(skeleton.up_axis, [0.0, 1.0, 0.0])
+ np.testing.assert_allclose(skeleton.forward_axis, [0.0, 0.0, 1.0])
+
+ model_indices = [skeleton.joint_index(name) for name in SOMA_N1_CONTRACT.joint_names]
+ self.assertTrue(all(index >= 0 for index in model_indices))
+ self.assertEqual(len(set(model_indices)), len(model_indices))
+ thumb_end = skeleton.joint_index("LeftHandThumbEnd")
+ self.assertEqual(skeleton.joint_name(skeleton.joint_parent(thumb_end)), "LeftHandThumb3")
+
+ def test_mesh_holds_relaxed_hands_and_a_fingers_mask(self) -> None:
+ mesh = get_soma_human_model()
+ finger = re.compile(r"(Left|Right)Hand(Thumb|Index|Middle|Ring|Pinky)")
+ fingers = [index for index, name in enumerate(mesh.skeleton.joint_names) if finger.match(name)]
+ self.assertEqual(len(fingers), 48)
+ weights = mesh.override_pose_masks["Fingers"].numpy()
+ np.testing.assert_array_equal(np.flatnonzero(weights), fingers)
+ np.testing.assert_array_equal(weights[fingers], 1.0)
+
+ # The reference pose keeps its own fingers, so only the drawn mesh curls them.
+ relaxed = mesh.override_poses["RelaxedHands"].numpy()[fingers, 3:]
+ rest = mesh.skeleton.reference_local_transforms.numpy()[fingers, 3:]
+ turns = np.degrees(2 * np.arccos(np.clip(np.abs(np.sum(relaxed * rest, axis=1)), 0, 1)))
+ self.assertGreater(turns.max(), 20)
+
+ def test_target_pose_ik_corrector_builds_on_the_usd_skeleton(self) -> None:
+ corrector = TargetPoseIKCorrector(self.skeleton, create_soma_target_pose_ik_rig(self.skeleton))
+ corrector.capture_pins(self.skeleton.reference_local_transforms, IKPin.ALL)
+ self.assertEqual(corrector.pin_mask, IKPin.ALL)
+
+ def test_decoder_restores_world_displacement_for_generated_frames(self) -> None:
+ num_model_joints = len(SOMA_N1_CONTRACT.joint_names)
+ num_full_joints = self.skeleton.num_joints
+ frame_count = valid_frame_count(6)
+ features = np.zeros((1, 64, 366), dtype=np.float32)
+ features[:, :, 0] = 2.0
+ features[:, :, 1] = 1.25
+ features[:, :, 2] = 3.0
+
+ position_offset = 5
+ rotation_offset = position_offset + (num_model_joints - 1) * 3
+ for joint in range(num_model_joints):
+ features[:, :, rotation_offset + joint * 6] = 1.0
+ features[:, :, rotation_offset + joint * 6 + 4] = 1.0
+
+ predicted = wp.array(features, dtype=wp.float32)
+ predicted_tokens = wp.array([6], dtype=wp.int32)
+ model_to_pose = [self.skeleton.joint_index(name) for name in SOMA_N1_CONTRACT.joint_names]
+ pose_to_model_values = np.full(num_full_joints, -1, dtype=np.int32)
+ for model_joint, pose_joint in enumerate(model_to_pose):
+ parent = self.skeleton.joint_parent(pose_joint)
+ if parent == -1 or pose_to_model_values[parent] >= 0:
+ pose_to_model_values[pose_joint] = model_joint
+ pose_to_model = wp.array(pose_to_model_values, dtype=wp.int32)
+ reference = self.skeleton.reference_local_transforms
+ alignment = wp.array([wp.transform(wp.vec3(100.0, 0.0, -200.0), wp.quat_identity())], dtype=wp.transform)
+ converter = SpaceConverter(FacingDirectionType.MAYA)
+ model_to_runtime = converter.convert_transform(wp.transform_identity())
+ output_capacity = frame_count + 2
+ sentinel = np.asarray(wp.transform(wp.vec3(-9.0, -8.0, -7.0), wp.quat_identity()), dtype=np.float32)
+ initial_output = np.tile(sentinel, (output_capacity, num_full_joints, 1))
+ output_local = wp.array(initial_output, dtype=wp.transform)
+ output_count = wp.empty(1, dtype=wp.int32)
+ output_contacts = wp.empty((output_capacity, 4), dtype=wp.float32)
+
+ wp.launch(kernels.decode_motionbricks_output_kernel, dim=output_capacity, inputs=[
+ num_model_joints, num_full_joints, self.skeleton.parent_indices,
+ pose_to_model, reference, alignment, model_to_runtime, predicted, predicted_tokens,
+ ], outputs=[output_local, output_contacts, output_count])
+
+ self.assertEqual(int(output_count.numpy()[0]), frame_count)
+ expected_hips = wp.mul(model_to_runtime, wp.transform(wp.vec3(102.0, 1.25, -197.0), wp.quat_identity()))
+ decoded_values = output_local.numpy()
+ np.testing.assert_allclose(decoded_values[0, 0], np.asarray(expected_hips), atol=1.0e-5)
+ np.testing.assert_allclose(decoded_values[frame_count:], initial_output[frame_count:], atol=1.0e-6)
+ reference_values = reference.numpy()
+ output_values = decoded_values[0]
+ for name in ("LeftHandThumbEnd", "LeftHandMiddleEnd", "RightHandThumbEnd", "RightHandMiddleEnd"):
+ joint = self.skeleton.joint_index(name)
+ self.assertEqual(pose_to_model_values[joint], -1)
+ np.testing.assert_allclose(output_values[joint], reference_values[joint])
+
+ def test_endpoint_correction_does_not_arc_hips_translation(self) -> None:
+ frame_count = 3
+ identity = np.asarray(wp.transform_identity(), dtype=np.float32)
+ context_values = np.tile(identity, (4, 1, 1))
+ target_values = context_values.copy()
+ output_values = np.tile(identity, (frame_count, 1, 1))
+
+ start_rotation = wp.quat_from_axis_angle(wp.vec3(0.0, 1.0, 0.0), 0.75)
+ end_rotation = wp.quat_from_axis_angle(wp.vec3(0.0, 1.0, 0.0), -0.75)
+ context_values[-1, 0] = np.asarray(wp.transform(wp.vec3(10.0, 0.0, 1.2), start_rotation))
+ target_values[0, 0] = np.asarray(wp.transform(wp.vec3(12.0, 0.0, 1.4), end_rotation))
+ output_values[:, 0, :3] = ((10.0, 0.0, 1.0), (11.0, 0.0, 1.0), (12.0, 0.0, 1.0))
+
+ context = wp.array(context_values, dtype=wp.transform)
+ target = wp.array(target_values, dtype=wp.transform)
+ output = wp.array(output_values, dtype=wp.transform)
+ output_count = wp.array([frame_count], dtype=wp.int32)
+ deltas = [wp.empty(1, dtype=wp.transform), wp.empty(1, dtype=wp.transform)]
+
+ wp.launch(kernels.compute_endpoint_deltas_kernel, dim=1,
+ inputs=[output_count, context, target, output], outputs=deltas)
+ wp.launch(kernels.apply_endpoint_deltas_kernel, dim=(frame_count, 1),
+ inputs=[output_count, *deltas], outputs=[output])
+
+ corrected = output.numpy()[:, 0]
+ np.testing.assert_allclose(corrected[0], context_values[-1, 0], atol=1.0e-5)
+ np.testing.assert_allclose(corrected[-1], target_values[0, 0], atol=1.0e-5)
+ np.testing.assert_allclose(
+ corrected[:, :3], [[10.0, 0.0, 1.2], [11.0, 0.0, 1.3], [12.0, 0.0, 1.4]], atol=1.0e-5,
+ )
+
+ def test_encoder_recenters_newton_poses_in_model_space(self) -> None:
+ skeleton = self.skeleton
+ reference = skeleton.reference_local_transforms.numpy()
+ context_poses = np.tile(reference[None, :, :], (MODEL_POSES_PER_TOKEN, 1, 1))
+ target_poses = np.tile(reference[None, :, :], (MODEL_POSES_PER_TOKEN, 1, 1))
+ planar_origin = np.array([10_000.0, 0.0, -20_000.0], dtype=np.float32)
+ context_poses[:, 0, :3] += planar_origin
+ target_poses[:, 0, :3] += planar_origin
+ target_poses[:, 0, 2] += 2.0
+
+ converter = SpaceConverter(FacingDirectionType.MAYA)
+ model_to_runtime = converter.convert_transform(wp.transform_identity())
+ for poses in (context_poses, target_poses):
+ for frame in range(poses.shape[0]):
+ poses[frame, 0] = np.asarray(wp.mul(model_to_runtime, _as_transform(poses[frame, 0])))
+ runtime_to_model = wp.transform_inverse(model_to_runtime)
+
+ num_model_joints = len(SOMA_N1_CONTRACT.joint_names)
+ model_to_pose = [skeleton.joint_index(name) for name in SOMA_N1_CONTRACT.joint_names]
+ model_indices = wp.array(model_to_pose, dtype=wp.int32)
+ right_leg, left_leg = skeleton.joint_index("RightLeg"), skeleton.joint_index("LeftLeg")
+ context_local = wp.array(context_poses, dtype=wp.transform)
+ target_local = wp.array(target_poses, dtype=wp.transform)
+ guide_world = wp.empty((MODEL_CONTEXT_AND_TARGET_POSES, skeleton.num_joints), dtype=wp.transform)
+ alignment = wp.empty(1, dtype=wp.transform)
+ specs = {spec.name: spec for spec in SOMA_N1_CONTRACT.tensor_specs}
+ global_root = wp.zeros(specs["global_root_values"].shape, dtype=wp.float32)
+ local_root = wp.zeros(specs["local_root_values"].shape, dtype=wp.float32)
+ local_pose = wp.zeros(specs["local_poses"].shape, dtype=wp.float32)
+
+ pose_utils.compute_world_poses(
+ context_local, skeleton.parent_indices, guide_world[:MODEL_POSES_PER_TOKEN], runtime_to_model,
+ )
+ pose_utils.compute_world_poses(
+ target_local, skeleton.parent_indices, guide_world[MODEL_POSES_PER_TOKEN:], runtime_to_model,
+ )
+ wp.launch(kernels.compute_guide_alignment_kernel, dim=1, inputs=[
+ right_leg, left_leg, wp.vec2(1.0, 0.0), guide_world,
+ ], outputs=[alignment])
+ wp.launch(kernels.encode_motionbricks_inputs_kernel, dim=MODEL_CONTEXT_AND_TARGET_POSES, inputs=[
+ num_model_joints, right_leg, left_leg, model_indices, guide_world, alignment,
+ ], outputs=[global_root, local_root, local_pose])
+
+ global_values = global_root.numpy()[0]
+ local_values = local_root.numpy()[0]
+ pose_values = local_pose.numpy()[0]
+ guide_values = guide_world.numpy()
+ context = MODEL_POSES_PER_TOKEN - 1
+ target = MODEL_POSES_PER_TOKEN
+
+ np.testing.assert_allclose(global_values[:MODEL_POSES_PER_TOKEN][:, [0, 2]], 0.0, atol=1.0e-5)
+ np.testing.assert_allclose(
+ global_values[MODEL_POSES_PER_TOKEN:][:, [0, 2]],
+ np.tile([2.0, 0.0], (MODEL_POSES_PER_TOKEN, 1)),
+ atol=1.0e-5,
+ )
+ self.assertAlmostEqual(float(global_values[context, 1]), float(guide_values[context, 0, 1]), places=5)
+ self.assertAlmostEqual(global_values[target, 0] - global_values[context, 0], 2.0, places=5)
+ np.testing.assert_allclose(local_values[context, :3], 0.0, atol=1.0e-5)
+ self.assertTrue(np.isfinite(pose_values).all())
+ rotations = pose_values[:, 3 * (num_model_joints - 1):].reshape(
+ MODEL_CONTEXT_AND_TARGET_POSES, num_model_joints, 6,
+ )
+ np.testing.assert_allclose(np.linalg.norm(rotations[..., :3], axis=-1), 1.0, atol=1.0e-5)
+ np.testing.assert_allclose(np.linalg.norm(rotations[..., 3:], axis=-1), 1.0, atol=1.0e-5)
+
+ def test_pose_utils_accept_single_and_batched_pose_storage(self) -> None:
+ reference = self.skeleton.reference_local_transforms.numpy()
+ local_values = np.repeat(reference[None], 2, axis=0)
+ local_values[1, 0, 0] += 1.0
+
+ parent_indices = self.skeleton.parent_indices
+ local_poses = wp.array(local_values, dtype=wp.transform)
+ world_poses = wp.empty_like(local_poses)
+ round_trip = wp.empty_like(local_poses)
+ pose_utils.compute_world_poses(local_poses, parent_indices, world_poses)
+ pose_utils.compute_local_poses(world_poses, parent_indices, round_trip)
+ np.testing.assert_allclose(round_trip.numpy(), local_values, atol=1.0e-5)
+
+ single_world = wp.empty(self.skeleton.num_joints, dtype=wp.transform)
+ pose_utils.compute_world_poses(local_poses[1], parent_indices, single_world)
+ np.testing.assert_allclose(single_world.numpy(), world_poses.numpy()[1], atol=1.0e-5)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_target_pose.py b/tests/motionbricks/test_target_pose.py
new file mode 100644
index 0000000..c0247c2
--- /dev/null
+++ b/tests/motionbricks/test_target_pose.py
@@ -0,0 +1,180 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for target-pose runtime contracts and utilities."""
+
+import unittest
+
+import numpy as np
+import warp as wp
+
+from motionbricks.animation.skeleton import Skeleton
+from motionbricks.runtime.target_pose import (
+ IKPin,
+ TargetPoseIKCorrector,
+ TwoBoneIKChainConfig,
+ adjust_target_dof_speed,
+ adjust_target_pose_speed,
+)
+
+
+def _transform(x: float, y: float, z: float) -> np.ndarray:
+ return np.array([x, y, z, 0.0, 0.0, 0.0, 1.0], dtype=np.float32)
+
+
+class TargetPoseTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls) -> None:
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+ cls.local_values = np.stack(
+ [
+ _transform(0.0, 0.0, 0.0),
+ _transform(0.0, 0.0, 0.0),
+ _transform(1.0, 0.0, 0.0),
+ _transform(1.0, 0.0, 0.0),
+ _transform(0.0, -3.0, 0.0),
+ _transform(1.0, 0.0, 0.0),
+ _transform(1.0, 0.0, 0.0),
+ ]
+ )
+ cls.skeleton = Skeleton(
+ ["Base", "RootA", "MidA", "TipA", "RootB", "MidB", "TipB"],
+ [-1, 0, 1, 2, 0, 4, 5],
+ cls.local_values,
+ )
+ cls.ik_chains = (
+ TwoBoneIKChainConfig(
+ IKPin.LEFT_HAND,
+ 1,
+ 2,
+ 3,
+ (0.0, 1.0, 0.0),
+ ),
+ TwoBoneIKChainConfig(
+ IKPin.RIGHT_HAND,
+ 4,
+ 5,
+ 6,
+ (0.0, 1.0, 0.0),
+ ),
+ )
+
+ @classmethod
+ def tearDownClass(cls) -> None:
+ wp.set_device(cls.previous_device)
+
+ def test_adjust_speed_scales_all_planar_velocities_and_preserves_pose_motion(self) -> None:
+ poses = np.zeros((4, 2, 7), dtype=np.float32)
+ poses[..., 6] = 1.0
+ # Unequal steps, lateral motion, and height changes must survive scaling.
+ poses[:, 0, :3] = [[2, -1, 0.8], [2.02, -0.97, 0.86],
+ [2.09, -0.98, 0.78], [2.12, -0.91, 0.9]]
+ poses[:, 1, :3] = [[0.1, 0.2, 0.3], [0.2, 0.1, 0.4],
+ [0.3, 0.4, 0.2], [0.2, 0.3, 0.1]]
+ angles = np.arange(8, dtype=np.float32).reshape(4, 2) * 0.1
+ poses[..., 5] = np.sin(angles)
+ poses[..., 6] = np.cos(angles)
+ for device in wp.get_devices():
+ for count in (2, 3, 4):
+ source = poses[:count]
+ velocities = np.diff(source[:, 0, :2], axis=0) * 30
+ source_speed = float(np.linalg.norm(velocities.mean(axis=0)))
+ for scale in (0.0, 0.5, 1.0, 2.0):
+ with self.subTest(device=str(device), count=count, scale=scale), wp.ScopedDevice(device):
+ target_poses = wp.array(source, dtype=wp.transform)
+ speed = source_speed * scale
+
+ adjust_target_pose_speed(target_poses, speed)
+
+ actual = target_poses.numpy()
+ actual_velocities = np.diff(actual[:, 0, :2], axis=0) * 30
+ np.testing.assert_allclose(actual_velocities, velocities * scale, atol=8e-6)
+ self.assertAlmostEqual(float(np.linalg.norm(actual_velocities.mean(axis=0))),
+ speed, delta=8e-6)
+ np.testing.assert_array_equal(actual[0], source[0])
+ np.testing.assert_array_equal(actual[:, 0, 2:], source[:, 0, 2:])
+ np.testing.assert_array_equal(actual[:, 1:], source[:, 1:])
+
+ def test_adjust_speed_leaves_zero_mean_planar_velocity_unchanged(self) -> None:
+ poses = np.zeros((4, 1, 7), dtype=np.float32)
+ poses[..., 6] = 1.0
+ poses[:, 0, 2] = [0.8, 0.86, 0.78, 0.9]
+ for device in wp.get_devices():
+ for xy in ([[2, -1]] * 4, [[2, -1], [2.1, -0.9], [1.9, -1.1], [2, -1]]):
+ poses[:, 0, :2] = xy
+ for speed in (0.0, 4.0):
+ with self.subTest(device=str(device), xy=xy, speed=speed), wp.ScopedDevice(device):
+ target_poses = wp.array(poses, dtype=wp.transform)
+
+ adjust_target_pose_speed(target_poses, speed)
+
+ np.testing.assert_array_equal(target_poses.numpy(), poses)
+
+ def test_adjust_dof_speed_applies_the_pose_rule_and_keeps_joint_angles(self) -> None:
+ roots = np.zeros((4, 7), dtype=np.float32)
+ roots[:, :3] = [[2, -1, 0.8], [2.02, -0.97, 0.86], [2.09, -0.98, 0.78], [2.12, -0.91, 0.9]]
+ angles = np.arange(4, dtype=np.float32) * 0.1
+ roots[:, 5] = np.sin(angles)
+ roots[:, 6] = np.cos(angles)
+ stationary = roots.copy()
+ stationary[:, :2] = [2, -1]
+ joint_angles = np.linspace(-1.0, 1.0, 12, dtype=np.float32).reshape(4, 3)
+ for device in wp.get_devices():
+ for window, source in (("moving", roots), ("stationary", stationary)):
+ for count in (2, 3, 4):
+ for speed in (0.0, 1.5, 4.0):
+ with (
+ self.subTest(device=str(device), window=window, count=count, speed=speed),
+ wp.ScopedDevice(device),
+ ):
+ target_poses = wp.array(source[:count, None], dtype=wp.transform)
+ target_joint_q = wp.array(
+ np.concatenate([source[:count], joint_angles[:count]], axis=1), dtype=wp.float32,
+ )
+
+ adjust_target_pose_speed(target_poses, speed)
+ adjust_target_dof_speed(target_joint_q, speed)
+
+ actual = target_joint_q.numpy()
+ np.testing.assert_array_equal(actual[:, :7], target_poses.numpy()[:, 0])
+ np.testing.assert_array_equal(actual[:, 7:], joint_angles[:count])
+
+ def test_ik_corrector_applies_only_captured_pins(self) -> None:
+ corrector = TargetPoseIKCorrector(self.skeleton, self.ik_chains)
+ target_values = self.local_values.copy()
+ target_values[3] = _transform(0.0, 1.0, 0.0)
+ target_values[6] = _transform(0.0, 1.0, 0.0)
+ target_pose = wp.array(target_values, dtype=wp.transform)
+ current_pose = wp.array(self.local_values, dtype=wp.transform)
+ world_before = wp.empty(7, dtype=wp.transform)
+ self.skeleton.compute_world_transforms(current_pose, world_before)
+
+ corrector.capture_pins(target_pose, IKPin.LEFT_HAND)
+ corrector.apply(current_pose, 1.0)
+
+ corrected_world = wp.empty(7, dtype=wp.transform)
+ self.skeleton.compute_world_transforms(current_pose, corrected_world)
+ corrected_values = corrected_world.numpy()
+ np.testing.assert_allclose(
+ corrected_values[3, :3],
+ [1.0, 1.0, 0.0],
+ atol=1.0e-4,
+ )
+ np.testing.assert_allclose(
+ corrected_values[4:7],
+ world_before.numpy()[4:7],
+ atol=1.0e-6,
+ )
+ self.assertEqual(corrector.pin_mask, IKPin.LEFT_HAND)
+
+ # A target without pins clears them, and the pose stays as sampled.
+ corrector.capture_pins(target_pose, IKPin.NONE)
+ uncorrected = wp.array(self.local_values, dtype=wp.transform)
+ corrector.apply(uncorrected, 1.0)
+ np.testing.assert_array_equal(uncorrected.numpy(), self.local_values)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_tensorrt_cache.py b/tests/motionbricks/test_tensorrt_cache.py
new file mode 100644
index 0000000..8ea62b4
--- /dev/null
+++ b/tests/motionbricks/test_tensorrt_cache.py
@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+
+from motionbricks.inference.cache import (
+ TensorRTEngineCache,
+ cache_key_for,
+ make_cache_identity,
+)
+
+
+class TensorRTCacheTests(unittest.TestCase):
+ def setUp(self) -> None:
+ temporary_directory = TemporaryDirectory()
+ self.addCleanup(temporary_directory.cleanup)
+ self.temporary_directory = Path(temporary_directory.name)
+
+ def _key(
+ self,
+ *,
+ onnx_sha256: str = "a" * 64,
+ tensorrt_version: str = "10.8.0",
+ device_fingerprint=None,
+ **option_overrides,
+ ):
+ options = {"workspace_size_bytes": None, "builder_optimization_level": 3}
+ options.update(option_overrides)
+ identity = make_cache_identity(
+ onnx_sha256=onnx_sha256,
+ tensorrt_version=tensorrt_version,
+ build_options=options,
+ device_fingerprint=device_fingerprint
+ or {"name": "GPU", "architecture": 89},
+ )
+ return cache_key_for(identity)
+
+ def _metadata(self):
+ metadata = make_cache_identity(
+ onnx_sha256="a" * 64,
+ tensorrt_version="10.8.0",
+ build_options={"workspace_size_bytes": None, "builder_optimization_level": 3},
+ device_fingerprint={"name": "GPU", "architecture": 89},
+ )
+ metadata["onnx_filename"] = "model.onnx"
+ return metadata
+
+ def test_key_is_deterministic_and_covers_build_environment(self) -> None:
+ self.assertEqual(self._key(), self._key())
+ self.assertNotEqual(self._key(), self._key(builder_optimization_level=4))
+ self.assertNotEqual(self._key(), self._key(onnx_sha256="b" * 64))
+ self.assertNotEqual(self._key(), self._key(tensorrt_version="10.9.0"))
+ self.assertNotEqual(
+ self._key(),
+ self._key(
+ device_fingerprint={
+ "name": "Another GPU",
+ "architecture": 90,
+ }
+ ),
+ )
+
+ def test_cache_round_trip_and_invalidation(self) -> None:
+ cache = TensorRTEngineCache(self.temporary_directory)
+ key = self._key()
+ cache.store(
+ "a model",
+ key,
+ b"serialized-plan",
+ metadata=self._metadata(),
+ )
+ path = cache.path_for("a model", key)
+ metadata_path = cache.metadata_path_for("a model", key)
+
+ self.assertTrue(path.is_file())
+ self.assertTrue(metadata_path.is_file())
+ self.assertEqual(cache.load("a model", key), b"serialized-plan")
+ metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+ self.assertEqual(metadata["onnx_sha256"], "a" * 64)
+ self.assertEqual(metadata["cache_key"], key)
+ self.assertEqual(metadata["plan_file"], path.name)
+ cache.invalidate("a model", key)
+ self.assertIsNone(cache.load("a model", key))
+ self.assertFalse(metadata_path.exists())
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_unitree_g1_generation.py b/tests/motionbricks/test_unitree_g1_generation.py
new file mode 100644
index 0000000..1ec330f
--- /dev/null
+++ b/tests/motionbricks/test_unitree_g1_generation.py
@@ -0,0 +1,312 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""G1 generation behavior with synthetic poses and controlled predictor output."""
+
+import unittest
+
+import numpy as np
+from scipy.spatial.transform import Rotation
+import warp as wp
+
+from motionbricks.inference.builder import TensorRTBuildOptions
+from motionbricks.inference.errors import TensorContractError
+from motionbricks.model.config import MotionBricksInferenceConfig
+from motionbricks.model.kernels import write_motionbricks_conditions_kernel
+from motionbricks.model.unitree_g1 import kernels
+from motionbricks.model.unitree_g1.engine import MotionBricksUnitreeG1Engine
+from motionbricks.robotics.dof_animation_buffer import DOFAnimationBuffer
+
+
+def _poses(count):
+ frames = np.arange(count, dtype=np.float32)
+ poses = np.zeros((count, 36), dtype=np.float32)
+ poses[:, :3] = np.column_stack((10 + frames * .02, -7 + frames * .01, .8 + frames * .002))
+ angles = np.column_stack((frames * .01 - .1, frames * .005 + .2, frames * .03 + 1.4))
+ poses[:, 3:7] = Rotation.from_euler("xyz", angles).as_quat()
+ poses[:, 7:] = frames[:, None] * .013 + np.arange(29)[None] * .025
+ return poses
+
+
+def _assert_poses(test, actual, expected, atol=3e-6):
+ np.testing.assert_allclose(actual[:, :3], expected[:, :3], atol=atol, rtol=0)
+ np.testing.assert_allclose(actual[:, 7:], expected[:, 7:], atol=atol, rtol=0)
+ delta = Rotation.from_quat(actual[:, 3:7]).inv() * Rotation.from_quat(expected[:, 3:7])
+ test.assertLess(float(delta.magnitude().max()), atol)
+
+
+class G1GenerationKernelTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ cls.previous_device = wp.get_device()
+ wp.set_device("cpu")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def test_alignment_preserves_height_tilt_and_hinges(self):
+ source = _poses(4)
+ # Quaternion sign and length must not change the represented heading.
+ source[:, 3:7] *= np.array([-1.03, 1.03, -1.03, -1.03])[:, None]
+ source_device = wp.array(source, dtype=wp.float32)
+ alignment = wp.empty(1, dtype=wp.transform)
+ encoded = wp.empty((1, 4, 36), dtype=wp.float32)
+ root_matrix = Rotation.from_quat(source[-1, 3:7]).as_matrix()
+ heading = np.arctan2(root_matrix[1, 0], root_matrix[0, 0])
+ origin = source[-1, :3] * [1, 1, 0]
+
+ for desired in ((0., 1.), (1., 0.), (-3., 2.)):
+ with self.subTest(desired=desired):
+ wp.launch(kernels.compute_guide_alignment_kernel, dim=1,
+ inputs=[wp.vec2(*desired), wp.transform_identity(), source_device], outputs=[alignment])
+ wp.launch(kernels.encode_motionbricks_inputs_kernel, dim=4,
+ inputs=[wp.transform_identity(), source_device, alignment], outputs=[encoded[0]])
+ actual = encoded.numpy()[0]
+ rotation = Rotation.from_euler("z", np.arctan2(desired[1], desired[0]) - heading)
+ expected = source.copy()
+ expected[:, :3] = rotation.apply(source[:, :3] - origin)
+ expected[:, 3:7] = (rotation * Rotation.from_quat(source[:, 3:7])).as_quat()
+ _assert_poses(self, actual, expected)
+ np.testing.assert_array_equal(actual[:, 2], source[:, 2])
+ np.testing.assert_array_equal(actual[:, 7:], source[:, 7:])
+ np.testing.assert_allclose(actual[-1, :2], 0, atol=1e-7)
+ np.testing.assert_allclose(np.linalg.norm(actual[:, 3:7], axis=1), 1, atol=1e-7)
+ np.testing.assert_array_equal(source_device.numpy(), source)
+
+ def test_world_restoration_trims_only_valid_frames(self):
+ poses = _poses(58)
+ world_rotation = Rotation.from_euler("z", -2.1)
+ origin = np.array([103., -71., 0.], dtype=np.float32)
+ align = wp.transform(wp.vec3(*origin), wp.quat(*world_rotation.as_quat()))
+ alignment = wp.array([align], dtype=wp.transform)
+ local = poses.copy()
+ local[:, :3] = world_rotation.inv().apply(poses[:, :3] - origin)
+ local[:, 3:7] = (world_rotation.inv() * Rotation.from_quat(poses[:, 3:7])).as_quat()
+ output = wp.full((61, 36), 999., dtype=wp.float32)
+ output_count = wp.empty(1, dtype=wp.int32)
+ pointer = output.ptr
+ unfiltered = wp.array([1.0], dtype=wp.float32)
+ raw_contacts, output_contacts = wp.zeros((1, 64, 4), dtype=wp.float32), wp.empty((61, 4), dtype=wp.float32)
+
+ for tokens in (16, 6, 8):
+ count = tokens * 4 - 6
+ raw = np.full((1, 64, 36), np.nan, dtype=np.float32)
+ raw[0, 3:3 + count] = local[:count]
+ before = output.numpy()
+ wp.launch(kernels.decode_motionbricks_output_kernel, dim=output.shape[0], inputs=[
+ alignment, wp.transform_identity(), wp.array(raw[0], dtype=wp.float32), raw_contacts[0],
+ wp.array([tokens], dtype=wp.int32), unfiltered,
+ ], outputs=[output, output_contacts, output_count])
+ actual = output.numpy()
+ self.assertEqual(output_count.numpy()[0], count)
+ _assert_poses(self, actual[:count], poses[:count], atol=3e-5)
+ np.testing.assert_array_equal(actual[count:], before[count:])
+ self.assertEqual(output.ptr, pointer)
+
+ def test_root_filter_keeps_steady_motion_and_removes_frame_jitter(self):
+ poses = _poses(64)
+ world_rotation = Rotation.from_euler("z", 0.7)
+ origin = np.array([-4., 9., 0.], dtype=np.float32)
+ alignment = wp.array([wp.transform(wp.vec3(*origin), wp.quat(*world_rotation.as_quat()))], dtype=wp.transform)
+ local = poses.copy()
+ local[:, :3] = world_rotation.inv().apply(poses[:, :3] - origin)
+ local[:, 3:7] = (world_rotation.inv() * Rotation.from_quat(poses[:, 3:7])).as_quat()
+ # One centimetre of alternating jitter on every axis, the fastest change a 30 Hz clip can hold.
+ local[:, :3] += 0.01 * (-1.0) ** np.arange(64)[:, None]
+ root_filter = wp.array(kernels.ROOT_POSITION_FILTER, dtype=wp.float32)
+ output = wp.empty((58, 36), dtype=wp.float32)
+ output_count = wp.empty(1, dtype=wp.int32)
+ raw_contacts, output_contacts = wp.zeros((1, 64, 4), dtype=wp.float32), wp.empty((58, 4), dtype=wp.float32)
+
+ for tokens in (16, 6):
+ raw = np.full((1, 64, 36), np.nan, dtype=np.float32)
+ raw[0, :tokens * 4] = local[:tokens * 4]
+ wp.launch(kernels.decode_motionbricks_output_kernel, dim=output.shape[0], inputs=[
+ alignment, wp.transform_identity(), wp.array(raw[0], dtype=wp.float32), raw_contacts[0],
+ wp.array([tokens], dtype=wp.int32), root_filter,
+ ], outputs=[output, output_contacts, output_count])
+ count = tokens * 4 - 6
+ actual = output.numpy()[:count]
+ expected = poses[3:3 + count]
+ self.assertTrue(np.isfinite(actual).all())
+ np.testing.assert_allclose(actual[:, :3], expected[:, :3], atol=1e-3, rtol=0)
+ np.testing.assert_array_equal(actual[:, 7:], expected[:, 7:])
+ delta = Rotation.from_quat(actual[:, 3:7]).inv() * Rotation.from_quat(expected[:, 3:7])
+ self.assertLess(float(delta.magnitude().max()), 3e-6)
+
+ def test_masks_clear_stale_targets_and_unknown_derivatives(self):
+ masks = [wp.full((1, 8), -1, dtype=wp.int32) for _ in range(3)]
+ tokens = wp.full((1, 11), -1, dtype=wp.int32)
+ for target_count, allowed in ((4, (6, 9, 16)), (1, (8,)), (3, (7, 14)), (2, (6, 16))):
+ config = MotionBricksInferenceConfig(allowed_token_counts=allowed)
+ wp.launch(write_motionbricks_conditions_kernel, dim=11,
+ inputs=[target_count, config.allowed_token_bits()], outputs=[*masks, tokens])
+ expected = np.array([1] * (4 + target_count) + [0] * (4 - target_count))
+ np.testing.assert_array_equal(masks[0].numpy()[0], expected)
+ np.testing.assert_array_equal(masks[2].numpy()[0], expected)
+ expected[[3, 4 + target_count - 1]] = 0
+ np.testing.assert_array_equal(masks[1].numpy()[0], expected)
+ np.testing.assert_array_equal(tokens.numpy()[0], [int(n in allowed) for n in range(6, 17)])
+
+
+class _ControlledG1Engine(MotionBricksUnitreeG1Engine):
+ """Exercise the real generation path, replacing only the TensorRT backend."""
+
+ def _initialize(self, build_options, *, cache_dir, force_rebuild, progress_monitor):
+ self.build_options = build_options
+ self._tensor_specs = {spec.name: spec for spec in self.contract.tensor_specs}
+ self._buffers = {
+ spec.name: wp.empty(spec.shape, dtype=wp.float32 if spec.dtype == np.dtype(np.float32) else wp.int32,
+ device=self.device)
+ for spec in self.contract.tensor_specs
+ }
+ self.prediction = wp.array(_poses(64)[None], dtype=wp.float32, device=self.device)
+ self.contacts = wp.zeros((1, 64, 4), dtype=wp.float32, device=self.device)
+ self.tokens = 8
+
+ def _enqueue_tensorrt(self):
+ with wp.ScopedStream(self.stream):
+ wp.copy(self.device_tensor("pred_qpos"), self.prediction)
+ wp.copy(self.device_tensor("pred_foot_contacts"), self.contacts)
+ self.device_tensor("pred_num_tokens").assign([self.tokens])
+
+
+class G1GenerationEngineTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ wp.init()
+ if not wp.is_cuda_available():
+ raise unittest.SkipTest("CUDA is unavailable")
+ cls.previous_device = wp.get_device()
+ wp.set_device("cuda:0")
+
+ @classmethod
+ def tearDownClass(cls):
+ wp.set_device(cls.previous_device)
+
+ def setUp(self):
+ self.engine = _ControlledG1Engine("controlled.onnx", bake_cuda_graph=False)
+ self.addCleanup(self.engine.close)
+ self.context = self.engine.create_input()
+ self.target = self.engine.create_input()
+ self.output = self.engine.create_output()
+ with wp.ScopedStream(self.engine.stream):
+ self.source = wp.array(_poses(4), dtype=wp.float32)
+ self.context.update_from_poses(self.source, stream=self.engine.stream)
+ self.target.update_from_poses(self.source, stream=self.engine.stream)
+
+ def test_tf32_is_off_by_default_and_explicit_options_win(self):
+ self.assertIs(self.engine.build_options.enable_tf32, False)
+ for options, expected in (
+ (TensorRTBuildOptions(enable_fp16=True), False),
+ (TensorRTBuildOptions(enable_tf32=True), True),
+ ):
+ with self.subTest(options=options):
+ engine = _ControlledG1Engine("controlled.onnx", build_options=options, bake_cuda_graph=False)
+ self.addCleanup(engine.close)
+ self.assertIs(engine.build_options.enable_fp16, options.enable_fp16)
+ self.assertIs(engine.build_options.enable_tf32, expected)
+
+ def test_default_and_explicit_alignment_set_the_encoded_heading(self):
+ for config, heading in ((None, 0.0), (MotionBricksInferenceConfig(heading_alignment=(0., 1.)), np.pi / 2)):
+ self.engine.generate_animation(self.context, self.target, self.output, config=config)
+ last_context = self.engine.device_tensor("context_qpos").numpy()[0, -1]
+ forward = Rotation.from_quat(last_context[3:7]).as_matrix()[:, 0]
+ self.assertAlmostEqual(np.arctan2(forward[1], forward[0]), heading, places=6)
+
+ def test_model_to_runtime_moves_the_same_motion_into_world_space(self):
+ # A Y up world, turned and moved away from the origin.
+ rotation = Rotation.from_euler("xz", (90, 40), degrees=True)
+ to_world = wp.transform(wp.vec3(3.0, -2.0, 0.5), wp.quat(*rotation.as_quat()))
+ engine = _ControlledG1Engine("controlled.onnx", model_to_runtime=to_world, bake_cuda_graph=False)
+ self.addCleanup(engine.close)
+ context, target, output = engine.create_input(), engine.create_input(), engine.create_output()
+ world = _poses(4)
+ for frame in world:
+ frame[:7] = np.asarray(wp.mul(to_world, wp.transform(wp.vec3(*frame[:3]), wp.quat(*frame[3:7]))))
+ with wp.ScopedStream(engine.stream):
+ world_device = wp.array(world, dtype=wp.float32)
+ context.update_from_poses(world_device, stream=engine.stream)
+ target.update_from_poses(world_device, stream=engine.stream)
+ config = MotionBricksInferenceConfig(allowed_token_counts=(8,), correct_generated_diff=False)
+ self.engine.generate_animation(self.context, self.target, self.output, config=config)
+ engine.generate_animation(context, target, output, config=config)
+
+ # Both engines see the same model space input.
+ for name in ("context_qpos", "target_qpos"):
+ _assert_poses(
+ self, engine.device_tensor(name).numpy()[0], self.engine.device_tensor(name).numpy()[0], atol=1e-5,
+ )
+ expected = self.output.poses.numpy()[:self.output.num_frames].copy()
+ for frame in expected:
+ frame[:7] = np.asarray(wp.mul(to_world, wp.transform(wp.vec3(*frame[:3]), wp.quat(*frame[3:7]))))
+ self.assertEqual(output.num_frames, self.output.num_frames)
+ _assert_poses(self, output.poses.numpy()[:output.num_frames], expected, atol=1e-5)
+
+ def test_repeated_generation_trims_padding_into_the_same_output(self):
+ engine = self.engine
+ pointer = self.output.poses.ptr
+ for count in (16, 6, 8, 14):
+ engine.tokens = count
+ result = engine.generate_animation(self.context, self.target, self.output,
+ config=MotionBricksInferenceConfig(allowed_token_counts=(count,), correct_generated_diff=False))
+ self.assertIs(result, self.output)
+ self.assertEqual(result.poses.ptr, pointer)
+ self.assertEqual(result.num_frames, count * 4 - 6)
+ self.assertAlmostEqual(result.duration, (count * 4 - 7) / 30)
+
+ def test_generation_copies_each_output_frames_foot_contacts_clamped(self):
+ contacts = np.arange(64 * 4, dtype=np.float32).reshape(1, 64, 4) / 128.0 - 0.5
+ self.engine.contacts = wp.array(contacts, dtype=wp.float32, device=self.engine.device)
+ self.engine.generate_animation(self.context, self.target, self.output,
+ config=MotionBricksInferenceConfig(allowed_token_counts=(8,), correct_generated_diff=False))
+ frames = self.output.num_frames
+ # Output frame 0 is the raw frame after the three padding frames.
+ np.testing.assert_array_equal(
+ self.output.foot_contacts.numpy()[:frames], np.clip(contacts[0, 3:3 + frames], 0, 1),
+ )
+
+ def test_invalid_model_lengths_do_not_publish_output(self):
+ for correction in (False, True):
+ config = MotionBricksInferenceConfig(allowed_token_counts=(8,), correct_generated_diff=correction)
+ for tokens in (5, 17, 7):
+ with self.subTest(tokens=tokens, correction=correction):
+ self.output.num_frames = 26
+ self.engine.tokens = tokens
+ with self.assertRaises(TensorContractError):
+ self.engine.generate_animation(self.context, self.target, self.output, config=config)
+ self.assertEqual(self.output.num_frames, 0)
+
+ def test_uninitialized_target_is_rejected(self):
+ with self.assertRaisesRegex(ValueError, "Target token"):
+ self.engine.generate_animation(self.context, self.engine.create_input(), self.output)
+
+ def test_output_without_foot_contacts_is_rejected(self):
+ output = DOFAnimationBuffer(self.output.joint_names, 30.0, wp.empty_like(self.output.poses), num_frames=0)
+ with self.assertRaisesRegex(ValueError, "foot_contacts"):
+ self.engine.generate_animation(self.context, self.target, output)
+
+ def test_correction_matches_endpoints_and_can_be_disabled_on_the_next_call(self):
+ engine = self.engine
+ for count, target_count in ((16, 1), (6, 4), (8, 2)):
+ engine.tokens = count
+ self.target.update_from_poses(self.source[:target_count], stream=engine.stream)
+ engine.generate_animation(self.context, self.target, self.output,
+ config=MotionBricksInferenceConfig(allowed_token_counts=(count,), correct_generated_diff=False))
+ raw = self.output.poses.numpy()[:self.output.num_frames].copy()
+ engine.generate_animation(self.context, self.target, self.output,
+ config=MotionBricksInferenceConfig(allowed_token_counts=(count,), correct_generated_diff=True))
+ actual = self.output.poses.numpy()[:self.output.num_frames].copy()
+ expected = np.stack((self.context.poses.numpy()[-1], self.target.poses.numpy()[0]))
+ _assert_poses(self, actual[[0, -1]], expected, atol=1e-5)
+ self.assertTrue(np.isfinite(actual).all())
+ engine.generate_animation(self.context, self.target, self.output,
+ config=MotionBricksInferenceConfig(allowed_token_counts=(count,), correct_generated_diff=False))
+ np.testing.assert_array_equal(self.output.poses.numpy()[:self.output.num_frames], raw)
+ self.assertEqual(engine.timer.milliseconds["post_process"], 0)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_unitree_g1_robot.py b/tests/motionbricks/test_unitree_g1_robot.py
new file mode 100644
index 0000000..cf52d40
--- /dev/null
+++ b/tests/motionbricks/test_unitree_g1_robot.py
@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""The bundled Unitree G1 robot matches the joint layout of the G1 model."""
+
+import unittest
+
+from motionbricks.io.utils import get_unitree_g1_model
+from motionbricks.model.unitree_g1.contract import UNITREE_G1_N1_CONTRACT
+
+
+class UnitreeG1RobotTests(unittest.TestCase):
+ def test_robot_joints_follow_the_model_order(self):
+ # Generated poses are written straight into joint_q, as the free root followed by one angle per model joint.
+ robot = get_unitree_g1_model(device="cpu", load_visuals=False)
+ joint_names = list(UNITREE_G1_N1_CONTRACT.joint_names)
+ self.assertEqual([label.rsplit("/", 1)[-1] for label in robot.joint_label[1:]], joint_names)
+ self.assertEqual(robot.joint_coord_count, 7 + len(joint_names))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/motionbricks/test_usd.py b/tests/motionbricks/test_usd.py
new file mode 100644
index 0000000..842c2e6
--- /dev/null
+++ b/tests/motionbricks/test_usd.py
@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""USD loading reports a stage that cannot open, or missing skinning data, as ValueError."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from pxr import Gf, Usd, UsdGeom, UsdSkel
+
+from motionbricks.io.usd import load_skeletal_mesh_with_skeleton_from_usd, load_skeleton_from_usd
+
+
+def _write_character(path, *, bind_transforms=True, joint_indices=True):
+ """Write a one joint character with a one triangle skinned mesh."""
+ stage = Usd.Stage.CreateNew(str(path))
+ UsdSkel.Root.Define(stage, "/Root")
+ skeleton = UsdSkel.Skeleton.Define(stage, "/Root/Skeleton")
+ skeleton.CreateJointsAttr(["Hips"])
+ skeleton.CreateRestTransformsAttr([Gf.Matrix4d(1.0)])
+ if bind_transforms:
+ skeleton.CreateBindTransformsAttr([Gf.Matrix4d(1.0)])
+ mesh = UsdGeom.Mesh.Define(stage, "/Root/Mesh")
+ mesh.CreatePointsAttr([(0, 0, 0), (1, 0, 0), (0, 1, 0)])
+ mesh.CreateFaceVertexCountsAttr([3])
+ mesh.CreateFaceVertexIndicesAttr([0, 1, 2])
+ binding = UsdSkel.BindingAPI.Apply(mesh.GetPrim())
+ binding.CreateSkeletonRel().SetTargets([skeleton.GetPath()])
+ if joint_indices:
+ binding.CreateJointIndicesPrimvar(False, 1).Set([0, 0, 0])
+ binding.CreateJointWeightsPrimvar(False, 1).Set([1, 1, 1])
+ stage.Save()
+
+
+class UsdLoadingTests(unittest.TestCase):
+ def test_a_missing_file_raises_value_error_from_both_loaders(self):
+ with tempfile.TemporaryDirectory() as directory:
+ missing = Path(directory) / "missing.usda"
+ with self.assertRaisesRegex(ValueError, "Could not open USD stage"):
+ load_skeleton_from_usd(missing, "/Root/Skeleton")
+ with self.assertRaisesRegex(ValueError, "Could not open USD stage"):
+ load_skeletal_mesh_with_skeleton_from_usd(missing, "/Root/Mesh", "/Root/Skeleton")
+
+ def test_missing_skinning_data_raises_value_error_with_the_reason(self):
+ with tempfile.TemporaryDirectory() as directory:
+ folder = Path(directory)
+ _write_character(folder / "complete.usda")
+ mesh = load_skeletal_mesh_with_skeleton_from_usd(folder / "complete.usda", "/Root/Mesh", "/Root/Skeleton")
+ self.assertEqual(len(mesh.skinned_meshes), 1)
+ with self.assertRaisesRegex(ValueError, "Mesh prim not found"):
+ load_skeletal_mesh_with_skeleton_from_usd(folder / "complete.usda", "/Root/Missing", "/Root/Skeleton")
+ for name, options, message in (
+ ("no_binds", {"bind_transforms": False}, "needs one bind transform per joint"),
+ ("no_indices", {"joint_indices": False}, "needs jointIndices and jointWeights"),
+ ):
+ with self.subTest(case=name):
+ path = folder / f"{name}.usda"
+ _write_character(path, **options)
+ with self.assertRaisesRegex(ValueError, message):
+ load_skeletal_mesh_with_skeleton_from_usd(path, "/Root/Mesh", "/Root/Skeleton")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_all.py b/tests/test_all.py
new file mode 100644
index 0000000..5a29989
--- /dev/null
+++ b/tests/test_all.py
@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Collect the tests in every folder under tests, so one command runs them all.
+
+Unittest discovery skips plain folders, so this module discovers each folder that
+holds tests:
+
+ python -m unittest discover -s tests
+"""
+
+import unittest
+from pathlib import Path
+
+
+def load_tests(loader, tests, pattern):
+ pattern = pattern or "test*.py"
+ root = Path(__file__).resolve().parent
+ for folder in sorted({path.parent for path in root.rglob(pattern)} - {root}):
+ # A separate loader leaves the outer discovery untouched and keeps its -k filters.
+ folder_loader = unittest.TestLoader()
+ folder_loader.testNamePatterns = loader.testNamePatterns
+ tests.addTests(folder_loader.discover(str(folder), pattern, str(folder)))
+ return tests
diff --git a/tools/onnx/.gitignore b/tools/onnx/.gitignore
new file mode 100644
index 0000000..e5d24d3
--- /dev/null
+++ b/tools/onnx/.gitignore
@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+output/
diff --git a/tools/onnx/.python-version b/tools/onnx/.python-version
new file mode 100644
index 0000000..f36fa5f
--- /dev/null
+++ b/tools/onnx/.python-version
@@ -0,0 +1 @@
+3.12.14
diff --git a/tools/onnx/README.md b/tools/onnx/README.md
new file mode 100644
index 0000000..26e1c16
--- /dev/null
+++ b/tools/onnx/README.md
@@ -0,0 +1,65 @@
+# Export MotionBricks checkpoints to ONNX
+
+Export the SOMA and Unitree G1 checkpoints from Hugging Face to batched ONNX models in FP32 or
+mixed FP16.
+
+## Export
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and the
+[Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/en/guides/cli).
+The checkpoints are folders in one
+[MotionBricks repository](https://huggingface.co/nvidia/MotionBricks) on Hugging Face:
+
+| Model | Checkpoint folder |
+| --- | --- |
+| SOMA | [soma/](https://huggingface.co/nvidia/MotionBricks/tree/main/soma) |
+| Unitree G1 | [g1/](https://huggingface.co/nvidia/MotionBricks/tree/main/g1) |
+
+Run these commands from the root of this repository. Keep the downloaded folder structure
+intact. uv installs the exporter and its dependencies automatically on first use.
+
+```sh
+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/*"`. Download checkpoints only
+for export or another runtime. The demo apps use the ONNX models bundled with the software.
+
+FP32 is the default. The command saves `mmm_v6_soma_fp32.onnx` or `mmm_v6_g1_fp32.onnx` in the
+current directory. Add `--precision fp16` for mixed FP16. The file name then ends in `_fp16.onnx`.
+
+Use `--output path/to/model.onnx` to choose a different destination, or `--force` to replace an
+existing file. The exporter stages its temporary files in the output folder. Allow several GB of
+free disk space there.
+
+Add `--verbose` for detailed log messages.
+
+## Output and checks
+
+The models support different batch sizes, and the demos use a batch size of one (`N=1`).
+Floating point inputs and outputs use FP32 for both precisions. For shapes and usage examples, see
+[ONNX inference](../../docs/onnx_inference.md), the [SOMA model card](../../docs/soma_model.md), and
+the [G1 model card](../../docs/unitree_g1_model.md).
+
+The exporter checks the checkpoint checksums, the exported ONNX graph, and its tensor interface.
+Invalid checkpoints stop the export before any weights load. An existing output is replaced only
+after the export succeeds.
+
+Each checkpoint holds SafeTensors weights and normalization statistics in `.npy` files. The
+exporter reads no other format.
+
+## License
+
+The source uses the repository's [Apache 2.0 license](../../LICENSE). Dependency licenses are in
+[licenses/](licenses/).
+
+The downloaded checkpoints are licensed under the
+[NVIDIA Open Model Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-agreement/).
+
+Licensed by NVIDIA Corporation under the NVIDIA Open Model Agreement.
diff --git a/tools/onnx/__init__.py b/tools/onnx/__init__.py
new file mode 100644
index 0000000..84e68ff
--- /dev/null
+++ b/tools/onnx/__init__.py
@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from ._version import __version__ # noqa: F401
diff --git a/tools/onnx/_version.py b/tools/onnx/_version.py
new file mode 100644
index 0000000..d218b02
--- /dev/null
+++ b/tools/onnx/_version.py
@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+__version__ = "0.1.0"
diff --git a/tools/onnx/assets/g1_model_rig.npz b/tools/onnx/assets/g1_model_rig.npz
new file mode 100644
index 0000000..557f4a8
--- /dev/null
+++ b/tools/onnx/assets/g1_model_rig.npz
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c119d24e0447fd7b0ba4fd8eb84f07f398ec1aa396a9e3548573776373f8b30e
+size 3801
diff --git a/tools/onnx/assets/soma_model_rig.npz b/tools/onnx/assets/soma_model_rig.npz
new file mode 100644
index 0000000..9a5a7c6
--- /dev/null
+++ b/tools/onnx/assets/soma_model_rig.npz
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3a349e4dd10b13731528c8613bd564629df9b8444201bd9278a5c414ffd2b40
+size 1184
diff --git a/tools/onnx/checkpoints.py b/tools/onnx/checkpoints.py
new file mode 100644
index 0000000..f608f2b
--- /dev/null
+++ b/tools/onnx/checkpoints.py
@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Find the downloaded checkpoint files, and load them after checking their checksums."""
+
+import hashlib
+import logging
+from pathlib import Path
+
+import numpy as np
+from safetensors import SafetensorError
+from safetensors.torch import load_file
+
+logger = logging.getLogger(__name__)
+
+
+def sha256(path):
+ """Return the SHA-256 digest of a file in lowercase hexadecimal."""
+ with Path(path).open("rb") as stream:
+ return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def verify_file(path, expected):
+ """Check a file's size and SHA-256 digest against its checksum entry."""
+ if not path.is_file():
+ raise ValueError(f"Missing checkpoint file: {path}.")
+ if path.stat().st_size != expected["bytes"] or sha256(path) != expected["sha256"]:
+ raise ValueError(
+ f"Checksum mismatch: {path}. Use the unmodified checkpoint files."
+ )
+ logger.debug("Verified %s", path)
+
+
+def checkpoint_root(source, release):
+ """Return the folder that holds the checkpoint files.
+
+ source is a downloaded model folder, such as checkpoints/MotionBricks/soma, with the
+ files inside its root_directory. That inner folder works too.
+ """
+ source = source.expanduser().resolve()
+ if source.is_file():
+ raise ValueError(f"Checkpoints must be a folder, not a file: {source}.")
+ if (source / release["files"][0]["path"]).is_file():
+ return source
+ return source / release["root_directory"]
+
+
+def load_sources(root, release):
+ """Verify every file, then load the weights and normalization arrays as plain data."""
+ for entry in release["files"]:
+ verify_file(root / entry["path"], entry)
+ sources = {}
+ for entry in release["files"]:
+ filename = entry["path"]
+ if filename.endswith(".safetensors"):
+ logger.debug("Loading %s", filename)
+ try:
+ sources[filename] = load_file(root / filename, device="cpu")
+ except SafetensorError as error:
+ raise ValueError(f"Invalid SafeTensors weights: {filename}.") from error
+ elif filename.endswith(".npy"):
+ sources[filename] = np.load(root / filename, allow_pickle=False)
+ else:
+ raise ValueError(
+ f"Unsupported checkpoint file format: {filename}. Use the released checkpoint files."
+ )
+ return sources
diff --git a/tools/onnx/checksums.py b/tools/onnx/checksums.py
new file mode 100644
index 0000000..eafb78a
--- /dev/null
+++ b/tools/onnx/checksums.py
@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Checksums of the released checkpoint files on Hugging Face."""
+
+CHECKPOINTS = {
+ "soma": {
+ "root_directory": "soma-v6-nova-4n8g-ea43dd8-fp32-v1",
+ "files": [
+ {
+ "path": "mmm-v6-soma-pose-nova-4n8g-ea43dd8-fp32-v1/version_0/checkpoints/model-step=1500000.safetensors",
+ "bytes": 546109841,
+ "sha256": "8537d9d33a880ff1df6c16c28ed061d60c461a5918d70b1cf99251ff91a10a10",
+ },
+ {
+ "path": "mmm-v6-soma-pose-nova-4n8g-ea43dd8-fp32-v1/version_0/stats/motion/mean.npy",
+ "bytes": 3088,
+ "sha256": "802f79631ea88a1a920cf44725f5d0e9973a0c8d7adb5359b01bd7a5af57492d",
+ },
+ {
+ "path": "mmm-v6-soma-pose-nova-4n8g-ea43dd8-fp32-v1/version_0/stats/motion/std.npy",
+ "bytes": 3088,
+ "sha256": "1a97818fea2a10e562de059013b081ecf7943d6815a36396f0d94f54ad26acb6",
+ },
+ {
+ "path": "mmm-v6-soma-root-nova-4n8g-ea43dd8-fp32-v1/version_0/checkpoints/model-step=1500000.safetensors",
+ "bytes": 161695084,
+ "sha256": "a48d48c3d8ff98c825ca315797644789ae37f2db9069779a3118f42e84f4f29e",
+ },
+ {
+ "path": "vqvae-v6-soma-nova-4n8g-ea43dd8-fp32-v1/version_0/checkpoints/model-step=1500000.safetensors",
+ "bytes": 93442464,
+ "sha256": "ba0d1db48ba7182ef5d1a72268bfaa1a196f1f1fbf00144c046d947b90684a1a",
+ },
+ ],
+ },
+ "g1": {
+ "root_directory": "out",
+ "files": [
+ {
+ "path": "motionbricks_pose/version_1/checkpoints/model-step=2000000.safetensors",
+ "bytes": 546380073,
+ "sha256": "2154d80cac2beb4bb4074b4db92ae59d9fdfbc58651550c32941fe8527d28313",
+ },
+ {
+ "path": "motionbricks_pose/version_1/stats/motion/mean.npy",
+ "bytes": 3472,
+ "sha256": "ca390f0081e2373ab71e860a3546cb70cc11fdfac6ce525155403e047b66fdea",
+ },
+ {
+ "path": "motionbricks_pose/version_1/stats/motion/std.npy",
+ "bytes": 3472,
+ "sha256": "fca7dd6135cbe96504b1307a7db97e9004556937a2fc72d139077b962cee6bd7",
+ },
+ {
+ "path": "motionbricks_root/version_1/checkpoints/model-step=2000000.safetensors",
+ "bytes": 136510540,
+ "sha256": "da6ff2c05e45dfe4ac5e8e8362a6404f5c927fcddb18410e6804b61e55d4f2dc",
+ },
+ {
+ "path": "motionbricks_vqvae/version_1/checkpoints/model-step=2000000.safetensors",
+ "bytes": 95194080,
+ "sha256": "bf9c31173b334303bf392d184c24701ad1a095b3e94a5fe6b11db4d01343a454",
+ },
+ ],
+ },
+}
diff --git a/tools/onnx/export.py b/tools/onnx/export.py
new file mode 100644
index 0000000..c728803
--- /dev/null
+++ b/tools/onnx/export.py
@@ -0,0 +1,274 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Export the Python inference models from the released checkpoints."""
+
+import argparse
+import gc
+import importlib.metadata
+import logging
+import os
+from pathlib import Path
+import sys
+import tempfile
+import warnings
+
+import onnx
+import torch
+
+from .checkpoints import checkpoint_root, load_sources
+from .checksums import CHECKPOINTS
+
+logger = logging.getLogger(__name__)
+
+
+def check_environment(kind):
+ """Check that Python and the key packages match the pinned export environment."""
+ python = (3, 12)
+ versions = {
+ "torch": "2.14.0",
+ "onnx": "1.23.2",
+ "numpy": "1.26.4",
+ "safetensors": "0.8.0",
+ "protobuf": "7.36.1",
+ }
+ if sys.version_info[:2] != python:
+ raise ValueError(
+ f"The exporter requires Python {python[0]}.{python[1]}. Use the command in tools/onnx/README.md."
+ )
+ for package, expected in versions.items():
+ actual = importlib.metadata.version(package).split("+")[0]
+ if actual != expected:
+ raise ValueError(
+ f"Expected {package}=={expected}, found {actual}. Use the locked exporter environment."
+ )
+
+
+def example_inputs(kind):
+ """Create trace inputs: a batch of two requests with different allowed token counts."""
+ allowed = torch.eye(11, dtype=torch.int32)[[0, 10]]
+ masks = [torch.ones(2, 8, dtype=torch.int32) for _ in range(3)]
+ for mask in masks:
+ mask[:, 4:6] = 0
+ if kind == "g1":
+ context = torch.zeros(2, 4, 36)
+ context[..., 2] = 0.75
+ context[..., 6] = 1.0 # Identity quaternion, XYZW.
+ target = context.clone()
+ target[..., 0] = 1.0
+ return (context, target, *masks, allowed)
+
+ global_root = torch.zeros(2, 8, 5)
+ global_root[..., 1] = 1.0
+ global_root[..., 3] = 1.0 # cos(heading), with heading zero.
+ local_root = torch.zeros(2, 8, 4)
+ local_root[..., 3] = 1.0
+ local_pose = torch.zeros(2, 8, 267)
+ # Each joint's 6D rotation contains the first two columns of identity.
+ rotations = torch.tensor([1.0, 0.0, 0.0, 0.0, 1.0, 0.0]).repeat(30)
+ local_pose[..., 87:] = rotations
+ return (global_root, masks[0], local_root, masks[1], local_pose, masks[2], allowed)
+
+
+def export_fp32(kind, model, output):
+ """Trace the batched inference graph with the pinned export options."""
+ if kind == "g1":
+ from .models.g1 import INPUT_NAMES, OUTPUT_NAMES
+ else:
+ from .models.soma import INPUT_NAMES, OUTPUT_NAMES
+ kwargs = dict(
+ input_names=list(INPUT_NAMES),
+ output_names=list(OUTPUT_NAMES),
+ dynamic_axes={name: {0: "batch_size"} for name in INPUT_NAMES + OUTPUT_NAMES},
+ opset_version=17,
+ dynamo=False,
+ do_constant_folding=(kind == "soma"),
+ )
+ with warnings.catch_warnings():
+ # The shape and configuration checks are specific to these release architectures.
+ warnings.simplefilter("ignore", torch.jit.TracerWarning)
+ warnings.filterwarnings(
+ "ignore", category=FutureWarning, module=r"torch\.onnx\..*"
+ )
+ if kind == "g1":
+ torch.backends.mha.set_fastpath_enabled(False)
+ with torch.inference_mode():
+ torch.onnx.export(model, example_inputs(kind), str(output), **kwargs)
+ else:
+ torch.onnx.export(model, example_inputs(kind), str(output), **kwargs)
+
+
+def validate_output(path, kind):
+ """Check graph validity and the batched interface used by the demos."""
+ try:
+ onnx.checker.check_model(str(path), full_check=True)
+ except (onnx.checker.ValidationError, onnx.shape_inference.InferenceError) as error:
+ raise ValueError(f"Invalid ONNX model: {error}") from error
+
+ model = onnx.load(path)
+ if kind == "g1":
+ from .models.g1 import INPUT_NAMES
+
+ outputs = {
+ "pred_qpos": (onnx.TensorProto.FLOAT, (64, 36)),
+ "pred_num_tokens": (onnx.TensorProto.INT32, ()),
+ "pred_foot_contacts": (onnx.TensorProto.FLOAT, (64, 4)),
+ }
+ else:
+ from .models.soma import INPUT_NAMES
+
+ outputs = {
+ "pred_global_motions": (onnx.TensorProto.FLOAT, (64, 366)),
+ "pred_num_tokens": (onnx.TensorProto.INT32, ()),
+ }
+ inputs = {
+ name: (
+ onnx.helper.np_dtype_to_tensor_dtype(value.numpy().dtype),
+ value.shape[1:],
+ )
+ for name, value in zip(INPUT_NAMES, example_inputs(kind), strict=True)
+ }
+ batch_dimension = None
+ for mode, values, expected in (
+ ("input", model.graph.input, inputs),
+ ("output", model.graph.output, outputs),
+ ):
+ if {value.name for value in values} != set(expected):
+ raise ValueError(
+ f"Unexpected ONNX {mode} names. Expected {list(expected)}."
+ )
+ for value in values:
+ dtype, shape = expected[value.name]
+ tensor = value.type.tensor_type
+ dimensions = tensor.shape.dim
+ if tensor.elem_type != dtype or len(dimensions) != len(shape) + 1:
+ raise ValueError(f"Unexpected ONNX dtype or rank for {value.name}.")
+ batch = dimensions[0].dim_param
+ if not batch or (batch_dimension is not None and batch != batch_dimension):
+ raise ValueError(
+ f"{value.name} must share the symbolic batch dimension."
+ )
+ batch_dimension = batch
+ for dimension, size in zip(dimensions[1:], shape, strict=True):
+ # The TorchScript exporter leaves some SOMA output sizes symbolic.
+ # TensorRT resolves and checks them when it builds the engine.
+ if mode == "output" and dimension.dim_param:
+ continue
+ if not dimension.HasField("dim_value") or dimension.dim_value != size:
+ raise ValueError(f"Unexpected ONNX shape for {value.name}.")
+
+
+def export_release(variant, checkpoints, output, force=False):
+ """Verify the checkpoints, then export and validate the ONNX model before saving it."""
+ kind, separator, precision = variant.partition("_")
+ if not separator or kind not in CHECKPOINTS or precision not in ("fp32", "fp16"):
+ raise ValueError(f"Unknown model variant: {variant}")
+ output = Path(output).expanduser().resolve()
+ if output.exists() and not force:
+ raise ValueError(f"Output already exists: {output}. Use --force to replace it.")
+ check_environment(kind)
+ torch.set_num_threads(1)
+ sources = load_sources(checkpoint_root(Path(checkpoints), CHECKPOINTS[kind]), CHECKPOINTS[kind])
+ if kind == "g1":
+ from .models.g1 import build_g1
+
+ model = build_g1(sources)
+ else:
+ from .models.soma import build_soma
+
+ model = build_soma(sources)
+ # load_state_dict copies the weights, so release the loaded checkpoint before exporting.
+ del sources
+ gc.collect()
+
+ output.parent.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(
+ prefix="motionbricks-export-", dir=output.parent
+ ) as temporary:
+ staged = Path(temporary) / "model.onnx"
+ logger.debug("Exporting the batched %s model...", kind.upper())
+ export_fp32(kind, model, staged)
+ del model
+ gc.collect()
+ if precision == "fp16":
+ logger.debug("Converting to mixed FP16...")
+ graph = onnx.load(staged)
+ if kind == "g1":
+ from .precision import g1_fp16
+
+ graph = g1_fp16(graph)
+ else:
+ from .precision import soma_fp16
+
+ graph = soma_fp16(graph)
+ onnx.save(graph, staged)
+ del graph
+ validate_output(staged, kind)
+ if force:
+ staged.replace(output)
+ else:
+ # A hard link fails if another process created the output meanwhile.
+ os.link(staged, output)
+ logger.info("Saved %s. The ONNX graph and tensor interface checks passed.", output)
+ return {
+ "variant": variant,
+ "bytes": output.stat().st_size,
+ }
+
+
+class _MessageFormatter(logging.Formatter):
+ """Show messages as they are, with the level in front of warnings and errors."""
+
+ def format(self, record):
+ message = super().format(record)
+ return f"{record.levelname}: {message}" if record.levelno >= logging.WARNING else message
+
+
+def configure_logging(args):
+ """Show the result and any problems, or every step with --verbose."""
+ handler = logging.StreamHandler()
+ handler.setFormatter(_MessageFormatter())
+ logging.basicConfig(level=logging.WARNING, handlers=[handler], force=True)
+ level = logging.DEBUG if args.verbose else logging.INFO
+ for name in ("__main__", __package__):
+ logging.getLogger(name).setLevel(level)
+
+
+def main():
+ """Parse the command line and export one model."""
+ parser = argparse.ArgumentParser(
+ description="Export SOMA or Unitree G1 checkpoints to batched ONNX."
+ )
+ parser.add_argument("--model", choices=("soma", "unitree_g1"), required=True, help="Model to export.")
+ parser.add_argument(
+ "--checkpoints",
+ required=True,
+ type=Path,
+ help="Downloaded checkpoint folder, such as checkpoints/MotionBricks/soma.",
+ )
+ parser.add_argument(
+ "--precision", choices=("fp32", "fp16"), default="fp32", help="fp32, or fp16 for mixed FP16."
+ )
+ parser.add_argument(
+ "--output",
+ type=Path,
+ help="Output path (default: mmm_v6_{soma|g1}_{fp32|fp16}.onnx).",
+ )
+ parser.add_argument(
+ "--force",
+ action="store_true",
+ help="Replace an existing output after all checks pass.",
+ )
+ parser.add_argument("--verbose", action="store_true", help="Show each export step and verified checkpoint file.")
+ args = parser.parse_args()
+ configure_logging(args)
+ kind = {"soma": "soma", "unitree_g1": "g1"}[args.model]
+ variant = f"{kind}_{args.precision}"
+ output = args.output or Path(f"mmm_v6_{variant}.onnx")
+ try:
+ export_release(variant, args.checkpoints, output, force=args.force)
+ except (ValueError, OSError, RuntimeError) as error:
+ parser.exit(1, f"Export failed: {error}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/onnx/licenses/MotionGPT-LICENSE.txt b/tools/onnx/licenses/MotionGPT-LICENSE.txt
new file mode 100644
index 0000000..387755b
--- /dev/null
+++ b/tools/onnx/licenses/MotionGPT-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 OpenMotionLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/tools/onnx/licenses/T2M-GPT-LICENSE.txt b/tools/onnx/licenses/T2M-GPT-LICENSE.txt
new file mode 100644
index 0000000..e07bc45
--- /dev/null
+++ b/tools/onnx/licenses/T2M-GPT-LICENSE.txt
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2023 tencent
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/tools/onnx/licenses/numpy-LICENSE.txt b/tools/onnx/licenses/numpy-LICENSE.txt
new file mode 100644
index 0000000..014d51c
--- /dev/null
+++ b/tools/onnx/licenses/numpy-LICENSE.txt
@@ -0,0 +1,30 @@
+Copyright (c) 2005-2023, NumPy Developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.
+
+ * Neither the name of the NumPy Developers nor the names of any
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/tools/onnx/licenses/onnx-LICENSE.txt b/tools/onnx/licenses/onnx-LICENSE.txt
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/tools/onnx/licenses/onnx-LICENSE.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/tools/onnx/licenses/safetensors-LICENSE.txt b/tools/onnx/licenses/safetensors-LICENSE.txt
new file mode 100644
index 0000000..261eeb9
--- /dev/null
+++ b/tools/onnx/licenses/safetensors-LICENSE.txt
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/tools/onnx/licenses/torch-LICENSE.txt b/tools/onnx/licenses/torch-LICENSE.txt
new file mode 100644
index 0000000..c23172f
--- /dev/null
+++ b/tools/onnx/licenses/torch-LICENSE.txt
@@ -0,0 +1,84 @@
+From PyTorch:
+
+Copyright (c) 2016- Facebook, Inc (Adam Paszke)
+Copyright (c) 2014- Facebook, Inc (Soumith Chintala)
+Copyright (c) 2011-2014 Idiap Research Institute (Ronan Collobert)
+Copyright (c) 2012-2014 Deepmind Technologies (Koray Kavukcuoglu)
+Copyright (c) 2011-2012 NEC Laboratories America (Koray Kavukcuoglu)
+Copyright (c) 2011-2013 NYU (Clement Farabet)
+Copyright (c) 2006-2010 NEC Laboratories America (Ronan Collobert, Leon Bottou, Iain Melvin, Jason Weston)
+Copyright (c) 2006 Idiap Research Institute (Samy Bengio)
+Copyright (c) 2001-2004 Idiap Research Institute (Ronan Collobert, Samy Bengio, Johnny Mariethoz)
+
+From Caffe2:
+
+Copyright (c) 2016-present, Facebook Inc. All rights reserved.
+
+All contributions by Facebook:
+Copyright (c) 2016 Facebook Inc.
+
+All contributions by Google:
+Copyright (c) 2015 Google Inc.
+All rights reserved.
+
+All contributions by Yangqing Jia:
+Copyright (c) 2015 Yangqing Jia
+All rights reserved.
+
+All contributions by Kakao Brain:
+Copyright 2019-2020 Kakao Brain
+
+All contributions by Cruise LLC:
+Copyright (c) 2022 Cruise LLC.
+All rights reserved.
+
+All contributions by Tri Dao:
+Copyright (c) 2024 Tri Dao.
+All rights reserved.
+
+All contributions by Arm:
+Copyright (c) 2021, 2023-2025 Arm Limited and/or its affiliates
+
+All contributions from Caffe:
+Copyright(c) 2013, 2014, 2015, the respective contributors
+All rights reserved.
+
+All other contributions:
+Copyright(c) 2015, 2016 the respective contributors
+All rights reserved.
+
+Caffe2 uses a copyright model similar to Caffe: each contributor holds
+copyright over their contributions to Caffe2. The project versioning records
+all such contribution and copyright details. If a contributor wants to further
+mark their specific copyright on a particular contribution, they should
+indicate their copyright solely in the commit message of the change when it is
+committed.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+3. Neither the names of Facebook, Deepmind Technologies, NYU, NEC Laboratories America
+ and IDIAP Research Institute nor the names of its contributors may be
+ used to endorse or promote products derived from this software without
+ specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
diff --git a/tools/onnx/licenses/vector-quantize-pytorch-LICENSE.txt b/tools/onnx/licenses/vector-quantize-pytorch-LICENSE.txt
new file mode 100644
index 0000000..cad4321
--- /dev/null
+++ b/tools/onnx/licenses/vector-quantize-pytorch-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Phil Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/tools/onnx/models/__init__.py b/tools/onnx/models/__init__.py
new file mode 100644
index 0000000..f65a8f8
--- /dev/null
+++ b/tools/onnx/models/__init__.py
@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Standalone MotionBricks model definitions."
+
+from __future__ import annotations
diff --git a/tools/onnx/models/features.py b/tools/onnx/models/features.py
new file mode 100644
index 0000000..801258a
--- /dev/null
+++ b/tools/onnx/models/features.py
@@ -0,0 +1,173 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Select root and pose features and expand pose constraints."
+
+from __future__ import annotations
+
+
+import numpy as np
+import torch as t
+from torch import nn
+
+
+def convert_sparse_cond_to_dense_cond_if_needed(
+ cond: t.Tensor, has_cond: t.Tensor, num_max_cond: int
+):
+ """Return conditions as a dense [batch, slot, feature] tensor with a boolean mask.
+
+ A boolean has_cond is already dense. Integer has_cond lists the slot of each
+ condition.
+ """
+ assert cond.shape[1] == has_cond.shape[1]
+ batch_size, feat_dim = (cond.shape[0], cond.shape[2])
+ if has_cond.dtype == t.bool:
+ assert cond.shape[1] == num_max_cond
+ return (cond, has_cond)
+ else:
+ assert cond.shape[1] <= num_max_cond
+ has_cond_map = t.nn.functional.one_hot(has_cond, num_classes=num_max_cond)
+ dense_has_cond = (
+ has_cond_map.sum(dim=1)
+ .reshape([batch_size, num_max_cond, 1])
+ .tile([1, 1, feat_dim])
+ .bool()
+ )
+ dense_cond = t.zeros([batch_size, num_max_cond, feat_dim]).to(
+ cond.device, cond.dtype
+ )
+ dense_cond[dense_has_cond] = cond.view(-1)
+ return (dense_cond, dense_has_cond)
+
+
+def extract_feature_from_motion_rep(
+ x: t.Tensor | None,
+ motion_rep: nn.Module,
+ feature: str,
+ fetch_feat_idx: bool = False,
+):
+ """Select a named feature from a motion representation.
+
+ Names that end in _with_mask append a zero mask column. With fetch_feat_idx, it
+ returns the feature's indices instead.
+ """
+ if feature in [
+ "root_with_mask",
+ "root_without_heading_with_mask",
+ "root_without_hip_height_with_mask",
+ "root_without_hip_height_without_heading_with_mask",
+ ]:
+ if fetch_feat_idx:
+ raise NotImplementedError(
+ "fetch_feat_idx does not support with_mask features."
+ )
+ else:
+ raw_feature = extract_feature_from_motion_rep(
+ x, motion_rep, feature.split("_with_mask")[0]
+ )
+ mask = t.zeros([x.shape[0], x.shape[1], 1]).to(x.device)
+ return t.concat([raw_feature, mask], dim=-1)
+ elif feature == "root":
+ if fetch_feat_idx:
+ return motion_rep.indices["root"]
+ else:
+ return (
+ x
+ if x.shape[-1] == len(motion_rep.indices["root"])
+ else x[:, :, motion_rep.indices["root"]]
+ )
+ elif feature == "root_without_heading":
+ if motion_rep.root_mode == "global":
+ feat_idx = np.concatenate(
+ [
+ motion_rep.indices["global_root_pos_2d"],
+ np.array(
+ [
+ i
+ for i in motion_rep.indices["global_root_pos"]
+ if i not in motion_rep.indices["global_root_pos_2d"]
+ ]
+ ),
+ ]
+ )
+ else:
+ feat_idx = np.concatenate(
+ [
+ motion_rep.indices["local_root_vel"],
+ motion_rep.indices["global_root_y"],
+ ]
+ )
+ if fetch_feat_idx:
+ return feat_idx
+ else:
+ return x if x.shape[-1] == len(feat_idx) else x[:, :, feat_idx]
+ elif feature == "root_without_hip_height":
+ if motion_rep.root_mode == "global":
+ feat_idx = np.concatenate(
+ [
+ motion_rep.indices["global_root_pos_2d"],
+ motion_rep.indices["global_root_heading"],
+ ]
+ )
+ else:
+ feat_idx = np.concatenate(
+ [
+ motion_rep.indices["local_root_rot_vel"],
+ motion_rep.indices["local_root_vel"],
+ ]
+ )
+ if fetch_feat_idx:
+ return feat_idx
+ else:
+ return x if x.shape[-1] == len(feat_idx) else x[:, :, feat_idx]
+ elif feature == "root_without_hip_height_without_heading":
+ if motion_rep.root_mode == "global":
+ feat_idx = motion_rep.indices["global_root_pos_2d"]
+ else:
+ feat_idx = motion_rep.indices["local_root_vel"]
+ if fetch_feat_idx:
+ return feat_idx
+ else:
+ return x if x.shape[-1] == len(feat_idx) else x[:, :, feat_idx]
+ elif feature == "pose":
+ if fetch_feat_idx:
+ return motion_rep.indices["all"]
+ else:
+ assert x.shape[-1] == len(motion_rep.indices["all"])
+ return x
+ elif feature == "joint_positions_and_rotations":
+ feat_idx = np.concatenate(
+ [motion_rep.indices["ric_data"], motion_rep.indices["global_rot_data"]]
+ )
+ if fetch_feat_idx:
+ return feat_idx
+ else:
+ return x if x.shape[-1] == len(feat_idx) else x[:, :, feat_idx]
+ elif feature == "joint_positions_and_rotations_and_hip_height":
+ if motion_rep.root_mode == "global":
+ feat_idx = np.concatenate(
+ [
+ np.array(
+ [
+ i
+ for i in motion_rep.indices["global_root_pos"]
+ if i not in motion_rep.indices["global_root_pos_2d"]
+ ]
+ ),
+ motion_rep.indices["ric_data"],
+ motion_rep.indices["global_rot_data"],
+ ]
+ )
+ else:
+ feat_idx = np.concatenate(
+ [
+ motion_rep.indices["global_root_y"],
+ motion_rep.indices["ric_data"],
+ motion_rep.indices["global_rot_data"],
+ ]
+ )
+ if fetch_feat_idx:
+ return feat_idx
+ else:
+ return x if x.shape[-1] == len(feat_idx) else x[:, :, feat_idx]
+ else:
+ raise NotImplementedError
diff --git a/tools/onnx/models/g1/__init__.py b/tools/onnx/models/g1/__init__.py
new file mode 100644
index 0000000..d5aa0ec
--- /dev/null
+++ b/tools/onnx/models/g1/__init__.py
@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Standalone G1 checkpoint export model."""
+
+from .model import INPUT_NAMES, OUTPUT_NAMES, build_g1
+
+__all__ = ["INPUT_NAMES", "OUTPUT_NAMES", "build_g1"]
diff --git a/tools/onnx/models/g1/inference.py b/tools/onnx/models/g1/inference.py
new file mode 100644
index 0000000..dff5fbd
--- /dev/null
+++ b/tools/onnx/models/g1/inference.py
@@ -0,0 +1,535 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Combine the G1 predictors and decoder into a batched inference model."
+
+from __future__ import annotations
+
+import logging
+from typing import Dict
+
+import numpy as np
+import torch as t
+from ..features import extract_feature_from_motion_rep
+from ..representation import global_root_to_local_onnx_compatible
+
+logger = logging.getLogger(__name__)
+
+
+class motion_inference(t.nn.Module):
+ """Run the G1 root predictor, pose predictor, and motion decoder for inference.
+
+ predict() runs them in order on one batch.
+ """
+
+ BATCH_SIZE = 1
+ EXTERNAL_POSE_FEATURE_MODE = "joint_positions_and_rotations"
+ EXTERNAL_ROOT_FEATURE_MODE = "root"
+ INTERNAL_POSE_FEATURE_MODE = "joint_positions_and_rotations_and_hip_height"
+ EPS = 1e-05
+
+ def __init__(self, models: list, args: Dict, device: str = "cuda"):
+ super(motion_inference, self).__init__()
+ self._pose_model: t.nn.Module = models["pose"].eval().to(device)
+ self._root_model: t.nn.Module = models["root"].eval().to(device)
+ self._vqvae_pose_model: t.nn.Module = (
+ self._pose_model.supporting_nets["pose_net"].eval().to(device)
+ )
+ self.global_motion_rep = self._pose_model.global_motion_rep
+ self.local_motion_rep = self._pose_model.local_motion_rep
+ self.motion_rep = self._pose_model.motion_rep
+ self._args = args
+ self._device = device
+ self._IS_ROOT_MODEL_TOKENIZED = self._root_model.backbone_net.IS_MODEL_TOKENIZED
+ assert (
+ self._pose_model.backbone_net.initted
+ and self._pose_model.vqvae_model_loaded
+ and self._root_model.vqvae_model_loaded
+ ), "The model should be initialized before inference."
+ assert not self._IS_ROOT_MODEL_TOKENIZED, "The root model is not tokenized."
+
+ def predict(
+ self,
+ global_root_values: t.Tensor,
+ has_global_root_values: t.Tensor,
+ local_root_values: t.Tensor,
+ has_local_root_values: t.Tensor,
+ local_poses: t.Tensor,
+ has_local_poses: t.Tensor,
+ num_tokens: t.Tensor,
+ text_embeddings: t.Tensor = None,
+ has_text_embeddings: t.Tensor = None,
+ allowed_pred_num_tokens: t.Tensor = None,
+ config: dict = {},
+ info: dict = {},
+ ):
+ """Predict the motion features and token count for a batch of conditions.
+
+ It predicts the root trajectory, then the pose tokens, then decodes the motion.
+ """
+ batch_size, device, dtype = (
+ has_global_root_values.shape[0],
+ has_global_root_values.device,
+ local_poses.dtype,
+ )
+ num_frames_per_token = self._pose_model.backbone_net.get_num_frames_per_token()
+ if not (
+ t.all(has_global_root_values[:, :num_frames_per_token])
+ and t.all(has_local_root_values[:, :num_frames_per_token])
+ and t.all(has_local_poses[:, :num_frames_per_token])
+ ):
+ if not getattr(self, "_warned_missing_frames", False):
+ logger.warning("Results are best when all of the first four frames are provided.")
+ self._warned_missing_frames = True
+ if type(num_tokens) == int:
+ num_tokens = t.full([batch_size, 1], num_tokens, dtype=t.int).to(device)
+ elif num_tokens is None:
+ num_tokens = self._root_model.backbone_net.MASKED_NUM_TOKENS * t.ones(
+ [batch_size, 1], dtype=t.int
+ ).to(device)
+ batch = {}
+ (
+ batch["reference_start_root_global_offsets"],
+ batch["reference_start_root_global_heading"],
+ recentered_global_root_values,
+ ) = self._extract_initial_root_info(global_root_values)
+ batch["global_root_values"] = self.global_motion_rep.normalize(
+ recentered_global_root_values
+ )
+ batch["local_root_values"] = self.local_motion_rep.normalize(local_root_values)
+ local_pose_feat_idx = extract_feature_from_motion_rep(
+ t.zeros([1, 1, len(self.local_motion_rep.indices["all"])]),
+ self.local_motion_rep,
+ self.INTERNAL_POSE_FEATURE_MODE,
+ fetch_feat_idx=True,
+ )
+ global_height_values = recentered_global_root_values[
+ :, :, self.global_motion_rep.indices["global_root_pos"][[1]]
+ ]
+ mean = self.local_motion_rep.stats.mean[None, None, local_pose_feat_idx].to(
+ device=device, dtype=dtype
+ )
+ std = self.local_motion_rep.stats.std[None, None, local_pose_feat_idx].to(
+ device=device, dtype=dtype
+ )
+ batch["local_poses"] = (
+ t.concat([global_height_values, local_poses], dim=-1) - mean
+ ) / t.sqrt(std**2 + self.EPS)
+ batch["has_global_root_values"] = has_global_root_values
+ batch["has_local_root_values"] = has_local_root_values
+ batch["has_local_poses"] = has_local_poses
+ batch["text_embeddings"] = text_embeddings
+ batch["has_text_embeddings"] = has_text_embeddings
+ batch["num_tokens"] = num_tokens
+ batch["allowed_pred_num_tokens"] = allowed_pred_num_tokens
+ (
+ batch["pred_num_tokens"],
+ batch["pred_global_root_values"],
+ batch["pred_local_root_values"],
+ ) = self._predict_root_trajectories(batch, config)
+ (
+ batch["pred_pose_tokens"],
+ batch["pred_pose_cond"],
+ batch["pred_has_pose_cond"],
+ ) = self._predict_pose_tokens(batch, config, info)
+ batch["pred_local_poses"], batch["pred_global_poses"] = (
+ self._decode_motions_from_predicted_root_and_pose_tokens(
+ batch, config, info
+ )
+ )
+ batch["pred_global_poses"] = self._reapply_initial_root_info(batch)
+ return (batch["pred_global_poses"], batch["pred_num_tokens"])
+
+ def _sample_tokens_with_highest_prob(
+ self,
+ pose_tokens: t.Tensor,
+ pose_tokens_prob: t.Tensor,
+ pred_num_tokens: t.Tensor,
+ step: int,
+ num_pose_inference_steps: int,
+ ):
+ batch_size, device = (pose_tokens.shape[0], pose_tokens.device)
+ rand_mask_prob = np.cos(float(step) / num_pose_inference_steps * np.pi * 0.5)
+ num_pose_heads = self._pose_model.backbone_net.get_num_heads()[0]
+ num_tokens = (
+ self._args["max_tokens"] * self._pose_model.backbone_net.get_num_heads()[0]
+ )
+ num_pose_token_masked = t.clip(
+ (
+ rand_mask_prob
+ * pred_num_tokens
+ * self._pose_model.backbone_net.get_num_heads()[0]
+ ).int(),
+ min=1,
+ )
+ pose_tokens_prob = t.where(
+ t.arange(self._args["max_tokens"]).to(device).view([1, -1, 1])
+ < pred_num_tokens.view([batch_size, 1, 1]).repeat([1, 1, num_pose_heads]),
+ pose_tokens_prob,
+ t.full_like(pose_tokens_prob, t.inf),
+ )
+ indices = pose_tokens_prob.view([batch_size, -1]).sort(descending=False)[1]
+ tokens_to_be_masked = t.arange(num_tokens).to(device)[None, :].expand(
+ batch_size, -1
+ ) < num_pose_token_masked.reshape(-1, 1)
+ indices = indices * tokens_to_be_masked + indices[:, :1] * ~tokens_to_be_masked
+ pose_tokens = pose_tokens.view([batch_size, -1]).clone()
+ pose_tokens.scatter_(
+ dim=-1, index=indices, value=self._pose_model.backbone_net.POSE_MASK_ID
+ )
+ return pose_tokens.view([batch_size, self._args["max_tokens"], -1])
+
+ @property
+ def device(self):
+ """Device the networks run on."""
+ return self._device
+
+ def _extract_initial_root_info(self, global_root_values: t.Tensor):
+ reference_start_root_global_offsets = global_root_values[
+ :, :1, self.global_motion_rep.indices["global_root_pos_2d"]
+ ].clone()
+ _, reference_start_root_global_heading = (
+ self.global_motion_rep.compute_root_pos_and_rot(
+ global_root_values[:, :1, :], return_angle=True, return_quat=False
+ )
+ )
+ recentered_global_root_values = global_root_values.clone()
+ recentered_global_root_values[
+ :, :, self.global_motion_rep.indices["global_root_pos_2d"]
+ ] -= reference_start_root_global_offsets
+ return (
+ reference_start_root_global_offsets,
+ reference_start_root_global_heading,
+ recentered_global_root_values,
+ )
+
+ def _reapply_initial_root_info(self, batch: dict):
+ _, root_rot_angle = self.global_motion_rep.compute_root_pos_and_rot(
+ batch["pred_global_poses"], return_angle=True, return_quat=False
+ )
+ corrective_angle = batch["reference_start_root_global_heading"].reshape(
+ root_rot_angle[..., 0].shape
+ )
+ new_angles = root_rot_angle + corrective_angle[..., None]
+ new_heading = t.stack([t.cos(new_angles), t.sin(new_angles)], dim=-1)
+ batch["pred_global_poses"][
+ :, :, self.global_motion_rep.indices["global_root_pos_2d"]
+ ] += batch["reference_start_root_global_offsets"]
+ batch["pred_global_poses"][
+ :, :, self.global_motion_rep.indices["global_root_heading"]
+ ] = new_heading
+ return batch["pred_global_poses"]
+
+ def _predict_root_trajectories(self, batch: dict = {}, config: dict = {}):
+ assert (
+ self._root_model.args["local_root_feature"]
+ == self.EXTERNAL_ROOT_FEATURE_MODE
+ ), (
+ self._root_model.args["global_root_feature"]
+ == self.EXTERNAL_ROOT_FEATURE_MODE
+ )
+ assert (
+ self._root_model.args["local_pose_feature"]
+ == self.INTERNAL_POSE_FEATURE_MODE
+ ), (
+ f"All submodules should only use {self.INTERNAL_POSE_FEATURE_MODE} as the local pose feature."
+ )
+ assert self.EXTERNAL_ROOT_FEATURE_MODE == "root", (
+ "The root model supports only full root features."
+ )
+ num_frames_per_token = self._pose_model.backbone_net.get_num_frames_per_token()
+ assert (
+ num_frames_per_token
+ == self._root_model.backbone_net.get_num_frames_per_token()
+ )
+ root_model_outputs = self._root_model.backbone_net(
+ batch["global_root_values"],
+ batch["has_global_root_values"],
+ batch["local_root_values"],
+ batch["has_local_root_values"],
+ batch["local_poses"],
+ batch["has_local_poses"],
+ batch["num_tokens"],
+ text_embeddings=batch["text_embeddings"],
+ has_text_embeddings=batch["has_text_embeddings"],
+ allowed_pred_num_tokens=batch["allowed_pred_num_tokens"],
+ config=config,
+ )
+ pred_num_tokens = root_model_outputs["pred_num_tokens"]
+ pred_global_root_values = root_model_outputs["pred_global_root_values"]
+ if config.get("debug_ground_truth_root_trajectories", None) is not None:
+ pred_num_tokens[:] = (
+ config["debug_ground_truth_root_trajectories"].shape[1]
+ // num_frames_per_token
+ )
+ pred_global_root_values[
+ :, : config["debug_ground_truth_root_trajectories"].shape[1]
+ ] = config["debug_ground_truth_root_trajectories"]
+ pred_local_root_values = global_root_to_local_onnx_compatible(
+ pred_global_root_values,
+ self.motion_rep.dual_rep,
+ pred_num_tokens * num_frames_per_token,
+ )
+ estimated_final_local_root_motion = t.gather(
+ pred_local_root_values,
+ 1,
+ pred_num_tokens.long().reshape(-1, 1).repeat([1, 4])[:, None, :]
+ * num_frames_per_token
+ - 1,
+ )
+ local_root_feat_dim = len(self.local_motion_rep.indices["root"])
+ final_local_root_motion = (
+ batch["has_local_root_values"][:, -1:, None]
+ .expand([-1, -1, local_root_feat_dim])
+ .float()
+ * batch["local_root_values"][:, -1:]
+ + (
+ 1
+ - batch["has_local_root_values"][:, -1:, None]
+ .expand([-1, -1, local_root_feat_dim])
+ .float()
+ )
+ * estimated_final_local_root_motion
+ )
+ pred_local_root_values = pred_local_root_values.scatter(
+ 1,
+ pred_num_tokens.long().reshape(-1, 1).repeat([1, 4])[:, None, :]
+ * num_frames_per_token
+ - 1,
+ final_local_root_motion,
+ )
+ return (pred_num_tokens, pred_global_root_values, pred_local_root_values)
+
+ def _predict_pose_tokens(
+ self, batch: dict = {}, config: dict = {}, info: dict = {}
+ ):
+ assert (
+ self._pose_model.args["local_pose_feature"]
+ == self.INTERNAL_POSE_FEATURE_MODE
+ )
+ assert (
+ self.INTERNAL_POSE_FEATURE_MODE
+ == "joint_positions_and_rotations_and_hip_height"
+ )
+ assert (
+ self._pose_model.args["cond_root_feature_is_from_motion_rep"] == "local"
+ and self._pose_model.args["cond_root_feature"]
+ == "root_without_hip_height_without_heading"
+ or (
+ self._pose_model.args["cond_root_feature_is_from_motion_rep"]
+ == "global"
+ and self._pose_model.args["cond_root_feature"]
+ == "root_without_hip_height"
+ )
+ ), "Only these two root condition feature combinations are supported."
+ num_pose_heads, num_frames_per_token = (
+ self._pose_model.backbone_net.get_num_heads()[0],
+ self._pose_model.backbone_net.get_num_frames_per_token(),
+ )
+ batch_size, device = (
+ batch["local_poses"].shape[0],
+ batch["local_poses"].device,
+ )
+ num_pose_inference_steps = config.get("num_inference_step", 1)
+ pose_tokens = t.full(
+ [batch_size, self._args["max_tokens"], num_pose_heads],
+ self._pose_model.backbone_net.POSE_MASK_ID,
+ ).to(device)
+ chosen_pose_tokens_prob = t.full(
+ [batch_size, self._args["max_tokens"], num_pose_heads], 1.0 / num_pose_heads
+ ).to(device)
+ pose_cond = t.concat(
+ [
+ batch["local_poses"][:, :num_frames_per_token],
+ t.zeros(
+ [
+ batch_size,
+ (self._args["max_tokens"] - 1) * num_frames_per_token,
+ batch["local_poses"].shape[-1],
+ ]
+ ).to(device),
+ ],
+ dim=1,
+ )
+ has_pose_cond = t.concat(
+ [
+ batch["has_local_poses"][:, :num_frames_per_token],
+ t.zeros(
+ [batch_size, (self._args["max_tokens"] - 1) * num_frames_per_token],
+ dtype=bool,
+ ).to(device),
+ ],
+ dim=1,
+ )
+ for i in range(num_frames_per_token):
+ onehot_idx = t.nn.functional.one_hot(
+ batch["pred_num_tokens"].view([-1]).long() * num_frames_per_token
+ - num_frames_per_token
+ + i,
+ num_classes=self._args["max_tokens"] * num_frames_per_token,
+ )
+ pose_cond = pose_cond + onehot_idx.float().view(
+ [batch_size, -1, 1]
+ ) * batch["local_poses"][:, -num_frames_per_token + i].view(
+ [batch_size, 1, -1]
+ )
+ has_pose_cond = t.logical_or(
+ has_pose_cond,
+ (
+ onehot_idx.float().view([batch_size, -1])
+ * batch["has_local_poses"][:, -num_frames_per_token + i].view(
+ [batch_size, 1]
+ )
+ ).bool(),
+ )
+ for step in range(num_pose_inference_steps):
+ pose_tokens = self._sample_tokens_with_highest_prob(
+ pose_tokens,
+ chosen_pose_tokens_prob,
+ batch["pred_num_tokens"],
+ step,
+ num_pose_inference_steps,
+ )
+ assert self._args["cond_root_feature_is_from_motion_rep"] in [
+ "local",
+ "global",
+ ]
+ if self._args["cond_root_feature_is_from_motion_rep"] == "local":
+ pose_root_cond = extract_feature_from_motion_rep(
+ batch["pred_local_root_values"],
+ self.local_motion_rep,
+ self._pose_model.args["cond_root_feature"],
+ )
+ else:
+ assert self._args["cond_root_feature_is_from_motion_rep"] == "global"
+ pose_root_cond = extract_feature_from_motion_rep(
+ batch["pred_global_root_values"],
+ self.global_motion_rep,
+ self._pose_model.args["cond_root_feature"],
+ )
+ pose_model_output = self._pose_model.backbone_net(
+ pose_tokens,
+ pose_root_cond,
+ pose_cond,
+ has_pose_cond,
+ batch["pred_num_tokens"],
+ batch["text_embeddings"],
+ batch["has_text_embeddings"],
+ )
+ if config.get("pose_token_sampling_use_argmax", False):
+ pose_tokens = pose_model_output["pose_logits"].argmax(dim=-1)
+ else:
+ raise ValueError("The release exporter uses argmax token selection.")
+ pose_tokens_prob = pose_model_output["pose_logits"].softmax(dim=-1)
+ chosen_pose_tokens_prob = pose_tokens_prob.gather(
+ dim=-1, index=pose_tokens.unsqueeze(-1)
+ ).squeeze(-1)
+ if config.get("debug_ground_truth_pose_tokens", None) is not None:
+ pose_tokens[:, : config["debug_ground_truth_pose_tokens"].shape[1]] = (
+ config["debug_ground_truth_pose_tokens"][:, :]
+ )
+ return (pose_tokens, pose_cond, has_pose_cond)
+
+ def _decode_motions_from_predicted_root_and_pose_tokens(
+ self, batch: dict = {}, config: dict = {}, info: dict = {}
+ ):
+ if self._pose_model.args["pose_vqvae_motion_rep"] == "local":
+ assert self._vqvae_pose_model.motion_rep.name == "local"
+ assert (
+ self._vqvae_pose_model.decoder_external_cond_feature_mode
+ == "root_without_hip_height_without_heading"
+ )
+ else:
+ assert self._vqvae_pose_model.motion_rep.name == "global"
+ assert (
+ self._vqvae_pose_model.decoder_external_cond_feature_mode
+ == "root_without_hip_height_without_heading_with_mask"
+ )
+ assert (
+ self._vqvae_pose_model.decoder_target_cond_feature_mode
+ == self.INTERNAL_POSE_FEATURE_MODE
+ )
+ pose_external_root_cond = extract_feature_from_motion_rep(
+ batch["pred_local_root_values"]
+ if self._vqvae_pose_model.motion_rep.name == "local"
+ else batch["pred_global_root_values"],
+ self._vqvae_pose_model.motion_rep,
+ self._vqvae_pose_model.decoder_external_cond_feature_mode,
+ )
+ if self._vqvae_pose_model.motion_rep.name == "global":
+ raise NotImplementedError("The global root feature is not supported.")
+ batch_size, device = (
+ batch["local_poses"].shape[0],
+ batch["local_poses"].device,
+ )
+ pose_token_mask = t.arange(self._args["max_tokens"]).to(device)[None, :].repeat(
+ [batch_size, 1]
+ ) < batch["pred_num_tokens"].view([batch_size, 1])
+ if type(config.get("use_target_cond_in_decoder", True)) == t.Tensor:
+ global_target_cond = (
+ config["use_target_cond_in_decoder"]
+ .bool()
+ .expand_as(batch["pred_has_pose_cond"])
+ )
+ has_target_cond = t.logical_and(
+ batch["pred_has_pose_cond"], global_target_cond
+ )
+ else:
+ assert type(config.get("use_target_cond_in_decoder", True)) == bool
+ has_target_cond = (
+ batch["pred_has_pose_cond"]
+ if config.get("use_target_cond_in_decoder", True)
+ else t.zeros_like(batch["pred_has_pose_cond"]).bool()
+ )
+ if not config.get("use_constraints_at_decoder", True):
+ has_target_cond = t.zeros_like(has_target_cond).bool()
+ if config.get("skip_ending_target_cond", False):
+ num_frames_per_token = (
+ self._pose_model.backbone_net.get_num_frames_per_token()
+ )
+ has_target_cond[:, num_frames_per_token:] = False
+ pred_poses = self._vqvae_pose_model.forward_decoder(
+ batch["pred_pose_tokens"],
+ target_cond=batch["pred_pose_cond"],
+ has_target_cond=has_target_cond,
+ external_cond=pose_external_root_cond,
+ use_overall_indices=False,
+ token_mask=pose_token_mask,
+ )["recon_state"]
+ num_pred_frames = (
+ batch["pred_num_tokens"]
+ * self._pose_model.backbone_net.get_num_frames_per_token()
+ )
+ if self._vqvae_pose_model.motion_rep.name == "local":
+ pred_global_poses = self.motion_rep.dual_rep.local_to_global(
+ pred_poses,
+ is_normalized=True,
+ to_normalize=False,
+ lengths=num_pred_frames,
+ )
+ pred_local_poses = self.local_motion_rep.unnormalize(pred_poses)
+ else:
+ pred_local_poses = self.motion_rep.dual_rep.global_to_local(
+ pred_poses,
+ is_normalized=True,
+ to_normalize=False,
+ lengths=num_pred_frames,
+ )
+ pred_global_poses = self.global_motion_rep.unnormalize(pred_poses)
+ if config.get("final_root_pred_mode", "from_pose_module") == "from_pose_module":
+ pass
+ elif config["final_root_pred_mode"] == "from_root_module":
+ local_root_index, global_root_index = (
+ self.local_motion_rep.indices["root"],
+ self.global_motion_rep.indices["root"],
+ )
+ pred_global_poses[:, :, global_root_index] = (
+ self.global_motion_rep.unnormalize(batch["pred_global_root_values"])
+ )
+ pred_local_poses[:, :, local_root_index] = (
+ self.local_motion_rep.unnormalize(batch["pred_local_root_values"])
+ )
+ else:
+ raise NotImplementedError(
+ f"Unsupported final_root_pred_mode: {config['final_root_pred_mode']}."
+ )
+ return (pred_local_poses, pred_global_poses)
diff --git a/tools/onnx/models/g1/model.py b/tools/onnx/models/g1/model.py
new file mode 100644
index 0000000..7dab2db
--- /dev/null
+++ b/tools/onnx/models/g1/model.py
@@ -0,0 +1,233 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Build the G1 inference model from the three released checkpoint states."""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import numpy as np
+import torch
+from torch import nn
+
+from .inference import motion_inference
+from .networks import pose_backbone_network, root_backbone_network
+from .rig import G1PlacedPosePreprocess, G1PlacedPosePostprocess
+from ..representation import GlobalRootGlobalJoints, Stats
+from ..vqvae import VQVAE
+
+INPUT_NAMES = (
+ "context_qpos",
+ "target_qpos",
+ "has_global_root_values",
+ "has_local_root_values",
+ "has_local_poses",
+ "allowed_pred_num_tokens",
+)
+OUTPUT_NAMES = ("pred_qpos", "pred_num_tokens", "pred_foot_contacts")
+CONFIG = {
+ "num_inference_step": 1,
+ "smooth_root_traj": False,
+ "allow_pred_out_of_reach_num_tokens": False,
+ "pose_token_sampling_use_argmax": True,
+ "skip_ending_target_cond": False,
+}
+
+
+class G1JointSpace(nn.Module):
+ """Run G1 inference on encoded inputs, and return motion features and token counts."""
+
+ def __init__(self, inferencer):
+ super().__init__()
+ self.inferencer = inferencer
+
+ def forward(
+ self,
+ global_root_values,
+ has_global_root_values,
+ local_root_values,
+ has_local_root_values,
+ local_poses,
+ has_local_poses,
+ allowed_pred_num_tokens,
+ ):
+ features, tokens = self.inferencer.predict(
+ global_root_values,
+ has_global_root_values.bool(),
+ local_root_values,
+ has_local_root_values.bool(),
+ local_poses,
+ has_local_poses.bool(),
+ num_tokens=None,
+ allowed_pred_num_tokens=allowed_pred_num_tokens,
+ config=CONFIG,
+ info={},
+ )
+ return features, tokens.to(torch.int32)
+
+
+class BatchedG1(nn.Module):
+ """Batched G1 graph that takes and returns joint coordinates.
+
+ It encodes the context and target poses, runs inference, and decodes the result with
+ its foot contacts.
+ """
+
+ def __init__(self, inferencer):
+ super().__init__()
+ with np.load(
+ Path(__file__).resolve().parents[2] / "assets/g1_model_rig.npz",
+ allow_pickle=False,
+ ) as data:
+ arrays = dict(data)
+ indices = inferencer.global_motion_rep.indices
+ self.pre = G1PlacedPosePreprocess(arrays, indices)
+ self.core = G1JointSpace(inferencer)
+ self.post = G1PlacedPosePostprocess(arrays, indices)
+
+ def forward(
+ self,
+ context_qpos,
+ target_qpos,
+ has_global_root_values,
+ has_local_root_values,
+ has_local_poses,
+ allowed_pred_num_tokens,
+ ):
+ joint_inputs = self.pre(
+ context_qpos,
+ target_qpos,
+ has_global_root_values,
+ has_local_root_values,
+ has_local_poses,
+ allowed_pred_num_tokens,
+ )
+ return self.post(*self.core(*joint_inputs))
+
+
+class Predictor(nn.Module):
+ """One predictor network with its motion representation and settings."""
+
+ def __init__(self, backbone, motion_rep, args, pose_decoder=None):
+ super().__init__()
+ self.backbone_net = backbone
+ self.motion_rep = motion_rep
+ self.global_motion_rep = motion_rep.dual_rep.global_motion_rep
+ self.local_motion_rep = motion_rep.dual_rep.local_motion_rep
+ self.args = args
+ self.supporting_nets = {"pose_net": pose_decoder}
+ self.vqvae_model_loaded = True
+
+
+def build_g1(sources):
+ """Load the root predictor, the pose predictor, and the VQ-VAE motion decoder."""
+ mean = next(value for path, value in sources.items() if path.endswith("mean.npy"))
+ std = next(value for path, value in sources.items() if path.endswith("std.npy"))
+ stats = Stats()
+ stats.register_from_tensors(
+ torch.from_numpy(mean).float(), torch.from_numpy(std).float()
+ )
+ motion_rep = GlobalRootGlobalJoints(
+ fps=30,
+ skeleton=SimpleNamespace(nbjoints=34),
+ name="g1skel34_dual_root_global_joints",
+ stats=stats,
+ )
+ common = dict(
+ min_tokens=6,
+ max_tokens=16,
+ down_t=2,
+ local_pose_feature="joint_positions_and_rotations_and_hip_height",
+ )
+ pose_args = dict(
+ common,
+ pose_root_mode="pose",
+ pose_vqvae_motion_rep="local",
+ cond_root_feature="root_without_hip_height",
+ cond_root_feature_is_from_motion_rep="global",
+ )
+ root_args = dict(
+ common,
+ pose_root_mode="root",
+ local_root_feature="root",
+ global_root_feature="root",
+ use_hard_num_token_emb_for_root_prediction=True,
+ )
+ pose_network_args = dict(
+ pose_args,
+ pose_token_mlp_num_layers=2,
+ root_feat_width=256,
+ pose_feat_width=640,
+ token_length_feat_width=128,
+ text_emb_dim=4096,
+ text_embeddings=None,
+ n_embd=1024,
+ n_head=16,
+ n_layers=16,
+ pose_vqvae=dict(
+ nb_code=100000000, code_dim=256, num_heads=8, has_codebook=True
+ ),
+ root_vqvae=dict(nb_code=1024, code_dim=60, num_heads=1),
+ )
+ root_network_args = dict(
+ root_args,
+ pose_feat_dim=256,
+ local_root_feat_dim=64,
+ global_root_feat_dim=64,
+ text_emb_dim=4096,
+ text_embeddings=None,
+ input_feat_mlp_num_layers=2,
+ n_embd=512,
+ n_head=16,
+ n_layers_shared=3,
+ n_layers_root_token=3,
+ width=512,
+ depth=4,
+ dilation_growth_rate=3,
+ activation="relu",
+ norm="None",
+ pose_vqvae=dict(nb_code=1024, code_dim=60, num_heads=1),
+ root_vqvae=dict(nb_code=1024, code_dim=60, num_heads=1),
+ )
+ pose_backbone = pose_backbone_network(motion_rep, pose_network_args)
+ root_backbone = root_backbone_network(root_network_args, motion_rep)
+ vqvae = VQVAE(
+ pose_root_mode="pose",
+ motion_rep=motion_rep.dual_rep.local_motion_rep,
+ feature_mode=[
+ "joint_positions_and_rotations_and_hip_height",
+ "pose",
+ "joint_positions_and_rotations_and_hip_height",
+ "root_without_hip_height_without_heading",
+ ],
+ nb_code=100000000,
+ code_dim=256,
+ output_emb_width=256,
+ down_t=2,
+ stride_t=2,
+ width=512,
+ depth=4,
+ dilation_growth_rate=3,
+ activation="relu",
+ num_heads=8,
+ norm="None",
+ cond_fusion_last_layer=False,
+ )
+ for kind, network, prefix in (
+ ("pose", pose_backbone, "backbone_net."),
+ ("root", root_backbone, "backbone_net."),
+ ("vqvae", vqvae, "pose_net."),
+ ):
+ state = sources[
+ f"motionbricks_{kind}/version_1/checkpoints/model-step=2000000.safetensors"
+ ]
+ weights = {
+ name.removeprefix(prefix): value
+ for name, value in state.items()
+ if name.startswith(prefix)
+ }
+ network.load_state_dict(weights, strict=True)
+ models = dict(
+ pose=Predictor(pose_backbone, motion_rep, pose_args, vqvae),
+ root=Predictor(root_backbone, motion_rep, root_args),
+ )
+ return BatchedG1(motion_inference(models, pose_args, device="cpu")).eval()
diff --git a/tools/onnx/models/g1/networks.py b/tools/onnx/models/g1/networks.py
new file mode 100644
index 0000000..3996ee8
--- /dev/null
+++ b/tools/onnx/models/g1/networks.py
@@ -0,0 +1,653 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""G1 root and pose predictors."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Dict, Optional
+
+import numpy as np
+import torch
+import torch as t
+from torch import nn
+
+from ..features import (
+ convert_sparse_cond_to_dense_cond_if_needed,
+ extract_feature_from_motion_rep,
+)
+from ..layers import FCBlock as mlp, PositionEmbedding, DoubleCondDecoder
+
+
+class root_backbone_network(nn.Module):
+ """Transformer that predicts the root trajectory and the token count for G1."""
+
+ def __init__(self, args: Dict, motion_rep: nn.Module):
+ super().__init__()
+ self._args = args
+ self.motion_rep = motion_rep
+ self.global_motion_rep = motion_rep.dual_rep.global_motion_rep
+ self.local_motion_rep = motion_rep.dual_rep.local_motion_rep
+ self.IS_MODEL_TOKENIZED = False
+ self._build_backbone()
+ self._build_input_embeddings()
+
+ def _build_backbone(self):
+ encoder_layer = nn.TransformerEncoderLayer(
+ d_model=self._args["n_embd"], nhead=self._args["n_head"], batch_first=True
+ )
+ self._shared_transformer_model = nn.TransformerEncoder(
+ encoder_layer, num_layers=self._args["n_layers_shared"]
+ )
+ if self._args["n_layers_root_token"] > 0:
+ self._root_token_transformer_model = nn.TransformerEncoder(
+ encoder_layer, num_layers=self._args["n_layers_root_token"]
+ )
+ else:
+ self._root_token_transformer_model = None
+ self._args["local_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["local_root_feature"],
+ ).shape[2]
+ self._args["global_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.global_motion_rep,
+ self._args["global_root_feature"],
+ ).shape[2]
+ self._args["local_pose_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["local_pose_feature"],
+ ).shape[2]
+ self._conv_output = DoubleCondDecoder(
+ self._args["global_root_dim"],
+ self._args["n_embd"],
+ down_t=self._args["down_t"],
+ width=self._args["width"],
+ depth=self._args["depth"],
+ dilation_growth_rate=self._args["dilation_growth_rate"],
+ activation=self._args["activation"],
+ norm=self._args["norm"],
+ target_cond_dim=self._args["global_root_dim"],
+ external_cond_dim=self._args["n_embd"],
+ )
+
+ def _build_input_embeddings(self):
+ num_frames_per_token = self.get_num_frames_per_token()
+ self._proj_local_pose = nn.Linear(
+ self._args["local_pose_dim"], self._args["pose_feat_dim"]
+ )
+ self._proj_local_root_value = nn.Linear(
+ self.args["local_root_dim"], self._args["local_root_feat_dim"]
+ )
+ self._proj_global_root_value = nn.Linear(
+ self.args["global_root_dim"], self._args["global_root_feat_dim"]
+ )
+ self._no_local_pose_emb = nn.Parameter(
+ torch.randn([self._args["pose_feat_dim"]])
+ )
+ self._no_local_root_emb = nn.Parameter(
+ torch.randn([self._args["local_root_feat_dim"]])
+ )
+ self._no_global_root_emb = nn.Parameter(
+ torch.randn([self._args["global_root_feat_dim"]])
+ )
+ self._conv_no_frame_emb = nn.Parameter(torch.randn([self._args["n_embd"]]))
+ proj_input_dim = (
+ self._args["pose_feat_dim"]
+ + self._args["local_root_feat_dim"]
+ + self._args["global_root_feat_dim"]
+ )
+ self._proj_start_input = mlp(
+ num_layers=self._args["input_feat_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=proj_input_dim,
+ size_out=self._args["n_embd"],
+ )
+ self._proj_end_input = mlp(
+ num_layers=self._args["input_feat_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=proj_input_dim,
+ size_out=self._args["n_embd"],
+ )
+ self._input_position_emb = t.nn.Embedding(
+ num_frames_per_token * 2, self._args["n_embd"]
+ )
+ self._proj_input_num_tokens = t.nn.Embedding(
+ self._args["max_tokens"] - self._args["min_tokens"] + 1 + 1 + 1,
+ self._args["n_embd"],
+ )
+ self._position_emb = PositionEmbedding(
+ seq_length=self._args["max_tokens"], dim=self._args["n_embd"]
+ )
+ self._proj_num_token_output_logit = t.nn.Linear(
+ self._args["n_embd"],
+ self._args["max_tokens"] - self._args["min_tokens"] + 1 + 1,
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT:
+ self._proj_text_embeddings = mlp(
+ num_layers=self._args["input_feat_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=self._args["text_emb_dim"],
+ size_out=self._args["n_embd"],
+ )
+ if (
+ self.USE_HARD_NUM_TOKEN_EMB_FOR_ROOT_PREDICTION
+ and self._root_token_transformer_model is not None
+ ):
+ self._middle_token_emb = t.nn.Embedding(
+ self._args["max_tokens"] - self._args["min_tokens"] + 1 + 1,
+ self._args["n_embd"],
+ )
+
+ def forward(
+ self,
+ global_root_values: t.Tensor,
+ has_global_root_values: t.Tensor,
+ local_root_values: t.Tensor,
+ has_local_root_values: t.Tensor,
+ poses: t.Tensor,
+ has_poses: t.Tensor,
+ num_tokens: t.Tensor,
+ text_embeddings: Optional[t.Tensor] = None,
+ has_text_embeddings: Optional[t.Tensor] = None,
+ groundtruth_num_tokens: t.Tensor = None,
+ allowed_pred_num_tokens: t.Tensor = None,
+ config: dict = {},
+ ):
+ batch_size, device = (poses.shape[0], poses.device)
+ num_frames_per_token = self.get_num_frames_per_token()
+ local_pose_emb = self._proj_local_pose(poses)
+ local_root_emb = self._proj_local_root_value(local_root_values)
+ global_root_emb = self._proj_global_root_value(global_root_values)
+ local_pose_emb = local_pose_emb * has_poses[
+ :, :, None
+ ].float() + self._no_local_pose_emb[None, None, :] * (
+ 1 - has_poses[:, :, None].float()
+ )
+ local_root_emb = local_root_emb * has_local_root_values[
+ :, :, None
+ ].float() + self._no_local_root_emb[None, None, :] * (
+ 1 - has_local_root_values[:, :, None].float()
+ )
+ global_root_emb = global_root_emb * has_global_root_values[
+ :, :, None
+ ].float() + self._no_global_root_emb[None, None, :] * (
+ 1 - has_global_root_values[:, :, None].float()
+ )
+ start_frame_emb = torch.cat(
+ [
+ local_pose_emb[:, :num_frames_per_token, :],
+ local_root_emb[:, :num_frames_per_token, :],
+ global_root_emb[:, :num_frames_per_token, :],
+ ],
+ dim=-1,
+ )
+ start_frame_emb = self._proj_start_input(start_frame_emb)
+ end_frame_emb = torch.cat(
+ [
+ local_pose_emb[:, -num_frames_per_token:, :],
+ local_root_emb[:, -num_frames_per_token:, :],
+ global_root_emb[:, -num_frames_per_token:, :],
+ ],
+ dim=-1,
+ )
+ end_frame_emb = self._proj_end_input(end_frame_emb)
+ frame_emb = torch.cat([start_frame_emb, end_frame_emb], dim=1)
+ positioned_frame_emb = frame_emb + self._input_position_emb.weight[None, :, :]
+ first_stage_time_emb = self._proj_input_num_tokens(
+ num_tokens - self._args["min_tokens"]
+ )
+ first_stage_time_emb = first_stage_time_emb.view(
+ [batch_size, 1, self._args["n_embd"]]
+ )
+ first_stage_input_emb = t.concat(
+ [first_stage_time_emb, positioned_frame_emb], dim=1
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT and text_embeddings is not None:
+ text_embeddings = self._proj_text_embeddings(text_embeddings)[:, None, :]
+ first_stage_input_emb = t.concat(
+ [text_embeddings, first_stage_input_emb], dim=1
+ )
+ first_stage_mask = t.zeros(
+ [batch_size, 1 + 1 + num_frames_per_token * 2], device=device
+ ).bool()
+ first_stage_mask[:, :1] = ~has_text_embeddings.bool()
+ else:
+ first_stage_mask = None
+ first_stage_output_emb = self._shared_transformer_model(
+ first_stage_input_emb, src_key_padding_mask=first_stage_mask
+ )
+ num_token_logits = self._proj_num_token_output_logit(
+ first_stage_output_emb[:, self.TRANSFORMER_TIME_LOGIT_ID, :]
+ )
+ assert self.USE_HARD_NUM_TOKEN_EMB_FOR_ROOT_PREDICTION, (
+ "Only support hard num token emb."
+ )
+ if groundtruth_num_tokens is not None:
+ chosen_token = (
+ groundtruth_num_tokens.view([batch_size]) - self._args["min_tokens"]
+ )
+ else:
+ assert not self.training, "groundtruth_num_tokens is required in training."
+ if not config.get("allow_pred_out_of_reach_num_tokens", True):
+ num_token_logits = num_token_logits.clone()
+ num_token_logits[
+ :, self.OUT_OF_REACH_NUM_TOKENS - self._args["min_tokens"]
+ ] = -t.inf
+ if allowed_pred_num_tokens is not None:
+ num_time_tokens = (
+ self._args["max_tokens"] - self._args["min_tokens"] + 1
+ )
+ modified_num_token_logits = t.where(
+ allowed_pred_num_tokens == 1,
+ num_token_logits[:, :num_time_tokens],
+ t.full([batch_size, num_time_tokens], -t.inf).to(device),
+ )
+ num_token_logits = t.cat(
+ [modified_num_token_logits, num_token_logits[:, num_time_tokens:]],
+ dim=-1,
+ )
+ chosen_token = torch.argmax(num_token_logits, dim=-1).int()
+ chosen_token = t.where(
+ num_tokens.view([batch_size]) == self.MASKED_NUM_TOKENS,
+ chosen_token,
+ num_tokens.view([batch_size]) - self._args["min_tokens"],
+ )
+ position_ids = t.arange(self._args["max_tokens"]).to(device=device)
+ position_emb = self._position_emb.embed[position_ids].view(
+ [1, self._args["max_tokens"], self._args["n_embd"]]
+ )
+ position_emb = position_emb.expand([batch_size, -1, -1])
+ token_mask = (
+ t.arange(self._args["max_tokens"]).view([1, -1]).to(device)
+ < chosen_token.view([-1, 1]) + self._args["min_tokens"]
+ )
+ if self._root_token_transformer_model is None:
+ second_stage_output_emb = position_emb
+ else:
+ second_stage_token_emb = self._middle_token_emb(chosen_token)
+ second_stage_input_emb = t.concat(
+ [
+ second_stage_token_emb[:, None, :],
+ positioned_frame_emb,
+ position_emb,
+ ],
+ dim=1,
+ )
+ second_stage_mask = t.cat(
+ [
+ t.zeros(
+ [batch_size, 1 + num_frames_per_token * 2], device=device
+ ).bool(),
+ ~token_mask,
+ ],
+ dim=1,
+ )
+ second_stage_output_emb = self._root_token_transformer_model(
+ second_stage_input_emb, src_key_padding_mask=second_stage_mask
+ )
+ second_stage_output_emb = second_stage_output_emb[
+ :, -self._args["max_tokens"] :
+ ]
+ pred_num_tokens = chosen_token + self._args["min_tokens"]
+ batch = {}
+ keys = ["frame", "global_root"]
+ num_total_frames = self._args["max_tokens"] * num_frames_per_token
+ batch["has_frame"] = t.logical_or(
+ t.logical_or(has_poses, has_global_root_values), has_local_root_values
+ )
+ batch["frame"] = t.where(
+ batch["has_frame"][:, :, None],
+ frame_emb,
+ self._conv_no_frame_emb[None, None, :],
+ )
+ batch["dense_frame"] = t.cat(
+ [
+ batch["frame"][:, :num_frames_per_token],
+ self._conv_no_frame_emb[None, None, :].repeat(
+ [batch_size, num_total_frames - num_frames_per_token, 1]
+ ),
+ ],
+ dim=1,
+ )
+ batch["global_root"], batch["has_global_root"] = (
+ global_root_values,
+ has_global_root_values,
+ )
+ batch["dense_global_root"] = t.cat(
+ [
+ batch["global_root"][:, :num_frames_per_token],
+ t.zeros(
+ [
+ batch_size,
+ num_total_frames - num_frames_per_token,
+ self._args["global_root_dim"],
+ ],
+ device=device,
+ ),
+ ],
+ dim=1,
+ )
+ for key in keys:
+ batch["dense_has_" + key] = t.cat(
+ [
+ batch["has_" + key][:, :num_frames_per_token],
+ t.zeros(
+ [batch_size, num_total_frames - num_frames_per_token],
+ device=device,
+ ).bool(),
+ ],
+ dim=1,
+ )
+ for i in range(num_frames_per_token):
+ offsets = (
+ pred_num_tokens[:, None] * num_frames_per_token
+ - num_frames_per_token
+ + i
+ ).long()
+ batch["dense_" + key] = batch["dense_" + key].scatter(
+ 1,
+ offsets[:, :, None].repeat([1, 1, batch[key].shape[-1]]),
+ batch[key][:, -num_frames_per_token + i][:, None, :],
+ )
+ batch["dense_has_" + key] = batch["dense_has_" + key].scatter(
+ 1,
+ offsets[:, :],
+ batch["has_" + key][:, -num_frames_per_token + i][:, None],
+ )
+ pred_global_root_values = self._conv_output(
+ second_stage_output_emb.transpose(1, 2),
+ external_cond=batch["dense_frame"],
+ target_cond=batch["dense_global_root"],
+ has_target_cond=batch["dense_has_global_root"],
+ token_mask=token_mask,
+ ).transpose(1, 2)
+ return {
+ "num_token_logits": num_token_logits,
+ "pred_num_tokens": pred_num_tokens,
+ "pred_global_root_values": pred_global_root_values,
+ }
+
+ def get_num_frames_per_token(self):
+ """Return the frames per motion token, 2 ** down_t."""
+ return 2 ** self._args["down_t"]
+
+ @property
+ def args(self):
+ """Network settings from the checkpoint."""
+ return self._args
+
+ @property
+ def OUT_OF_REACH_NUM_TOKENS(self):
+ """Token count class for a target that is out of reach."""
+ return self._args["max_tokens"] + 1
+
+ @property
+ def MASKED_NUM_TOKENS(self):
+ """Token count class for a masked token count."""
+ return self._args["max_tokens"] + 2
+
+ @cached_property
+ def ACCEPT_TEXT_EMB_INPUT(self):
+ """Whether the network takes text embeddings."""
+ return True if self._args.get("text_embeddings", None) is not None else False
+
+ @property
+ def TRANSFORMER_TIME_LOGIT_ID(self):
+ """Index of the token count output in the transformer sequence."""
+ return 1 if self.ACCEPT_TEXT_EMB_INPUT else 0
+
+ @cached_property
+ def USE_HARD_NUM_TOKEN_EMB_FOR_ROOT_PREDICTION(self):
+ """Whether root prediction embeds the exact token count."""
+ return self._args.get("use_hard_num_token_emb_for_root_prediction", False)
+
+
+class pose_backbone_network(nn.Module):
+ """Transformer that predicts the pose tokens for G1."""
+
+ def __init__(self, motion_rep: nn.Module, args: Dict = None):
+ super().__init__()
+ self.motion_rep = motion_rep
+ self.global_motion_rep = motion_rep.dual_rep.global_motion_rep
+ self.local_motion_rep = motion_rep.dual_rep.local_motion_rep
+ self._args = args
+ self._build_transformer_backbone()
+ self._build_input_embeddings_projections()
+ self.register_buffer("initted", torch.Tensor([False]).to(dtype=t.bool))
+
+ def _build_transformer_backbone(self):
+ encoder_layer = nn.TransformerEncoderLayer(
+ d_model=self._args["n_embd"], nhead=self._args["n_head"], batch_first=True
+ )
+ self._transformer_model = nn.TransformerEncoder(
+ encoder_layer, num_layers=self._args["n_layers"]
+ )
+
+ def _build_input_embeddings_projections(self):
+ num_pose_heads, _ = self.get_num_heads()
+ num_pose_tokens, _ = self.get_num_codes(include_aug_tokens=False)
+ if self._args["pose_vqvae"].get("has_codebook", True):
+ pose_token_dim = self._args["pose_vqvae"]["code_dim"] // num_pose_heads
+ else:
+ pose_token_dim = self._args["n_embd"] // num_pose_heads
+ self._pose_token_emb = t.nn.Embedding(
+ num_pose_heads * self.NUM_WITH_AUG_POSE_TOKENS, pose_token_dim
+ )
+ self._proj_pose_token_emb = mlp(
+ num_layers=self._args["pose_token_mlp_num_layers"],
+ layer_width=self._args["pose_feat_width"],
+ size_in=num_pose_heads * pose_token_dim,
+ size_out=self._args["pose_feat_width"],
+ )
+ num_frames_per_token = self.get_num_frames_per_token()
+ if self._args["cond_root_feature_is_from_motion_rep"] == "local":
+ self._args["local_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["cond_root_feature"],
+ ).shape[2]
+ else:
+ self._args["local_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.global_motion_rep,
+ self._args["cond_root_feature"],
+ ).shape[2]
+ self._proj_local_root_values = t.nn.Linear(
+ self._args["local_root_dim"] * num_frames_per_token,
+ self._args["root_feat_width"],
+ )
+ self._args["local_pose_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["local_pose_feature"],
+ ).shape[2]
+ self._proj_local_pose = t.nn.Linear(
+ self._args["local_pose_dim"],
+ self._args["pose_feat_width"] // num_frames_per_token,
+ )
+ assert self._args["pose_feat_width"] % self.get_num_frames_per_token() == 0, (
+ "pose_feat_width needs to be divisible by num_frames_per_token"
+ )
+ self._proj_num_valid_positions = t.nn.Embedding(
+ self._args["max_tokens"] - self._args["min_tokens"] + 1,
+ self._args["token_length_feat_width"],
+ )
+ self._proj_input = t.nn.Sequential(
+ t.nn.Linear(
+ self._args["pose_feat_width"]
+ + self._args["root_feat_width"]
+ + self._args["token_length_feat_width"],
+ self._args["n_embd"],
+ ),
+ t.nn.ReLU(),
+ )
+ self._position_emb = PositionEmbedding(
+ seq_length=self._args["max_tokens"], dim=self._args["n_embd"]
+ )
+ self._proj_pose_output_logit = t.nn.Linear(
+ self._args["n_embd"], num_pose_heads * num_pose_tokens
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT:
+ self._proj_text_embeddings = mlp(
+ num_layers=self._args["pose_token_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=self._args["text_emb_dim"],
+ size_out=self._args["n_embd"],
+ )
+
+ def forward(
+ self,
+ pose_tokens: t.Tensor,
+ local_root_values: t.Tensor,
+ pose_cond: t.Tensor,
+ has_pose_cond: t.Tensor,
+ num_tokens: t.Tensor,
+ text_embeddings: t.Tensor = None,
+ has_text_embeddings: t.Tensor = None,
+ ):
+ batch_size, num_positions, num_pose_heads = pose_tokens.shape
+ device = pose_tokens.device
+ num_frames_per_token = self.get_num_frames_per_token()
+ local_root_values = local_root_values.reshape(
+ [
+ batch_size,
+ num_positions,
+ num_frames_per_token * self._args["local_root_dim"],
+ ]
+ )
+ root_embedding = self._proj_local_root_values(local_root_values)
+ dense_pose_cond, dense_has_pose_cond = (
+ convert_sparse_cond_to_dense_cond_if_needed(
+ pose_cond, has_pose_cond, num_positions * num_frames_per_token
+ )
+ )
+ pose_cond_embedding = self._proj_local_pose(dense_pose_cond)
+ pose_cond_embedding = pose_cond_embedding.view(
+ [
+ batch_size,
+ num_positions * num_frames_per_token,
+ self._args["pose_feat_width"] // num_frames_per_token,
+ ]
+ )
+ pose_token_id_offsets = (
+ torch.arange(num_pose_heads).view([1, 1, num_pose_heads]).to(device=device)
+ * self.NUM_WITH_AUG_POSE_TOKENS
+ )
+ pose_tokens = pose_tokens + pose_token_id_offsets
+ pose_token_embedding = self._pose_token_emb(pose_tokens)
+ pose_token_embedding = self._proj_pose_token_emb(
+ pose_token_embedding.view([batch_size, num_positions, -1])
+ )
+ pose_token_embedding = pose_token_embedding.view(
+ [
+ batch_size,
+ num_positions * num_frames_per_token,
+ self._args["pose_feat_width"] // num_frames_per_token,
+ ]
+ )
+ dense_has_pose_cond = dense_has_pose_cond[:, :, None].float()
+ pose_embedding = (
+ pose_cond_embedding * dense_has_pose_cond
+ + pose_token_embedding * (1 - dense_has_pose_cond)
+ )
+ pose_embedding = pose_embedding.view(
+ [batch_size, num_positions, self._args["pose_feat_width"]]
+ )
+ num_token_embedding = self._proj_num_valid_positions(
+ num_tokens.reshape([batch_size, 1]) - self._args["min_tokens"]
+ ).expand([-1, num_positions, -1])
+ position_ids = t.arange(num_positions).to(device=device)
+ position_emb = self._position_emb.embed[position_ids].view(
+ [1, num_positions, self._args["n_embd"]]
+ )
+ input_embeddings = (
+ self._proj_input(
+ t.cat([pose_embedding, root_embedding, num_token_embedding], dim=-1)
+ )
+ + position_emb
+ )
+ token_mask = t.arange(num_positions).to(device) < num_tokens.view(
+ [batch_size, -1]
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT and text_embeddings is not None:
+ text_embeddings = self._proj_text_embeddings(text_embeddings)[:, None, :]
+ input_embeddings = t.concat([text_embeddings, input_embeddings], dim=1)
+ mask = t.zeros([batch_size, 1 + num_positions], device=device).bool()
+ mask[:, :1] = ~has_text_embeddings.bool()
+ mask[:, 1:] = ~token_mask.bool()
+ else:
+ mask = ~token_mask.bool()
+ output = self._transformer_model(input_embeddings, src_key_padding_mask=mask)[
+ :, -num_positions:
+ ]
+ pred_logits = self._proj_pose_output_logit(output).reshape(
+ [batch_size, num_positions, num_pose_heads, -1]
+ )
+ return {"pose_logits": pred_logits}
+
+ def get_num_codes(self, include_aug_tokens: bool):
+ """Return the code counts of the pose and root codebooks.
+
+ With include_aug_tokens, the counts include the extra tokens, such as the mask
+ token.
+ """
+ num_codes_per_head = {}
+ for vqvae in ["pose_vqvae", "root_vqvae"]:
+ nb_code = self._args[vqvae]["nb_code"]
+ len_nb_code = len(np.array(self._args[vqvae]["nb_code"]).reshape([-1]))
+ if len_nb_code > 1:
+ assert np.all(np.array(nb_code) == nb_code[0]), (
+ "fsq config should have the same number of codes for each head"
+ )
+ num_codes_per_head[vqvae] = nb_code[0]
+ else:
+ num_heads = self._args[vqvae]["num_heads"]
+ code_dim = self._args[vqvae]["code_dim"]
+ if self._args[vqvae].get("has_codebook", True):
+ assert code_dim % num_heads == 0, (
+ "code dim cannot be divided by the number of heads."
+ )
+ num_codes_per_head[vqvae] = int(
+ round(2 ** (np.log2(nb_code) / num_heads))
+ )
+ assert num_codes_per_head[vqvae] ** num_heads == nb_code, (
+ "the specified number of code is not compatible with the number of heads."
+ )
+ else:
+ num_codes_per_head[vqvae] = nb_code
+ if include_aug_tokens:
+ return (
+ num_codes_per_head["pose_vqvae"] + 1,
+ num_codes_per_head["root_vqvae"] + 1,
+ )
+ else:
+ return (num_codes_per_head["pose_vqvae"], num_codes_per_head["root_vqvae"])
+
+ def get_num_heads(self):
+ """Return the head counts of the pose and root codebooks."""
+ return (
+ self._args["pose_vqvae"]["num_heads"],
+ self._args["root_vqvae"]["num_heads"],
+ )
+
+ def get_num_frames_per_token(self):
+ """Return the frames per motion token, 2 ** down_t."""
+ return 2 ** self._args["down_t"]
+
+ @property
+ def NUM_WITH_AUG_POSE_TOKENS(self):
+ """Number of pose token values, including the extra tokens."""
+ return self.get_num_codes(include_aug_tokens=True)[0]
+
+ @property
+ def POSE_MASK_ID(self):
+ """Token value that marks a masked pose token."""
+ return self.get_num_codes(include_aug_tokens=True)[0] - 1
+
+ @cached_property
+ def ACCEPT_TEXT_EMB_INPUT(self):
+ """Whether the network takes text embeddings."""
+ return True if self._args.get("text_embeddings", None) is not None else False
diff --git a/tools/onnx/models/g1/rig.py b/tools/onnx/models/g1/rig.py
new file mode 100644
index 0000000..4f517ce
--- /dev/null
+++ b/tools/onnx/models/g1/rig.py
@@ -0,0 +1,258 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"G1 forward kinematics and conversion between joint coordinates and motion features."
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+from torch import nn
+
+
+def wrap(value):
+ """Wrap angles in radians to [-pi, pi)."""
+ return (value + np.pi) % (2 * np.pi) - np.pi
+
+
+def quat_matrix(q):
+ """Convert WXYZ quaternions to rotation matrices."""
+ r, i, j, k = q.unbind(-1)
+ s = 2 / (q * q).sum(-1)
+ return torch.stack(
+ (
+ 1 - s * (j * j + k * k),
+ s * (i * j - k * r),
+ s * (i * k + j * r),
+ s * (i * j + k * r),
+ 1 - s * (i * i + k * k),
+ s * (j * k - i * r),
+ s * (i * k - j * r),
+ s * (j * k + i * r),
+ 1 - s * (i * i + j * j),
+ ),
+ -1,
+ ).reshape(q.shape[:-1] + (3, 3))
+
+
+def matrix_quat(m):
+ """Convert rotation matrices to WXYZ quaternions."""
+ m00, m01, m02 = (m[..., 0, 0], m[..., 0, 1], m[..., 0, 2])
+ m10, m11, m12 = (m[..., 1, 0], m[..., 1, 1], m[..., 1, 2])
+ m20, m21, m22 = (m[..., 2, 0], m[..., 2, 1], m[..., 2, 2])
+ a = (
+ torch.stack(
+ (
+ 1 + m00 + m11 + m22,
+ 1 + m00 - m11 - m22,
+ 1 - m00 + m11 - m22,
+ 1 - m00 - m11 + m22,
+ ),
+ -1,
+ )
+ .clamp_min(0)
+ .sqrt()
+ )
+ rows = torch.stack(
+ (
+ torch.stack((a[..., 0] ** 2, m21 - m12, m02 - m20, m10 - m01), -1),
+ torch.stack((m21 - m12, a[..., 1] ** 2, m10 + m01, m02 + m20), -1),
+ torch.stack((m02 - m20, m10 + m01, a[..., 2] ** 2, m12 + m21), -1),
+ torch.stack((m10 - m01, m20 + m02, m21 + m12, a[..., 3] ** 2), -1),
+ ),
+ -2,
+ ) / (2 * a[..., :, None].clamp_min(0.1))
+ indices = a.argmax(-1)[..., None, None].expand(a.shape[:-1] + (1, 4))
+ return rows.gather(-2, indices).squeeze(-2)
+
+
+def rotate(m, p):
+ """Rotate points by matrices."""
+ return (m @ p[..., None])[..., 0]
+
+
+def six_matrix(value):
+ """Convert 6D rotations to rotation matrices by orthonormalizing their two vectors."""
+ x = value[..., :3] / value[..., :3].norm(dim=-1, keepdim=True)
+ z = torch.cross(x, value[..., 3:], dim=-1)
+ z = z / z.norm(dim=-1, keepdim=True)
+ return torch.stack((x, torch.cross(z, x, dim=-1), z), dim=-1)
+
+
+class G1Rig(nn.Module):
+ """G1 forward kinematics, and decoding of motion features into joint coordinates."""
+
+ def __init__(self, arrays, indices):
+ super().__init__()
+ for key, value in {
+ "basis": arrays["mujoco_to_motion_matrix"],
+ "axes": arrays["mujoco_joint_axis_values_mujoco_space"],
+ "model_axes": arrays["mujoco_joint_axis_values_motion_space"],
+ "q2t": arrays["rot_offsets_q2t"],
+ "f2q": arrays["rot_offsets_f2q"],
+ "rest": arrays["capture_neutral_joints_mujoco"],
+ "neutral": arrays["neutral_joints"],
+ "horizontal_robot": np.array([1, 1, 0], np.float32),
+ "horizontal_model": np.array([1, 0, 1], np.float32),
+ "identity": np.eye(3, dtype=np.float32),
+ }.items():
+ self.register_buffer(key, torch.tensor(value, dtype=torch.float32))
+ self.parents = arrays["mujoco_joint_including_root_parent_list"].tolist()
+ self.model_parents = arrays["joint_parents"].tolist()
+ self.reverse = arrays["motion_indices_to_mujoco_indices"].tolist()
+ self.register_buffer(
+ "mapping",
+ torch.tensor(arrays["mujoco_indices_to_motion_indices"], dtype=torch.long),
+ )
+ self.register_buffer(
+ "rotation_indices",
+ torch.tensor(indices["global_rot_data"], dtype=torch.long),
+ )
+ self.register_buffer(
+ "root_indices", torch.tensor(indices["global_root_pos"], dtype=torch.long)
+ )
+ self.register_buffer(
+ "contact_indices", torch.tensor(indices["foot_contacts"], dtype=torch.long)
+ )
+ self.register_buffer(
+ "parent_indices", torch.tensor(self.model_parents, dtype=torch.long)
+ )
+
+ def fk(self, qpos):
+ """Compute joint positions and rotations from joint coordinates."""
+ dofs = qpos[..., 7:]
+ quats = torch.cat(
+ (
+ torch.cos(dofs / 2)[..., None],
+ torch.sin(dofs / 2)[..., None] * self.axes,
+ ),
+ -1,
+ )
+ local = self.q2t[self.mapping] @ quat_matrix(quats)
+ rotations = [quat_matrix(qpos[..., 3:7])]
+ positions = [qpos[..., :3] + self.rest[0]]
+ for joint in range(1, 30):
+ parent = self.parents[joint]
+ positions.append(
+ positions[parent]
+ + rotate(rotations[parent], self.rest[joint] - self.rest[parent])
+ )
+ rotations.append(rotations[parent] @ local[..., joint - 1, :, :])
+ p = [rotate(self.basis, value) for value in positions]
+ r = [self.basis @ value @ self.basis.T for value in rotations]
+ model_p, model_r = ([], [])
+ for joint, robot_index in enumerate(self.reverse):
+ if robot_index >= 0:
+ model_p.append(p[robot_index])
+ model_r.append(r[robot_index])
+ else:
+ parent = self.model_parents[joint]
+ model_p.append(
+ model_p[parent]
+ + rotate(
+ model_r[parent], self.neutral[joint] - self.neutral[parent]
+ )
+ )
+ model_r.append(self.identity.expand_as(model_r[parent]))
+ return (torch.stack(model_p, -2), torch.stack(model_r, -3))
+
+ def decode(self, features):
+ """Decode motion features into the root position, rotation, and joint angles."""
+ r = six_matrix(
+ features[..., self.rotation_indices].reshape(features.shape[0], 64, 34, 6)
+ )
+ parents = torch.cat(
+ (
+ self.identity.expand_as(r[..., :1, :, :]),
+ r[..., self.parent_indices[1:], :, :],
+ ),
+ -3,
+ )
+ local = self.f2q @ (parents.transpose(-2, -1) @ r)
+ root_p = rotate(self.basis.T, features[..., self.root_indices])
+ root_r = self.basis.T @ local[..., 0, :, :] @ self.basis
+ hinge = local[..., self.mapping, :, :]
+ angles = torch.stack(
+ (
+ torch.atan2(hinge[..., 2, 1], hinge[..., 2, 2]),
+ torch.atan2(hinge[..., 0, 2], hinge[..., 0, 0]),
+ torch.atan2(hinge[..., 1, 0], hinge[..., 1, 1]),
+ ),
+ -1,
+ )
+ return (root_p, root_r, (angles * self.model_axes).sum(-1))
+
+
+class G1PlacedPosePreprocess(G1Rig):
+ """Encode placed G1 context and target poses into the model's root and pose inputs."""
+
+ def forward(
+ self,
+ context_qpos,
+ target_qpos,
+ has_global_root_values,
+ has_local_root_values,
+ has_local_poses,
+ allowed_pred_num_tokens,
+ ):
+ poses = torch.cat((context_qpos, target_qpos), 1)
+ poses = torch.cat(
+ (poses[..., :3], poses[..., [6, 3, 4, 5]], poses[..., 7:]), -1
+ )
+ p, r = self.fk(poses)
+ root = p[:, :, 0]
+ heading = torch.atan2(r[:, :, 0, 0, 2], r[:, :, 0, 2, 2])
+ global_root = torch.cat(
+ (root, heading.cos()[..., None], heading.sin()[..., None]), -1
+ )
+ windows = []
+ for start in (0, 4):
+ yaw_vel = (
+ wrap(heading[:, start + 1 : start + 4] - heading[:, start : start + 3])
+ * 30
+ )
+ velocity = (
+ root[:, start + 1 : start + 4, [0, 2]]
+ - root[:, start : start + 3, [0, 2]]
+ ) * 30
+ first = torch.cat(
+ (yaw_vel[..., None], velocity, root[:, start : start + 3, 1:2]), -1
+ )
+ last = torch.cat(
+ (
+ torch.zeros_like(first[:, :1, :3]),
+ root[:, start + 3 : start + 4, 1:2],
+ ),
+ -1,
+ )
+ windows.append(torch.cat((first, last), 1))
+ nonroot = p[:, :, 1:] - root[:, :, None] * self.horizontal_model
+ six = torch.cat((r[..., :, 0], r[..., :, 1]), -1)
+ local_poses = torch.cat(
+ (
+ nonroot.reshape(nonroot.shape[0], 8, 99),
+ six.reshape(six.shape[0], 8, 204),
+ ),
+ -1,
+ )
+ return (
+ global_root,
+ has_global_root_values,
+ torch.cat(windows, 1),
+ has_local_root_values,
+ local_poses,
+ has_local_poses,
+ allowed_pred_num_tokens,
+ )
+
+
+class G1PlacedPosePostprocess(G1Rig):
+ """Decode motion features into joint coordinates, token counts, and foot contacts."""
+
+ def forward(self, pred_global_motions, pred_num_tokens):
+ root_p, root_r, hinges = self.decode(pred_global_motions)
+ quaternion = matrix_quat(root_r)[..., [1, 2, 3, 0]]
+ return (
+ torch.cat((root_p, quaternion, hinges), -1),
+ pred_num_tokens,
+ pred_global_motions[..., self.contact_indices],
+ )
diff --git a/tools/onnx/models/layers.py b/tools/onnx/models/layers.py
new file mode 100644
index 0000000..80f4e05
--- /dev/null
+++ b/tools/onnx/models/layers.py
@@ -0,0 +1,369 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+# The residual blocks and Encoder are adapted from T2M-GPT through MotionGPT.
+# https://github.com/Mael-zys/T2M-GPT
+# https://github.com/OpenMotionLab/MotionGPT
+# Copyright 2023 tencent.
+# See tools/onnx/licenses/T2M-GPT-LICENSE.txt for the upstream Apache-2.0 license.
+# See tools/onnx/licenses/MotionGPT-LICENSE.txt for the MotionGPT MIT notice.
+# NVIDIA modified these layers, including adding token-mask handling.
+# NVIDIA additions retain the copyright and Apache-2.0 terms above.
+"Transformer embeddings and convolutional motion encoders and decoders."
+
+from __future__ import annotations
+
+import math
+
+import torch
+import torch as t
+from torch import nn
+
+
+class FCBlock(t.nn.Module):
+ """Stack of fully connected layers with LeakyReLU activations."""
+
+ def __init__(
+ self,
+ num_layers: int,
+ layer_width: int,
+ size_in: int,
+ size_out: int,
+ dropout: float = 0.0,
+ ):
+ super(FCBlock, self).__init__()
+ self.num_layers = num_layers
+ self.layer_width = layer_width
+ self.fc_layers = [t.nn.Linear(size_in, layer_width)]
+ self.relu_layers = [t.nn.LeakyReLU(inplace=True)]
+ if dropout > 0.0:
+ self.fc_layers.append(t.nn.Dropout(p=dropout))
+ self.relu_layers.append(t.nn.Identity())
+ self.fc_layers += [
+ t.nn.Linear(layer_width, layer_width) for _ in range(num_layers - 1)
+ ]
+ self.relu_layers += [
+ t.nn.LeakyReLU(inplace=True) for _ in range(num_layers - 1)
+ ]
+ self.forward_projection = t.nn.Linear(layer_width, size_out)
+ self.fc_layers = t.nn.ModuleList(self.fc_layers)
+ self.relu_layers = t.nn.ModuleList(self.relu_layers)
+
+ def forward(self, x: t.Tensor):
+ h = x
+ for layer, relu in zip(self.fc_layers, self.relu_layers):
+ h = relu(layer(h))
+ f = self.forward_projection(h)
+ return f
+
+
+def PE1d_sincos(seq_length, dim):
+ """Return a sine and cosine positional encoding of shape [seq_length, dim].
+
+ dim must be even.
+ """
+ if dim % 2 != 0:
+ raise ValueError(
+ "Cannot use sine and cosine positional encoding with an odd dim ({:d}).".format(
+ dim
+ )
+ )
+ pe = torch.zeros(seq_length, dim)
+ position = torch.arange(0, seq_length).unsqueeze(1)
+ div_term = torch.exp(
+ torch.arange(0, dim, 2, dtype=torch.float) * -(math.log(10000.0) / dim)
+ )
+ pe[:, 0::2] = torch.sin(position.float() * div_term)
+ pe[:, 1::2] = torch.cos(position.float() * div_term)
+ return pe.unsqueeze(1)
+
+
+class PositionEmbedding(nn.Module):
+ """Add a fixed sine and cosine positional encoding to a sequence."""
+
+ def __init__(self, seq_length, dim, dropout: float = 0.0, grad=False):
+ super().__init__()
+ self.embed = nn.Parameter(data=PE1d_sincos(seq_length, dim), requires_grad=grad)
+ self.dropout = nn.Dropout(p=dropout)
+
+ def forward(self, x):
+ l = x.shape[1]
+ x = x.permute(1, 0, 2) + self.embed[:l].expand(x.permute(1, 0, 2).shape)
+ x = self.dropout(x.permute(1, 0, 2))
+ return x
+
+
+class nonlinearity(nn.Module):
+ """SiLU activation, x * sigmoid(x)."""
+
+ def __init__(self):
+ super().__init__()
+
+ def forward(self, x):
+ return x * torch.sigmoid(x)
+
+
+class ResConv1DBlock(nn.Module):
+ """Residual block of two 1D convolutions with an optional norm."""
+
+ def __init__(
+ self, n_in, n_state, dilation=1, activation="silu", norm=None, dropout=None
+ ):
+ super().__init__()
+ padding = dilation
+ self.norm = norm
+ if norm == "LN":
+ self.norm1 = nn.LayerNorm(n_in)
+ self.norm2 = nn.LayerNorm(n_in)
+ elif norm == "GN":
+ self.norm1 = nn.GroupNorm(
+ num_groups=32, num_channels=n_in, eps=1e-06, affine=True
+ )
+ self.norm2 = nn.GroupNorm(
+ num_groups=32, num_channels=n_in, eps=1e-06, affine=True
+ )
+ elif norm == "BN":
+ self.norm1 = nn.BatchNorm1d(num_features=n_in, eps=1e-06, affine=True)
+ self.norm2 = nn.BatchNorm1d(num_features=n_in, eps=1e-06, affine=True)
+ else:
+ self.norm1 = nn.Identity()
+ self.norm2 = nn.Identity()
+ if activation == "relu":
+ self.activation1 = nn.ReLU()
+ self.activation2 = nn.ReLU()
+ elif activation == "silu":
+ self.activation1 = nonlinearity()
+ self.activation2 = nonlinearity()
+ elif activation == "gelu":
+ self.activation1 = nn.GELU()
+ self.activation2 = nn.GELU()
+ self.conv1 = nn.Conv1d(n_in, n_state, 3, 1, padding, dilation)
+ self.conv2 = nn.Conv1d(n_state, n_in, 1, 1, 0)
+
+ def forward(self, x: torch.Tensor, token_mask: torch.Tensor = None):
+ x = x * token_mask[:, None, :] if token_mask is not None else x
+ x_orig = x
+ if self.norm == "LN":
+ x = self.norm1(x.transpose(-2, -1))
+ x = self.activation1(x.transpose(-2, -1))
+ else:
+ x = self.norm1(x)
+ x = self.activation1(x)
+ x = x * token_mask[:, None, :] if token_mask is not None else x
+ x = self.conv1(x)
+ if self.norm == "LN":
+ x = self.norm2(x.transpose(-2, -1))
+ x = self.activation2(x.transpose(-2, -1))
+ else:
+ x = self.norm2(x)
+ x = self.activation2(x)
+ x = x * token_mask[:, None, :] if token_mask is not None else x
+ x = self.conv2(x)
+ x = x + x_orig
+ x = x * token_mask[:, None, :] if token_mask is not None else x
+ return x
+
+
+class Resnet1D(nn.Module):
+ """Stack of residual 1D convolution blocks with growing dilation."""
+
+ def __init__(
+ self,
+ n_in,
+ n_depth,
+ dilation_growth_rate=1,
+ reverse_dilation=True,
+ activation="relu",
+ norm=None,
+ ):
+ super().__init__()
+ blocks = [
+ ResConv1DBlock(
+ n_in,
+ n_in,
+ dilation=dilation_growth_rate**depth,
+ activation=activation,
+ norm=norm,
+ )
+ for depth in range(n_depth)
+ ]
+ if reverse_dilation:
+ blocks = blocks[::-1]
+ self.model = nn.Sequential(*blocks)
+
+ def forward(self, x: torch.Tensor, token_mask: torch.Tensor = None):
+ for block in self.model:
+ x = block(x, token_mask)
+ return x
+
+
+class Encoder(nn.Module):
+ """Convolutional encoder that downsamples motion features in time."""
+
+ def __init__(
+ self,
+ input_emb_width,
+ output_emb_width=512,
+ down_t=3,
+ stride_t=2,
+ width=512,
+ depth=3,
+ dilation_growth_rate=3,
+ activation="relu",
+ norm=None,
+ ):
+ super().__init__()
+ blocks = []
+ filter_t, pad_t = (stride_t * 2, stride_t // 2)
+ blocks.append(nn.Conv1d(input_emb_width, width, 3, 1, 1))
+ blocks.append(nn.ReLU())
+ input_dim = width
+ for i in range(down_t):
+ input_dim = width
+ block = nn.Sequential(
+ nn.Conv1d(input_dim, width, filter_t, stride_t, pad_t),
+ Resnet1D(
+ width, depth, dilation_growth_rate, activation=activation, norm=norm
+ ),
+ )
+ blocks.append(block)
+ blocks.append(nn.Conv1d(width, output_emb_width, 3, 1, 1))
+ self.model = nn.Sequential(*blocks)
+
+ def forward(self, x):
+ return self.model(x)
+
+
+class DoubleCondDecoder(nn.Module):
+ """Convolutional decoder that upsamples motion tokens into motion features.
+
+ It is conditioned on the target poses and on external features.
+ """
+
+ def __init__(
+ self,
+ input_emb_width: int = 3,
+ output_emb_width: int = 512,
+ down_t: int = 3,
+ width: int = 512,
+ depth: int = 3,
+ dilation_growth_rate: int = 3,
+ activation: str = "relu",
+ norm: str = None,
+ target_cond_dim: int = -1,
+ external_cond_dim: int = -1,
+ cond_fusion_last_layer=False,
+ ):
+ super().__init__()
+ self._down_t, self._width, self._input_emb_width, self._output_emb_width = (
+ down_t,
+ width,
+ input_emb_width,
+ output_emb_width,
+ )
+ self._target_cond_dim, self._external_cond_dim = (
+ target_cond_dim,
+ external_cond_dim,
+ )
+ self._HAS_EXTERNAL_COND, self._HAS_TARGET_COND = (
+ external_cond_dim > 0,
+ target_cond_dim > 0,
+ )
+ self._COND_FUSION_LAST_LAYER = cond_fusion_last_layer
+ blocks = []
+ blocks.append(nn.Conv1d(output_emb_width, width, 3, 1, 1))
+ blocks.append(nn.ReLU())
+ for i in range(down_t):
+ out_dim = width
+ block = nn.Sequential(
+ Resnet1D(
+ width,
+ depth,
+ dilation_growth_rate,
+ reverse_dilation=True,
+ activation=activation,
+ norm=norm,
+ ),
+ nn.Upsample(scale_factor=2, mode="nearest"),
+ nn.Conv1d(width, out_dim, 3, 1, 1),
+ )
+ blocks.append(block)
+ blocks.append(nn.Conv1d(width, width, 3, 1, 1))
+ blocks.append(nn.ReLU())
+ blocks.append(nn.Conv1d(width, input_emb_width, 3, 1, 1))
+ self.model = nn.Sequential(*blocks)
+ if self._HAS_EXTERNAL_COND:
+ external_cond_blocks = []
+ for i in range(down_t + (1 if self._COND_FUSION_LAST_LAYER else 0)):
+ cond_feat_dim = 2 ** (down_t - i) * self._external_cond_dim
+ external_cond_blocks.append(nn.Linear(cond_feat_dim + width, width))
+ external_cond_blocks.append(nn.ReLU())
+ self.external_cond_blocks = nn.ModuleList(external_cond_blocks)
+ if self._HAS_TARGET_COND:
+ target_cond_blocks = []
+ assert width % 2**down_t == 0, (
+ "width % (2 ** down_t) needs to 0 so that hidden can be split for each frame in earlier layers."
+ )
+ for i in range(down_t + (1 if self._COND_FUSION_LAST_LAYER else 0)):
+ target_cond_blocks.append(
+ nn.Linear(self._target_cond_dim, int(width / 2 ** (down_t - i)))
+ )
+ target_cond_blocks.append(nn.ReLU())
+ self.target_cond_blocks = nn.ModuleList(target_cond_blocks)
+
+ def forward(
+ self,
+ x: torch.Tensor,
+ external_cond: torch.Tensor = None,
+ target_cond: torch.Tensor = None,
+ has_target_cond: torch.Tensor = None,
+ token_mask: torch.Tensor = None,
+ ):
+ batch_size = x.shape[0]
+ x = x * token_mask[:, None, :] if token_mask is not None else x
+ h = self.model[0](x)
+ h = self.model[1](h)
+ for i in range(self._down_t + (1 if self._COND_FUSION_LAST_LAYER else 0)):
+ numFrames_per_position = 2 ** (self._down_t - i)
+ numPositions = h.shape[-1]
+ timesteps = numPositions * numFrames_per_position
+ if (
+ not self._HAS_TARGET_COND
+ or target_cond is None
+ or has_target_cond is None
+ ):
+ pass
+ else:
+ h_target_cond = self.target_cond_blocks[i * 2](target_cond)
+ h_target_cond = self.target_cond_blocks[i * 2 + 1](h_target_cond)
+ h = h.transpose(1, 2)
+ h = h.reshape(
+ [
+ batch_size,
+ numPositions * numFrames_per_position,
+ self._width // numFrames_per_position,
+ ]
+ )
+ h = torch.where(has_target_cond[:, :, None], h_target_cond, h)
+ h = h.reshape([batch_size, numPositions, self._width]).transpose(1, 2)
+ if self._HAS_EXTERNAL_COND:
+ assert external_cond is not None and external_cond.shape[1] == timesteps
+ h_cond = external_cond.reshape([batch_size, numPositions, -1])
+ h = torch.cat([h.transpose(1, 2), h_cond], dim=-1)
+ h = self.external_cond_blocks[i * 2](h).transpose(1, 2)
+ h = self.external_cond_blocks[i * 2 + 1](h)
+ if i == self._down_t:
+ continue
+ h = self.model[i + 2][0](h, token_mask)
+ h = self.model[i + 2][1](h)
+ token_mask = (
+ token_mask.repeat_interleave(2, 1) if token_mask is not None else None
+ )
+ h = h * token_mask[:, None, :] if token_mask is not None else h
+ h = self.model[i + 2][2](h)
+ h = h * token_mask[:, None, :] if token_mask is not None else h
+ h = self.model[2 + self._down_t](h)
+ h = self.model[2 + self._down_t + 1](h)
+ h = h * token_mask[:, None, :] if token_mask is not None else h
+ h = self.model[2 + self._down_t + 2](h)
+ h = h * token_mask[:, None, :] if token_mask is not None else h
+ return h
diff --git a/tools/onnx/models/quantizer.py b/tools/onnx/models/quantizer.py
new file mode 100644
index 0000000..6064028
--- /dev/null
+++ b/tools/onnx/models/quantizer.py
@@ -0,0 +1,176 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Shared codebook lookup for the SOMA and G1 inference models."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+import torch
+from torch import nn
+
+
+# The original MotionBricks quantizer credits MotionGPT.
+# https://github.com/OpenMotionLab/MotionGPT
+# See tools/onnx/licenses/MotionGPT-LICENSE.txt for its MIT notice.
+# The original MotionBricks quantizer used vector-quantize-pytorch.
+# https://github.com/lucidrains/vector-quantize-pytorch
+# See tools/onnx/licenses/vector-quantize-pytorch-LICENSE.txt for its MIT notice.
+# NVIDIA additions retain the copyright and Apache-2.0 terms above.
+class MultiHeadCodebook(nn.Module):
+ """Load checkpoint codebooks and look up predicted tokens using PyTorch."""
+
+ def __init__(self, heads, entries, width):
+ super().__init__()
+ self._codebook = nn.Module()
+ # Preserve the checkpoint structure for strict loading. Inference only
+ # reads embed, and the other buffers are statistics recorded during training.
+ self._codebook.register_buffer("initted", torch.zeros(1, dtype=torch.bool))
+ self._codebook.register_buffer("cluster_size", torch.zeros(heads, entries))
+ self._codebook.register_buffer("embed_avg", torch.zeros(heads, entries, width))
+ self._codebook.register_buffer("embed", torch.zeros(heads, entries, width))
+
+ @property
+ def codebook(self):
+ """Codebook vectors, laid out as [head, entry, width]."""
+ return self._codebook.embed
+
+ def get_codes_from_indices(self, indices):
+ """Look up each head's code vector, and concatenate the heads."""
+ batch, frames, _ = indices.shape
+ index = indices.transpose(1, 2).unsqueeze(-1)
+ index = index.expand(-1, -1, -1, self.codebook.shape[-1])
+ codebook = self.codebook.unsqueeze(0).expand(batch, -1, -1, -1)
+ codes = codebook.gather(2, index)
+ return codes.transpose(1, 2).reshape(batch, frames, -1)
+
+
+class QuantizeEMAResetMultiHead(nn.Module):
+ """Multi-head vector quantizer, used here only to look up codes."""
+
+ def __init__(self, nb_code: int, code_dim: int, num_heads: int):
+ super().__init__()
+ self.nb_code = nb_code
+ self.code_dim = code_dim
+ self.num_heads = num_heads
+ assert self.code_dim % self.num_heads == 0, (
+ "code dim cannot be divided by the number of heads."
+ )
+ self.nb_code_per_head = int(
+ round(2 ** (np.log2(self.nb_code) / self.num_heads))
+ )
+ assert self.nb_code_per_head**self.num_heads == self.nb_code, (
+ "the specified number of code is not compatible with the number of heads."
+ )
+ self.vq = MultiHeadCodebook(
+ self.num_heads, self.nb_code_per_head, self.code_dim // self.num_heads
+ )
+
+ def from_overall_indices_to_mh_indices(self, overall_indices):
+ """Split overall code indices into one index per head."""
+ exponential_mul = self.nb_code_per_head ** torch.arange(0, self.num_heads)[
+ None, None, :
+ ].to(overall_indices.device)
+ mh_indices = (
+ overall_indices[:, :, None]
+ % (exponential_mul * self.nb_code_per_head)
+ // exponential_mul
+ )
+ return mh_indices
+
+ def dequantize(self, code_idx, use_overall_indices=True):
+ """Return the code vectors for token indices.
+
+ With use_overall_indices, overall indices are split per head first.
+ """
+ if use_overall_indices:
+ mh_indices = self.from_overall_indices_to_mh_indices(code_idx)
+ else:
+ mh_indices = code_idx
+ batch_size, numToken = (code_idx.shape[0], code_idx.shape[1])
+ x = self.vq.get_codes_from_indices(mh_indices).view([batch_size, numToken, -1])
+ return x
+
+
+@dataclass(frozen=True)
+class MultiHeadVQDimensions:
+ """Head count, codes per head, and code width per head of a multi-head quantizer."""
+
+ num_heads: int
+ codes_per_head: int
+ code_dim_per_head: int
+
+ @property
+ def combined_code_space(self) -> int:
+ """Number of distinct overall codes, codes_per_head ** num_heads."""
+ return self.codes_per_head**self.num_heads
+
+ @property
+ def latent_dim(self) -> int:
+ """Width of a full code vector across all heads."""
+ return self.code_dim_per_head * self.num_heads
+
+
+def _exact_integer_root(value: int, degree: int, field_name: str) -> int:
+ candidate = int(round(value ** (1.0 / degree)))
+ for possible in range(max(1, candidate - 1), candidate + 2):
+ if possible**degree == value:
+ return possible
+ raise ValueError(
+ f"{field_name}={value} is not an exact {degree}-head product code space."
+ )
+
+
+def resolve_multihead_vq_dimensions(
+ *,
+ num_heads: int,
+ codes_per_head: Optional[int] = None,
+ code_dim_per_head: Optional[int] = None,
+ nb_code: Optional[int] = None,
+ code_dim: Optional[int] = None,
+) -> MultiHeadVQDimensions:
+ """Resolve and check a multi-head quantizer's dimensions from checkpoint settings.
+
+ Missing values come from the others. Conflicting values raise ValueError.
+ """
+ if not isinstance(num_heads, int) or num_heads <= 0:
+ raise ValueError(f"num_heads must be a positive integer, got {num_heads!r}.")
+ if codes_per_head is None:
+ if nb_code is None:
+ raise ValueError("codes_per_head is required when nb_code is not provided.")
+ codes_per_head = _exact_integer_root(nb_code, num_heads, "nb_code")
+ elif not isinstance(codes_per_head, int) or codes_per_head <= 0:
+ raise ValueError(
+ f"codes_per_head must be a positive integer, got {codes_per_head!r}."
+ )
+ combined_code_space = codes_per_head**num_heads
+ if nb_code is not None and nb_code != combined_code_space:
+ raise ValueError(
+ f"nb_code={nb_code} conflicts with {num_heads} heads x {codes_per_head} codes "
+ f"(expected {combined_code_space})."
+ )
+ if code_dim_per_head is None:
+ if code_dim is None:
+ raise ValueError(
+ "code_dim_per_head is required when code_dim is not provided."
+ )
+ if code_dim % num_heads:
+ raise ValueError(
+ f"code_dim={code_dim} must be divisible by num_heads={num_heads}."
+ )
+ code_dim_per_head = code_dim // num_heads
+ elif not isinstance(code_dim_per_head, int) or code_dim_per_head <= 0:
+ raise ValueError(
+ f"code_dim_per_head must be a positive integer, got {code_dim_per_head!r}."
+ )
+ latent_dim = code_dim_per_head * num_heads
+ if code_dim is not None and code_dim != latent_dim:
+ raise ValueError(
+ f"code_dim={code_dim} conflicts with {num_heads} heads x {code_dim_per_head} dimensions "
+ f"(expected {latent_dim})."
+ )
+ return MultiHeadVQDimensions(
+ num_heads=num_heads,
+ codes_per_head=codes_per_head,
+ code_dim_per_head=code_dim_per_head,
+ )
diff --git a/tools/onnx/models/representation.py b/tools/onnx/models/representation.py
new file mode 100644
index 0000000..0d0befa
--- /dev/null
+++ b/tools/onnx/models/representation.py
@@ -0,0 +1,591 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Normalization and conversion between local and global motion features."
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Optional, Tuple
+
+import numpy as np
+import torch
+
+
+def quat_conjugate(a):
+ """Return the conjugates of WXYZ quaternions."""
+ shape = a.shape
+ a = a.reshape(-1, 4)
+ return torch.cat((a[:, 0:1], -a[:, 1:]), dim=-1).view(shape)
+
+
+def quat_apply(a, b):
+ """Rotate vectors by WXYZ quaternions."""
+ shape = b.shape
+ a = a.reshape(-1, 4)
+ b = b.reshape(-1, 3)
+ xyz = a[:, 1:].clone()
+ t = xyz.cross(b, dim=-1) * 2
+ return (b + a[:, 0:1].clone() * t + xyz.cross(t, dim=-1)).view(shape)
+
+
+def diff_angles(angles, fps: float):
+ """Return the angular velocity between neighboring angles, by the shortest turn."""
+ cos = torch.cos(angles)
+ sin = torch.sin(angles)
+ cos_diff = cos[..., 1:] * cos[..., :-1] + sin[..., 1:] * sin[..., :-1]
+ sin_diff = sin[..., 1:] * cos[..., :-1] - cos[..., 1:] * sin[..., :-1]
+ angles_diff = fps * torch.arctan2(sin_diff, cos_diff)
+ return angles_diff
+
+
+class Stats(torch.nn.Module):
+ """Mean and standard deviation used to normalize motion features."""
+
+ def __init__(self, eps=1e-05, legacy=False):
+ super().__init__()
+ self.legacy = legacy
+ self.eps = eps
+
+ def register_from_tensors(self, mean: torch.Tensor, std: torch.Tensor):
+ """Store the mean and standard deviation as buffers."""
+ self.register_buffer("mean", mean, persistent=False)
+ self.register_buffer("std", std, persistent=False)
+
+ def normalize(self, data: torch.Tensor, index=None) -> torch.Tensor:
+ """Normalize data, optionally for a subset of feature indices."""
+ mean = self.mean.to(device=data.device, dtype=data.dtype)
+ std = self.std.to(device=data.device, dtype=data.dtype)
+ if index is not None:
+ mean = mean[..., index]
+ std = std[..., index]
+ if self.legacy:
+ return (data - mean) / torch.clip(std, 0.001)
+ return (data - mean) / torch.sqrt(std**2 + self.eps)
+
+ def unnormalize(self, data: torch.Tensor, index=None) -> torch.Tensor:
+ """Undo normalize()."""
+ mean = self.mean.to(device=data.device, dtype=data.dtype)
+ std = self.std.to(device=data.device, dtype=data.dtype)
+ if index is not None:
+ mean = mean[..., index]
+ std = std[..., index]
+ if self.legacy:
+ return data * torch.clip(std, 0.001) + mean
+ return data * torch.sqrt(std**2 + self.eps) + mean
+
+ def is_loaded(self):
+ """Return whether the statistics are set."""
+ return hasattr(self, "mean")
+
+ def get_dim(self):
+ """Return the number of features the statistics cover."""
+ return self.mean.shape[0]
+
+
+class MotionRepBase(torch.nn.Module):
+ """Base for motion feature layouts, with their sample rate, skeleton, and statistics."""
+
+ def __init__(
+ self,
+ fps: float,
+ skeleton: SimpleNamespace,
+ name: str,
+ stats: Optional[Stats] = None,
+ ):
+ super().__init__()
+ self.stats = stats
+ self.fps = fps
+ self.skeleton = skeleton
+ self.name = name
+ self.num_joints = self.nbjoints = skeleton.nbjoints
+
+ def normalize(self, motion: torch.Tensor, index=None) -> torch.Tensor:
+ """Normalize motion features with the layout's statistics."""
+ return self.stats.normalize(motion, index=index)
+
+ def unnormalize(self, motion: torch.Tensor, index=None) -> torch.Tensor:
+ """Undo normalize()."""
+ return self.stats.unnormalize(motion, index=index)
+
+
+class SeparatedRootLocalBody(MotionRepBase):
+ """Motion features split into a root part and a body part."""
+
+ def __init__(
+ self,
+ fps: float,
+ skeleton: SimpleNamespace,
+ name: str,
+ stats: Optional[Stats] = None,
+ ):
+ super().__init__(fps, skeleton, name, stats)
+ self.name = name
+ [*self.root_keys], [*self.root_ps] = zip(*self.root_keys_dim.items())
+ [*self.body_keys], [*self.body_ps] = zip(*self.body_keys_dim.items())
+ self.keys_dim = self.root_keys_dim | self.body_keys_dim
+ self.keys = self.root_keys + self.body_keys
+ self.ps = self.root_ps + self.body_ps
+ self.motion_rep_dim = sum((sum(x) if x else 1 for x in self.ps))
+ self.motion_root_dim = sum((sum(x) if x else 1 for x in self.root_ps))
+ self.motion_body_dim = sum((sum(x) if x else 1 for x in self.body_ps))
+ if stats is not None and stats.is_loaded():
+ assert self.motion_rep_dim == stats.get_dim()
+ self.motion_rep_subset_dim = self.motion_rep_dim
+ self.indices = {}
+ idx = 0
+ for key, x in zip(self.keys, self.ps):
+ dim = sum(x) if x else 1
+ self.indices[key] = np.arange(idx, idx + dim)
+ idx += dim
+ self.indices["all"] = np.arange(0, self.motion_rep_dim)
+ self.indices["root"] = np.arange(0, self.motion_root_dim)
+ self.indices["body"] = np.arange(
+ self.motion_root_dim, self.motion_root_dim + self.motion_body_dim
+ )
+ self.removed_heading = self.compute_kwargs.get("removing_heading", True)
+ self.using_smooth_root = self.compute_kwargs.get("using_smooth_root", False)
+ self.extra_skel = self.compute_kwargs.get("extra_skel", False)
+ if self.extra_skel:
+ assert repr(self.skeleton.__class__).split("'")[1].endswith("Extra"), (
+ "The skeleton should be an extra skeleton"
+ )
+
+ def slice(self, motion, key: str):
+ """Return the features stored under key."""
+ assert key in self.indices
+ assert motion.shape[-1] == self.motion_rep_dim
+ return motion[..., self.indices[key]]
+
+ def detect_all_body_or_root(self, motion: torch.Tensor):
+ """Return which part motion holds: "all", "root", or "body".
+
+ The width of the last axis decides.
+ """
+ dim = motion.shape[-1]
+ if dim == self.motion_rep_dim:
+ return "all"
+ elif dim == self.motion_root_dim:
+ return "root"
+ elif dim == self.motion_body_dim:
+ return "body"
+ else:
+ raise ValueError(f"Unrecognized input dim: {dim}.")
+
+ def normalize(self, motion: torch.Tensor, index=None) -> torch.Tensor:
+ """Normalize motion features.
+
+ Without index, the part they cover decides which statistics apply.
+ """
+ if index is None:
+ index = self.indices[self.detect_all_body_or_root(motion)]
+ return self.stats.normalize(motion, index=index)
+
+ def unnormalize(self, motion: torch.Tensor, index=None) -> torch.Tensor:
+ """Undo normalize()."""
+ if index is None:
+ index = self.indices[self.detect_all_body_or_root(motion)]
+ return self.stats.unnormalize(motion, index=index)
+
+ def extract_root(self, motion: torch.Tensor) -> torch.Tensor:
+ """Return the root features of motion."""
+ type = self.detect_all_body_or_root(motion)
+ if type == "root":
+ return motion
+ elif type == "all":
+ return self.slice(motion, "root")
+ else:
+ raise ValueError("Cannot compute root info without root data.")
+
+ def extract_body(self, motion: torch.Tensor) -> torch.Tensor:
+ """Return the body features of motion."""
+ type = self.detect_all_body_or_root(motion)
+ if type == "body":
+ return motion
+ elif type == "all":
+ return self.slice(motion, "body")
+ else:
+ raise ValueError("Cannot compute body info without body data.")
+
+ def concat_root_body(self, root_data: torch.Tensor, body_data: torch.Tensor):
+ """Join root and body features into full motion features."""
+ assert root_data.shape[-1] == self.motion_root_dim
+ assert body_data.shape[-1] == self.motion_body_dim
+ motion_data = torch.cat([root_data, body_data], axis=-1)
+ assert motion_data.shape[-1] == self.motion_rep_dim
+ return motion_data
+
+
+class GlobalRootLocalBody(SeparatedRootLocalBody):
+ """Motion features with the root position and heading given in model space."""
+
+ dual_class = None
+
+ def __init__(
+ self,
+ fps: float,
+ skeleton: SimpleNamespace,
+ name: str,
+ stats: Optional[Stats] = None,
+ ):
+ self.root_keys_dim = {"global_root_pos": [3], "global_root_heading": [2]}
+ self.body_keys_dim = self.get_body_keys_dim(skeleton.nbjoints)
+ if self.dual_class is not None and self.dual_class._name_ in name:
+ super().__init__(fps, skeleton, name, stats=None)
+ self.dual_rep = self.dual_class(fps, skeleton, name, stats=stats)
+ self.dual_rep_mode = "global"
+ self.stats = self.dual_rep.global_motion_rep.stats
+ else:
+ self.dual_rep = None
+ super().__init__(fps, skeleton, name, stats)
+ self.indices["global_root_pos_2d"] = self.indices["global_root_pos"][[0, 2]]
+ self.root_mode = "global"
+
+ def compute_root_pos_and_rot(
+ self, motion: torch.Tensor, return_quat: bool = True, return_angle: bool = False
+ ) -> Tuple[torch.Tensor, torch.Tensor]:
+ """Return the root positions and rotations, as quaternions or angles."""
+ root_motion = self.extract_root(motion)
+ r_pos = root_motion[..., :3]
+ rot_cos = root_motion[..., 3]
+ rot_sin = root_motion[..., 4]
+ r_rot_ang = torch.atan2(rot_sin, rot_cos)
+ r_rot_quat = torch.stack(
+ [
+ torch.cos(r_rot_ang / 2),
+ torch.zeros_like(rot_cos),
+ torch.sin(r_rot_ang / 2),
+ torch.zeros_like(rot_cos),
+ ],
+ dim=-1,
+ )
+ if return_quat and (not return_angle):
+ return (r_pos, r_rot_quat)
+ if not return_quat and return_angle:
+ return (r_pos, r_rot_ang)
+ if return_quat and return_angle:
+ return (r_pos, r_rot_quat, r_rot_ang)
+ if not return_quat and (not return_angle):
+ return r_pos
+
+ def compute_root_rep_from_root_pos_and_rot(
+ self,
+ r_pos: torch.Tensor,
+ r_rot_quat: torch.Tensor,
+ lengths: Optional[torch.Tensor] = None,
+ ) -> torch.Tensor:
+ """Build root features from root positions and rotations."""
+ root_rot_angles = torch.arctan2(r_rot_quat[..., 2], r_rot_quat[..., 0]) * 2
+ root_motion = torch.cat(
+ [
+ r_pos,
+ torch.cos(root_rot_angles)[..., None],
+ torch.sin(root_rot_angles)[..., None],
+ ],
+ axis=-1,
+ )
+ return root_motion
+
+
+class LocalRootLocalBody(SeparatedRootLocalBody):
+ """Motion features with the root given as velocities and height."""
+
+ dual_class = None
+
+ def __init__(
+ self,
+ fps: float,
+ skeleton: SimpleNamespace,
+ name: str,
+ stats: Optional[Stats] = None,
+ ):
+ self.nfeats_vel = 3 if self.compute_kwargs["local_root_vel_with_y"] else 2
+ self.root_keys_dim = {
+ "local_root_rot_vel": [],
+ "local_root_vel": [self.nfeats_vel],
+ "global_root_y": [],
+ }
+ self.body_keys_dim = self.get_body_keys_dim(skeleton.nbjoints)
+ if self.dual_class is not None and self.dual_class._name_ in name:
+ super().__init__(fps, skeleton, name, stats=None)
+ self.dual_rep = self.dual_class(fps, skeleton, name, stats=stats)
+ self.dual_rep_mode = "local"
+ self.stats = self.dual_rep.local_motion_rep.stats
+ else:
+ self.dual_rep = None
+ super().__init__(fps, skeleton, name, stats)
+ self.root_mode = "local"
+
+ def compute_root_pos_and_rot(
+ self, motion: torch.Tensor
+ ) -> Tuple[torch.Tensor, torch.Tensor]:
+ """Integrate root velocities into root positions and rotations."""
+ root_motion = self.extract_root(motion)
+ device = root_motion.device
+ batch, nbframes = root_motion.shape[:2]
+ root_rot_vel_angles = root_motion[..., 0]
+ root_local_vel = root_motion[..., 1 : 1 + self.nfeats_vel]
+ root_y_pos = root_motion[..., 1 + self.nfeats_vel]
+ root_rot_vel_angles = root_rot_vel_angles / self.fps
+ root_local_vel = root_local_vel / self.fps
+ r_rot_ang = torch.zeros_like(root_rot_vel_angles, device=device)
+ r_rot_ang[..., 1:] = root_rot_vel_angles[..., :-1]
+ r_rot_ang = torch.cumsum(r_rot_ang, dim=-1)
+ r_rot_quat = torch.zeros((batch, nbframes, 4), device=device)
+ r_rot_quat[..., 0] = torch.cos(r_rot_ang / 2)
+ r_rot_quat[..., 2] = torch.sin(r_rot_ang / 2)
+ r_pos = torch.zeros((batch, nbframes, 3), device=device)
+ r_pos[..., 1:, [0, 2]] = root_local_vel[..., :-1, :]
+ removed_heading = self.compute_kwargs.get("removing_heading", True)
+ if removed_heading:
+ r_pos[..., 1:, :] = quat_apply(r_rot_quat[..., :-1, :], r_pos[..., 1:, :])
+ r_pos = torch.cumsum(r_pos, dim=-2)
+ r_pos[..., 1] = root_y_pos
+ return (r_pos, r_rot_quat)
+
+
+class DualRootLocalBody(SeparatedRootLocalBody):
+ """Pair of the global and local feature layouts, with conversion between them."""
+
+ def __init__(
+ self,
+ fps: float,
+ skeleton: SimpleNamespace,
+ name: str,
+ *,
+ global_class: GlobalRootLocalBody,
+ local_class: LocalRootLocalBody,
+ stats: Optional[Stats] = None,
+ ):
+ global_motion_rep = global_class(fps=fps, skeleton=skeleton, name="global")
+ local_motion_rep = local_class(fps=fps, skeleton=skeleton, name="local")
+ assert (
+ global_motion_rep.default_joint_positions_from
+ == local_motion_rep.default_joint_positions_from
+ )
+ self.default_joint_positions_from = (
+ global_motion_rep.default_joint_positions_from
+ )
+ self.root_keys_dim = (
+ global_motion_rep.root_keys_dim | local_motion_rep.root_keys_dim
+ )
+ assert len(self.root_keys_dim) == len(global_motion_rep.root_keys_dim) + len(
+ local_motion_rep.root_keys_dim
+ )
+ assert global_motion_rep.body_keys_dim == local_motion_rep.body_keys_dim
+ self.body_keys_dim = global_motion_rep.body_keys_dim
+ super().__init__(fps, skeleton, name, stats)
+ self.global_motion_rep = global_motion_rep
+ self.local_motion_rep = local_motion_rep
+ self.indices["global_root"] = np.arange(0, global_motion_rep.motion_root_dim)
+ self.indices["local_root"] = np.arange(
+ global_motion_rep.motion_root_dim, self.motion_root_dim
+ )
+ self.indices["global_rep"] = np.concatenate(
+ (self.indices["global_root"], self.indices["body"])
+ )
+ self.indices["local_rep"] = np.concatenate(
+ (self.indices["local_root"], self.indices["body"])
+ )
+ assert global_motion_rep.compute_kwargs == local_motion_rep.compute_kwargs
+ self.compute_kwargs = global_motion_rep.compute_kwargs
+ self.motion_rep_subset_dim = self.global_motion_rep.motion_rep_dim
+ self.dual_rep = None
+ if stats is not None and stats.is_loaded():
+ global_mean = stats.mean[self.indices["global_rep"]]
+ global_std = stats.std[self.indices["global_rep"]]
+ self.global_motion_rep.stats = Stats(eps=stats.eps, legacy=stats.legacy)
+ self.global_motion_rep.stats.register_from_tensors(global_mean, global_std)
+ local_mean = stats.mean[self.indices["local_rep"]]
+ local_std = stats.std[self.indices["local_rep"]]
+ self.local_motion_rep.stats = Stats(eps=stats.eps, legacy=stats.legacy)
+ self.local_motion_rep.stats.register_from_tensors(local_mean, local_std)
+
+ def _one_subset_to_the_other(
+ self,
+ features: torch.Tensor,
+ is_normalized: bool,
+ to_normalize: bool,
+ mode: str,
+ lengths: Optional[torch.Tensor] = None,
+ ) -> torch.Tensor:
+ if mode == "local_to_global":
+ motion_rep_from = self.local_motion_rep
+ motion_rep_to = self.global_motion_rep
+ elif mode == "global_to_local":
+ motion_rep_from = self.global_motion_rep
+ motion_rep_to = self.local_motion_rep
+ else:
+ raise ValueError("Unrecognized mode.")
+ from_rep, to_rep = mode.split("_to_")
+ data_type = motion_rep_from.detect_all_body_or_root(features)
+ if data_type == "all":
+ body_motion = motion_rep_from.extract_body(features)
+ else:
+ assert data_type == "root"
+ root_motion = motion_rep_from.extract_root(features)
+ if is_normalized:
+ root_motion = self.unnormalize(
+ root_motion, index=self.indices[f"{from_rep}_root"]
+ )
+ if not to_normalize and data_type == "all":
+ body_motion = self.unnormalize(body_motion, index=self.indices["body"])
+ r_pos, r_rot_quat = motion_rep_from.compute_root_pos_and_rot(root_motion)
+ new_root_motion = motion_rep_to.compute_root_rep_from_root_pos_and_rot(
+ r_pos, r_rot_quat, lengths
+ )
+ if to_normalize:
+ new_root_motion = self.normalize(
+ new_root_motion, index=self.indices[f"{to_rep}_root"]
+ )
+ if not is_normalized and data_type == "all":
+ body_motion = self.normalize(body_motion, index=self.indices["body"])
+ if data_type == "root":
+ assert new_root_motion.shape[-1] == motion_rep_to.motion_root_dim
+ return new_root_motion
+ new_features = motion_rep_to.concat_root_body(new_root_motion, body_motion)
+ assert new_features.shape[-1] == motion_rep_to.motion_rep_dim
+ return new_features
+
+ def global_to_local(
+ self,
+ features: torch.Tensor,
+ is_normalized: bool,
+ to_normalize: bool,
+ lengths: Optional[torch.Tensor] = None,
+ ) -> torch.Tensor:
+ """Convert features from the global root layout to the local one."""
+ return self._one_subset_to_the_other(
+ features,
+ is_normalized=is_normalized,
+ to_normalize=to_normalize,
+ mode="global_to_local",
+ lengths=lengths,
+ )
+
+ def local_to_global(
+ self,
+ features: torch.Tensor,
+ is_normalized: bool,
+ to_normalize: bool,
+ lengths: Optional[torch.Tensor] = None,
+ ) -> torch.Tensor:
+ """Convert features from the local root layout to the global one."""
+ return self._one_subset_to_the_other(
+ features,
+ is_normalized=is_normalized,
+ to_normalize=to_normalize,
+ mode="local_to_global",
+ lengths=lengths,
+ )
+
+
+COMPUTE_KWARGS = {
+ "local_vel_without_root": False,
+ "local_root_vel_with_y": False,
+ "compute_heading_method": "hips_pos",
+ "removing_heading": False,
+}
+DEFAULT_JOINT_POSITIONS_FROM = "global_rot_data"
+
+
+class DualRootGlobalJoints(DualRootLocalBody):
+ """Dual layout whose body features hold joint positions and rotations in model space."""
+
+ _name_ = "dual_root_global_joints"
+ compute_kwargs = COMPUTE_KWARGS
+ default_joint_positions_from = DEFAULT_JOINT_POSITIONS_FROM
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(
+ *args,
+ global_class=GlobalRootGlobalJoints,
+ local_class=LocalRootGlobalJoints,
+ **kwargs,
+ )
+
+
+def get_body_keys_dim(self, nbjoints: int):
+ """Return the size of each body feature.
+
+ The features are joint positions, 6D rotations, velocities, and foot contacts.
+ """
+ return {
+ "ric_data": [(nbjoints - 1) * 3],
+ "global_rot_data": [nbjoints * 6],
+ "local_vel": [nbjoints * 3],
+ "foot_contacts": [4],
+ }
+
+
+class GlobalRootGlobalJoints(GlobalRootLocalBody):
+ """Global root layout with joint positions and rotations in model space."""
+
+ dual_class = DualRootGlobalJoints
+ get_body_keys_dim = get_body_keys_dim
+ compute_kwargs = COMPUTE_KWARGS
+ default_joint_positions_from = DEFAULT_JOINT_POSITIONS_FROM
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+
+class LocalRootGlobalJoints(LocalRootLocalBody):
+ """Local root layout with joint positions and rotations in model space."""
+
+ dual_class = DualRootGlobalJoints
+ get_body_keys_dim = get_body_keys_dim
+ compute_kwargs = COMPUTE_KWARGS
+ default_joint_positions_from = DEFAULT_JOINT_POSITIONS_FROM
+
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+
+
+def global_root_to_local_onnx_compatible(
+ normalized_global_root: torch.Tensor, dual_motion_rep, lengths: torch.Tensor
+) -> torch.Tensor:
+ """Convert normalized global root features to local ones, with ONNX operations only.
+
+ Velocities at each request's last frame repeat the frame before it.
+ """
+ global_motion_rep = dual_motion_rep.global_motion_rep
+ local_motion_rep = dual_motion_rep.local_motion_rep
+ if local_motion_rep.compute_kwargs.get("local_root_vel_with_y", False):
+ raise NotImplementedError(
+ "Dynamic ONNX root conversion does not support local Y velocity."
+ )
+ global_root = dual_motion_rep.unnormalize(
+ normalized_global_root, index=dual_motion_rep.indices["global_root"]
+ )
+ root_positions, root_rotations = global_motion_rep.compute_root_pos_and_rot(
+ global_root
+ )
+ root_angles = torch.atan2(root_rotations[..., 2], root_rotations[..., 0]) * 2
+ angular_velocity = diff_angles(root_angles, local_motion_rep.fps)
+ angular_velocity = torch.cat(
+ [angular_velocity, torch.zeros_like(root_angles[:, :1])], dim=1
+ )
+ root_velocity = local_motion_rep.fps * (
+ root_positions[:, 1:] - root_positions[:, :-1]
+ )
+ root_velocity = torch.cat(
+ [root_velocity, torch.zeros_like(root_positions[:, :1])], dim=1
+ )
+ last_indices = lengths.reshape([-1, 1]).long() - 1
+ angular_velocity = angular_velocity.scatter(
+ 1, last_indices, angular_velocity.gather(1, last_indices - 1)
+ )
+ root_last_indices = last_indices[..., None].expand_as(root_velocity[:, :1])
+ root_velocity = root_velocity.scatter(
+ 1, root_last_indices, root_velocity.gather(1, root_last_indices - 1)
+ )
+ if local_motion_rep.compute_kwargs.get("removing_heading", True):
+ root_velocity = quat_apply(quat_conjugate(root_rotations), root_velocity)
+ local_root_velocity = root_velocity[..., [0, 2]]
+ local_root = torch.cat(
+ [angular_velocity[..., None], local_root_velocity, root_positions[..., [1]]],
+ dim=-1,
+ )
+ return dual_motion_rep.normalize(
+ local_root, index=dual_motion_rep.indices["local_root"]
+ )
diff --git a/tools/onnx/models/soma/__init__.py b/tools/onnx/models/soma/__init__.py
new file mode 100644
index 0000000..f206d51
--- /dev/null
+++ b/tools/onnx/models/soma/__init__.py
@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Standalone SOMA checkpoint export model."""
+
+from .model import INPUT_NAMES, OUTPUT_NAMES, build_soma
+
+__all__ = ["INPUT_NAMES", "OUTPUT_NAMES", "build_soma"]
diff --git a/tools/onnx/models/soma/features.py b/tools/onnx/models/soma/features.py
new file mode 100644
index 0000000..41f8637
--- /dev/null
+++ b/tools/onnx/models/soma/features.py
@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Combine SOMA constraint masks without changing their numeric dtype."
+
+from __future__ import annotations
+
+import torch
+
+
+def numeric_mask_union(*masks: torch.Tensor) -> torch.Tensor:
+ """Combine masks by their element-wise maximum, keeping their numeric dtype."""
+ if not masks:
+ raise ValueError("numeric_mask_union requires at least one mask.")
+ result = masks[0]
+ for mask in masks[1:]:
+ result = torch.maximum(result, mask)
+ return result
diff --git a/tools/onnx/models/soma/inference.py b/tools/onnx/models/soma/inference.py
new file mode 100644
index 0000000..edbddf6
--- /dev/null
+++ b/tools/onnx/models/soma/inference.py
@@ -0,0 +1,623 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Combine the SOMA predictors and decoder for batched inference."
+
+from __future__ import annotations
+
+import logging
+from typing import Dict
+import numpy as np
+import torch as t
+from .features import numeric_mask_union
+from ..features import extract_feature_from_motion_rep
+from ..representation import global_root_to_local_onnx_compatible
+
+logger = logging.getLogger(__name__)
+
+
+def target_frame_indices(
+ pred_num_tokens: t.Tensor, num_frames_per_token: int
+) -> t.Tensor:
+ """Return the frame indices of each request's last motion token."""
+ return (
+ pred_num_tokens.long().reshape([-1, 1]) - 1
+ ) * num_frames_per_token + t.arange(
+ num_frames_per_token, device=pred_num_tokens.device
+ ).reshape([1, -1])
+
+
+class mmm_inference_class(t.nn.Module):
+ """Run the SOMA root predictor, pose predictor, and motion decoder for inference.
+
+ predict() runs them in order on one batch.
+ """
+
+ EXTERNAL_POSE_FEATURE_MODE = "joint_positions_and_rotations"
+ EXTERNAL_ROOT_FEATURE_MODE = "root"
+ INTERNAL_POSE_FEATURE_MODE = "joint_positions_and_rotations_and_hip_height"
+ EPS = 1e-05
+
+ def __init__(self, models: list, args: Dict, device: str = "cuda"):
+ super(mmm_inference_class, self).__init__()
+ self._mmm_pose_model: t.nn.Module = models["pose"].eval().to(device)
+ self._mmm_root_model: t.nn.Module = models["root"].eval().to(device)
+ self._vqvae_pose_model: t.nn.Module = (
+ self._mmm_pose_model.supporting_nets["pose_net"].eval().to(device)
+ )
+ self.global_motion_rep = self._mmm_pose_model.global_motion_rep
+ self.local_motion_rep = self._mmm_pose_model.local_motion_rep
+ self.motion_rep = self._mmm_pose_model.motion_rep
+ self._args = args
+ self._device = device
+ self._IS_ROOT_MODEL_TOKENIZED = self._mmm_root_model.mmm_net.IS_MODEL_TOKENIZED
+ assert (
+ self._mmm_pose_model.mmm_net.initted
+ and self._mmm_pose_model.vqvae_model_loaded
+ and self._mmm_root_model.vqvae_model_loaded
+ ), "The model should be initialized before inference."
+ assert not self._IS_ROOT_MODEL_TOKENIZED, (
+ "The root model is not tokenized."
+ )
+
+ def predict(
+ self,
+ global_root_values: t.Tensor,
+ has_global_root_values: t.Tensor,
+ local_root_values: t.Tensor,
+ has_local_root_values: t.Tensor,
+ local_poses: t.Tensor,
+ has_local_poses: t.Tensor,
+ num_tokens: t.Tensor,
+ text_embeddings: t.Tensor = None,
+ has_text_embeddings: t.Tensor = None,
+ allowed_pred_num_tokens: t.Tensor = None,
+ config: dict = {},
+ info: dict = {},
+ ):
+ """Predict the motion features and token count for a batch of conditions.
+
+ It predicts the root trajectory, then the pose tokens, then decodes the motion.
+ """
+ batch_size, device, dtype = (
+ has_global_root_values.shape[0],
+ has_global_root_values.device,
+ local_poses.dtype,
+ )
+ num_frames_per_token = self._mmm_pose_model.mmm_net.get_num_frames_per_token()
+ if not (
+ t.all(has_global_root_values[:, :num_frames_per_token])
+ and t.all(has_local_root_values[:, :num_frames_per_token])
+ and t.all(has_local_poses[:, :num_frames_per_token])
+ ):
+ if not getattr(self, "_warned_missing_frames", False):
+ logger.warning("Results are best when all of the first four frames are provided.")
+ self._warned_missing_frames = True
+ if type(num_tokens) == int:
+ num_tokens = t.full([batch_size, 1], num_tokens, dtype=t.int).to(device)
+ elif num_tokens is None:
+ num_tokens = self._mmm_root_model.mmm_net.MASKED_NUM_TOKENS * t.ones(
+ [batch_size, 1], dtype=t.int
+ ).to(device)
+ batch = {}
+ (
+ batch["reference_start_root_global_offsets"],
+ batch["reference_start_root_global_heading"],
+ recentered_global_root_values,
+ ) = self._extract_initial_root_info(global_root_values)
+ batch["global_root_values"] = self.global_motion_rep.normalize(
+ recentered_global_root_values
+ )
+ batch["local_root_values"] = self.local_motion_rep.normalize(local_root_values)
+ local_pose_feat_idx = extract_feature_from_motion_rep(
+ t.zeros([1, 1, len(self.local_motion_rep.indices["all"])]),
+ self.local_motion_rep,
+ self.INTERNAL_POSE_FEATURE_MODE,
+ fetch_feat_idx=True,
+ )
+ global_height_values = recentered_global_root_values[
+ :, :, self.global_motion_rep.indices["global_root_pos"][[1]]
+ ]
+ mean = self.local_motion_rep.stats.mean[None, None, local_pose_feat_idx].to(
+ device=device, dtype=dtype
+ )
+ std = self.local_motion_rep.stats.std[None, None, local_pose_feat_idx].to(
+ device=device, dtype=dtype
+ )
+ batch["local_poses"] = (
+ t.concat([global_height_values, local_poses], dim=-1) - mean
+ ) / t.sqrt(std**2 + self.EPS)
+ batch["has_global_root_values"] = has_global_root_values
+ batch["has_local_root_values"] = has_local_root_values
+ batch["has_local_poses"] = has_local_poses
+ batch["text_embeddings"] = text_embeddings
+ batch["has_text_embeddings"] = has_text_embeddings
+ batch["num_tokens"] = num_tokens
+ batch["allowed_pred_num_tokens"] = allowed_pred_num_tokens
+ (
+ batch["pred_num_tokens"],
+ batch["pred_global_root_values"],
+ batch["pred_local_root_values"],
+ ) = self._predict_root_trajectories(batch, config)
+ (
+ batch["pred_pose_tokens"],
+ batch["pred_pose_cond"],
+ batch["pred_has_pose_cond"],
+ ) = self._predict_pose_tokens(batch, config, info)
+ batch["pred_local_poses"], batch["pred_global_poses"] = (
+ self._decode_motions_from_predicted_root_and_pose_tokens(
+ batch, config, info
+ )
+ )
+ batch["pred_global_poses"] = self._reapply_initial_root_info(batch)
+ return (batch["pred_global_poses"], batch["pred_num_tokens"])
+
+ def _sample_tokens_with_highest_prob(
+ self,
+ pose_tokens: t.Tensor,
+ pose_tokens_prob: t.Tensor,
+ pred_num_tokens: t.Tensor,
+ step: int,
+ num_pose_inference_steps: int,
+ ):
+ batch_size, device = (pose_tokens.shape[0], pose_tokens.device)
+ rand_mask_prob = np.cos(float(step) / num_pose_inference_steps * np.pi * 0.5)
+ num_pose_heads = self._mmm_pose_model.mmm_net.get_num_heads()[0]
+ num_tokens = (
+ self._args["max_tokens"] * self._mmm_pose_model.mmm_net.get_num_heads()[0]
+ )
+ num_pose_token_masked = t.clip(
+ (
+ rand_mask_prob
+ * pred_num_tokens
+ * self._mmm_pose_model.mmm_net.get_num_heads()[0]
+ ).int(),
+ min=1,
+ )
+ pose_tokens_prob = t.where(
+ t.arange(self._args["max_tokens"])
+ .to(device)
+ .view([1, -1, 1])
+ .expand([batch_size, -1, -1])
+ < pred_num_tokens.view([batch_size, 1, 1]).repeat([1, 1, num_pose_heads]),
+ pose_tokens_prob,
+ t.full_like(pose_tokens_prob, t.inf),
+ )
+ indices = pose_tokens_prob.view([batch_size, -1]).sort(descending=False)[1]
+ tokens_to_be_masked = t.arange(num_tokens).to(device)[None, :].repeat(
+ [batch_size, 1]
+ ) < num_pose_token_masked.view([batch_size, 1])
+ indices = indices * tokens_to_be_masked + indices[:, :1] * ~tokens_to_be_masked
+ pose_tokens = pose_tokens.view([batch_size, -1]).clone()
+ pose_tokens.scatter_(
+ dim=-1, index=indices, value=self._mmm_pose_model.mmm_net.POSE_MASK_ID
+ )
+ return pose_tokens.view([batch_size, self._args["max_tokens"], -1])
+
+ @property
+ def device(self):
+ """Device the networks run on."""
+ return self._device
+
+ def _extract_initial_root_info(self, global_root_values: t.Tensor):
+ reference_start_root_global_offsets = global_root_values[
+ :, :1, self.global_motion_rep.indices["global_root_pos_2d"]
+ ].clone()
+ _, reference_start_root_global_heading = (
+ self.global_motion_rep.compute_root_pos_and_rot(
+ global_root_values[:, :1, :], return_angle=True, return_quat=False
+ )
+ )
+ recentered_global_root_values = global_root_values.clone()
+ recentered_global_root_values[
+ :, :, self.global_motion_rep.indices["global_root_pos_2d"]
+ ] -= reference_start_root_global_offsets
+ return (
+ reference_start_root_global_offsets,
+ reference_start_root_global_heading,
+ recentered_global_root_values,
+ )
+
+ def _reapply_initial_root_info(self, batch: dict):
+ _, root_rot_angle = self.global_motion_rep.compute_root_pos_and_rot(
+ batch["pred_global_poses"], return_angle=True, return_quat=False
+ )
+ corrective_angle = batch["reference_start_root_global_heading"].reshape(
+ root_rot_angle[..., 0].shape
+ )
+ new_angles = root_rot_angle + corrective_angle[..., None]
+ new_heading = t.stack([t.cos(new_angles), t.sin(new_angles)], dim=-1)
+ batch["pred_global_poses"][
+ :, :, self.global_motion_rep.indices["global_root_pos_2d"]
+ ] += batch["reference_start_root_global_offsets"]
+ batch["pred_global_poses"][
+ :, :, self.global_motion_rep.indices["global_root_heading"]
+ ] = new_heading
+ return batch["pred_global_poses"]
+
+ def _predict_root_trajectories(self, batch: dict = {}, config: dict = {}):
+ assert (
+ self._mmm_root_model.args["local_root_feature"]
+ == self.EXTERNAL_ROOT_FEATURE_MODE
+ ), (
+ self._mmm_root_model.args["global_root_feature"]
+ == self.EXTERNAL_ROOT_FEATURE_MODE
+ )
+ assert (
+ self._mmm_root_model.args["local_pose_feature"]
+ == self.INTERNAL_POSE_FEATURE_MODE
+ ), (
+ f"All submodules should only use {self.INTERNAL_POSE_FEATURE_MODE} as the local pose feature."
+ )
+ assert self.EXTERNAL_ROOT_FEATURE_MODE == "root", (
+ "The root model supports only full root features."
+ )
+ num_frames_per_token = self._mmm_pose_model.mmm_net.get_num_frames_per_token()
+ assert (
+ num_frames_per_token
+ == self._mmm_root_model.mmm_net.get_num_frames_per_token()
+ )
+ root_mmm_outputs = self._mmm_root_model.mmm_net(
+ batch["global_root_values"],
+ batch["has_global_root_values"],
+ batch["local_root_values"],
+ batch["has_local_root_values"],
+ batch["local_poses"],
+ batch["has_local_poses"],
+ batch["num_tokens"],
+ text_embeddings=batch["text_embeddings"],
+ has_text_embeddings=batch["has_text_embeddings"],
+ allowed_pred_num_tokens=batch["allowed_pred_num_tokens"],
+ config=config,
+ )
+ pred_num_tokens = root_mmm_outputs["pred_num_tokens"]
+ pred_global_root_values = root_mmm_outputs["pred_global_root_values"]
+ if config.get("debug_ground_truth_root_trajectories", None) is not None:
+ pred_num_tokens[:] = (
+ config["debug_ground_truth_root_trajectories"].shape[1]
+ // num_frames_per_token
+ )
+ pred_global_root_values[
+ :, : config["debug_ground_truth_root_trajectories"].shape[1]
+ ] = config["debug_ground_truth_root_trajectories"]
+ num_pred_frames = pred_num_tokens * num_frames_per_token
+ if config.get("use_onnx_dynamic_batch_root_conversion", False):
+ pred_local_root_values = global_root_to_local_onnx_compatible(
+ pred_global_root_values, self.motion_rep.dual_rep, num_pred_frames
+ )
+ else:
+ pred_local_root_values = self.motion_rep.dual_rep.global_to_local(
+ pred_global_root_values,
+ is_normalized=True,
+ to_normalize=True,
+ lengths=num_pred_frames,
+ )
+ local_root_feat_dim = len(self.local_motion_rep.indices["root"])
+ final_root_indices = (
+ pred_num_tokens.long()
+ .view([-1, 1])
+ .repeat([1, local_root_feat_dim])[:, None, :]
+ * num_frames_per_token
+ - 1
+ )
+ estimated_final_local_root_motion = t.gather(
+ pred_local_root_values, 1, final_root_indices
+ )
+ final_local_root_motion = (
+ batch["has_local_root_values"][:, -1:, None]
+ .expand([-1, -1, local_root_feat_dim])
+ .float()
+ * batch["local_root_values"][:, -1:]
+ + (
+ 1
+ - batch["has_local_root_values"][:, -1:, None]
+ .expand([-1, -1, local_root_feat_dim])
+ .float()
+ )
+ * estimated_final_local_root_motion
+ )
+ pred_local_root_values = pred_local_root_values.scatter(
+ 1, final_root_indices, final_local_root_motion
+ )
+ return (pred_num_tokens, pred_global_root_values, pred_local_root_values)
+
+ def _predict_pose_tokens(
+ self, batch: dict = {}, config: dict = {}, info: dict = {}
+ ):
+ assert (
+ self._mmm_pose_model.args["local_pose_feature"]
+ == self.INTERNAL_POSE_FEATURE_MODE
+ )
+ assert (
+ self.INTERNAL_POSE_FEATURE_MODE
+ == "joint_positions_and_rotations_and_hip_height"
+ )
+ assert (
+ self._mmm_pose_model.args["cond_root_feature_is_from_motion_rep"] == "local"
+ and self._mmm_pose_model.args["cond_root_feature"]
+ == "root_without_hip_height_without_heading"
+ or (
+ self._mmm_pose_model.args["cond_root_feature_is_from_motion_rep"]
+ == "global"
+ and self._mmm_pose_model.args["cond_root_feature"]
+ == "root_without_hip_height"
+ )
+ ), "Only these two root condition feature combinations are supported."
+ num_pose_heads, num_frames_per_token = (
+ self._mmm_pose_model.mmm_net.get_num_heads()[0],
+ self._mmm_pose_model.mmm_net.get_num_frames_per_token(),
+ )
+ batch_size, device = (
+ batch["local_poses"].shape[0],
+ batch["local_poses"].device,
+ )
+ num_pose_inference_steps = config.get("num_inference_step", 1)
+ pose_tokens = t.full(
+ [batch_size, self._args["max_tokens"], num_pose_heads],
+ self._mmm_pose_model.mmm_net.POSE_MASK_ID,
+ ).to(device)
+ chosen_pose_tokens_prob = t.full(
+ [batch_size, self._args["max_tokens"], num_pose_heads], 1.0 / num_pose_heads
+ ).to(device)
+ pose_cond = t.concat(
+ [
+ batch["local_poses"][:, :num_frames_per_token],
+ t.zeros(
+ [
+ batch_size,
+ (self._args["max_tokens"] - 1) * num_frames_per_token,
+ batch["local_poses"].shape[-1],
+ ]
+ ).to(device),
+ ],
+ dim=1,
+ )
+ has_pose_cond = t.concat(
+ [
+ batch["has_local_poses"][:, :num_frames_per_token],
+ t.zeros(
+ [batch_size, (self._args["max_tokens"] - 1) * num_frames_per_token],
+ dtype=batch["has_local_poses"].dtype,
+ device=device,
+ ),
+ ],
+ dim=1,
+ )
+ for i in range(num_frames_per_token):
+ onehot_idx = t.nn.functional.one_hot(
+ batch["pred_num_tokens"].view([-1]).long() * num_frames_per_token
+ - num_frames_per_token
+ + i,
+ num_classes=self._args["max_tokens"] * num_frames_per_token,
+ )
+ pose_cond = pose_cond + onehot_idx.float().view(
+ [batch_size, -1, 1]
+ ) * batch["local_poses"][:, -num_frames_per_token + i].view(
+ [batch_size, 1, -1]
+ )
+ target_pose_mask = onehot_idx.to(has_pose_cond.dtype).view(
+ [batch_size, -1]
+ ) * batch["has_local_poses"][:, -num_frames_per_token + i].view(
+ [batch_size, 1]
+ )
+ has_pose_cond = numeric_mask_union(has_pose_cond, target_pose_mask)
+ has_pose_cond = has_pose_cond.bool()
+ for step in range(num_pose_inference_steps):
+ pose_tokens = self._sample_tokens_with_highest_prob(
+ pose_tokens,
+ chosen_pose_tokens_prob,
+ batch["pred_num_tokens"],
+ step,
+ num_pose_inference_steps,
+ )
+ assert self._args["cond_root_feature_is_from_motion_rep"] in [
+ "local",
+ "global",
+ ]
+ if self._args["cond_root_feature_is_from_motion_rep"] == "local":
+ pose_mmm_root_cond = extract_feature_from_motion_rep(
+ batch["pred_local_root_values"],
+ self.local_motion_rep,
+ self._mmm_pose_model.args["cond_root_feature"],
+ )
+ else:
+ assert self._args["cond_root_feature_is_from_motion_rep"] == "global"
+ pose_mmm_root_cond = extract_feature_from_motion_rep(
+ batch["pred_global_root_values"],
+ self.global_motion_rep,
+ self._mmm_pose_model.args["cond_root_feature"],
+ )
+ pose_mmm_output = self._mmm_pose_model.mmm_net(
+ pose_tokens,
+ pose_mmm_root_cond,
+ pose_cond,
+ has_pose_cond,
+ batch["pred_num_tokens"],
+ batch["text_embeddings"],
+ batch["has_text_embeddings"],
+ )
+ if config.get("pose_token_sampling_use_argmax", False):
+ pose_tokens = pose_mmm_output["pose_logits"].argmax(dim=-1)
+ else:
+ raise ValueError("The release exporter uses argmax token selection.")
+ pose_tokens_prob = pose_mmm_output["pose_logits"].softmax(dim=-1)
+ chosen_pose_tokens_prob = pose_tokens_prob.gather(
+ dim=-1, index=pose_tokens.unsqueeze(-1)
+ ).squeeze(-1)
+ if config.get("debug_ground_truth_pose_tokens", None) is not None:
+ pose_tokens[:, : config["debug_ground_truth_pose_tokens"].shape[1]] = (
+ config["debug_ground_truth_pose_tokens"][:, :]
+ )
+ if config.get("perturb_token_percentage", 0.0) > 0.0:
+ perturb_token_percentage = config.get("perturb_token_percentage", 0.0)
+ random_tokens = t.randint_like(
+ pose_tokens,
+ high=self._mmm_pose_model.mmm_net.get_num_codes(False)[0],
+ low=0,
+ )
+ pose_tokens = t.where(
+ t.rand_like(pose_tokens.float()) < perturb_token_percentage,
+ random_tokens,
+ pose_tokens,
+ )
+ return (pose_tokens, pose_cond, has_pose_cond)
+
+ def _decode_motions_from_predicted_root_and_pose_tokens(
+ self, batch: dict = {}, config: dict = {}, info: dict = {}
+ ):
+ if self._mmm_pose_model.args["pose_vqvae_motion_rep"] == "local":
+ assert self._vqvae_pose_model.motion_rep.name == "local"
+ assert (
+ self._vqvae_pose_model.decoder_external_cond_feature_mode
+ == "root_without_hip_height_without_heading"
+ )
+ else:
+ assert self._vqvae_pose_model.motion_rep.name == "global"
+ assert (
+ self._vqvae_pose_model.decoder_external_cond_feature_mode
+ == "root_without_hip_height_without_heading_with_mask"
+ )
+ assert (
+ self._vqvae_pose_model.decoder_target_cond_feature_mode
+ == self.INTERNAL_POSE_FEATURE_MODE
+ )
+ pose_external_root_cond = extract_feature_from_motion_rep(
+ batch["pred_local_root_values"]
+ if self._vqvae_pose_model.motion_rep.name == "local"
+ else batch["pred_global_root_values"],
+ self._vqvae_pose_model.motion_rep,
+ self._vqvae_pose_model.decoder_external_cond_feature_mode,
+ )
+ if self._vqvae_pose_model.motion_rep.name == "global":
+ raise NotImplementedError("The global root feature is not supported.")
+ batch_size, device = (
+ batch["local_poses"].shape[0],
+ batch["local_poses"].device,
+ )
+ pose_token_mask = t.arange(self._args["max_tokens"]).to(device)[None, :].repeat(
+ [batch_size, 1]
+ ) < batch["pred_num_tokens"].view([batch_size, 1])
+ if type(config.get("use_target_cond_in_decoder", True)) == t.Tensor:
+ global_target_cond = (
+ config["use_target_cond_in_decoder"]
+ .bool()
+ .expand_as(batch["pred_has_pose_cond"])
+ )
+ has_target_cond = t.logical_and(
+ batch["pred_has_pose_cond"], global_target_cond
+ )
+ else:
+ assert type(config.get("use_target_cond_in_decoder", True)) == bool
+ has_target_cond = (
+ batch["pred_has_pose_cond"]
+ if config.get("use_target_cond_in_decoder", True)
+ else t.zeros_like(batch["pred_has_pose_cond"]).bool()
+ )
+ if not config.get("use_constraints_at_decoder", True):
+ has_target_cond = t.zeros_like(has_target_cond).bool()
+ if config.get("skip_ending_target_cond", False):
+ num_frames_per_token = (
+ self._mmm_pose_model.mmm_net.get_num_frames_per_token()
+ )
+ has_target_cond[:, num_frames_per_token:] = False
+ if abs(config.get("root_interpolation_ratio", 1.0) - 1.0) > 1e-06:
+ pose_external_root_cond = self.local_motion_rep.unnormalize(
+ pose_external_root_cond, self.local_motion_rep.indices["local_root_vel"]
+ )
+ pose_external_root_cond *= config.get("root_interpolation_ratio", 1.0)
+ pose_external_root_cond = self.local_motion_rep.normalize(
+ pose_external_root_cond, self.local_motion_rep.indices["local_root_vel"]
+ )
+ pred_poses = self._vqvae_pose_model.forward_decoder(
+ batch["pred_pose_tokens"],
+ target_cond=batch["pred_pose_cond"],
+ has_target_cond=has_target_cond,
+ external_cond=pose_external_root_cond,
+ use_overall_indices=False,
+ token_mask=pose_token_mask,
+ )["recon_state"]
+ num_pred_frames = (
+ batch["pred_num_tokens"]
+ * self._mmm_pose_model.mmm_net.get_num_frames_per_token()
+ )
+ if self._vqvae_pose_model.motion_rep.name == "local":
+ pred_global_poses = self.motion_rep.dual_rep.local_to_global(
+ pred_poses,
+ is_normalized=True,
+ to_normalize=False,
+ lengths=num_pred_frames,
+ )
+ pred_local_poses = self.local_motion_rep.unnormalize(pred_poses)
+ else:
+ pred_local_poses = self.motion_rep.dual_rep.global_to_local(
+ pred_poses,
+ is_normalized=True,
+ to_normalize=False,
+ lengths=num_pred_frames,
+ )
+ pred_global_poses = self.global_motion_rep.unnormalize(pred_poses)
+ if config.get("final_root_pred_mode", "from_pose_module") == "from_pose_module":
+ pass
+ elif config["final_root_pred_mode"] == "from_root_module":
+ local_root_index, global_root_index = (
+ self.local_motion_rep.indices["root"],
+ self.global_motion_rep.indices["root"],
+ )
+ pred_global_poses[:, :, global_root_index] = (
+ self.global_motion_rep.unnormalize(batch["pred_global_root_values"])
+ )
+ pred_local_poses[:, :, local_root_index] = (
+ self.local_motion_rep.unnormalize(batch["pred_local_root_values"])
+ )
+ else:
+ assert config["final_root_pred_mode"] == "from_height_constraint_violation"
+ num_frames_per_token = (
+ self._mmm_pose_model.mmm_net.get_num_frames_per_token()
+ )
+ target_frame_inds = target_frame_indices(
+ batch["pred_num_tokens"], num_frames_per_token
+ )
+ root_height_index = self.global_motion_rep.indices["global_root_pos"][1]
+ pred_global_height_from_root_module = t.gather(
+ self.global_motion_rep.unnormalize(batch["pred_global_root_values"])[
+ :, :, root_height_index
+ ],
+ 1,
+ target_frame_inds,
+ )
+ pred_global_height_from_pose_module = t.gather(
+ pred_global_poses[:, :, root_height_index], 1, target_frame_inds
+ )
+ target_global_height = self.global_motion_rep.unnormalize(
+ batch["global_root_values"]
+ )[:, -num_frames_per_token:, root_height_index]
+ avg_height_error_from_pose = (
+ (pred_global_height_from_pose_module - target_global_height).abs()
+ * batch["has_global_root_values"][:, -num_frames_per_token:].float()
+ ).sum(dim=1) / batch["has_global_root_values"][
+ :, -num_frames_per_token:
+ ].float().sum(dim=1)
+ avg_height_error_from_root = (
+ (pred_global_height_from_root_module - target_global_height).abs()
+ * batch["has_global_root_values"][:, -num_frames_per_token:].float()
+ ).sum(dim=1) / batch["has_global_root_values"][
+ :, -num_frames_per_token:
+ ].float().sum(dim=1)
+ use_root_module = t.logical_and(
+ avg_height_error_from_root < avg_height_error_from_pose,
+ avg_height_error_from_pose > 0.05,
+ )[:, None, None].float()
+ local_root_index, global_root_index = (
+ self.local_motion_rep.indices["root"],
+ self.global_motion_rep.indices["root"],
+ )
+ pred_global_poses[:, :, global_root_index] = (
+ use_root_module
+ * self.global_motion_rep.unnormalize(batch["pred_global_root_values"])
+ + (1 - use_root_module) * pred_global_poses[:, :, global_root_index]
+ )
+ pred_local_poses[:, :, local_root_index] = (
+ use_root_module
+ * self.local_motion_rep.unnormalize(batch["pred_local_root_values"])
+ + (1 - use_root_module) * pred_local_poses[:, :, local_root_index]
+ )
+ return (pred_local_poses, pred_global_poses)
diff --git a/tools/onnx/models/soma/layers.py b/tools/onnx/models/soma/layers.py
new file mode 100644
index 0000000..31bbdef
--- /dev/null
+++ b/tools/onnx/models/soma/layers.py
@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"SOMA convolutional decoder with numeric constraint masks."
+
+from __future__ import annotations
+
+import torch
+
+from ..layers import DoubleCondDecoder as BaseDecoder
+
+
+class DoubleCondDecoder(BaseDecoder):
+ """Decoder that casts numeric token masks to the feature dtype."""
+
+ def forward(
+ self,
+ x: torch.Tensor,
+ external_cond: torch.Tensor = None,
+ target_cond: torch.Tensor = None,
+ has_target_cond: torch.Tensor = None,
+ token_mask: torch.Tensor = None,
+ ):
+ if token_mask is not None:
+ token_mask = token_mask.to(dtype=x.dtype)
+ return super().forward(
+ x, external_cond, target_cond, has_target_cond, token_mask
+ )
diff --git a/tools/onnx/models/soma/model.py b/tools/onnx/models/soma/model.py
new file mode 100644
index 0000000..0e3f658
--- /dev/null
+++ b/tools/onnx/models/soma/model.py
@@ -0,0 +1,292 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Build SOMA inference from the released checkpoint states."
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch as t
+from torch import nn
+from types import SimpleNamespace
+from ..representation import GlobalRootGlobalJoints, Stats
+from ..vqvae import VQVAE
+from .networks import pose_mmm_network, root_mmm_network
+from .inference import mmm_inference_class
+from .layers import DoubleCondDecoder
+from .rotations import (
+ cont6d_to_matrix,
+ matrix_to_cont6d,
+ change_t_pose_global_mats_onnx_compatible,
+)
+
+INPUT_NAMES = (
+ "global_root_values",
+ "has_global_root_values",
+ "local_root_values",
+ "has_local_root_values",
+ "local_poses",
+ "has_local_poses",
+ "allowed_pred_num_tokens",
+)
+OUTPUT_NAMES = ("pred_global_motions", "pred_num_tokens")
+
+
+def replace_contiguous_features(
+ values: t.Tensor, replacement: t.Tensor, feature_slice: slice
+) -> t.Tensor:
+ """Replace a contiguous feature range along the last axis.
+
+ A slice with a step or an open end raises ValueError.
+ """
+ if (
+ feature_slice.start is None
+ or feature_slice.stop is None
+ or feature_slice.step not in (None, 1)
+ or (feature_slice.start < 0)
+ or (feature_slice.stop < feature_slice.start)
+ ):
+ raise ValueError(f"Invalid contiguous feature slice: {feature_slice}.")
+ return torch.cat(
+ [
+ values[..., : feature_slice.start],
+ replacement,
+ values[..., feature_slice.stop :],
+ ],
+ dim=-1,
+ )
+
+
+class BatchedSOMA(torch.nn.Module):
+ """Batched SOMA graph from encoded inputs to predicted motion features.
+
+ It moves the input joint rotations from the capture T pose to the standard one
+ first.
+ """
+
+ def __init__(self, model: mmm_inference_class) -> None:
+ super().__init__()
+ self.model = model
+ global_rotation_indices = self.model.global_motion_rep.indices[
+ "global_rot_data"
+ ]
+ local_rotation_start = len(self.model.local_motion_rep.indices["ric_data"])
+ self.local_rotation_slice = slice(
+ local_rotation_start,
+ local_rotation_start
+ + len(self.model.local_motion_rep.indices["global_rot_data"]),
+ )
+ self.global_rotation_slice = slice(
+ int(global_rotation_indices[0]), int(global_rotation_indices[-1]) + 1
+ )
+ self.config = {
+ "num_inference_step": 1,
+ "allow_pred_out_of_reach_num_tokens": False,
+ "pose_token_sampling_use_argmax": True,
+ "use_onnx_dynamic_batch_root_conversion": True,
+ }
+ self.config["final_root_pred_mode"] = "from_height_constraint_violation"
+ with np.load(
+ Path(__file__).resolve().parents[2] / "assets/soma_model_rig.npz",
+ allow_pickle=False,
+ ) as data:
+ self.capture_offsets = torch.from_numpy(data["capture_offsets"])
+ self.standard_offsets = torch.from_numpy(data["standard_offsets"])
+
+ def forward(
+ self,
+ global_root_values: t.Tensor,
+ has_global_root_values: t.Tensor,
+ local_root_values: t.Tensor,
+ has_local_root_values: t.Tensor,
+ local_poses: t.Tensor,
+ has_local_poses: t.Tensor,
+ allowed_pred_num_tokens: t.Tensor,
+ ):
+ rotation_start = self.local_rotation_slice.start
+ rotation_end = self.local_rotation_slice.stop
+ global_joints_ric_rot6d = local_poses[:, :, rotation_start:rotation_end]
+ global_rot_6d = global_joints_ric_rot6d.reshape(
+ local_poses.shape[0],
+ local_poses.shape[1],
+ self.model.global_motion_rep.num_joints,
+ 6,
+ )
+ global_rot_mats = cont6d_to_matrix(global_rot_6d)
+ global_rot_mats = change_t_pose_global_mats_onnx_compatible(
+ global_rot_mats, self.capture_offsets, self.standard_offsets
+ )
+ retargeted_local_poses = torch.cat(
+ [
+ local_poses[..., :rotation_start],
+ matrix_to_cont6d(global_rot_mats).reshape(
+ local_poses.shape[0],
+ local_poses.shape[1],
+ self.model.global_motion_rep.num_joints * 6,
+ ),
+ local_poses[..., rotation_end:],
+ ],
+ dim=-1,
+ )
+ pred_global_motions, pred_num_tokens = self.model.predict(
+ global_root_values,
+ has_global_root_values,
+ local_root_values,
+ has_local_root_values,
+ retargeted_local_poses,
+ has_local_poses,
+ num_tokens=None,
+ allowed_pred_num_tokens=allowed_pred_num_tokens,
+ config=self.config,
+ )
+ batch_size, num_frames, _ = pred_global_motions.shape
+ global_joints_ric_rot6d = pred_global_motions[:, :, self.global_rotation_slice]
+ global_rot_6d = global_joints_ric_rot6d.reshape(
+ batch_size, num_frames, self.model.global_motion_rep.num_joints, 6
+ )
+ global_rot_mats = cont6d_to_matrix(global_rot_6d)
+ global_rot_mats = change_t_pose_global_mats_onnx_compatible(
+ global_rot_mats, self.standard_offsets, self.capture_offsets
+ )
+ retargeted_global_rotations = matrix_to_cont6d(global_rot_mats).reshape(
+ pred_global_motions.shape[0],
+ pred_global_motions.shape[1],
+ self.model.global_motion_rep.num_joints * 6,
+ )
+ pred_global_motions = replace_contiguous_features(
+ pred_global_motions, retargeted_global_rotations, self.global_rotation_slice
+ )
+ return [pred_global_motions, pred_num_tokens]
+
+
+class Predictor(nn.Module):
+ """One predictor network with its motion representation and settings."""
+
+ def __init__(self, backbone, motion_rep, args, pose_decoder=None):
+ super().__init__()
+ self.mmm_net = backbone
+ self.motion_rep = motion_rep
+ self.global_motion_rep = motion_rep.dual_rep.global_motion_rep
+ self.local_motion_rep = motion_rep.dual_rep.local_motion_rep
+ self.args = args
+ self.supporting_nets = {"pose_net": pose_decoder}
+ self.vqvae_model_loaded = True
+
+
+def build_soma(sources):
+ """Load the root predictor, the pose predictor, and the VQ-VAE motion decoder."""
+ mean = next(value for path, value in sources.items() if path.endswith("mean.npy"))
+ std = next(value for path, value in sources.items() if path.endswith("std.npy"))
+ stats = Stats()
+ stats.register_from_tensors(
+ torch.from_numpy(mean).float(), torch.from_numpy(std).float()
+ )
+ motion_rep = GlobalRootGlobalJoints(
+ fps=30,
+ skeleton=SimpleNamespace(nbjoints=30),
+ name="novaskel30_dual_root_global_joints",
+ stats=stats,
+ )
+ common = dict(
+ min_tokens=6,
+ max_tokens=16,
+ down_t=2,
+ local_pose_feature="joint_positions_and_rotations_and_hip_height",
+ )
+ pose_args = dict(
+ common,
+ pose_root_mode="pose",
+ pose_vqvae_motion_rep="local",
+ cond_root_feature="root_without_hip_height",
+ cond_root_feature_is_from_motion_rep="global",
+ )
+ root_args = dict(
+ common,
+ pose_root_mode="root",
+ local_root_feature="root",
+ global_root_feature="root",
+ use_hard_num_token_emb_for_root_prediction=True,
+ )
+ pose_network_args = dict(
+ pose_args,
+ pose_token_mlp_num_layers=2,
+ root_feat_width=256,
+ pose_feat_width=640,
+ token_length_feat_width=128,
+ text_emb_dim=4096,
+ text_embeddings=None,
+ n_embd=1024,
+ n_head=16,
+ n_layers=16,
+ pose_vqvae=dict(nb_code=1048576, code_dim=160, num_heads=5, has_codebook=True),
+ root_vqvae=dict(nb_code=1024, code_dim=60, num_heads=1),
+ )
+ root_network_args = dict(
+ root_args,
+ pose_feat_dim=256,
+ local_root_feat_dim=64,
+ global_root_feat_dim=64,
+ text_emb_dim=4096,
+ text_embeddings=None,
+ input_feat_mlp_num_layers=2,
+ n_embd=512,
+ n_head=16,
+ n_layers_shared=6,
+ n_layers_root_token=2,
+ width=512,
+ depth=4,
+ dilation_growth_rate=3,
+ activation="relu",
+ norm="None",
+ pose_vqvae=dict(nb_code=1024, code_dim=60, num_heads=1),
+ root_vqvae=dict(nb_code=1024, code_dim=60, num_heads=1),
+ )
+ pose_backbone = pose_mmm_network(motion_rep, pose_network_args)
+ root_backbone = root_mmm_network(root_network_args, motion_rep)
+ vqvae = VQVAE(
+ decoder_type=DoubleCondDecoder,
+ pose_root_mode="pose",
+ motion_rep=motion_rep.dual_rep.local_motion_rep,
+ feature_mode=[
+ "joint_positions_and_rotations_and_hip_height",
+ "pose",
+ "joint_positions_and_rotations_and_hip_height",
+ "root_without_hip_height_without_heading",
+ ],
+ nb_code=1048576,
+ code_dim=160,
+ output_emb_width=160,
+ down_t=2,
+ stride_t=2,
+ width=512,
+ depth=4,
+ dilation_growth_rate=3,
+ activation="relu",
+ num_heads=5,
+ norm="None",
+ cond_fusion_last_layer=False,
+ )
+ for kind, network, prefix in (
+ ("pose", pose_backbone, "mmm_net."),
+ ("root", root_backbone, "mmm_net."),
+ ("vqvae", vqvae, "pose_net."),
+ ):
+ directory = (
+ f"mmm-v6-soma-{kind}-nova-4n8g-ea43dd8-fp32-v1"
+ if kind != "vqvae"
+ else "vqvae-v6-soma-nova-4n8g-ea43dd8-fp32-v1"
+ )
+ state = sources[f"{directory}/version_0/checkpoints/model-step=1500000.safetensors"]
+ weights = {
+ name.removeprefix(prefix): value
+ for name, value in state.items()
+ if name.startswith(prefix)
+ }
+ network.load_state_dict(weights, strict=True)
+ models = dict(
+ pose=Predictor(pose_backbone, motion_rep, pose_args, vqvae),
+ root=Predictor(root_backbone, motion_rep, root_args),
+ )
+ return BatchedSOMA(mmm_inference_class(models, pose_args, device="cpu")).eval()
diff --git a/tools/onnx/models/soma/networks.py b/tools/onnx/models/soma/networks.py
new file mode 100644
index 0000000..9a707c7
--- /dev/null
+++ b/tools/onnx/models/soma/networks.py
@@ -0,0 +1,680 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"SOMA pose and root predictors."
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Dict, Optional
+import numpy as np
+import torch
+import torch as t
+from torch import nn
+
+from ..layers import FCBlock as mlp, PositionEmbedding
+from .layers import DoubleCondDecoder
+from ..features import (
+ extract_feature_from_motion_rep,
+ convert_sparse_cond_to_dense_cond_if_needed,
+)
+from .features import numeric_mask_union
+from ..quantizer import resolve_multihead_vq_dimensions
+
+
+class pose_mmm_network(nn.Module):
+ """Transformer that predicts the pose tokens for SOMA."""
+
+ def __init__(self, motion_rep: nn.Module, args: Dict = None):
+ super().__init__()
+ self.motion_rep = motion_rep
+ self.global_motion_rep = motion_rep.dual_rep.global_motion_rep
+ self.local_motion_rep = motion_rep.dual_rep.local_motion_rep
+ self._args = args
+ self._build_transformer_backbone()
+ self._build_input_embeddings_projections()
+ self.register_buffer("initted", torch.Tensor([False]).to(dtype=t.bool))
+
+ def _semantic_vq_dimensions(self, vqvae: str):
+ config = self._args[vqvae]
+ if (
+ config.get("codes_per_head") is None
+ and config.get("code_dim_per_head") is None
+ ):
+ return None
+ return resolve_multihead_vq_dimensions(
+ num_heads=int(config["num_heads"]),
+ codes_per_head=config.get("codes_per_head"),
+ code_dim_per_head=config.get("code_dim_per_head"),
+ nb_code=config.get("nb_code"),
+ code_dim=config.get("code_dim"),
+ )
+
+ def _build_transformer_backbone(self):
+ encoder_layer = nn.TransformerEncoderLayer(
+ d_model=self._args["n_embd"], nhead=self._args["n_head"], batch_first=True
+ )
+ self._transformer_model = nn.TransformerEncoder(
+ encoder_layer, num_layers=self._args["n_layers"]
+ )
+
+ def _build_input_embeddings_projections(self):
+ num_pose_heads, _ = self.get_num_heads()
+ num_pose_tokens, _ = self.get_num_codes(include_aug_tokens=False)
+ if self._args["pose_vqvae"].get("has_codebook", True):
+ pose_dimensions = self._semantic_vq_dimensions("pose_vqvae")
+ pose_token_dim = (
+ pose_dimensions.code_dim_per_head
+ if pose_dimensions is not None
+ else self._args["pose_vqvae"]["code_dim"] // num_pose_heads
+ )
+ else:
+ pose_token_dim = self._args["n_embd"] // num_pose_heads
+ self._pose_token_emb = t.nn.Embedding(
+ num_pose_heads * self.NUM_WITH_AUG_POSE_TOKENS, pose_token_dim
+ )
+ self._proj_pose_token_emb = mlp(
+ num_layers=self._args["pose_token_mlp_num_layers"],
+ layer_width=self._args["pose_feat_width"],
+ size_in=num_pose_heads * pose_token_dim,
+ size_out=self._args["pose_feat_width"],
+ )
+ num_frames_per_token = self.get_num_frames_per_token()
+ if self._args["cond_root_feature_is_from_motion_rep"] == "local":
+ self._args["local_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["cond_root_feature"],
+ ).shape[2]
+ else:
+ self._args["local_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.global_motion_rep,
+ self._args["cond_root_feature"],
+ ).shape[2]
+ self._proj_local_root_values = t.nn.Linear(
+ self._args["local_root_dim"] * num_frames_per_token,
+ self._args["root_feat_width"],
+ )
+ self._args["local_pose_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["local_pose_feature"],
+ ).shape[2]
+ self._proj_local_pose = t.nn.Linear(
+ self._args["local_pose_dim"],
+ self._args["pose_feat_width"] // num_frames_per_token,
+ )
+ assert self._args["pose_feat_width"] % self.get_num_frames_per_token() == 0, (
+ "pose_feat_width needs to be divisible by num_frames_per_token"
+ )
+ self._proj_num_valid_positions = t.nn.Embedding(
+ self._args["max_tokens"] - self._args["min_tokens"] + 1,
+ self._args["token_length_feat_width"],
+ )
+ self._proj_input = t.nn.Sequential(
+ t.nn.Linear(
+ self._args["pose_feat_width"]
+ + self._args["root_feat_width"]
+ + self._args["token_length_feat_width"],
+ self._args["n_embd"],
+ ),
+ t.nn.ReLU(),
+ )
+ self._position_emb = PositionEmbedding(
+ seq_length=self._args["max_tokens"], dim=self._args["n_embd"]
+ )
+ self._proj_pose_output_logit = t.nn.Linear(
+ self._args["n_embd"], num_pose_heads * num_pose_tokens
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT:
+ self._proj_text_embeddings = mlp(
+ num_layers=self._args["pose_token_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=self._args["text_emb_dim"],
+ size_out=self._args["n_embd"],
+ )
+
+ def forward(
+ self,
+ pose_tokens: t.Tensor,
+ local_root_values: t.Tensor,
+ pose_cond: t.Tensor,
+ has_pose_cond: t.Tensor,
+ num_tokens: t.Tensor,
+ text_embeddings: t.Tensor = None,
+ has_text_embeddings: t.Tensor = None,
+ ):
+ batch_size, num_positions, num_pose_heads = pose_tokens.shape
+ device = pose_tokens.device
+ num_frames_per_token = self.get_num_frames_per_token()
+ local_root_values = local_root_values.reshape(
+ [
+ batch_size,
+ num_positions,
+ num_frames_per_token * self._args["local_root_dim"],
+ ]
+ )
+ root_embedding = self._proj_local_root_values(local_root_values)
+ dense_pose_cond, dense_has_pose_cond = (
+ convert_sparse_cond_to_dense_cond_if_needed(
+ pose_cond, has_pose_cond, num_positions * num_frames_per_token
+ )
+ )
+ pose_cond_embedding = self._proj_local_pose(dense_pose_cond)
+ pose_cond_embedding = pose_cond_embedding.view(
+ [
+ batch_size,
+ num_positions * num_frames_per_token,
+ self._args["pose_feat_width"] // num_frames_per_token,
+ ]
+ )
+ pose_token_id_offsets = (
+ torch.arange(num_pose_heads).view([1, 1, num_pose_heads]).to(device=device)
+ * self.NUM_WITH_AUG_POSE_TOKENS
+ )
+ pose_tokens = pose_tokens + pose_token_id_offsets
+ pose_token_embedding = self._pose_token_emb(pose_tokens)
+ pose_token_embedding = self._proj_pose_token_emb(
+ pose_token_embedding.view([batch_size, num_positions, -1])
+ )
+ pose_token_embedding = pose_token_embedding.view(
+ [
+ batch_size,
+ num_positions * num_frames_per_token,
+ self._args["pose_feat_width"] // num_frames_per_token,
+ ]
+ )
+ dense_has_pose_cond = dense_has_pose_cond[:, :, None].float()
+ pose_embedding = (
+ pose_cond_embedding * dense_has_pose_cond
+ + pose_token_embedding * (1 - dense_has_pose_cond)
+ )
+ pose_embedding = pose_embedding.view(
+ [batch_size, num_positions, self._args["pose_feat_width"]]
+ )
+ num_token_embedding = self._proj_num_valid_positions(
+ num_tokens.reshape([batch_size, 1]) - self._args["min_tokens"]
+ ).expand([-1, num_positions, -1])
+ position_ids = t.arange(num_positions).to(device=device)
+ position_emb = self._position_emb.embed[position_ids].view(
+ [1, num_positions, self._args["n_embd"]]
+ )
+ input_embeddings = (
+ self._proj_input(
+ t.cat([pose_embedding, root_embedding, num_token_embedding], dim=-1)
+ )
+ + position_emb
+ )
+ token_mask = t.arange(num_positions).to(device) < num_tokens.view(
+ [batch_size, -1]
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT and text_embeddings is not None:
+ text_embeddings = self._proj_text_embeddings(text_embeddings)[:, None, :]
+ input_embeddings = t.concat([text_embeddings, input_embeddings], dim=1)
+ mask = t.zeros([batch_size, 1 + num_positions], device=device).bool()
+ mask[:, :1] = ~has_text_embeddings.bool()
+ mask[:, 1:] = ~token_mask.bool()
+ else:
+ mask = ~token_mask.bool()
+ output = self._transformer_model(input_embeddings, src_key_padding_mask=mask)[
+ :, -num_positions:
+ ]
+ pred_logits = self._proj_pose_output_logit(output).reshape(
+ [batch_size, num_positions, num_pose_heads, -1]
+ )
+ return {"pose_logits": pred_logits}
+
+ def get_num_codes(self, include_aug_tokens: bool):
+ """Return the code counts of the pose and root codebooks.
+
+ With include_aug_tokens, the counts include the extra tokens, such as the mask
+ token.
+ """
+ num_codes_per_head = {}
+ for vqvae in ["pose_vqvae", "root_vqvae"]:
+ semantic_dimensions = self._semantic_vq_dimensions(vqvae)
+ if semantic_dimensions is not None:
+ num_codes_per_head[vqvae] = semantic_dimensions.codes_per_head
+ continue
+ nb_code = self._args[vqvae]["nb_code"]
+ len_nb_code = len(np.array(self._args[vqvae]["nb_code"]).reshape([-1]))
+ if len_nb_code > 1:
+ assert np.all(np.array(nb_code) == nb_code[0]), (
+ "fsq config should have the same number of codes for each head"
+ )
+ num_codes_per_head[vqvae] = nb_code[0]
+ else:
+ num_heads = self._args[vqvae]["num_heads"]
+ code_dim = self._args[vqvae]["code_dim"]
+ if self._args[vqvae].get("has_codebook", True):
+ assert code_dim % num_heads == 0, (
+ "code dim cannot be divided by the number of heads."
+ )
+ num_codes_per_head[vqvae] = int(
+ round(2 ** (np.log2(nb_code) / num_heads))
+ )
+ assert num_codes_per_head[vqvae] ** num_heads == nb_code, (
+ "the specified number of code is not compatible with the number of heads."
+ )
+ else:
+ num_codes_per_head[vqvae] = nb_code
+ if include_aug_tokens:
+ return (
+ num_codes_per_head["pose_vqvae"] + 1,
+ num_codes_per_head["root_vqvae"] + 1,
+ )
+ else:
+ return (num_codes_per_head["pose_vqvae"], num_codes_per_head["root_vqvae"])
+
+ def get_num_heads(self):
+ """Return the head counts of the pose and root codebooks."""
+ return (
+ self._args["pose_vqvae"]["num_heads"],
+ self._args["root_vqvae"]["num_heads"],
+ )
+
+ def get_num_frames_per_token(self):
+ """Return the frames per motion token, 2 ** down_t."""
+ return 2 ** self._args["down_t"]
+
+ @property
+ def NUM_WITH_AUG_POSE_TOKENS(self):
+ """Number of pose token values, including the extra tokens."""
+ return self.get_num_codes(include_aug_tokens=True)[0]
+
+ @property
+ def POSE_MASK_ID(self):
+ """Token value that marks a masked pose token."""
+ return self.get_num_codes(include_aug_tokens=True)[0] - 1
+
+ @cached_property
+ def ACCEPT_TEXT_EMB_INPUT(self):
+ """Whether the network takes text embeddings."""
+ return True if self._args.get("text_embeddings", None) is not None else False
+
+
+class root_mmm_network(nn.Module):
+ """Transformer that predicts the root trajectory and the token count for SOMA."""
+
+ def __init__(self, args: Dict, motion_rep: nn.Module):
+ super().__init__()
+ self._args = args
+ self.motion_rep = motion_rep
+ self.global_motion_rep = motion_rep.dual_rep.global_motion_rep
+ self.local_motion_rep = motion_rep.dual_rep.local_motion_rep
+ self.IS_MODEL_TOKENIZED = False
+ self._build_backbone()
+ self._build_input_embeddings()
+
+ def _build_backbone(self):
+ encoder_layer = nn.TransformerEncoderLayer(
+ d_model=self._args["n_embd"], nhead=self._args["n_head"], batch_first=True
+ )
+ self._shared_transformer_model = nn.TransformerEncoder(
+ encoder_layer, num_layers=self._args["n_layers_shared"]
+ )
+ if self._args["n_layers_root_token"] > 0:
+ self._root_token_transformer_model = nn.TransformerEncoder(
+ encoder_layer, num_layers=self._args["n_layers_root_token"]
+ )
+ else:
+ self._root_token_transformer_model = None
+ self._args["local_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["local_root_feature"],
+ ).shape[2]
+ self._args["global_root_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.global_motion_rep,
+ self._args["global_root_feature"],
+ ).shape[2]
+ self._args["local_pose_dim"] = extract_feature_from_motion_rep(
+ t.zeros([1, 1, 1000]),
+ self.local_motion_rep,
+ self._args["local_pose_feature"],
+ ).shape[2]
+ self._conv_output = DoubleCondDecoder(
+ self._args["global_root_dim"],
+ self._args["n_embd"],
+ down_t=self._args["down_t"],
+ width=self._args["width"],
+ depth=self._args["depth"],
+ dilation_growth_rate=self._args["dilation_growth_rate"],
+ activation=self._args["activation"],
+ norm=self._args["norm"],
+ target_cond_dim=self._args["global_root_dim"],
+ external_cond_dim=self._args["n_embd"],
+ )
+
+ def _build_input_embeddings(self):
+ num_frames_per_token = self.get_num_frames_per_token()
+ self._proj_local_pose = nn.Linear(
+ self._args["local_pose_dim"], self._args["pose_feat_dim"]
+ )
+ self._proj_local_root_value = nn.Linear(
+ self.args["local_root_dim"], self._args["local_root_feat_dim"]
+ )
+ self._proj_global_root_value = nn.Linear(
+ self.args["global_root_dim"], self._args["global_root_feat_dim"]
+ )
+ self._no_local_pose_emb = nn.Parameter(
+ torch.randn([self._args["pose_feat_dim"]])
+ )
+ self._no_local_root_emb = nn.Parameter(
+ torch.randn([self._args["local_root_feat_dim"]])
+ )
+ self._no_global_root_emb = nn.Parameter(
+ torch.randn([self._args["global_root_feat_dim"]])
+ )
+ self._conv_no_frame_emb = nn.Parameter(torch.randn([self._args["n_embd"]]))
+ proj_input_dim = (
+ self._args["pose_feat_dim"]
+ + self._args["local_root_feat_dim"]
+ + self._args["global_root_feat_dim"]
+ )
+ self._proj_start_input = mlp(
+ num_layers=self._args["input_feat_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=proj_input_dim,
+ size_out=self._args["n_embd"],
+ )
+ self._proj_end_input = mlp(
+ num_layers=self._args["input_feat_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=proj_input_dim,
+ size_out=self._args["n_embd"],
+ )
+ self._input_position_emb = t.nn.Embedding(
+ num_frames_per_token * 2, self._args["n_embd"]
+ )
+ self._proj_input_num_tokens = t.nn.Embedding(
+ self._args["max_tokens"] - self._args["min_tokens"] + 1 + 1 + 1,
+ self._args["n_embd"],
+ )
+ self._position_emb = PositionEmbedding(
+ seq_length=self._args["max_tokens"], dim=self._args["n_embd"]
+ )
+ self._proj_num_token_output_logit = t.nn.Linear(
+ self._args["n_embd"],
+ self._args["max_tokens"] - self._args["min_tokens"] + 1 + 1,
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT:
+ self._proj_text_embeddings = mlp(
+ num_layers=self._args["input_feat_mlp_num_layers"],
+ layer_width=self._args["n_embd"],
+ size_in=self._args["text_emb_dim"],
+ size_out=self._args["n_embd"],
+ )
+ if (
+ self.USE_HARD_NUM_TOKEN_EMB_FOR_ROOT_PREDICTION
+ and self._root_token_transformer_model is not None
+ ):
+ self._middle_token_emb = t.nn.Embedding(
+ self._args["max_tokens"] - self._args["min_tokens"] + 1 + 1,
+ self._args["n_embd"],
+ )
+
+ def forward(
+ self,
+ global_root_values: t.Tensor,
+ has_global_root_values: t.Tensor,
+ local_root_values: t.Tensor,
+ has_local_root_values: t.Tensor,
+ poses: t.Tensor,
+ has_poses: t.Tensor,
+ num_tokens: t.Tensor,
+ text_embeddings: Optional[t.Tensor] = None,
+ has_text_embeddings: Optional[t.Tensor] = None,
+ groundtruth_num_tokens: t.Tensor = None,
+ allowed_pred_num_tokens: t.Tensor = None,
+ config: dict = {},
+ ):
+ batch_size, device = (poses.shape[0], poses.device)
+ num_frames_per_token = self.get_num_frames_per_token()
+ local_pose_emb = self._proj_local_pose(poses)
+ local_root_emb = self._proj_local_root_value(local_root_values)
+ global_root_emb = self._proj_global_root_value(global_root_values)
+ local_pose_emb = local_pose_emb * has_poses[
+ :, :, None
+ ].float() + self._no_local_pose_emb[None, None, :] * (
+ 1 - has_poses[:, :, None].float()
+ )
+ local_root_emb = local_root_emb * has_local_root_values[
+ :, :, None
+ ].float() + self._no_local_root_emb[None, None, :] * (
+ 1 - has_local_root_values[:, :, None].float()
+ )
+ global_root_emb = global_root_emb * has_global_root_values[
+ :, :, None
+ ].float() + self._no_global_root_emb[None, None, :] * (
+ 1 - has_global_root_values[:, :, None].float()
+ )
+ start_frame_emb = torch.cat(
+ [
+ local_pose_emb[:, :num_frames_per_token, :],
+ local_root_emb[:, :num_frames_per_token, :],
+ global_root_emb[:, :num_frames_per_token, :],
+ ],
+ dim=-1,
+ )
+ start_frame_emb = self._proj_start_input(start_frame_emb)
+ end_frame_emb = torch.cat(
+ [
+ local_pose_emb[:, -num_frames_per_token:, :],
+ local_root_emb[:, -num_frames_per_token:, :],
+ global_root_emb[:, -num_frames_per_token:, :],
+ ],
+ dim=-1,
+ )
+ end_frame_emb = self._proj_end_input(end_frame_emb)
+ frame_emb = torch.cat([start_frame_emb, end_frame_emb], dim=1)
+ positioned_frame_emb = frame_emb + self._input_position_emb.weight[None, :, :]
+ first_stage_time_emb = self._proj_input_num_tokens(
+ num_tokens - self._args["min_tokens"]
+ )
+ first_stage_time_emb = first_stage_time_emb.view(
+ [batch_size, 1, self._args["n_embd"]]
+ )
+ first_stage_input_emb = t.concat(
+ [first_stage_time_emb, positioned_frame_emb], dim=1
+ )
+ if self.ACCEPT_TEXT_EMB_INPUT and text_embeddings is not None:
+ text_embeddings = self._proj_text_embeddings(text_embeddings)[:, None, :]
+ first_stage_input_emb = t.concat(
+ [text_embeddings, first_stage_input_emb], dim=1
+ )
+ first_stage_mask = t.zeros(
+ [batch_size, 1 + 1 + num_frames_per_token * 2], device=device
+ ).bool()
+ first_stage_mask[:, :1] = ~has_text_embeddings.bool()
+ else:
+ first_stage_mask = None
+ first_stage_output_emb = self._shared_transformer_model(
+ first_stage_input_emb, src_key_padding_mask=first_stage_mask
+ )
+ num_token_logits = self._proj_num_token_output_logit(
+ first_stage_output_emb[:, self.TRANSFORMER_TIME_LOGIT_ID, :]
+ )
+ assert self.USE_HARD_NUM_TOKEN_EMB_FOR_ROOT_PREDICTION, (
+ "Only support hard num token emb."
+ )
+ if groundtruth_num_tokens is not None:
+ chosen_token = (
+ groundtruth_num_tokens.view([batch_size]) - self._args["min_tokens"]
+ )
+ else:
+ assert not self.training, "groundtruth_num_tokens is required in training."
+ if not config.get("allow_pred_out_of_reach_num_tokens", True):
+ num_token_logits = num_token_logits.clone()
+ num_token_logits[
+ :, self.OUT_OF_REACH_NUM_TOKENS - self._args["min_tokens"]
+ ] = -t.inf
+ if allowed_pred_num_tokens is not None:
+ num_time_tokens = (
+ self._args["max_tokens"] - self._args["min_tokens"] + 1
+ )
+ modified_num_token_logits = t.where(
+ allowed_pred_num_tokens == 1,
+ num_token_logits[:, :num_time_tokens],
+ t.full([batch_size, num_time_tokens], -t.inf).to(device),
+ )
+ num_token_logits = t.cat(
+ [modified_num_token_logits, num_token_logits[:, num_time_tokens:]],
+ dim=-1,
+ )
+ chosen_token = torch.argmax(num_token_logits, dim=-1).int()
+ chosen_token = t.where(
+ num_tokens.view([batch_size]) == self.MASKED_NUM_TOKENS,
+ chosen_token,
+ num_tokens.view([batch_size]) - self._args["min_tokens"],
+ )
+ position_ids = t.arange(self._args["max_tokens"]).to(device=device)
+ position_emb = self._position_emb.embed[position_ids].view(
+ [1, self._args["max_tokens"], self._args["n_embd"]]
+ )
+ position_emb = position_emb.expand([batch_size, -1, -1])
+ token_mask = (
+ t.arange(self._args["max_tokens"]).view([1, -1]).to(device)
+ < chosen_token.view([-1, 1]) + self._args["min_tokens"]
+ )
+ if self._root_token_transformer_model is None:
+ second_stage_output_emb = position_emb
+ else:
+ second_stage_token_emb = self._middle_token_emb(chosen_token)
+ second_stage_input_emb = t.concat(
+ [
+ second_stage_token_emb[:, None, :],
+ positioned_frame_emb,
+ position_emb,
+ ],
+ dim=1,
+ )
+ second_stage_mask = t.cat(
+ [
+ t.zeros(
+ [batch_size, 1 + num_frames_per_token * 2], device=device
+ ).bool(),
+ ~token_mask,
+ ],
+ dim=1,
+ )
+ second_stage_output_emb = self._root_token_transformer_model(
+ second_stage_input_emb, src_key_padding_mask=second_stage_mask
+ )
+ second_stage_output_emb = second_stage_output_emb[
+ :, -self._args["max_tokens"] :
+ ]
+ pred_num_tokens = chosen_token + self._args["min_tokens"]
+ batch = {}
+ keys = ["frame", "global_root"]
+ num_total_frames = self._args["max_tokens"] * num_frames_per_token
+ batch["has_frame"] = numeric_mask_union(
+ has_poses, has_global_root_values, has_local_root_values
+ )
+ batch["frame"] = t.where(
+ batch["has_frame"][:, :, None].bool(),
+ frame_emb,
+ self._conv_no_frame_emb[None, None, :],
+ )
+ batch["dense_frame"] = t.cat(
+ [
+ batch["frame"][:, :num_frames_per_token],
+ self._conv_no_frame_emb[None, None, :].expand(
+ [batch_size, num_total_frames - num_frames_per_token, -1]
+ ),
+ ],
+ dim=1,
+ )
+ batch["global_root"], batch["has_global_root"] = (
+ global_root_values,
+ has_global_root_values,
+ )
+ batch["dense_global_root"] = t.cat(
+ [
+ batch["global_root"][:, :num_frames_per_token],
+ t.zeros(
+ [
+ batch_size,
+ num_total_frames - num_frames_per_token,
+ self._args["global_root_dim"],
+ ],
+ device=device,
+ ),
+ ],
+ dim=1,
+ )
+ for key in keys:
+ batch["dense_has_" + key] = t.cat(
+ [
+ batch["has_" + key][:, :num_frames_per_token],
+ t.zeros(
+ [batch_size, num_total_frames - num_frames_per_token],
+ dtype=batch["has_" + key].dtype,
+ device=device,
+ ),
+ ],
+ dim=1,
+ )
+ for i in range(num_frames_per_token):
+ offsets = (
+ pred_num_tokens[:, None] * num_frames_per_token
+ - num_frames_per_token
+ + i
+ ).long()
+ batch["dense_" + key] = batch["dense_" + key].scatter(
+ 1,
+ offsets[:, :, None].repeat([1, 1, batch[key].shape[-1]]),
+ batch[key][:, -num_frames_per_token + i][:, None, :],
+ )
+ batch["dense_has_" + key] = batch["dense_has_" + key].scatter(
+ 1,
+ offsets[:, :],
+ batch["has_" + key][:, -num_frames_per_token + i][:, None],
+ )
+ pred_global_root_values = self._conv_output(
+ second_stage_output_emb.transpose(1, 2),
+ external_cond=batch["dense_frame"],
+ target_cond=batch["dense_global_root"],
+ has_target_cond=batch["dense_has_global_root"].bool(),
+ token_mask=token_mask,
+ ).transpose(1, 2)
+ return {
+ "num_token_logits": num_token_logits,
+ "pred_num_tokens": pred_num_tokens,
+ "pred_global_root_values": pred_global_root_values,
+ }
+
+ def get_num_frames_per_token(self):
+ """Return the frames per motion token, 2 ** down_t."""
+ return 2 ** self._args["down_t"]
+
+ @property
+ def args(self):
+ """Network settings from the checkpoint."""
+ return self._args
+
+ @property
+ def OUT_OF_REACH_NUM_TOKENS(self):
+ """Token count class for a target that is out of reach."""
+ return self._args["max_tokens"] + 1
+
+ @property
+ def MASKED_NUM_TOKENS(self):
+ """Token count class for a masked token count."""
+ return self._args["max_tokens"] + 2
+
+ @cached_property
+ def ACCEPT_TEXT_EMB_INPUT(self):
+ """Whether the network takes text embeddings."""
+ return True if self._args.get("text_embeddings", None) is not None else False
+
+ @property
+ def TRANSFORMER_TIME_LOGIT_ID(self):
+ """Index of the token count output in the transformer sequence."""
+ return 1 if self.ACCEPT_TEXT_EMB_INPUT else 0
+
+ @cached_property
+ def USE_HARD_NUM_TOKEN_EMB_FOR_ROOT_PREDICTION(self):
+ """Whether root prediction embeds the exact token count."""
+ return self._args.get("use_hard_num_token_emb_for_root_prediction", False)
diff --git a/tools/onnx/models/soma/rotations.py b/tools/onnx/models/soma/rotations.py
new file mode 100644
index 0000000..ea3c099
--- /dev/null
+++ b/tools/onnx/models/soma/rotations.py
@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"Rotation conversion for the SOMA inference wrapper."
+
+from __future__ import annotations
+
+import torch
+
+
+def cont6d_to_matrix(cont6d):
+ """Convert 6D rotations to rotation matrices."""
+ assert cont6d.shape[-1] == 6, "The last dimension must be 6"
+ x_raw = cont6d[..., 0:3]
+ y_raw = cont6d[..., 3:6]
+ x = x_raw / torch.norm(x_raw, dim=-1, keepdim=True)
+ z = torch.cross(x, y_raw, dim=-1)
+ z = z / torch.norm(z, dim=-1, keepdim=True)
+ y = torch.cross(z, x, dim=-1)
+ x = x[..., None]
+ y = y[..., None]
+ z = z[..., None]
+ mat = torch.cat([x, y, z], dim=-1)
+ return mat
+
+
+def matrix_to_cont6d(matrix):
+ """Convert rotation matrices to 6D rotations, their first two columns."""
+ cont_6d = torch.concat([matrix[..., 0], matrix[..., 1]], dim=-1)
+ return cont_6d
+
+
+def change_t_pose_global_mats_onnx_compatible(
+ global_mats: torch.Tensor,
+ global_offset_from: torch.Tensor,
+ global_offset_to: torch.Tensor,
+):
+ """Move global joint rotations from one T pose to another.
+
+ Each result is global_mats @ offset_from @ offset_to^T.
+ """
+ dtype = global_mats.dtype
+ device = global_mats.device
+ new_global_mats = torch.matmul(
+ torch.matmul(
+ global_mats, global_offset_from[None, None].to(device=device, dtype=dtype)
+ ),
+ global_offset_to.transpose(-1, -2)[None, None].to(device=device, dtype=dtype),
+ )
+ return new_global_mats
diff --git a/tools/onnx/models/vqvae.py b/tools/onnx/models/vqvae.py
new file mode 100644
index 0000000..46da6fc
--- /dev/null
+++ b/tools/onnx/models/vqvae.py
@@ -0,0 +1,179 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""VQ-VAE decoding shared by SOMA and G1, compatible with their checkpoints."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import torch as t
+from torch import nn
+
+from .features import (
+ convert_sparse_cond_to_dense_cond_if_needed,
+ extract_feature_from_motion_rep,
+)
+from .layers import DoubleCondDecoder, Encoder
+from .quantizer import QuantizeEMAResetMultiHead, resolve_multihead_vq_dimensions
+
+
+class VQVAE(nn.Module):
+ """VQ-VAE that turns motion tokens back into motion features.
+
+ Only its decoder runs at export.
+ """
+
+ ALLOWED_FEATURE_MODE = [
+ "invalid",
+ "pose",
+ "root",
+ "root_without_hip_height",
+ "root_without_hip_height_without_heading",
+ "root_without_heading",
+ "root_without_hip_height_without_heading_with_mask",
+ "joint_positions_and_rotations",
+ "joint_positions_and_rotations_and_foot_contact",
+ "joint_positions_and_rotations_and_hip_height",
+ ]
+
+ def __init__(
+ self,
+ pose_root_mode: str,
+ motion_rep: nn.Module,
+ feature_mode: Optional[List[str]] = None,
+ nb_code: Optional[int] = None,
+ code_dim: Optional[int] = None,
+ output_emb_width: Optional[int] = None,
+ down_t: int = 2,
+ stride_t: int = 2,
+ width: int = 512,
+ depth: int = 3,
+ dilation_growth_rate: int = 3,
+ activation: str = "relu",
+ num_heads: int = 4,
+ codes_per_head: Optional[int] = None,
+ code_dim_per_head: Optional[int] = None,
+ norm: Optional[str] = None,
+ cond_fusion_last_layer: bool = False,
+ decoder_type: type[nn.Module] = DoubleCondDecoder,
+ ):
+ super().__init__()
+ if feature_mode is None or len(feature_mode) != 4:
+ raise ValueError("feature_mode must contain exactly four feature names.")
+ invalid_features = [
+ feature
+ for feature in feature_mode
+ if feature not in self.ALLOWED_FEATURE_MODE
+ ]
+ if invalid_features:
+ raise ValueError(f"Unsupported feature modes: {invalid_features}.")
+ if pose_root_mode not in ("pose", "root"):
+ raise ValueError("pose_root_mode must be 'pose' or 'root'.")
+ if codes_per_head is None and nb_code is None:
+ nb_code = 512
+ if code_dim_per_head is None and code_dim is None:
+ code_dim = 512
+ quantizer_dimensions = resolve_multihead_vq_dimensions(
+ num_heads=num_heads,
+ codes_per_head=codes_per_head,
+ code_dim_per_head=code_dim_per_head,
+ nb_code=nb_code,
+ code_dim=code_dim,
+ )
+ if output_emb_width is None:
+ output_emb_width = quantizer_dimensions.latent_dim
+ if output_emb_width != quantizer_dimensions.latent_dim:
+ raise ValueError(
+ f"output_emb_width={output_emb_width} must match the resolved latent dimension "
+ f"{quantizer_dimensions.latent_dim}."
+ )
+ self.code_dim = quantizer_dimensions.latent_dim
+ self.num_code = quantizer_dimensions.combined_code_space
+ self._motion_rep = motion_rep
+ self._pose_root_mode = pose_root_mode
+ self._down_t = down_t
+ (
+ self.encoder_input_feature_mode,
+ self.decoder_input_feature_mode,
+ self.decoder_target_cond_feature_mode,
+ self.decoder_external_cond_feature_mode,
+ ) = feature_mode
+ example = t.zeros([1, 1, len(motion_rep.indices["all"])])
+ encoder_dim, decoder_dim, target_dim, external_dim = (
+ int(extract_feature_from_motion_rep(example, motion_rep, feature).shape[-1])
+ for feature in feature_mode
+ )
+ self.encoder = Encoder(
+ encoder_dim,
+ output_emb_width,
+ down_t,
+ stride_t,
+ width,
+ depth,
+ dilation_growth_rate,
+ activation=activation,
+ norm=norm,
+ )
+ self.decoder = decoder_type(
+ decoder_dim,
+ output_emb_width,
+ down_t,
+ width,
+ depth,
+ dilation_growth_rate,
+ activation=activation,
+ norm=norm,
+ target_cond_dim=target_dim,
+ external_cond_dim=external_dim,
+ cond_fusion_last_layer=cond_fusion_last_layer,
+ )
+ self.quantizer = QuantizeEMAResetMultiHead(
+ self.num_code, self.code_dim, num_heads
+ )
+
+ def extract_feature(self, x: t.Tensor, feature: str = ""):
+ """Select a feature with extract_feature_from_motion_rep().
+
+ An empty feature selects pose_root_mode.
+ """
+ feature = self._pose_root_mode if feature == "" else feature
+ return extract_feature_from_motion_rep(x, self._motion_rep, feature)
+
+ def forward_decoder(
+ self,
+ x,
+ target_cond: t.Tensor,
+ has_target_cond: t.Tensor = None,
+ external_cond: t.Tensor = None,
+ use_overall_indices: bool = True,
+ token_mask: t.Tensor = None,
+ ):
+ """Decode tokens into motion features, conditioned on the target poses."""
+ num_expected_frames = x.shape[1] * 2**self._down_t
+ x_d = self.quantizer.dequantize(x, use_overall_indices=use_overall_indices)
+ x_quantized = x_d.permute(0, 2, 1).contiguous()
+ if target_cond is not None:
+ target_cond, has_target_cond = convert_sparse_cond_to_dense_cond_if_needed(
+ target_cond, has_target_cond, num_expected_frames
+ )
+ target_cond = self.extract_feature(
+ target_cond, self.decoder_target_cond_feature_mode
+ )
+ x_decoder = self.decoder(
+ x_quantized,
+ external_cond,
+ target_cond,
+ has_target_cond,
+ token_mask=token_mask,
+ )
+ return {"recon_state": x_decoder.permute(0, 2, 1)}
+
+ @property
+ def pose_root_mode(self):
+ """What the VQ-VAE models: "pose" or "root"."""
+ return self._pose_root_mode
+
+ @property
+ def motion_rep(self):
+ """Motion feature layout of the decoded features."""
+ return self._motion_rep
diff --git a/tools/onnx/precision.py b/tools/onnx/precision.py
new file mode 100644
index 0000000..fe5f2fe
--- /dev/null
+++ b/tools/onnx/precision.py
@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Mixed precision conversion for the released ONNX models."""
+
+from collections import defaultdict
+import numpy as np
+import onnx
+from onnx import TensorProto as T, helper, numpy_helper
+
+
+def g1_fp16(model):
+ """Use FP16 for the neural network and FP32 for sensitive and geometric operations."""
+ # matrix_quat gathers exactly one candidate at axis -2: (N,64,1,4).
+ # Inline the exporter's guaranteed singleton Squeeze branch.
+ conditionals = [n for n in model.graph.node if n.op_type == "If"]
+ assert len(conditionals) == 1 and conditionals[0].name == "/post/If"
+ conditional = conditionals[0]
+ branch = next(a.g for a in conditional.attribute if a.name == "then_branch")
+ assert [n.op_type for n in branch.node] == ["Constant", "Squeeze"]
+ assert numpy_helper.to_array(branch.node[0].attribute[0].t).tolist() == [-2]
+ branch.node[-1].output[0] = conditional.output[0]
+ nodes = []
+ for node in model.graph.node:
+ nodes.extend(branch.node if node.name == conditional.name else [node])
+ del model.graph.node[:]
+ model.graph.node.extend(nodes)
+ return convert_networks_to_fp16(model, ("/core/backbone_net/", "/core/decoder/"))
+
+
+def soma_fp16(model):
+ """Convert the SOMA predictors and decoder, keeping motion geometry in FP32."""
+ return convert_networks_to_fp16(model, ("/mmm_net/", "/decoder/"))
+
+
+def convert_networks_to_fp16(model, prefixes):
+ """Convert network operations and insert casts at precision boundaries."""
+ if any(n.op_type in {"If", "Loop", "Scan"} for n in model.graph.node):
+ raise ValueError(
+ "Mixed precision conversion requires a graph without control flow."
+ )
+ model = onnx.shape_inference.infer_shapes(model, strict_mode=True)
+ graph = model.graph
+ values = list(graph.input) + list(graph.value_info) + list(graph.output)
+ original = {v.name: v.type.tensor_type.elem_type for v in values}
+ original.update({v.name: v.data_type for v in graph.initializer})
+ assert all(name in original for n in graph.node for name in n.output)
+ # Keep the numerically sensitive normalization and attention reductions in full
+ # precision. Geometry, integration, and the public I/O stay in full precision too.
+ precision = {
+ n.name: (
+ T.FLOAT16
+ if n.name.startswith(prefixes)
+ and n.op_type not in ("LayerNormalization", "Softmax", "Resize")
+ else T.FLOAT
+ )
+ for n in graph.node
+ }
+ consumers = defaultdict(set)
+ for n in graph.node:
+ for name in n.input:
+ consumers[name].add(precision[n.name])
+ actual = dict(original)
+ for tensor in graph.initializer:
+ if tensor.data_type == T.FLOAT and consumers[tensor.name] == {T.FLOAT16}:
+ tensor.CopyFrom(
+ numpy_helper.from_array(
+ numpy_helper.to_array(tensor).astype(np.float16), tensor.name
+ )
+ )
+ actual[tensor.name] = T.FLOAT16
+ for n in graph.node:
+ for name in n.output:
+ if original[name] == T.FLOAT:
+ actual[name] = precision[n.name]
+ rewritten, cast_names = [], {}
+
+ def cast_input(name, dtype):
+ key = (name, dtype)
+ if key not in cast_names:
+ out = name + ("__fp16" if dtype == T.FLOAT16 else "__fp32")
+ assert out not in actual
+ rewritten.append(
+ helper.make_node("Cast", [name], [out], name=out + "_cast", to=dtype)
+ )
+ cast_names[key] = out
+ actual[out] = dtype
+ return cast_names[key]
+
+ for n in graph.node:
+ dtype = precision[n.name]
+ for i, name in enumerate(n.input):
+ if original.get(name) == T.FLOAT and actual[name] != dtype:
+ n.input[i] = cast_input(name, dtype)
+ if dtype == T.FLOAT16:
+ for attr in n.attribute:
+ if (
+ attr.type == onnx.AttributeProto.TENSOR
+ and attr.t.data_type == T.FLOAT
+ ):
+ # Ordinary IEEE half conversion, which keeps the attention -inf values.
+ attr.t.CopyFrom(
+ numpy_helper.from_array(
+ numpy_helper.to_array(attr.t).astype(np.float16),
+ attr.t.name,
+ )
+ )
+ elif n.op_type == "Cast" and attr.name == "to" and attr.i == T.FLOAT:
+ attr.i = T.FLOAT16
+ rewritten.append(n)
+ for v in graph.value_info:
+ if original[v.name] == T.FLOAT:
+ v.type.tensor_type.elem_type = actual[v.name]
+ assert all(actual[v.name] == v.type.tensor_type.elem_type for v in graph.output)
+ del graph.node[:]
+ graph.node.extend(rewritten)
+ # Re-infer all new boundary edges and check operator dtype consistency.
+ model = onnx.shape_inference.infer_shapes(model, strict_mode=True)
+ onnx.checker.check_model(model, full_check=True)
+ return model
diff --git a/tools/onnx/pyproject.toml b/tools/onnx/pyproject.toml
new file mode 100644
index 0000000..ea0b9a9
--- /dev/null
+++ b/tools/onnx/pyproject.toml
@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools >= 77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "motionbricks-onnx"
+dynamic = ["version"]
+description = "Export MotionBricks checkpoints to batched ONNX models"
+license = "Apache-2.0"
+license-files = ["licenses/**/*.txt"]
+requires-python = ">=3.12,<3.13"
+dependencies = [
+ "numpy==1.26.4",
+ "onnx==1.23.2",
+ "safetensors==0.8.0",
+ "torch==2.14.0+cpu",
+]
+
+[project.scripts]
+motionbricks-onnx = "motionbricks_onnx.export:main"
+
+[tool.setuptools]
+package-dir = { motionbricks_onnx = "." }
+include-package-data = false
+
+[tool.setuptools.package-data]
+motionbricks_onnx = ["assets/**/*"]
+
+[tool.setuptools.dynamic]
+version = { attr = "motionbricks_onnx.__version__" }
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = { index = "pytorch-cpu" }
+
+[tool.uv]
+managed = true
diff --git a/tools/onnx/setup.py b/tools/onnx/setup.py
new file mode 100644
index 0000000..e569b87
--- /dev/null
+++ b/tools/onnx/setup.py
@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Discover subpackages under the installed name while keeping the source layout."""
+
+from setuptools import find_packages, setup
+
+if __name__ == "__main__":
+ setup(
+ packages=[
+ "motionbricks_onnx",
+ *(
+ f"motionbricks_onnx.{name}"
+ for name in find_packages(exclude=["tests", "tests.*"])
+ ),
+ ]
+ )
diff --git a/tools/onnx/tests/test_export.py b/tools/onnx/tests/test_export.py
new file mode 100644
index 0000000..ef0b16a
--- /dev/null
+++ b/tools/onnx/tests/test_export.py
@@ -0,0 +1,262 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Check checkpoint validation, output preservation, and the tensors of exported models."""
+
+import hashlib
+from itertools import product
+import json
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+
+import numpy as np
+import onnx
+from onnx import TensorProto, helper
+
+from motionbricks_onnx import checkpoints, export
+
+_ONNX_ASSETS = Path(__file__).resolve().parents[3] / "motionbricks" / "assets" / "onnx"
+_MODEL_MANIFESTS = {
+ "soma": _ONNX_ASSETS / "soma" / "soma_n1.json",
+ "g1": _ONNX_ASSETS / "unitree_g1" / "unitree_g1_n1.json",
+}
+
+
+def g1_graph():
+ """A small, valid batched graph with the documented G1 interface."""
+ inputs = [
+ helper.make_tensor_value_info(name, dtype, ["N", *shape])
+ for name, dtype, shape in (
+ ("context_qpos", TensorProto.FLOAT, (4, 36)),
+ ("target_qpos", TensorProto.FLOAT, (4, 36)),
+ ("has_global_root_values", TensorProto.INT32, (8,)),
+ ("has_local_root_values", TensorProto.INT32, (8,)),
+ ("has_local_poses", TensorProto.INT32, (8,)),
+ ("allowed_pred_num_tokens", TensorProto.INT32, (11,)),
+ )
+ ]
+ outputs = [
+ helper.make_tensor_value_info("pred_qpos", TensorProto.FLOAT, ["N", 64, 36]),
+ helper.make_tensor_value_info("pred_num_tokens", TensorProto.INT32, ["N"]),
+ helper.make_tensor_value_info(
+ "pred_foot_contacts", TensorProto.FLOAT, ["N", 64, 4]
+ ),
+ ]
+ nodes = [
+ helper.make_node("Shape", ["context_qpos"], ["context_shape"]),
+ helper.make_node("Gather", ["context_shape", "batch_index"], ["batch_shape"]),
+ helper.make_node(
+ "Concat", ["batch_shape", "pose_shape"], ["output_shape"], axis=0
+ ),
+ helper.make_node(
+ "ConstantOfShape",
+ ["output_shape"],
+ ["pred_qpos"],
+ value=helper.make_tensor("zero", TensorProto.FLOAT, [1], [0]),
+ ),
+ helper.make_node(
+ "ConstantOfShape",
+ ["batch_shape"],
+ ["pred_num_tokens"],
+ value=helper.make_tensor("zero", TensorProto.INT32, [1], [0]),
+ ),
+ helper.make_node(
+ "Concat", ["batch_shape", "contact_shape"], ["contact_output_shape"], axis=0
+ ),
+ helper.make_node(
+ "ConstantOfShape",
+ ["contact_output_shape"],
+ ["pred_foot_contacts"],
+ value=helper.make_tensor("zero", TensorProto.FLOAT, [1], [0]),
+ ),
+ ]
+ graph = helper.make_graph(
+ nodes,
+ "test_g1",
+ inputs,
+ outputs,
+ initializer=[
+ helper.make_tensor("batch_index", TensorProto.INT64, [1], [0]),
+ helper.make_tensor("pose_shape", TensorProto.INT64, [2], [64, 36]),
+ helper.make_tensor("contact_shape", TensorProto.INT64, [2], [64, 4]),
+ ],
+ )
+ return helper.make_model(graph, opset_imports=[helper.make_opsetid("", 17)])
+
+
+class ReleaseExportTests(unittest.TestCase):
+ def test_missing_or_corrupt_checkpoints_reject_both_models_before_loading(self):
+ original = b"original checkpoint"
+ expected = dict(
+ bytes=len(original), sha256=hashlib.sha256(original).hexdigest()
+ )
+ release = dict(root_directory="out", files=[dict(expected, path="model.safetensors")])
+ # A corrupt file sits in the downloaded folder itself, or in its root_directory.
+ # A missing file is a folder without the checkpoint, such as a wrong path.
+ for kind, layout in product(("soma", "g1"), ("direct", "nested", "missing")):
+ with (
+ self.subTest(model=kind, layout=layout),
+ tempfile.TemporaryDirectory() as directory,
+ ):
+ root = Path(directory)
+ if layout != "missing":
+ files = root if layout == "direct" else root / "out"
+ files.mkdir(exist_ok=True)
+ # Corrupt one byte while keeping the expected file size.
+ (files / "model.safetensors").write_bytes(b"X" + original[1:])
+ output = root / "existing.onnx"
+ output.write_bytes(b"keep this file")
+ with (
+ patch.dict(export.CHECKPOINTS, {kind: release}),
+ patch.object(export, "check_environment"),
+ patch.object(
+ checkpoints,
+ "load_file",
+ side_effect=AssertionError("must not deserialize"),
+ ),
+ patch.object(
+ export,
+ "export_fp32",
+ side_effect=AssertionError("must not export"),
+ ),
+ ):
+ message = "Missing checkpoint file" if layout == "missing" else "Checksum mismatch"
+ with self.assertRaisesRegex(ValueError, message):
+ export.export_release(f"{kind}_fp32", root, output, force=True)
+ self.assertEqual(output.read_bytes(), b"keep this file")
+
+ def test_existing_output_is_preserved(self):
+ with tempfile.TemporaryDirectory() as directory:
+ output = Path(directory) / "existing.onnx"
+ output.write_bytes(b"keep this file")
+ with self.assertRaisesRegex(ValueError, "already exists"):
+ export.export_release("g1_fp32", Path("missing"), output)
+ self.assertEqual(output.read_bytes(), b"keep this file")
+
+ def test_force_preserves_output_when_export_is_invalid(self):
+ with tempfile.TemporaryDirectory() as directory:
+ output = Path(directory) / "existing.onnx"
+ output.write_bytes(b"keep this file")
+
+ def invalid_export(kind, model, path):
+ path.write_bytes(b"not an ONNX graph")
+
+ with (
+ patch.object(export, "check_environment"),
+ patch.object(export, "checkpoint_root", return_value=Path(directory)),
+ patch.object(export, "load_sources", return_value={}),
+ patch(
+ "motionbricks_onnx.models.g1.build_g1",
+ return_value=export.torch.nn.Identity(),
+ ),
+ patch.object(export, "export_fp32", side_effect=invalid_export),
+ ):
+ with self.assertRaisesRegex(ValueError, "Invalid ONNX model"):
+ export.export_release(
+ "g1_fp32", Path(directory), output, force=True
+ )
+ self.assertEqual(output.read_bytes(), b"keep this file")
+ self.assertEqual(list(Path(directory).iterdir()), [output])
+
+ def test_valid_export_can_replace_different_onnx_bytes(self):
+ with tempfile.TemporaryDirectory() as directory:
+ output = Path(directory) / "model.onnx"
+ graph = g1_graph()
+ onnx.save(graph, output)
+ previous = output.read_bytes()
+ graph.producer_name = "another exporter serialization"
+ with (
+ patch.object(export, "check_environment"),
+ patch.object(export, "checkpoint_root", return_value=Path(directory)),
+ patch.object(export, "load_sources", return_value={}),
+ patch(
+ "motionbricks_onnx.models.g1.build_g1",
+ return_value=export.torch.nn.Identity(),
+ ),
+ patch.object(
+ export,
+ "export_fp32",
+ side_effect=lambda kind, model, path: onnx.save(graph, path),
+ ),
+ ):
+ export.export_release("g1_fp32", Path(directory), output, force=True)
+ self.assertNotEqual(output.read_bytes(), previous)
+ self.assertEqual(onnx.load(output).producer_name, graph.producer_name)
+ self.assertEqual(list(Path(directory).iterdir()), [output])
+
+ def test_incompatible_tensor_interfaces_are_rejected(self):
+ for mismatch in (
+ "name",
+ "dtype",
+ "rank",
+ "shape",
+ "fixed_batch",
+ "different_batch",
+ ):
+ with (
+ self.subTest(mismatch=mismatch),
+ tempfile.TemporaryDirectory() as directory,
+ ):
+ graph = g1_graph()
+ value = graph.graph.input[1]
+ tensor = value.type.tensor_type
+ if mismatch == "name":
+ value.name = "unexpected_target"
+ elif mismatch == "dtype":
+ tensor.elem_type = TensorProto.FLOAT16
+ elif mismatch == "rank":
+ del tensor.shape.dim[-1]
+ elif mismatch == "shape":
+ tensor.shape.dim[-1].dim_value = 35
+ elif mismatch == "fixed_batch":
+ tensor.shape.dim[0].dim_value = 1
+ else:
+ tensor.shape.dim[0].dim_param = "different_batch"
+ path = Path(directory) / "incompatible.onnx"
+ onnx.save(graph, path)
+ with self.assertRaisesRegex(ValueError, "ONNX|symbolic batch"):
+ export.validate_output(path, "g1")
+
+ def test_bundled_models_have_the_tensors_the_runtime_expects(self):
+ # The bundled models are what the exporter produces from the released checkpoints.
+ # The runtime checks each TensorRT engine against the tensor specs in its manifest.
+ for kind, manifest_path in _MODEL_MANIFESTS.items():
+ manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+ filenames = [manifest["onnx_filename"]] + [
+ variant["onnx_filename"] for variant in manifest["precision_variants"].values()
+ ]
+ for filename in filenames:
+ path = manifest_path.parent / filename
+ with self.subTest(model=filename):
+ if path.stat().st_size < 1024:
+ self.skipTest(f"Git LFS has not fetched {filename}.")
+ export.validate_output(path, kind)
+ graph = onnx.load(path).graph
+ tensors = {value.name: ("input", value) for value in graph.input}
+ tensors |= {value.name: ("output", value) for value in graph.output}
+ self.assertEqual(set(tensors), {spec["name"] for spec in manifest["tensor_specs"]})
+ for spec in manifest["tensor_specs"]:
+ mode, value = tensors[spec["name"]]
+ tensor = value.type.tensor_type
+ self.assertEqual(mode, spec["mode"], spec["name"])
+ self.assertEqual(
+ helper.tensor_dtype_to_np_dtype(tensor.elem_type), np.dtype(spec["dtype"]), spec["name"]
+ )
+ self.assertEqual(len(tensor.shape.dim), len(spec["shape"]), spec["name"])
+ # The batch dimension is symbolic. Some SOMA output sizes stay symbolic
+ # until TensorRT builds the engine.
+ for dimension, size in zip(tensor.shape.dim[1:], spec["shape"][1:]):
+ if not (mode == "output" and dimension.dim_param):
+ self.assertEqual(dimension.dim_value, size, spec["name"])
+
+ def test_checkpoints_must_be_a_folder(self):
+ with tempfile.TemporaryDirectory() as directory:
+ path = Path(directory) / "checkpoints.txt"
+ path.write_bytes(b"not a folder")
+ with self.assertRaisesRegex(ValueError, "must be a folder"):
+ checkpoints.checkpoint_root(path, export.CHECKPOINTS["g1"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/onnx/uv.lock b/tools/onnx/uv.lock
new file mode 100644
index 0000000..4a76155
--- /dev/null
+++ b/tools/onnx/uv.lock
@@ -0,0 +1,235 @@
+version = 1
+revision = 3
+requires-python = "==3.12.*"
+resolution-markers = [
+ "platform_machine != 's390x'",
+ "platform_machine == 's390x'",
+]
+
+[[package]]
+name = "filelock"
+version = "4.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/38/88cd6eda96c40594a1e3da7d8b40f04bc40ace5a6aef9ac5cb407540f173/filelock-4.0.1.tar.gz", hash = "sha256:fdefc3f3e87716d855ae2b732c1cfd521dd99799ef2b4d00e8c0d4dcdc7cc94b", size = 238888, upload-time = "2026-09-19T01:08:15.958Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/29/33/af0635ab07fe83b1788a1dbe370ff3e226062495a998335cb18a1cac81aa/filelock-4.0.1-py3-none-any.whl", hash = "sha256:481a321a27bef441e23c53371c6abc8d7d16e26b97090074ba44f7538a3fd55a", size = 106219, upload-time = "2026-09-19T01:08:14.49Z" },
+]
+
+[[package]]
+name = "fsspec"
+version = "2026.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/77/cd/9be253869fc42e764de7f3dedd6969af7d44ff9c3375214a3442a6f3fc08/fsspec-2026.9.0.tar.gz", hash = "sha256:0f08147951c8cb31d844c3547d631053b127863b60be04cf06e121333ee0e2fe", size = 333545, upload-time = "2026-09-18T17:50:42.825Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/6c/c0/a98505f18594f1bce828bb159cec0fcf9860562f1a2c85913409fc8f3d9e/fsspec-2026.9.0-py3-none-any.whl", hash = "sha256:8dd6e646e99ea382bd85f97a45e6b526a442d79423a7dc673f1e2756d05fcb5f", size = 221738, upload-time = "2026-09-18T17:50:41.341Z" },
+]
+
+[[package]]
+name = "jinja2"
+version = "3.1.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "markupsafe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/df/bf/f7da0350254c0ed7c72f3e33cef02e048281fec7ecec5f032d4aac52226b/jinja2-3.1.6.tar.gz", hash = "sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d", size = 245115, upload-time = "2025-03-05T20:05:02.478Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" },
+]
+
+[[package]]
+name = "markupsafe"
+version = "3.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7e/99/7690b6d4034fffd95959cbe0c02de8deb3098cc577c67bb6a24fe5d7caa7/markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", size = 80313, upload-time = "2025-09-27T18:37:40.426Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/5a/72/147da192e38635ada20e0a2e1a51cf8823d2119ce8883f7053879c2199b5/markupsafe-3.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d53197da72cc091b024dd97249dfc7794d6a56530370992a5e1a08983ad9230e", size = 11615, upload-time = "2025-09-27T18:36:30.854Z" },
+ { url = "https://files.pythonhosted.org/packages/9a/81/7e4e08678a1f98521201c3079f77db69fb552acd56067661f8c2f534a718/markupsafe-3.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1872df69a4de6aead3491198eaf13810b565bdbeec3ae2dc8780f14458ec73ce", size = 12020, upload-time = "2025-09-27T18:36:31.971Z" },
+ { url = "https://files.pythonhosted.org/packages/1e/2c/799f4742efc39633a1b54a92eec4082e4f815314869865d876824c257c1e/markupsafe-3.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3a7e8ae81ae39e62a41ec302f972ba6ae23a5c5396c8e60113e9066ef893da0d", size = 24332, upload-time = "2025-09-27T18:36:32.813Z" },
+ { url = "https://files.pythonhosted.org/packages/3c/2e/8d0c2ab90a8c1d9a24f0399058ab8519a3279d1bd4289511d74e909f060e/markupsafe-3.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d6dd0be5b5b189d31db7cda48b91d7e0a9795f31430b7f271219ab30f1d3ac9d", size = 22947, upload-time = "2025-09-27T18:36:33.86Z" },
+ { url = "https://files.pythonhosted.org/packages/2c/54/887f3092a85238093a0b2154bd629c89444f395618842e8b0c41783898ea/markupsafe-3.0.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:94c6f0bb423f739146aec64595853541634bde58b2135f27f61c1ffd1cd4d16a", size = 21962, upload-time = "2025-09-27T18:36:35.099Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/2f/336b8c7b6f4a4d95e91119dc8521402461b74a485558d8f238a68312f11c/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:be8813b57049a7dc738189df53d69395eba14fb99345e0a5994914a3864c8a4b", size = 23760, upload-time = "2025-09-27T18:36:36.001Z" },
+ { url = "https://files.pythonhosted.org/packages/32/43/67935f2b7e4982ffb50a4d169b724d74b62a3964bc1a9a527f5ac4f1ee2b/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:83891d0e9fb81a825d9a6d61e3f07550ca70a076484292a70fde82c4b807286f", size = 21529, upload-time = "2025-09-27T18:36:36.906Z" },
+ { url = "https://files.pythonhosted.org/packages/89/e0/4486f11e51bbba8b0c041098859e869e304d1c261e59244baa3d295d47b7/markupsafe-3.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:77f0643abe7495da77fb436f50f8dab76dbc6e5fd25d39589a0f1fe6548bfa2b", size = 23015, upload-time = "2025-09-27T18:36:37.868Z" },
+ { url = "https://files.pythonhosted.org/packages/2f/e1/78ee7a023dac597a5825441ebd17170785a9dab23de95d2c7508ade94e0e/markupsafe-3.0.3-cp312-cp312-win32.whl", hash = "sha256:d88b440e37a16e651bda4c7c2b930eb586fd15ca7406cb39e211fcff3bf3017d", size = 14540, upload-time = "2025-09-27T18:36:38.761Z" },
+ { url = "https://files.pythonhosted.org/packages/aa/5b/bec5aa9bbbb2c946ca2733ef9c4ca91c91b6a24580193e891b5f7dbe8e1e/markupsafe-3.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:26a5784ded40c9e318cfc2bdb30fe164bdb8665ded9cd64d500a34fb42067b1c", size = 15105, upload-time = "2025-09-27T18:36:39.701Z" },
+ { url = "https://files.pythonhosted.org/packages/e5/f1/216fc1bbfd74011693a4fd837e7026152e89c4bcf3e77b6692fba9923123/markupsafe-3.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:35add3b638a5d900e807944a078b51922212fb3dedb01633a8defc4b01a3c85f", size = 13906, upload-time = "2025-09-27T18:36:40.689Z" },
+]
+
+[[package]]
+name = "ml-dtypes"
+version = "0.5.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "numpy" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0e/4a/c27b42ed9b1c7d13d9ba8b6905dece787d6259152f2309338aed29b2447b/ml_dtypes-0.5.4.tar.gz", hash = "sha256:8ab06a50fb9bf9666dd0fe5dfb4676fa2b0ac0f31ecff72a6c3af8e22c063453", size = 692314, upload-time = "2025-11-17T22:32:31.031Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a8/b8/3c70881695e056f8a32f8b941126cf78775d9a4d7feba8abcb52cb7b04f2/ml_dtypes-0.5.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a174837a64f5b16cab6f368171a1a03a27936b31699d167684073ff1c4237dac", size = 676927, upload-time = "2025-11-17T22:31:48.182Z" },
+ { url = "https://files.pythonhosted.org/packages/54/0f/428ef6881782e5ebb7eca459689448c0394fa0a80bea3aa9262cba5445ea/ml_dtypes-0.5.4-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a7f7c643e8b1320fd958bf098aa7ecf70623a42ec5154e3be3be673f4c34d900", size = 5028464, upload-time = "2025-11-17T22:31:50.135Z" },
+ { url = "https://files.pythonhosted.org/packages/3a/cb/28ce52eb94390dda42599c98ea0204d74799e4d8047a0eb559b6fd648056/ml_dtypes-0.5.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9ad459e99793fa6e13bd5b7e6792c8f9190b4e5a1b45c63aba14a4d0a7f1d5ff", size = 5009002, upload-time = "2025-11-17T22:31:52.001Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/f0/0cfadd537c5470378b1b32bd859cf2824972174b51b873c9d95cfd7475a5/ml_dtypes-0.5.4-cp312-cp312-win_amd64.whl", hash = "sha256:c1a953995cccb9e25a4ae19e34316671e4e2edaebe4cf538229b1fc7109087b7", size = 212222, upload-time = "2025-11-17T22:31:53.742Z" },
+ { url = "https://files.pythonhosted.org/packages/16/2e/9acc86985bfad8f2c2d30291b27cd2bb4c74cea08695bd540906ed744249/ml_dtypes-0.5.4-cp312-cp312-win_arm64.whl", hash = "sha256:9bad06436568442575beb2d03389aa7456c690a5b05892c471215bfd8cf39460", size = 160793, upload-time = "2025-11-17T22:31:55.358Z" },
+]
+
+[[package]]
+name = "motionbricks-onnx"
+source = { editable = "." }
+dependencies = [
+ { name = "numpy" },
+ { name = "onnx" },
+ { name = "safetensors" },
+ { name = "torch" },
+]
+
+[package.metadata]
+requires-dist = [
+ { name = "numpy", specifier = "==1.26.4" },
+ { name = "onnx", specifier = "==1.23.2" },
+ { name = "safetensors", specifier = "==0.8.0" },
+ { name = "torch", specifier = "==2.14.0+cpu", index = "https://download.pytorch.org/whl/cpu" },
+]
+
+[[package]]
+name = "mpmath"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e0/47/dd32fa426cc72114383ac549964eecb20ecfd886d1e5ccf5340b55b02f57/mpmath-1.3.0.tar.gz", hash = "sha256:7a28eb2a9774d00c7bc92411c19a89209d5da7c4c9a9e227be8330a23a25b91f", size = 508106, upload-time = "2023-03-07T16:47:11.061Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/43/e3/7d92a15f894aa0c9c4b49b8ee9ac9850d6e63b03c9c32c0367a13ae62209/mpmath-1.3.0-py3-none-any.whl", hash = "sha256:a0b2b9fe80bbcd81a6647ff13108738cfb482d481d826cc0e02f5b35e5c88d2c", size = 536198, upload-time = "2023-03-07T16:47:09.197Z" },
+]
+
+[[package]]
+name = "networkx"
+version = "3.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/dc/76/3af777226b63a5e64a6b36b1ec5855c14e2b94a37096d4760e595fc43511/networkx-3.7.tar.gz", hash = "sha256:fd77a511bd90f39f3d016351345b52cf5319b813bdca01de3f755d3cca62e96a", size = 1866482, upload-time = "2026-09-21T16:45:16.974Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7e/cd/fe58041e9011f307c490e3e17dd48cc516448f7c698a3f2d9d9d65d7e6a8/networkx-3.7-py3-none-any.whl", hash = "sha256:e3fd2c13a7814cee3746340d8d7f8598a67f16a58bf47fb7f8793fab6efca1b0", size = 2142205, upload-time = "2026-09-21T16:45:14.609Z" },
+]
+
+[[package]]
+name = "numpy"
+version = "1.26.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/6e/09db70a523a96d25e115e71cc56a6f9031e7b8cd166c1ac8438307c14058/numpy-1.26.4.tar.gz", hash = "sha256:2a02aba9ed12e4ac4eb3ea9421c420301a0c6460d9830d74a9df87efa4912010", size = 15786129, upload-time = "2024-02-06T00:26:44.495Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/95/12/8f2020a8e8b8383ac0177dc9570aad031a3beb12e38847f7129bacd96228/numpy-1.26.4-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:b3ce300f3644fb06443ee2222c2201dd3a89ea6040541412b8fa189341847218", size = 20335901, upload-time = "2024-02-05T23:55:32.801Z" },
+ { url = "https://files.pythonhosted.org/packages/75/5b/ca6c8bd14007e5ca171c7c03102d17b4f4e0ceb53957e8c44343a9546dcc/numpy-1.26.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:03a8c78d01d9781b28a6989f6fa1bb2c4f2d51201cf99d3dd875df6fbd96b23b", size = 13685868, upload-time = "2024-02-05T23:55:56.28Z" },
+ { url = "https://files.pythonhosted.org/packages/79/f8/97f10e6755e2a7d027ca783f63044d5b1bc1ae7acb12afe6a9b4286eac17/numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9fad7dcb1aac3c7f0584a5a8133e3a43eeb2fe127f47e3632d43d677c66c102b", size = 13925109, upload-time = "2024-02-05T23:56:20.368Z" },
+ { url = "https://files.pythonhosted.org/packages/0f/50/de23fde84e45f5c4fda2488c759b69990fd4512387a8632860f3ac9cd225/numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:675d61ffbfa78604709862923189bad94014bef562cc35cf61d3a07bba02a7ed", size = 17950613, upload-time = "2024-02-05T23:56:56.054Z" },
+ { url = "https://files.pythonhosted.org/packages/4c/0c/9c603826b6465e82591e05ca230dfc13376da512b25ccd0894709b054ed0/numpy-1.26.4-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:ab47dbe5cc8210f55aa58e4805fe224dac469cde56b9f731a4c098b91917159a", size = 13572172, upload-time = "2024-02-05T23:57:21.56Z" },
+ { url = "https://files.pythonhosted.org/packages/76/8c/2ba3902e1a0fc1c74962ea9bb33a534bb05984ad7ff9515bf8d07527cadd/numpy-1.26.4-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:1dda2e7b4ec9dd512f84935c5f126c8bd8b9f2fc001e9f54af255e8c5f16b0e0", size = 17786643, upload-time = "2024-02-05T23:57:56.585Z" },
+ { url = "https://files.pythonhosted.org/packages/28/4a/46d9e65106879492374999e76eb85f87b15328e06bd1550668f79f7b18c6/numpy-1.26.4-cp312-cp312-win32.whl", hash = "sha256:50193e430acfc1346175fcbdaa28ffec49947a06918b7b92130744e81e640110", size = 5677803, upload-time = "2024-02-05T23:58:08.963Z" },
+ { url = "https://files.pythonhosted.org/packages/16/2e/86f24451c2d530c88daf997cb8d6ac622c1d40d19f5a031ed68a4b73a374/numpy-1.26.4-cp312-cp312-win_amd64.whl", hash = "sha256:08beddf13648eb95f8d867350f6a018a4be2e5ad54c8d8caed89ebca558b2818", size = 15517754, upload-time = "2024-02-05T23:58:36.364Z" },
+]
+
+[[package]]
+name = "onnx"
+version = "1.23.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "ml-dtypes" },
+ { name = "numpy" },
+ { name = "protobuf" },
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3f/62/bc2dfadb63ecf04cb2d65a6b17751863039d36c65de51d6a3128ab35f1e7/onnx-1.23.2.tar.gz", hash = "sha256:008cb0467b2bbee41448acc7da8b6f4e704624cb0d327a2d5adafc7ce19bc5b8", size = 6023090, upload-time = "2026-10-06T04:25:58.681Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d7/d9/967d6f6838ad60964de912a5e7d01915282899b254460705d952f5d14c1a/onnx-1.23.2-cp312-abi3-macosx_13_0_universal2.whl", hash = "sha256:1b8680ce1e6a9a4736374a9dce4de14ea8ee05e0dccf0784a78a6e5646bdc1f6", size = 9725612, upload-time = "2026-10-06T04:25:34.299Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/50/2e156ef2cae1c9f4ff01a41dffa43fc1eb7b969755055436bf6df1805d54/onnx-1.23.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a203efdbaabbbe8f25e854e2b2921382d6fcf4c67895656f939044b0632974e8", size = 8640515, upload-time = "2026-10-06T04:25:36.727Z" },
+ { url = "https://files.pythonhosted.org/packages/87/56/21509a657f9a73ab0ca307d325043f49ca6c4ff6bf79edeb9e159190d44d/onnx-1.23.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7abf381d278f31ac62487fddedc9dd42da842dce94d5d43536836ee3efdf4a2b", size = 8881633, upload-time = "2026-10-06T04:25:38.868Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/ef/0a69093ffa0b999747b373c75d07182a812722a0e595d21f763a8d406260/onnx-1.23.2-cp312-abi3-pyemscripten_2026_0_wasm32.whl", hash = "sha256:e79e35e152d3095c6910ae81013bbc68679e32bfc0ca76f840968d4b6fdfb864", size = 7314844, upload-time = "2026-10-06T04:25:41.088Z" },
+ { url = "https://files.pythonhosted.org/packages/97/a3/e4d4aedd0cc6820de416bb99623fc12b9a22a387d00596bb98505de9a805/onnx-1.23.2-cp312-abi3-win32.whl", hash = "sha256:b0b8dae0d33dd8606370bc264b0b1d6e64cfdf8b83d7c676fab8eff6b88ca409", size = 7736405, upload-time = "2026-10-06T04:25:42.893Z" },
+ { url = "https://files.pythonhosted.org/packages/38/ce/102fd4a0b2a6d111a9c86745e084c4c68c0ee020eaa359a03a8d43e4646f/onnx-1.23.2-cp312-abi3-win_amd64.whl", hash = "sha256:9b382ba898a7c142a0801d03cf04ecabced96c1543c7b643a86f0928143802de", size = 7872489, upload-time = "2026-10-06T04:25:44.802Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/1d/37f2c7f821f79ceed3c976bd087d16abdd2b0bba6c19475322e7a31bae59/onnx-1.23.2-cp312-abi3-win_arm64.whl", hash = "sha256:80cef0fad59524d02c21ec93f4fbccdcc6223f1c33339d597519a2d27cac19a7", size = 8047076, upload-time = "2026-10-06T04:25:46.93Z" },
+]
+
+[[package]]
+name = "protobuf"
+version = "7.36.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/86/73/f66c748df06e7fe24e658eddd600d19c4b40bad836c97ce2d0ad9851fb6b/protobuf-7.36.1.tar.gz", hash = "sha256:d0f6470f0ce2b84e3feaea2d4b816378b37ba4d4aa08a274305373de93e2d524", size = 512499, upload-time = "2026-08-31T22:40:04.667Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f7/6c/3a54a58f2948b0f485df9ecdd06590f15d0a7abf46a89d50c3de709ff4ff/protobuf-7.36.1-cp310-abi3-macosx_10_9_universal2.whl", hash = "sha256:3cf2ee25d006cee57294a1196ea43b37feb78e0dcd1e8af5c1aeddb777655aca", size = 456046, upload-time = "2026-08-31T22:39:56.865Z" },
+ { url = "https://files.pythonhosted.org/packages/6e/08/9f9548793c771095245c0eeaf0c84b76b16a5ef26158043d456f551344a0/protobuf-7.36.1-cp310-abi3-manylinux2014_aarch64.whl", hash = "sha256:43d3d37b1eb24c113b9b7d02008cac44e423f00b611b7781ae998d7623972969", size = 344226, upload-time = "2026-08-31T22:39:58.263Z" },
+ { url = "https://files.pythonhosted.org/packages/fe/51/1bdbd612fa3c51e42ea6f45d05e84dc748ddcd2663e1aa1e89a00a33facd/protobuf-7.36.1-cp310-abi3-manylinux2014_s390x.whl", hash = "sha256:39c518c05586c016d7874ff6079ee115bcec1ea5fbb1d177fbf7867ef4c67e44", size = 357229, upload-time = "2026-08-31T22:39:59.198Z" },
+ { url = "https://files.pythonhosted.org/packages/22/df/c799fe7a05ef16ba853a59db01f3a2c5f7d0676469589ccc4874f76a2a88/protobuf-7.36.1-cp310-abi3-manylinux2014_x86_64.whl", hash = "sha256:97198b77e369a0abd8e262b8f6c7266c55ddb796a3a12c76d7b8881188ed83aa", size = 343228, upload-time = "2026-08-31T22:40:00.179Z" },
+ { url = "https://files.pythonhosted.org/packages/3d/33/d4724ec5d86d496fe4108e220618aa0837ad3423a7af7ccdd9684ccc77c8/protobuf-7.36.1-cp310-abi3-win32.whl", hash = "sha256:0b53ce95272aad50ad25d7ff03373743209822e8ba42ea7fad27d2bee1547d00", size = 443002, upload-time = "2026-08-31T22:40:01.32Z" },
+ { url = "https://files.pythonhosted.org/packages/db/37/155788a0d8daded960375af604202805308169f9b859419ea0aa370946e2/protobuf-7.36.1-cp310-abi3-win_amd64.whl", hash = "sha256:51139351435d9b43d88a55eaa49fb6f737fbb478fb0cbf2cf694d1a04a9d3363", size = 456518, upload-time = "2026-08-31T22:40:02.494Z" },
+ { url = "https://files.pythonhosted.org/packages/39/ca/c47f91d3cab175b01fd8c4f0d80fdf8613be876cc616e66ad281a59c5ddf/protobuf-7.36.1-py3-none-any.whl", hash = "sha256:7d951e46b3f963d6c264c367c437921de9d5aedd9c3f9612b9077736b4e3ad5c", size = 179813, upload-time = "2026-08-31T22:40:03.54Z" },
+]
+
+[[package]]
+name = "safetensors"
+version = "0.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/45/06/f955dbbb1859e3bd23c8ac6141af5106e7ad5fedec4a3a6e3d60f94b7001/safetensors-0.8.0.tar.gz", hash = "sha256:fabaf3e0f18a6618d9b36560682562157f77c2b71fcffc7b432be2baed9d753d", size = 325846, upload-time = "2026-06-09T07:52:25.563Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/39/a0/f718cda65b05407d228f97602cf60dca269c979867aa5beb25410de26cd3/safetensors-0.8.0-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:c554f85858e05226d3c2828e32395e677434685d6d94594a41643361c5e837f0", size = 473568, upload-time = "2026-06-09T07:52:18.829Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/b1/fa7c600e7dceae12e9606c7578cbc9ff1e1ed55844883ee5c92205e86226/safetensors-0.8.0-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:c80201d22cbf405b80647a60ada77bba06c8fba2da2743ba1e89cdcc39a81f25", size = 484562, upload-time = "2026-06-09T07:52:17.518Z" },
+ { url = "https://files.pythonhosted.org/packages/09/7d/65a7de0af421317bb36a067241e4235fff194eed60b961ed6d3f59a3fc60/safetensors-0.8.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7a46e5ff292c356d6991e60942ba7f79817682d3a2cef0702136448cb9c4d235", size = 502844, upload-time = "2026-06-09T07:52:07.624Z" },
+ { url = "https://files.pythonhosted.org/packages/91/4f/3175c9d75634e0e0dda0082794193521035edd7c70a6f212bf33ca06ddf4/safetensors-0.8.0-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:4124502b78f03534117c848f87a39b8f31e577b15eff423bf8bfb95f2a8c30d0", size = 511823, upload-time = "2026-06-09T07:52:09.565Z" },
+ { url = "https://files.pythonhosted.org/packages/20/87/846c289e7aa2299eff406335717cf43ce8777194ece8aad75772e0411615/safetensors-0.8.0-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:7bc0a787ba8a35be368ee3574edfa2b1ad389eebd0a72e482ae275490e3f6c98", size = 633461, upload-time = "2026-06-09T07:52:11.128Z" },
+ { url = "https://files.pythonhosted.org/packages/76/22/8d64d9df2c45d5ded401df889d0ad90882804ca172d79ec4f0df8f727fe0/safetensors-0.8.0-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:040070828e36dc8e122178bbbd5830ff9e97920affb84cbe0f46442497bed358", size = 545148, upload-time = "2026-06-09T07:52:13.603Z" },
+ { url = "https://files.pythonhosted.org/packages/28/50/f203ff3a3ddfe19308efc83c5a3a29ed02bf786732ec35e68bf9162f3365/safetensors-0.8.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fd6f3f93c9a0a7cc2788ee63fb763353d4bd2e89b0751bc78fcf7dda00bea774", size = 516040, upload-time = "2026-06-09T07:52:16.29Z" },
+ { url = "https://files.pythonhosted.org/packages/46/fb/cdaed17ceb2948784fd9c36b6fd3e951b608547cea81a48e8ee6f8cfdfcb/safetensors-0.8.0-cp310-abi3-manylinux_2_31_riscv64.whl", hash = "sha256:fcdd41ec4628fee5799f807c73c353629130fbd942aa23d83c623dd6c9d52d78", size = 513832, upload-time = "2026-06-09T07:52:12.37Z" },
+ { url = "https://files.pythonhosted.org/packages/0d/49/1e15de264dcc3b77943d2d0c56a95809956883b1c2d6d585c792523f180b/safetensors-0.8.0-cp310-abi3-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8e9f537aa183a38ace122d27303dcd986b26bd2a7591f9181d7f0c396f4677ca", size = 559930, upload-time = "2026-06-09T07:52:14.743Z" },
+ { url = "https://files.pythonhosted.org/packages/2a/43/bf38443278eab4b1be1fce2931e2b012ad9cb7df52ada751d0aab8f7659a/safetensors-0.8.0-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:87eec7ffed2b809f05a398a8becb7d013f19f7837cd15d9748580d6cf30dbaf4", size = 678670, upload-time = "2026-06-09T07:52:20.032Z" },
+ { url = "https://files.pythonhosted.org/packages/72/e3/68cd3fa5b48488e84add63e04cb12f3bc28ae4638c06d4508c6e88823d0e/safetensors-0.8.0-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:4a95ae2b05d7726d751da4ebf626a2ca782b706e101bd894c95bc2450b1cffcc", size = 786679, upload-time = "2026-06-09T07:52:21.322Z" },
+ { url = "https://files.pythonhosted.org/packages/29/4b/1c19c509d56e01f4fbb3d0a2e597450f6cc04d1d56cf52defb0a62dfd715/safetensors-0.8.0-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:3ae091f16662658bdc019a4ff6cb4c085bb7d725eb5978b183ffd265863b6d2d", size = 765683, upload-time = "2026-06-09T07:52:22.594Z" },
+ { url = "https://files.pythonhosted.org/packages/27/43/41c1621732edd934d868a00d1b891584c892a7b62a9aab82ea5a0a5623ee/safetensors-0.8.0-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:8e080062fcde23be189565e1c3305d16751a218ecf9412c8601e64204eb6f846", size = 722361, upload-time = "2026-06-09T07:52:23.924Z" },
+ { url = "https://files.pythonhosted.org/packages/8e/3f/73ccf82579412b4a71c4ca673f10b5f1f888d7cf5af7fe24f27d30307be4/safetensors-0.8.0-cp310-abi3-win32.whl", hash = "sha256:2ddf52eac562eda224f99acfa7889d02968c1fd59a5b011ae7d8137c37e9c02d", size = 342401, upload-time = "2026-06-09T07:52:28.895Z" },
+ { url = "https://files.pythonhosted.org/packages/1b/6d/3fba214c1e5e0f69991677ec3bc17023f0421776975e1de0c682dca475e2/safetensors-0.8.0-cp310-abi3-win_amd64.whl", hash = "sha256:096ec1a98435df7beb08853bb5aa9081a84f23d0adc67ed1a0a10550f608373f", size = 355540, upload-time = "2026-06-09T07:52:27.832Z" },
+ { url = "https://files.pythonhosted.org/packages/8d/fc/7eedc3510d97878876e32774eebbeb61c43f148a96e915c84229a3e967aa/safetensors-0.8.0-cp310-abi3-win_arm64.whl", hash = "sha256:f7838e5135a406ad3e02efdcb8cf2e5397d368b0154537c4fec682dbc544d452", size = 340500, upload-time = "2026-06-09T07:52:26.745Z" },
+]
+
+[[package]]
+name = "setuptools"
+version = "84.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6d/44/f5da03a8ef95d369145c5bb53050e7877c9f3d312e128605fd9504829143/setuptools-84.0.0.tar.gz", hash = "sha256:f4695c21257f0d9b537ec2692c941d02ee143b7cc1276941349a546573b2ef73", size = 1168449, upload-time = "2026-08-08T18:27:58.365Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/95/9c/c510029fc6ef33a6275cd2c5d3cecd6613dfd6aa401d57c54f1c18852ccf/setuptools-84.0.0-py3-none-any.whl", hash = "sha256:51a52592b3b99e102b609654876bd65f19f999935166d1352678931132b0c670", size = 818216, upload-time = "2026-08-08T18:27:56.719Z" },
+]
+
+[[package]]
+name = "sympy"
+version = "1.14.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "mpmath" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/83/d3/803453b36afefb7c2bb238361cd4ae6125a569b4db67cd9e79846ba2d68c/sympy-1.14.0.tar.gz", hash = "sha256:d3d3fe8df1e5a0b42f0e7bdf50541697dbe7d23746e894990c030e2b05e72517", size = 7793921, upload-time = "2025-04-27T18:05:01.611Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a2/09/77d55d46fd61b4a135c444fc97158ef34a095e5681d0a6c10b75bf356191/sympy-1.14.0-py3-none-any.whl", hash = "sha256:e091cc3e99d2141a0ba2847328f5479b05d94a6635cb96148ccb3f34671bd8f5", size = 6299353, upload-time = "2025-04-27T18:04:59.103Z" },
+]
+
+[[package]]
+name = "torch"
+version = "2.14.0+cpu"
+source = { registry = "https://download.pytorch.org/whl/cpu" }
+dependencies = [
+ { name = "filelock" },
+ { name = "fsspec" },
+ { name = "jinja2" },
+ { name = "networkx" },
+ { name = "setuptools" },
+ { name = "sympy" },
+ { name = "typing-extensions" },
+]
+wheels = [
+ { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.14.0%2Bcpu-cp312-cp312-linux_s390x.whl", hash = "sha256:07aefe1a437b6f1b41b0cba15e16583e2f43549ec9d062fcea8e7981a78e014a", upload-time = "2026-09-02T18:31:32Z" },
+ { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.14.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:da8140c3d4a41500d29710e35bf8e66a4295ec31026487c69f54a3f583310f8d", upload-time = "2026-09-02T18:31:37Z" },
+ { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.14.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:a09987c95ec4cffdb6df798d3d641558110a334cfccce22f2f046d83142bc260", upload-time = "2026-09-02T18:31:42Z" },
+ { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.14.0%2Bcpu-cp312-cp312-win_amd64.whl", hash = "sha256:738cd9237bf63443a5e5f9652e5115f7b0510b089636a43d4011e9fccede714f", upload-time = "2026-09-02T18:31:48Z" },
+ { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.14.0%2Bcpu-cp312-cp312-win_arm64.whl", hash = "sha256:420e7dbed969bbd045b34105fa90d1ccf3e5c09c4e9b0d0a5f9df25df9d02d2e", upload-time = "2026-09-02T18:31:52Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]
diff --git a/uv.lock b/uv.lock
new file mode 100644
index 0000000..2bbf977
--- /dev/null
+++ b/uv.lock
@@ -0,0 +1,388 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
+
+[[package]]
+name = "glfw"
+version = "2.10.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0f/62/096058bcb4b4fb28f7ecd28fb048f07969d90b243c417af5f6d09d45a0c2/glfw-2.10.2.tar.gz", hash = "sha256:5d2cf97c66bc42a6b583be0e307eae5a3945438322e2ed0c5e4f14dc251d693d", size = 36307, upload-time = "2026-07-21T14:42:36.732Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/c4/80/5e575ec14f54dc0a644e7215985b9ee7c5044fcc3594d6b83dfdeb04ccd4/glfw-2.10.2-py2.py3-none-macosx_10_6_intel.whl", hash = "sha256:a04d25bb535a3a29e173ea1abd658e161681b5d3816e00bc51c122f74cd7fa3a", size = 110295, upload-time = "2026-07-21T14:42:25.625Z" },
+ { url = "https://files.pythonhosted.org/packages/e5/2e/22216db429690aa51fa87d2e2b5e6b610c5a37b9df7768da2927f52f8704/glfw-2.10.2-py2.py3-none-macosx_11_0_arm64.whl", hash = "sha256:c000b8a5e5fb4374b2c18d12347255ccb92001b9bcf80ef74c56072acbb98fe3", size = 107146, upload-time = "2026-07-21T14:42:26.854Z" },
+ { url = "https://files.pythonhosted.org/packages/75/a4/9ccee9d5c3b9c5d6bafce3e8d53ab8318eff30124e3c19b95580bebaa6d4/glfw-2.10.2-py2.py3-none-manylinux2014_aarch64.whl", hash = "sha256:0ffe2b48b51f37b05e8f027f57c0b8cd213affaf22fc83401bd9621692d4c6c8", size = 235005, upload-time = "2026-07-21T14:42:27.955Z" },
+ { url = "https://files.pythonhosted.org/packages/77/44/37aeed50c581c76e1c5bb83b696a06f98f8ecc979ed8564dde3eef908e8b/glfw-2.10.2-py2.py3-none-manylinux2014_x86_64.whl", hash = "sha256:82daf1f87b2a48815637dc6f6720d4a55a57ba1d3683322dc20dc28065754f97", size = 246951, upload-time = "2026-07-21T14:42:29.107Z" },
+ { url = "https://files.pythonhosted.org/packages/52/fc/29b4f1a8c8e33d8934781330a0845458b01da7f389d9fe6a3350e752b7f3/glfw-2.10.2-py2.py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:7604425ec95665cc6a25c3ed7d07e9660d394a34472ceffaec0843c844e7b649", size = 236018, upload-time = "2026-07-21T14:42:30.623Z" },
+ { url = "https://files.pythonhosted.org/packages/69/84/1b98671314ea5f40397586b6cd14db913de3196333be558fdc177e61708f/glfw-2.10.2-py2.py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:b860de3ca0686182483f98f3ddd12e660acf25b3e0d521450ec9a3f999f72a65", size = 248490, upload-time = "2026-07-21T14:42:32.377Z" },
+ { url = "https://files.pythonhosted.org/packages/12/d9/bd2e6c8dbadcf69fcd2289705e75881258b46221c196903a52e9f6e97322/glfw-2.10.2-py2.py3-none-win32.whl", hash = "sha256:a94aefe8c48886fd83cd6e11e936846166a4b5b94abf1f4bf599d984774b0b1b", size = 557654, upload-time = "2026-07-21T14:42:33.903Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/6c/4ca5f3ab85a8d7f612ce857208726e9b834e54e559751e3d4f98cc2f7509/glfw-2.10.2-py2.py3-none-win_amd64.whl", hash = "sha256:15fd0666cd8f1b0ecb535c3abb712b8ddda053bf8d16de2353b1c6ced0e65402", size = 564433, upload-time = "2026-07-21T14:42:35.465Z" },
+]
+
+[[package]]
+name = "imgui-bundle"
+version = "1.92.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "glfw" },
+ { name = "munch" },
+ { name = "numpy" },
+ { name = "pillow" },
+ { name = "pyopengl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/88/2f/b5e5cd1567cf509235e24dd942b684c1c65d520a3950a524eef6097610c0/imgui_bundle-1.92.4.tar.gz", hash = "sha256:8a288de43c3ad05b11c2393197e2afdbcb8b504d698ebce8895eee019a510788", size = 40858627, upload-time = "2025-09-29T12:31:59.437Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/39/4d/a68d447c4eff411356651a8e75d0deaf1d69e0a8736ce26595e2c52d67c0/imgui_bundle-1.92.4-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:85760c2d6721f6ca383991d8040d7121755c6de353f40a251232a791c42b9029", size = 12516812, upload-time = "2025-09-29T11:33:08.883Z" },
+ { url = "https://files.pythonhosted.org/packages/4c/0a/59344438236d83062c649849c44d9377a5c70f146cd8908c22375776b6a9/imgui_bundle-1.92.4-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:74d401c5449f58dcc2fb318c0bccbc033fd1fb9bfdd5532169132557bf030ba0", size = 13694192, upload-time = "2025-09-29T12:31:41.025Z" },
+ { url = "https://files.pythonhosted.org/packages/59/d8/c0d8734fb0e3a4708b850b10fbe828d3fa5bbc510c53ae8553d6191bf98d/imgui_bundle-1.92.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cccbd06f4d9e587b24c7d8717dc5772485fcae2205bf4e93b5672a75765276a1", size = 22661004, upload-time = "2025-09-29T12:31:43.271Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/41/bebb09a6bbc5e73dc5e58cebaca2c4169163ad163aeaec128938e2d0cc4c/imgui_bundle-1.92.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bbd2fd3bf602274210854abd903aabe1b9bb9cdcfbdbb3f90dabb880a0089a0d", size = 24341237, upload-time = "2025-09-29T12:31:45.359Z" },
+ { url = "https://files.pythonhosted.org/packages/96/2c/b250651b747d52d263291e6c1b2aba28f944e58366ebe250a169418e01f2/imgui_bundle-1.92.4-cp312-cp312-win_amd64.whl", hash = "sha256:30d722262060f0d0c4ca45bb85ba8ede1a58a712bd1582441b71c485b95983da", size = 34851091, upload-time = "2025-09-29T12:31:47.814Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/a7/de9ee63778d825cc5a8b6f4731be326a08bda18b4bda5eb4a24d73e632b0/imgui_bundle-1.92.4-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:1762ce9de336bfd8ade38567d920e0473c93ece0c3527d00b2810b8c85ab7d0a", size = 12516659, upload-time = "2025-09-29T11:33:11.333Z" },
+ { url = "https://files.pythonhosted.org/packages/a1/9d/cf655075262491abdc7562141a98ae538539f7aa0bf918d991037cd4e145/imgui_bundle-1.92.4-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:37c89792cd1d76de70dd68ac3575fa543796ff2a35863d707a6f266f41e1a44c", size = 13694154, upload-time = "2025-09-29T12:31:50.226Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/47/478d02cf8352416fb6ee4d608630076830cb83469c2e8023509f3e2caca5/imgui_bundle-1.92.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d909f889386ab5f1f7541ab5aced910b29de3011c13d645bcf8322106221f459", size = 22660264, upload-time = "2025-09-29T12:31:51.989Z" },
+ { url = "https://files.pythonhosted.org/packages/64/a8/2928c2ff8fdbe9a106144940941fb133e9159952ead446239effacb60173/imgui_bundle-1.92.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:564bbe557256009ad407bc43353166fbf93cc5ec9ee5a2acc1edc42b9c318581", size = 24341113, upload-time = "2025-09-29T12:31:53.977Z" },
+ { url = "https://files.pythonhosted.org/packages/6c/2d/73ff5d09555711b5d72b780a3e394b6290c1b9d460ce1a24052121d065f2/imgui_bundle-1.92.4-cp313-cp313-win_amd64.whl", hash = "sha256:f186daeab73068d83f02cc4385e2240b51bfee585adebd583ca54cdce33391af", size = 34851097, upload-time = "2025-09-29T12:31:56.179Z" },
+]
+
+[[package]]
+name = "motionbricks"
+source = { editable = "." }
+dependencies = [
+ { name = "imgui-bundle" },
+ { name = "newton" },
+ { name = "numpy" },
+ { name = "pillow" },
+ { name = "pyglet" },
+ { name = "scipy" },
+ { name = "tensorrt-cu12" },
+ { name = "tensorrt-cu12-bindings" },
+ { name = "tensorrt-cu12-libs" },
+ { name = "trimesh" },
+ { name = "usd-core" },
+ { name = "warp-lang" },
+]
+
+[package.metadata]
+requires-dist = [
+ { name = "imgui-bundle", specifier = "==1.92.4" },
+ { name = "newton", specifier = "==1.6.0" },
+ { name = "numpy", specifier = "==2.4.3" },
+ { name = "pillow", specifier = ">=13.0.0" },
+ { name = "pyglet", specifier = "==2.1.13" },
+ { name = "scipy", specifier = "==1.17.1" },
+ { name = "tensorrt-cu12", specifier = "==10.8.0.43" },
+ { name = "tensorrt-cu12-bindings", specifier = "==10.8.0.43" },
+ { name = "tensorrt-cu12-libs", specifier = "==10.8.0.43" },
+ { name = "trimesh", specifier = ">=4.6.8" },
+ { name = "usd-core", specifier = "==26.3" },
+ { name = "warp-lang", specifier = ">=1.17.0" },
+]
+
+[[package]]
+name = "munch"
+version = "4.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/2b/45098135b5f9f13221820d90f9e0516e11a2a0f55012c13b081d202b782a/munch-4.0.0.tar.gz", hash = "sha256:542cb151461263216a4e37c3fd9afc425feeaf38aaa3025cd2a981fadb422235", size = 19089, upload-time = "2023-07-01T09:49:35.98Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/56/b3/7c69b37f03260a061883bec0e7b05be7117c1b1c85f5212c72c8c2bc3c8c/munch-4.0.0-py2.py3-none-any.whl", hash = "sha256:71033c45db9fb677a0b7eb517a4ce70ae09258490e419b0e7f00d1e386ecb1b4", size = 9950, upload-time = "2023-07-01T09:49:34.472Z" },
+]
+
+[[package]]
+name = "newton"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "warp-lang" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7b/d0/1955c2623762fd1d9f3bc0bb9866b6c0669e1e277202bdc16772520d7da1/newton-1.6.0-py3-none-any.whl", hash = "sha256:5eedebe17d7261ca39e8f97c2f2f20e22e7264d0aed01782f3cb1dd60180b872", size = 6159741, upload-time = "2026-09-10T13:50:10.666Z" },
+]
+
+[[package]]
+name = "numpy"
+version = "2.4.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/10/8b/c265f4823726ab832de836cdd184d0986dcf94480f81e8739692a7ac7af2/numpy-2.4.3.tar.gz", hash = "sha256:483a201202b73495f00dbc83796c6ae63137a9bdade074f7648b3e32613412dd", size = 20727743, upload-time = "2026-03-09T07:58:53.426Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a9/ed/6388632536f9788cea23a3a1b629f25b43eaacd7d7377e5d6bc7b9deb69b/numpy-2.4.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:61b0cbabbb6126c8df63b9a3a0c4b1f44ebca5e12ff6997b80fcf267fb3150ef", size = 16669628, upload-time = "2026-03-09T07:56:24.252Z" },
+ { url = "https://files.pythonhosted.org/packages/74/1b/ee2abfc68e1ce728b2958b6ba831d65c62e1b13ce3017c13943f8f9b5b2e/numpy-2.4.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7395e69ff32526710748f92cd8c9849b361830968ea3e24a676f272653e8983e", size = 14696872, upload-time = "2026-03-09T07:56:26.991Z" },
+ { url = "https://files.pythonhosted.org/packages/ba/d1/780400e915ff5638166f11ca9dc2c5815189f3d7cf6f8759a1685e586413/numpy-2.4.3-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:abdce0f71dcb4a00e4e77f3faf05e4616ceccfe72ccaa07f47ee79cda3b7b0f4", size = 5203489, upload-time = "2026-03-09T07:56:29.414Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/bb/baffa907e9da4cc34a6e556d6d90e032f6d7a75ea47968ea92b4858826c4/numpy-2.4.3-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:48da3a4ee1336454b07497ff7ec83903efa5505792c4e6d9bf83d99dc07a1e18", size = 6550814, upload-time = "2026-03-09T07:56:32.225Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/12/8c9f0c6c95f76aeb20fc4a699c33e9f827fa0d0f857747c73bb7b17af945/numpy-2.4.3-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:32e3bef222ad6b052280311d1d60db8e259e4947052c3ae7dd6817451fc8a4c5", size = 15666601, upload-time = "2026-03-09T07:56:34.461Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/79/cc665495e4d57d0aa6fbcc0aa57aa82671dfc78fbf95fe733ed86d98f52a/numpy-2.4.3-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e7dd01a46700b1967487141a66ac1a3cf0dd8ebf1f08db37d46389401512ca97", size = 16621358, upload-time = "2026-03-09T07:56:36.852Z" },
+ { url = "https://files.pythonhosted.org/packages/a8/40/b4ecb7224af1065c3539f5ecfff879d090de09608ad1008f02c05c770cb3/numpy-2.4.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:76f0f283506c28b12bba319c0fab98217e9f9b54e6160e9c79e9f7348ba32e9c", size = 17016135, upload-time = "2026-03-09T07:56:39.337Z" },
+ { url = "https://files.pythonhosted.org/packages/f7/b1/6a88e888052eed951afed7a142dcdf3b149a030ca59b4c71eef085858e43/numpy-2.4.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:737f630a337364665aba3b5a77e56a68cc42d350edd010c345d65a3efa3addcc", size = 18345816, upload-time = "2026-03-09T07:56:42.31Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/8f/103a60c5f8c3d7fc678c19cd7b2476110da689ccb80bc18050efbaeae183/numpy-2.4.3-cp312-cp312-win32.whl", hash = "sha256:26952e18d82a1dbbc2f008d402021baa8d6fc8e84347a2072a25e08b46d698b9", size = 5960132, upload-time = "2026-03-09T07:56:44.851Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/7c/f5ee1bf6ed888494978046a809df2882aad35d414b622893322df7286879/numpy-2.4.3-cp312-cp312-win_amd64.whl", hash = "sha256:65f3c2455188f09678355f5cae1f959a06b778bc66d535da07bf2ef20cd319d5", size = 12316144, upload-time = "2026-03-09T07:56:47.057Z" },
+ { url = "https://files.pythonhosted.org/packages/71/46/8d1cb3f7a00f2fb6394140e7e6623696e54c6318a9d9691bb4904672cf42/numpy-2.4.3-cp312-cp312-win_arm64.whl", hash = "sha256:2abad5c7fef172b3377502bde47892439bae394a71bc329f31df0fd829b41a9e", size = 10220364, upload-time = "2026-03-09T07:56:49.849Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/d0/1fe47a98ce0df229238b77611340aff92d52691bcbc10583303181abf7fc/numpy-2.4.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b346845443716c8e542d54112966383b448f4a3ba5c66409771b8c0889485dd3", size = 16665297, upload-time = "2026-03-09T07:56:52.296Z" },
+ { url = "https://files.pythonhosted.org/packages/27/d9/4e7c3f0e68dfa91f21c6fb6cf839bc829ec920688b1ce7ec722b1a6202fb/numpy-2.4.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2629289168f4897a3c4e23dc98d6f1731f0fc0fe52fb9db19f974041e4cc12b9", size = 14691853, upload-time = "2026-03-09T07:56:54.992Z" },
+ { url = "https://files.pythonhosted.org/packages/3a/66/bd096b13a87549683812b53ab211e6d413497f84e794fb3c39191948da97/numpy-2.4.3-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:bb2e3cf95854233799013779216c57e153c1ee67a0bf92138acca0e429aefaee", size = 5198435, upload-time = "2026-03-09T07:56:57.184Z" },
+ { url = "https://files.pythonhosted.org/packages/a2/2f/687722910b5a5601de2135c891108f51dfc873d8e43c8ed9f4ebb440b4a2/numpy-2.4.3-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:7f3408ff897f8ab07a07fbe2823d7aee6ff644c097cc1f90382511fe982f647f", size = 6546347, upload-time = "2026-03-09T07:56:59.531Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/ec/7971c4e98d86c564750393fab8d7d83d0a9432a9d78bb8a163a6dc59967a/numpy-2.4.3-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:decb0eb8a53c3b009b0962378065589685d66b23467ef5dac16cbe818afde27f", size = 15664626, upload-time = "2026-03-09T07:57:01.385Z" },
+ { url = "https://files.pythonhosted.org/packages/7e/eb/7daecbea84ec935b7fc732e18f532073064a3816f0932a40a17f3349185f/numpy-2.4.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d5f51900414fc9204a0e0da158ba2ac52b75656e7dce7e77fb9f84bfa343b4cc", size = 16608916, upload-time = "2026-03-09T07:57:04.008Z" },
+ { url = "https://files.pythonhosted.org/packages/df/58/2a2b4a817ffd7472dca4421d9f0776898b364154e30c95f42195041dc03b/numpy-2.4.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:6bd06731541f89cdc01b261ba2c9e037f1543df7472517836b78dfb15bd6e476", size = 17015824, upload-time = "2026-03-09T07:57:06.347Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/ca/627a828d44e78a418c55f82dd4caea8ea4a8ef24e5144d9e71016e52fb40/numpy-2.4.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:22654fe6be0e5206f553a9250762c653d3698e46686eee53b399ab90da59bd92", size = 18334581, upload-time = "2026-03-09T07:57:09.114Z" },
+ { url = "https://files.pythonhosted.org/packages/cd/c0/76f93962fc79955fcba30a429b62304332345f22d4daec1cb33653425643/numpy-2.4.3-cp313-cp313-win32.whl", hash = "sha256:d71e379452a2f670ccb689ec801b1218cd3983e253105d6e83780967e899d687", size = 5958618, upload-time = "2026-03-09T07:57:11.432Z" },
+ { url = "https://files.pythonhosted.org/packages/b1/3c/88af0040119209b9b5cb59485fa48b76f372c73068dbf9254784b975ac53/numpy-2.4.3-cp313-cp313-win_amd64.whl", hash = "sha256:0a60e17a14d640f49146cb38e3f105f571318db7826d9b6fef7e4dce758faecd", size = 12312824, upload-time = "2026-03-09T07:57:13.586Z" },
+ { url = "https://files.pythonhosted.org/packages/58/ce/3d07743aced3d173f877c3ef6a454c2174ba42b584ab0b7e6d99374f51ed/numpy-2.4.3-cp313-cp313-win_arm64.whl", hash = "sha256:c9619741e9da2059cd9c3f206110b97583c7152c1dc9f8aafd4beb450ac1c89d", size = 10221218, upload-time = "2026-03-09T07:57:16.183Z" },
+ { url = "https://files.pythonhosted.org/packages/62/09/d96b02a91d09e9d97862f4fc8bfebf5400f567d8eb1fe4b0cc4795679c15/numpy-2.4.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:7aa4e54f6469300ebca1d9eb80acd5253cdfa36f2c03d79a35883687da430875", size = 14819570, upload-time = "2026-03-09T07:57:18.564Z" },
+ { url = "https://files.pythonhosted.org/packages/b5/ca/0b1aba3905fdfa3373d523b2b15b19029f4f3031c87f4066bd9d20ef6c6b/numpy-2.4.3-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:d1b90d840b25874cf5cd20c219af10bac3667db3876d9a495609273ebe679070", size = 5326113, upload-time = "2026-03-09T07:57:21.052Z" },
+ { url = "https://files.pythonhosted.org/packages/c0/63/406e0fd32fcaeb94180fd6a4c41e55736d676c54346b7efbce548b94a914/numpy-2.4.3-cp313-cp313t-macosx_14_0_x86_64.whl", hash = "sha256:a749547700de0a20a6718293396ec237bb38218049cfce788e08fcb716e8cf73", size = 6646370, upload-time = "2026-03-09T07:57:22.804Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/d0/10f7dc157d4b37af92720a196be6f54f889e90dcd30dce9dc657ed92c257/numpy-2.4.3-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:94f3c4a151a2e529adf49c1d54f0f57ff8f9b233ee4d44af623a81553ab86368", size = 15723499, upload-time = "2026-03-09T07:57:24.693Z" },
+ { url = "https://files.pythonhosted.org/packages/66/f1/d1c2bf1161396629701bc284d958dc1efa3a5a542aab83cf11ee6eb4cba5/numpy-2.4.3-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:22c31dc07025123aedf7f2db9e91783df13f1776dc52c6b22c620870dc0fab22", size = 16657164, upload-time = "2026-03-09T07:57:27.676Z" },
+ { url = "https://files.pythonhosted.org/packages/1a/be/cca19230b740af199ac47331a21c71e7a3d0ba59661350483c1600d28c37/numpy-2.4.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:148d59127ac95979d6f07e4d460f934ebdd6eed641db9c0db6c73026f2b2101a", size = 17081544, upload-time = "2026-03-09T07:57:30.664Z" },
+ { url = "https://files.pythonhosted.org/packages/b9/c5/9602b0cbb703a0936fb40f8a95407e8171935b15846de2f0776e08af04c7/numpy-2.4.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:a97cbf7e905c435865c2d939af3d93f99d18eaaa3cabe4256f4304fb51604349", size = 18380290, upload-time = "2026-03-09T07:57:33.763Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/81/9f24708953cd30be9ee36ec4778f4b112b45165812f2ada4cc5ea1c1f254/numpy-2.4.3-cp313-cp313t-win32.whl", hash = "sha256:be3b8487d725a77acccc9924f65fd8bce9af7fac8c9820df1049424a2115af6c", size = 6082814, upload-time = "2026-03-09T07:57:36.491Z" },
+ { url = "https://files.pythonhosted.org/packages/e2/9e/52f6eaa13e1a799f0ab79066c17f7016a4a8ae0c1aefa58c82b4dab690b4/numpy-2.4.3-cp313-cp313t-win_amd64.whl", hash = "sha256:1ec84fd7c8e652b0f4aaaf2e6e9cc8eaa9b1b80a537e06b2e3a2fb176eedcb26", size = 12452673, upload-time = "2026-03-09T07:57:38.281Z" },
+ { url = "https://files.pythonhosted.org/packages/c4/04/b8cece6ead0b30c9fbd99bb835ad7ea0112ac5f39f069788c5558e3b1ab2/numpy-2.4.3-cp313-cp313t-win_arm64.whl", hash = "sha256:120df8c0a81ebbf5b9020c91439fccd85f5e018a927a39f624845be194a2be02", size = 10290907, upload-time = "2026-03-09T07:57:40.747Z" },
+ { url = "https://files.pythonhosted.org/packages/70/ae/3936f79adebf8caf81bd7a599b90a561334a658be4dcc7b6329ebf4ee8de/numpy-2.4.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:5884ce5c7acfae1e4e1b6fde43797d10aa506074d25b531b4f54bde33c0c31d4", size = 16664563, upload-time = "2026-03-09T07:57:43.817Z" },
+ { url = "https://files.pythonhosted.org/packages/9b/62/760f2b55866b496bb1fa7da2a6db076bef908110e568b02fcfc1422e2a3a/numpy-2.4.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:297837823f5bc572c5f9379b0c9f3a3365f08492cbdc33bcc3af174372ebb168", size = 14702161, upload-time = "2026-03-09T07:57:46.169Z" },
+ { url = "https://files.pythonhosted.org/packages/32/af/a7a39464e2c0a21526fb4fb76e346fb172ebc92f6d1c7a07c2c139cc17b1/numpy-2.4.3-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:a111698b4a3f8dcbe54c64a7708f049355abd603e619013c346553c1fd4ca90b", size = 5208738, upload-time = "2026-03-09T07:57:48.506Z" },
+ { url = "https://files.pythonhosted.org/packages/29/8c/2a0cf86a59558fa078d83805589c2de490f29ed4fb336c14313a161d358a/numpy-2.4.3-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:4bd4741a6a676770e0e97fe9ab2e51de01183df3dcbcec591d26d331a40de950", size = 6543618, upload-time = "2026-03-09T07:57:50.591Z" },
+ { url = "https://files.pythonhosted.org/packages/aa/b8/612ce010c0728b1c363fa4ea3aa4c22fe1c5da1de008486f8c2f5cb92fae/numpy-2.4.3-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:54f29b877279d51e210e0c80709ee14ccbbad647810e8f3d375561c45ef613dd", size = 15680676, upload-time = "2026-03-09T07:57:52.34Z" },
+ { url = "https://files.pythonhosted.org/packages/a9/7e/4f120ecc54ba26ddf3dc348eeb9eb063f421de65c05fc961941798feea18/numpy-2.4.3-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:679f2a834bae9020f81534671c56fd0cc76dd7e5182f57131478e23d0dc59e24", size = 16613492, upload-time = "2026-03-09T07:57:54.91Z" },
+ { url = "https://files.pythonhosted.org/packages/2c/86/1b6020db73be330c4b45d5c6ee4295d59cfeef0e3ea323959d053e5a6909/numpy-2.4.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:d84f0f881cb2225c2dfd7f78a10a5645d487a496c6668d6cc39f0f114164f3d0", size = 17031789, upload-time = "2026-03-09T07:57:57.641Z" },
+ { url = "https://files.pythonhosted.org/packages/07/3a/3b90463bf41ebc21d1b7e06079f03070334374208c0f9a1f05e4ae8455e7/numpy-2.4.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d213c7e6e8d211888cc359bab7199670a00f5b82c0978b9d1c75baf1eddbeac0", size = 18339941, upload-time = "2026-03-09T07:58:00.577Z" },
+ { url = "https://files.pythonhosted.org/packages/a8/74/6d736c4cd962259fd8bae9be27363eb4883a2f9069763747347544c2a487/numpy-2.4.3-cp314-cp314-win32.whl", hash = "sha256:52077feedeff7c76ed7c9f1a0428558e50825347b7545bbb8523da2cd55c547a", size = 6007503, upload-time = "2026-03-09T07:58:03.331Z" },
+ { url = "https://files.pythonhosted.org/packages/48/39/c56ef87af669364356bb011922ef0734fc49dad51964568634c72a009488/numpy-2.4.3-cp314-cp314-win_amd64.whl", hash = "sha256:0448e7f9caefb34b4b7dd2b77f21e8906e5d6f0365ad525f9f4f530b13df2afc", size = 12444915, upload-time = "2026-03-09T07:58:06.353Z" },
+ { url = "https://files.pythonhosted.org/packages/9d/1f/ab8528e38d295fd349310807496fabb7cf9fe2e1f70b97bc20a483ea9d4a/numpy-2.4.3-cp314-cp314-win_arm64.whl", hash = "sha256:b44fd60341c4d9783039598efadd03617fa28d041fc37d22b62d08f2027fa0e7", size = 10494875, upload-time = "2026-03-09T07:58:08.734Z" },
+ { url = "https://files.pythonhosted.org/packages/e6/ef/b7c35e4d5ef141b836658ab21a66d1a573e15b335b1d111d31f26c8ef80f/numpy-2.4.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0a195f4216be9305a73c0e91c9b026a35f2161237cf1c6de9b681637772ea657", size = 14822225, upload-time = "2026-03-09T07:58:11.034Z" },
+ { url = "https://files.pythonhosted.org/packages/cd/8d/7730fa9278cf6648639946cc816e7cc89f0d891602584697923375f801ed/numpy-2.4.3-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:cd32fbacb9fd1bf041bf8e89e4576b6f00b895f06d00914820ae06a616bdfef7", size = 5328769, upload-time = "2026-03-09T07:58:13.67Z" },
+ { url = "https://files.pythonhosted.org/packages/47/01/d2a137317c958b074d338807c1b6a383406cdf8b8e53b075d804cc3d211d/numpy-2.4.3-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:2e03c05abaee1f672e9d67bc858f300b5ccba1c21397211e8d77d98350972093", size = 6649461, upload-time = "2026-03-09T07:58:15.912Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/34/812ce12bc0f00272a4b0ec0d713cd237cb390666eb6206323d1cc9cedbb2/numpy-2.4.3-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7d1ce23cce91fcea443320a9d0ece9b9305d4368875bab09538f7a5b4131938a", size = 15725809, upload-time = "2026-03-09T07:58:17.787Z" },
+ { url = "https://files.pythonhosted.org/packages/25/c0/2aed473a4823e905e765fee3dc2cbf504bd3e68ccb1150fbdabd5c39f527/numpy-2.4.3-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c59020932feb24ed49ffd03704fbab89f22aa9c0d4b180ff45542fe8918f5611", size = 16655242, upload-time = "2026-03-09T07:58:20.476Z" },
+ { url = "https://files.pythonhosted.org/packages/f2/c8/7e052b2fc87aa0e86de23f20e2c42bd261c624748aa8efd2c78f7bb8d8c6/numpy-2.4.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:9684823a78a6cd6ad7511fc5e25b07947d1d5b5e2812c93fe99d7d4195130720", size = 17080660, upload-time = "2026-03-09T07:58:23.067Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/3d/0876746044db2adcb11549f214d104f2e1be00f07a67edbb4e2812094847/numpy-2.4.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:0200b25c687033316fb39f0ff4e3e690e8957a2c3c8d22499891ec58c37a3eb5", size = 18380384, upload-time = "2026-03-09T07:58:25.839Z" },
+ { url = "https://files.pythonhosted.org/packages/07/12/8160bea39da3335737b10308df4f484235fd297f556745f13092aa039d3b/numpy-2.4.3-cp314-cp314t-win32.whl", hash = "sha256:5e10da9e93247e554bb1d22f8edc51847ddd7dde52d85ce31024c1b4312bfba0", size = 6154547, upload-time = "2026-03-09T07:58:28.289Z" },
+ { url = "https://files.pythonhosted.org/packages/42/f3/76534f61f80d74cc9cdf2e570d3d4eeb92c2280a27c39b0aaf471eda7b48/numpy-2.4.3-cp314-cp314t-win_amd64.whl", hash = "sha256:45f003dbdffb997a03da2d1d0cb41fbd24a87507fb41605c0420a3db5bd4667b", size = 12633645, upload-time = "2026-03-09T07:58:30.384Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/b6/7c0d4334c15983cec7f92a69e8ce9b1e6f31857e5ee3a413ac424e6bd63d/numpy-2.4.3-cp314-cp314t-win_arm64.whl", hash = "sha256:4d382735cecd7bcf090172489a525cd7d4087bc331f7df9f60ddc9a296cf208e", size = 10565454, upload-time = "2026-03-09T07:58:33.031Z" },
+]
+
+[[package]]
+name = "nvidia-cuda-runtime-cu12"
+version = "12.9.79"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/bc/e0/0279bd94539fda525e0c8538db29b72a5a8495b0c12173113471d28bce78/nvidia_cuda_runtime_cu12-12.9.79-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:83469a846206f2a733db0c42e223589ab62fd2fabac4432d2f8802de4bded0a4", size = 3515012, upload-time = "2025-06-05T20:00:35.519Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/46/a92db19b8309581092a3add7e6fceb4c301a3fd233969856a8cbf042cd3c/nvidia_cuda_runtime_cu12-12.9.79-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:25bba2dfb01d48a9b59ca474a1ac43c6ebf7011f1b0b8cc44f54eb6ac48a96c3", size = 3493179, upload-time = "2025-06-05T20:00:53.735Z" },
+ { url = "https://files.pythonhosted.org/packages/59/df/e7c3a360be4f7b93cee39271b792669baeb3846c58a4df6dfcf187a7ffab/nvidia_cuda_runtime_cu12-12.9.79-py3-none-win_amd64.whl", hash = "sha256:8e018af8fa02363876860388bd10ccb89eb9ab8fb0aa749aaf58430a9f7c4891", size = 3591604, upload-time = "2025-06-05T20:11:17.036Z" },
+]
+
+[[package]]
+name = "pillow"
+version = "13.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ce/a4/9cc30690a394a8305e8be4c9036aa16d0dfddadd09079860b582f562496d/pillow-13.0.0.tar.gz", hash = "sha256:cdcd1ba258178f7356d74170c9a81ba4eab6a5d55748bc402a5a2a6fe6be3510", size = 47058631, upload-time = "2026-10-16T22:18:09.718Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/7a/b8/58d79332229482eb0d27c82973850808c19d37e5bdc14443d3417bd373f5/pillow-13.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:67c8d44ad89fa7eb88de5d6ef6199b1e03dd24974f85a67639fc8badb801fe79", size = 5568643, upload-time = "2026-10-16T22:15:44.474Z" },
+ { url = "https://files.pythonhosted.org/packages/39/4b/f2ed53d83aa44ac19599ac0a54897f867fafb95f406980d1e24083f8cbe3/pillow-13.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc481f742ccda20e9ed760b8f978dff50f2a4e9bc253ac167fb0a05b0783ef52", size = 4852329, upload-time = "2026-10-16T22:15:46.284Z" },
+ { url = "https://files.pythonhosted.org/packages/3b/bb/9e30e8ed18c20800ee327a12107d5249ad8dc444867b3adfcc21654e3c71/pillow-13.0.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8bf295fe459343bc6093c8e5e0df60bfa189e0fcb775a22e2c2488fdeccc6c0d", size = 6519309, upload-time = "2026-10-16T22:15:48.14Z" },
+ { url = "https://files.pythonhosted.org/packages/e6/99/fdf65cc539e266ab93546c261bdf98411fe165c6e4e13f9dbf597097192b/pillow-13.0.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:42d63be3af4f9b951b199b0a9d23365d37ab14687e6d77b74940432c8515c4ca", size = 7144542, upload-time = "2026-10-16T22:15:50.093Z" },
+ { url = "https://files.pythonhosted.org/packages/26/9b/f38b7c4d8f599537e2d1a6d546cec9beef7536ff8f5c49a3f9c78179d8ac/pillow-13.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:4bd024d567eca931b668978d672dba914d4b8e2628e2c3073a2ad178de8a2620", size = 6618042, upload-time = "2026-10-16T22:15:52.054Z" },
+ { url = "https://files.pythonhosted.org/packages/a8/7c/45ee28531f89ee4582967d8a17f7a26d71ca64cd902b93c269590cd60a00/pillow-13.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:23edf4ec4b6f4f240e8df6e4985e9ee2ced86474632433e55fb1e2548744bf40", size = 7228137, upload-time = "2026-10-16T22:15:54.009Z" },
+ { url = "https://files.pythonhosted.org/packages/01/bc/9c2a969cb1b70201d04fa17fd5aedf02a732870b8da86bceaaa30b0ca385/pillow-13.0.0-cp312-cp312-win32.whl", hash = "sha256:02464da86f561f410e13b061ec37c3068a9cb557a095494157742d07b3c24a27", size = 6515423, upload-time = "2026-10-16T22:15:56.25Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/cd/73a79ecdc822076002eb24b5e1e4a530b0bb5310fcb6d239abbec877110b/pillow-13.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:ff3fe9eb621fbb9db4c4be33ab946f6bac5f98ab50ca8d3260503653656c961b", size = 7272166, upload-time = "2026-10-16T22:15:58.597Z" },
+ { url = "https://files.pythonhosted.org/packages/4a/a3/be5a1236efd085b3984e4305da8f179ae9dab80c991d2ad78f2bd5c4c843/pillow-13.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:c3bc8ee0271387e0b1e3ad0ff893645990a656e79bf9c42f4f734a3642b11d51", size = 2698943, upload-time = "2026-10-16T22:16:00.637Z" },
+ { url = "https://files.pythonhosted.org/packages/82/e2/9132d38df320e8099e2642d9fa538f18a7dfebf68a875a31725dc2a115aa/pillow-13.0.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:e98b4f91f99b24b1da72e10621ba181f7281922384a7403094debb4199de6c00", size = 4190620, upload-time = "2026-10-16T22:16:02.527Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/be/436dac0996876f65ef1916ffb711c5ef4af2ebc57414b6f16642e07f6b47/pillow-13.0.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:34fb3db1149c879343861831728c243c432d4a5afc8f1878ca7612ef8de2a033", size = 4290286, upload-time = "2026-10-16T22:16:04.861Z" },
+ { url = "https://files.pythonhosted.org/packages/60/16/7c1007162e4169ea0d5bec47e2e0b2174f56c50cf5b8c02a1dc23e41037e/pillow-13.0.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:2d50500a4a3bc6469adcdb319cf05d688b08ca3bf0f22a05339f3b25b433a599", size = 3723169, upload-time = "2026-10-16T22:16:06.956Z" },
+ { url = "https://files.pythonhosted.org/packages/08/bc/578ab2eaa04705a8978bd9be0fe15c3d43a8fc95097c4f7e39540e79e4fa/pillow-13.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:ef5fe6b7db3f501c56000ba8fe7c7e1a35ca1d45824fbeb95a67daa85cff4dbe", size = 5568469, upload-time = "2026-10-16T22:16:08.664Z" },
+ { url = "https://files.pythonhosted.org/packages/98/c8/ccede3dcc4f274b80fb49199eed1ef34ba05566c8b71976b9d1f111da2e3/pillow-13.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f11a3c1358bb3c68012a7b1f41b223c3db9f7bfde90b481df028cfe1c3363313", size = 4852187, upload-time = "2026-10-16T22:16:10.693Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/3c/cd0770e96d20bfd990db024bcbd43897ff3e88da1f4782cf90ea231b1d4f/pillow-13.0.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:19b66ca0a4d25cc0200b381ce824c7ea090db61427315e73cfb05dbf1b35c369", size = 6515908, upload-time = "2026-10-16T22:16:12.896Z" },
+ { url = "https://files.pythonhosted.org/packages/ef/fe/f5cdaa2d1c4086e757430f368c271a58ee29cfe7378e7ae7b9d964015c25/pillow-13.0.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5f56499c1a74d2b862beb0c33b8016f99d095858455df9d21583bbbc1c15b582", size = 7142544, upload-time = "2026-10-16T22:16:14.844Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/b5/a54f6d44adbcd23737c8c12953f42be107e4cca64e247c0ca3a5b563061c/pillow-13.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a2a14cd73d5e6c927f644b0110ee81f59c4ef506259ec9183904747f2caacc81", size = 6613097, upload-time = "2026-10-16T22:16:16.893Z" },
+ { url = "https://files.pythonhosted.org/packages/e6/b4/9e6c1207c21b2e91db0d15c16d30f3701ce5add1bd4da0e787761e66cb6e/pillow-13.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:08b826a9bf1265c76de04a42061d61ea6b109418b7826f28ff1ecdfaa26c5502", size = 7224846, upload-time = "2026-10-16T22:16:19.195Z" },
+ { url = "https://files.pythonhosted.org/packages/78/9f/d3c3cb0518f3dd1eee0ef501535f53d15597a53c5c4118d178086143397a/pillow-13.0.0-cp313-cp313-win32.whl", hash = "sha256:12b0fa15879fe5a9d9eebe66e4e2d74128a773b1a4448010c9c714f45e04b9d8", size = 6516013, upload-time = "2026-10-16T22:16:21.389Z" },
+ { url = "https://files.pythonhosted.org/packages/d7/ed/1b16fb66a37e1b9e41370b93b2c614c7da761a5b2a41dc333f7af4639962/pillow-13.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:9dda0788a9932776a75d8bcc020076edc308ce2508b51f6739a45e3158b3fc42", size = 7284777, upload-time = "2026-10-16T22:16:23.393Z" },
+ { url = "https://files.pythonhosted.org/packages/87/7d/8d02eba9f7ecc87f8e90f731e032cc4773802f2a843763afd0c66a535ff4/pillow-13.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:40a266371ece581e5de13b6635ef78d7487824af80561b6ca27694a88c19bc0f", size = 2698826, upload-time = "2026-10-16T22:16:25.382Z" },
+ { url = "https://files.pythonhosted.org/packages/8e/45/fbad9c7f5e2f1745c373a434d46072bc84eddfefaa28b852425ac957fda6/pillow-13.0.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:44629d4498c9cb6b2051806155f22141df0d8a929c56134b166655232dfb2f8c", size = 4190721, upload-time = "2026-10-16T22:16:27.524Z" },
+ { url = "https://files.pythonhosted.org/packages/a2/bf/2074902a259a90692c5dbf132885d21671644cbbd3f690047516243a55db/pillow-13.0.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:bf97ba1b5542050e9b0c74e632323b6d8136cc99d64e193abebee22fe6013c76", size = 4290236, upload-time = "2026-10-16T22:16:29.562Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/a5/3d1bb93b8ea38d15d21356c1b8e9f50971ac592aaa248f7fb71739094c0e/pillow-13.0.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:aa694c49787040943570d61c9b8fc01271bd2a2cfdd55f0d896f8aecdce1a981", size = 3723093, upload-time = "2026-10-16T22:16:31.249Z" },
+ { url = "https://files.pythonhosted.org/packages/84/a1/be060135d85187b25fa8b2573786c0e45c62ae27527fff5257675eb97f4a/pillow-13.0.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:49c12af515073e9bf511e4ef736743bf70d531a643668722279314b937742ba4", size = 5572253, upload-time = "2026-10-16T22:16:33.103Z" },
+ { url = "https://files.pythonhosted.org/packages/b5/f4/0bf6f1ac9ba7ee2ffe9914aeb410a1035a0c1a3c42f122388d7fc950bc4b/pillow-13.0.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d9b0a2bee3f3e03e9f29057aedb807dbf1e1d96ee1b9d0f422d9db6c8583271d", size = 4852269, upload-time = "2026-10-16T22:16:35.102Z" },
+ { url = "https://files.pythonhosted.org/packages/83/16/b603274617b3e6728da3a0133d4fba1ea8d7fbe0c4ea5fef9cbffa398b8b/pillow-13.0.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5933fcea5a5ba64c686f55c886a115cbfd92f2900460784a1e79909fdbafd7b6", size = 6516058, upload-time = "2026-10-16T22:16:37.228Z" },
+ { url = "https://files.pythonhosted.org/packages/1d/f2/1371707ce438ba9a43f9d24089828494ec6f9396e28cd7903aa704dd6306/pillow-13.0.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e91c2b1cbeae768c98752e67e717e283d68dae45717b41f2d91eaee648e37b7d", size = 7142574, upload-time = "2026-10-16T22:16:39.172Z" },
+ { url = "https://files.pythonhosted.org/packages/b9/a9/62cf68587f910bc87c5951bcb6e9430c7643a65076adf5f18b4bf350e2bd/pillow-13.0.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7f6299e494e46253d40c34653cac369412f44ca53b5f85d848d3f95b1ed0546c", size = 6614295, upload-time = "2026-10-16T22:16:41.117Z" },
+ { url = "https://files.pythonhosted.org/packages/6c/c9/9e9b48178649730299be0bafbf5f810a5b6977538f5a92d47e4ba5f5d608/pillow-13.0.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f9bd7d260d986f3553518c5d723544346fa48031f8aef3265d786aeb59845bc0", size = 7224841, upload-time = "2026-10-16T22:16:43.118Z" },
+ { url = "https://files.pythonhosted.org/packages/8f/48/c44e91384b1b6c072a714a63d00608acc16a6a968735e478e4be4384e5ac/pillow-13.0.0-cp314-cp314-win32.whl", hash = "sha256:2e31c4e68cffd7b1f116127626813b82fcba19edf6b940a7b0c266d6484d0055", size = 6508694, upload-time = "2026-10-16T22:16:45.883Z" },
+ { url = "https://files.pythonhosted.org/packages/50/e2/7ad17747517e4c813dca78257d6bb593466f8231baf1384bc98d92745edb/pillow-13.0.0-cp314-cp314-win_amd64.whl", hash = "sha256:f7cbb7a64e7ec664775195e4f81923bc8a93d9451b963f844e59118f63147a7a", size = 7281830, upload-time = "2026-10-16T22:16:47.725Z" },
+ { url = "https://files.pythonhosted.org/packages/41/9f/e5b51f2ce8ef4563215334035403ce61a244f93a2e65c24a940131618f87/pillow-13.0.0-cp314-cp314-win_arm64.whl", hash = "sha256:a6aaa7871aebca081eb5c45f83e845bbd9712ae99fa9286dbfdcee835e63f4b4", size = 2695468, upload-time = "2026-10-16T22:16:49.515Z" },
+ { url = "https://files.pythonhosted.org/packages/97/73/a53502f731f6c84805a4ce87a8881e86d07a65aee64728b900d112dc703e/pillow-13.0.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:7b999816b5850a35ada08443e6e03945f1f6488144a83afe2d37b240a552aafa", size = 5578196, upload-time = "2026-10-16T22:16:51.291Z" },
+ { url = "https://files.pythonhosted.org/packages/21/50/7e949959a56b5559c78ef172b70fc6025706acb289f3f648a15329e4fa6f/pillow-13.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:67871a13cf47275201553b536c025da777f997fa562a19eb798af4ad4b97c18f", size = 4857276, upload-time = "2026-10-16T22:16:53.399Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/52/43ded0ac08e77e39d17bd6d894162572201b5e8fdc4a022b14c55a1960a4/pillow-13.0.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e8ca8f69b7c77fa96dad99f8638c1fc4f1c0bed4acaa1baf7a3c31bdb80a0ab1", size = 6607008, upload-time = "2026-10-16T22:16:55.525Z" },
+ { url = "https://files.pythonhosted.org/packages/0d/2e/4a57ed216d5bf877387cba4d44c02aa87abe51ad2e06404aa6b597c4da39/pillow-13.0.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6bce6a29c3898191f4c9998e4d4e8f69790caeabde46e54da4bc235ce5bde683", size = 7224281, upload-time = "2026-10-16T22:16:57.738Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/3d/2929b248e135752d63aaeabf53f6de797e905b7b6263f9c1e2adade20aba/pillow-13.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:816752a5ef76a80484c8c441c85593b7ea9304f6231fc5776ad1fbff7e773058", size = 6695600, upload-time = "2026-10-16T22:16:59.842Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/33/fb0da992cf084ed1ee6ee05e96b6191e35c351eb707ca2df874feb24ce47/pillow-13.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5bdb38ba220b61b4ec31dd1046dea6b016d3c6850a23f43ed8b58332b2fc668e", size = 7300589, upload-time = "2026-10-16T22:17:01.686Z" },
+ { url = "https://files.pythonhosted.org/packages/bb/af/c30dd9ef6a3dce84ecb1b2393cac629047a32e66279056c6cb46c3ffd65c/pillow-13.0.0-cp314-cp314t-win32.whl", hash = "sha256:06903aac074d00c988e77a1fc435286dc498506d4ca8d6f69df9babddf4ecc15", size = 6517204, upload-time = "2026-10-16T22:17:03.722Z" },
+ { url = "https://files.pythonhosted.org/packages/85/d5/ef3a8ae7609c8ab26570abf18194882534b480d245a9148b895a2262c004/pillow-13.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:9a635068d9793c7f0d929f39f18b58f1bd86c236e8e7b64167b86af9232ebca0", size = 7286695, upload-time = "2026-10-16T22:17:05.543Z" },
+ { url = "https://files.pythonhosted.org/packages/84/3c/0861db0c69a03689ebe3e7599d35668a414deb5aaafd8255215e4e62e3d3/pillow-13.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0d1a9cf7bc6917538b20f8d06b9ab2147e542f68849e96fc58eb66bdf6acc692", size = 2698098, upload-time = "2026-10-16T22:17:07.674Z" },
+ { url = "https://files.pythonhosted.org/packages/6e/eb/e86a41962a3a31ad495a3d6a912d9002b01bba4a6fa71c28703abdca7f69/pillow-13.0.0-cp315-cp315-ios_13_0_arm64_iphoneos.whl", hash = "sha256:7d5e097eabd5d4915c27ac9f6e9325bb1e01a7c94d7348b5c4451d3fc30e8521", size = 4191213, upload-time = "2026-10-16T22:17:09.449Z" },
+ { url = "https://files.pythonhosted.org/packages/dd/04/7e7445e706afec84ef06dc25b2c77f9cecff242c23730c62928ad1089d4a/pillow-13.0.0-cp315-cp315-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:51ebb529fc5e8abdd55302f6c3f8943037348ec2384329a3e55677f69ae2fdfc", size = 4290650, upload-time = "2026-10-16T22:17:11.196Z" },
+ { url = "https://files.pythonhosted.org/packages/46/85/d534089068ac40c0f61f650389a296c812eab745a8a733f81feec39ae955/pillow-13.0.0-cp315-cp315-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:c87a04e7f152ee4db5dbe15f0bfa3fe628a1aeedbe66b81c43b87f52c813f9ac", size = 3723078, upload-time = "2026-10-16T22:17:12.772Z" },
+ { url = "https://files.pythonhosted.org/packages/ce/2b/00b5c3b401df538b5dbe311d3899730fae5ba1e21cb8b80a128887ac6747/pillow-13.0.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:20722cd5375533ad754053363a80b8fb30c79d37930a6f7228030e237ce3bd5d", size = 5572292, upload-time = "2026-10-16T22:17:14.539Z" },
+ { url = "https://files.pythonhosted.org/packages/72/f5/a6b0610f946e9b54ae888ba7ad29d6e2f8d9b11f69e212d70416b7186c09/pillow-13.0.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:04a63720f79e22fd54d897c233a68314c50ca0603360f54ce2bd5db8f0f43782", size = 4852222, upload-time = "2026-10-16T22:17:16.521Z" },
+ { url = "https://files.pythonhosted.org/packages/1e/d0/c0ff25bb0427ec70f32aac995453321fc3c4494a46c7292ff02d9d260b04/pillow-13.0.0-cp315-cp315-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4f8db54177035a2b5f717f94475b74907e12a96dc74f6d487f3966b0a4694071", size = 6527349, upload-time = "2026-10-16T22:17:18.534Z" },
+ { url = "https://files.pythonhosted.org/packages/85/11/e46fa0bcc0fc117f1eacc206b3d51f04d583fab328b4b740672d0438d83f/pillow-13.0.0-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8f36aa77f74b14a2103622b196402c71330e4e7cf4122ee45c854e9a01e0eecf", size = 7152873, upload-time = "2026-10-16T22:17:20.415Z" },
+ { url = "https://files.pythonhosted.org/packages/7c/53/2bdeca705f3a58679fa9201233193c86a30238340ca29b3a152c3fcc719b/pillow-13.0.0-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:149a1c323ba366f90b48e6f1a6db6582eb50512df374588de56fc909abc0f0f3", size = 6626871, upload-time = "2026-10-16T22:17:22.361Z" },
+ { url = "https://files.pythonhosted.org/packages/14/de/3829030f209722ade3753bb456b805a0e7f885cf885b483407365c82e9ca/pillow-13.0.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:e892354a424b1e82a78ba16785822bdd40de06f19446a3d4a28047df1a4f8932", size = 7236439, upload-time = "2026-10-16T22:17:24.352Z" },
+ { url = "https://files.pythonhosted.org/packages/44/b1/67fc37388382bc036a74f04da5bb6fcbf90ec3ac1f45893e06176c373fd3/pillow-13.0.0-cp315-cp315-win32.whl", hash = "sha256:8e459b613cf31f8980f584387b4fe47bf08e076e288d61aa8eba1f7fd4ddbb81", size = 6508688, upload-time = "2026-10-16T22:17:26.314Z" },
+ { url = "https://files.pythonhosted.org/packages/44/05/fdb6a79aee10861165526b41b7b440e36ee1ff58613b2fbefe3acbf06d4f/pillow-13.0.0-cp315-cp315-win_amd64.whl", hash = "sha256:d4737f50d23ddd11d6685faacbb9252887dde0bc7997127757247983d74399d6", size = 7281107, upload-time = "2026-10-16T22:17:28.198Z" },
+ { url = "https://files.pythonhosted.org/packages/e6/9c/6c6f7dc2a566467baf121394e83de25ac287cffe34cc030726beb4be0224/pillow-13.0.0-cp315-cp315-win_arm64.whl", hash = "sha256:2310e2adfc13c6d457d7d0f2ffdd5c56a74a317650cf765887df8d515a647ac0", size = 2695513, upload-time = "2026-10-16T22:17:30.013Z" },
+ { url = "https://files.pythonhosted.org/packages/23/16/e9120defdb8bff693b582d035312acc6f530cdc2bc5238a87f410efccd82/pillow-13.0.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:21c32061a5512dc13f87cc7303e120e4d77c2f70df89a35af0e3ce246e5ac57f", size = 5578129, upload-time = "2026-10-16T22:17:31.642Z" },
+ { url = "https://files.pythonhosted.org/packages/47/22/76faf2bb2448f48a84cf894c1e2bb1090d7d2b1aa521ece131cb2f05d631/pillow-13.0.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:1c774b9c0ba0d0b356f71530677b39028878a2cae5a93e0a13779cfd17120f88", size = 4857428, upload-time = "2026-10-16T22:17:33.43Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/64/0861ea4e03c50b14af9ed9dd8b9f388ab42f445c623a9fcbab19aef7aa55/pillow-13.0.0-cp315-cp315t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:20822140c9a2ba9c5e42df342b0a892ab2e102fc0e3db967a133bb9ce3f898bb", size = 6612582, upload-time = "2026-10-16T22:17:35.415Z" },
+ { url = "https://files.pythonhosted.org/packages/5c/20/cd1e9b3f60a9f3d5ebe46da36955c26004092a501f7f2c42f9fcc26611bc/pillow-13.0.0-cp315-cp315t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ffea6b2986a797c84b6d1d27d4f43e0b83c73fc16281a930891cd237cf0d08fe", size = 7230176, upload-time = "2026-10-16T22:17:37.362Z" },
+ { url = "https://files.pythonhosted.org/packages/b6/ef/ffb0a2fc85690714fb7ac662956949645d57f15bf4426f520da361e7b6e3/pillow-13.0.0-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:05cd2cd39055d0b9650060e4513ef4a9a0aea870083950bd046a0d6490f93a22", size = 6703640, upload-time = "2026-10-16T22:17:39.313Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/c2/6402ee3ccb3363aeed8fdb3f9fe56703ac5377a539f0b81b53999d7e121f/pillow-13.0.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:c6fd031333dedcad7ce3e03d244093f43504f209e86925ebdb2b868fa4037630", size = 7309231, upload-time = "2026-10-16T22:17:41.021Z" },
+ { url = "https://files.pythonhosted.org/packages/fc/96/d6b82e8b8c06ad143b66b12e0b31051e4bf489b4fabca1f390a14fe1ebde/pillow-13.0.0-cp315-cp315t-win32.whl", hash = "sha256:c50c80e3591e5cf9a8dfa6007d4f10732f02e32263850999286e56ccd650cfb2", size = 6517200, upload-time = "2026-10-16T22:17:42.886Z" },
+ { url = "https://files.pythonhosted.org/packages/60/d4/0062e6005e9b270b165015aafd343364ac378ec5a685431ea42baad33357/pillow-13.0.0-cp315-cp315t-win_amd64.whl", hash = "sha256:adb3c2124c68e480f4632d06cb7caa3b48a51678475f483b4edb1c6dee29ea43", size = 7287488, upload-time = "2026-10-16T22:17:45.56Z" },
+ { url = "https://files.pythonhosted.org/packages/e4/81/b8eb349746be7bce47dd95337c6634e84910af91b59aaa9159c034c614fa/pillow-13.0.0-cp315-cp315t-win_arm64.whl", hash = "sha256:4a25756244bdcce3b50580baadf320fa48297f0eeb8e114ba64139a40d4d0fc8", size = 2698073, upload-time = "2026-10-16T22:17:47.556Z" },
+ { url = "https://files.pythonhosted.org/packages/60/da/f6d644e631c5b370c5d0b899f3ccadd2780aab070b29a110527cf4e1fd2c/pillow-13.0.0-pp312-pypy312_pp80-macosx_10_15_x86_64.whl", hash = "sha256:8619685cad8efc4c38c66d3b36aad854523297c43d748b3b6f0cc03c90ba3463", size = 5523188, upload-time = "2026-10-16T22:17:59.334Z" },
+ { url = "https://files.pythonhosted.org/packages/e4/b0/2594f202d743a35d4fe80682bfd96f277e5ca7aecb27cf64ef5bfc1d000b/pillow-13.0.0-pp312-pypy312_pp80-macosx_11_0_arm64.whl", hash = "sha256:7e91e97a929232cdb828889ee6ad0e48d7f40f4ec38818f4e4a8968b2b1af22e", size = 4806808, upload-time = "2026-10-16T22:18:01.188Z" },
+ { url = "https://files.pythonhosted.org/packages/8e/ed/d504165ef79af6fafe25c76726cf30f544cc236002f7ed054f1d51adc4ff/pillow-13.0.0-pp312-pypy312_pp80-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:93ff9c9c3663ce23aaa5d0b6b6abac55359e2a0c06c7e30f3771829af816be63", size = 5464358, upload-time = "2026-10-16T22:18:02.779Z" },
+ { url = "https://files.pythonhosted.org/packages/7b/fe/a10aba5503ca13e9e009b8bd0a1a4ce5584bdce246245fd6f3a83701369c/pillow-13.0.0-pp312-pypy312_pp80-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e65dd6e75de67b2362a4fa3e16aa627595f65054dc4ec73d64680c84d592fa61", size = 6043514, upload-time = "2026-10-16T22:18:04.538Z" },
+ { url = "https://files.pythonhosted.org/packages/c0/37/66b12dc476041fe523bca29c9d58fbf1ea92a4eaf73acfb9e993948f1191/pillow-13.0.0-pp312-pypy312_pp80-win_amd64.whl", hash = "sha256:567f20f1c75897d7663830da6ea8af719e03d712b1d9ee7f813319f9ece42e5a", size = 7366030, upload-time = "2026-10-16T22:18:06.638Z" },
+]
+
+[[package]]
+name = "pyglet"
+version = "2.1.13"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/77/b4/b78df1ec545a151cb7ee64a1632e8f33ba8bd1a97329e4918e76761a80d9/pyglet-2.1.13.tar.gz", hash = "sha256:37a31c212b51658f7c125613f93818a199e8808f86e9b1abe7bfe5395661eee3", size = 6594811, upload-time = "2026-02-04T00:28:11.369Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/73/54/14edde2376d6e264e66c6aeba0f31d58319084ae93b794503b5e140d45d1/pyglet-2.1.13-py3-none-any.whl", hash = "sha256:7ded34c30d07a9290b9bddb2aa91b2861be552144a87dc68fb6f4288b5dbb21a", size = 1032775, upload-time = "2026-02-04T00:28:06.954Z" },
+]
+
+[[package]]
+name = "pyopengl"
+version = "3.1.10"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/16/912b7225d56284859cd9a672827f18be43f8012f8b7b932bc4bd959a298e/pyopengl-3.1.10.tar.gz", hash = "sha256:c4a02d6866b54eb119c8e9b3fb04fa835a95ab802dd96607ab4cdb0012df8335", size = 1915580, upload-time = "2025-08-18T02:33:01.76Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/de/e4/1ba6f44e491c4eece978685230dde56b14d51a0365bc1b774ddaa94d14cd/pyopengl-3.1.10-py3-none-any.whl", hash = "sha256:794a943daced39300879e4e47bd94525280685f42dbb5a998d336cfff151d74f", size = 3194996, upload-time = "2025-08-18T02:32:59.902Z" },
+]
+
+[[package]]
+name = "scipy"
+version = "1.17.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "numpy" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7a/97/5a3609c4f8d58b039179648e62dd220f89864f56f7357f5d4f45c29eb2cc/scipy-1.17.1.tar.gz", hash = "sha256:95d8e012d8cb8816c226aef832200b1d45109ed4464303e997c5b13122b297c0", size = 30573822, upload-time = "2026-02-23T00:26:24.851Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/35/48/b992b488d6f299dbe3f11a20b24d3dda3d46f1a635ede1c46b5b17a7b163/scipy-1.17.1-cp312-cp312-macosx_10_14_x86_64.whl", hash = "sha256:35c3a56d2ef83efc372eaec584314bd0ef2e2f0d2adb21c55e6ad5b344c0dcb8", size = 31610954, upload-time = "2026-02-23T00:17:49.855Z" },
+ { url = "https://files.pythonhosted.org/packages/b2/02/cf107b01494c19dc100f1d0b7ac3cc08666e96ba2d64db7626066cee895e/scipy-1.17.1-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:fcb310ddb270a06114bb64bbe53c94926b943f5b7f0842194d585c65eb4edd76", size = 28172662, upload-time = "2026-02-23T00:18:01.64Z" },
+ { url = "https://files.pythonhosted.org/packages/cf/a9/599c28631bad314d219cf9ffd40e985b24d603fc8a2f4ccc5ae8419a535b/scipy-1.17.1-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:cc90d2e9c7e5c7f1a482c9875007c095c3194b1cfedca3c2f3291cdc2bc7c086", size = 20344366, upload-time = "2026-02-23T00:18:12.015Z" },
+ { url = "https://files.pythonhosted.org/packages/35/f5/906eda513271c8deb5af284e5ef0206d17a96239af79f9fa0aebfe0e36b4/scipy-1.17.1-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:c80be5ede8f3f8eded4eff73cc99a25c388ce98e555b17d31da05287015ffa5b", size = 22704017, upload-time = "2026-02-23T00:18:21.502Z" },
+ { url = "https://files.pythonhosted.org/packages/da/34/16f10e3042d2f1d6b66e0428308ab52224b6a23049cb2f5c1756f713815f/scipy-1.17.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e19ebea31758fac5893a2ac360fedd00116cbb7628e650842a6691ba7ca28a21", size = 32927842, upload-time = "2026-02-23T00:18:35.367Z" },
+ { url = "https://files.pythonhosted.org/packages/01/8e/1e35281b8ab6d5d72ebe9911edcdffa3f36b04ed9d51dec6dd140396e220/scipy-1.17.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:02ae3b274fde71c5e92ac4d54bc06c42d80e399fec704383dcd99b301df37458", size = 35235890, upload-time = "2026-02-23T00:18:49.188Z" },
+ { url = "https://files.pythonhosted.org/packages/c5/5c/9d7f4c88bea6e0d5a4f1bc0506a53a00e9fcb198de372bfe4d3652cef482/scipy-1.17.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8a604bae87c6195d8b1045eddece0514d041604b14f2727bbc2b3020172045eb", size = 35003557, upload-time = "2026-02-23T00:18:54.74Z" },
+ { url = "https://files.pythonhosted.org/packages/65/94/7698add8f276dbab7a9de9fb6b0e02fc13ee61d51c7c3f85ac28b65e1239/scipy-1.17.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:f590cd684941912d10becc07325a3eeb77886fe981415660d9265c4c418d0bea", size = 37625856, upload-time = "2026-02-23T00:19:00.307Z" },
+ { url = "https://files.pythonhosted.org/packages/a2/84/dc08d77fbf3d87d3ee27f6a0c6dcce1de5829a64f2eae85a0ecc1f0daa73/scipy-1.17.1-cp312-cp312-win_amd64.whl", hash = "sha256:41b71f4a3a4cab9d366cd9065b288efc4d4f3c0b37a91a8e0947fb5bd7f31d87", size = 36549682, upload-time = "2026-02-23T00:19:07.67Z" },
+ { url = "https://files.pythonhosted.org/packages/bc/98/fe9ae9ffb3b54b62559f52dedaebe204b408db8109a8c66fdd04869e6424/scipy-1.17.1-cp312-cp312-win_arm64.whl", hash = "sha256:f4115102802df98b2b0db3cce5cb9b92572633a1197c77b7553e5203f284a5b3", size = 24547340, upload-time = "2026-02-23T00:19:12.024Z" },
+ { url = "https://files.pythonhosted.org/packages/76/27/07ee1b57b65e92645f219b37148a7e7928b82e2b5dbeccecb4dff7c64f0b/scipy-1.17.1-cp313-cp313-macosx_10_14_x86_64.whl", hash = "sha256:5e3c5c011904115f88a39308379c17f91546f77c1667cea98739fe0fccea804c", size = 31590199, upload-time = "2026-02-23T00:19:17.192Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/ae/db19f8ab842e9b724bf5dbb7db29302a91f1e55bc4d04b1025d6d605a2c5/scipy-1.17.1-cp313-cp313-macosx_12_0_arm64.whl", hash = "sha256:6fac755ca3d2c3edcb22f479fceaa241704111414831ddd3bc6056e18516892f", size = 28154001, upload-time = "2026-02-23T00:19:22.241Z" },
+ { url = "https://files.pythonhosted.org/packages/5b/58/3ce96251560107b381cbd6e8413c483bbb1228a6b919fa8652b0d4090e7f/scipy-1.17.1-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:7ff200bf9d24f2e4d5dc6ee8c3ac64d739d3a89e2326ba68aaf6c4a2b838fd7d", size = 20325719, upload-time = "2026-02-23T00:19:26.329Z" },
+ { url = "https://files.pythonhosted.org/packages/b2/83/15087d945e0e4d48ce2377498abf5ad171ae013232ae31d06f336e64c999/scipy-1.17.1-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:4b400bdc6f79fa02a4d86640310dde87a21fba0c979efff5248908c6f15fad1b", size = 22683595, upload-time = "2026-02-23T00:19:30.304Z" },
+ { url = "https://files.pythonhosted.org/packages/b4/e0/e58fbde4a1a594c8be8114eb4aac1a55bcd6587047efc18a61eb1f5c0d30/scipy-1.17.1-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2b64ca7d4aee0102a97f3ba22124052b4bd2152522355073580bf4845e2550b6", size = 32896429, upload-time = "2026-02-23T00:19:35.536Z" },
+ { url = "https://files.pythonhosted.org/packages/f5/5f/f17563f28ff03c7b6799c50d01d5d856a1d55f2676f537ca8d28c7f627cd/scipy-1.17.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:581b2264fc0aa555f3f435a5944da7504ea3a065d7029ad60e7c3d1ae09c5464", size = 35203952, upload-time = "2026-02-23T00:19:42.259Z" },
+ { url = "https://files.pythonhosted.org/packages/8d/a5/9afd17de24f657fdfe4df9a3f1ea049b39aef7c06000c13db1530d81ccca/scipy-1.17.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:beeda3d4ae615106d7094f7e7cef6218392e4465cc95d25f900bebabfded0950", size = 34979063, upload-time = "2026-02-23T00:19:47.547Z" },
+ { url = "https://files.pythonhosted.org/packages/8b/13/88b1d2384b424bf7c924f2038c1c409f8d88bb2a8d49d097861dd64a57b2/scipy-1.17.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6609bc224e9568f65064cfa72edc0f24ee6655b47575954ec6339534b2798369", size = 37598449, upload-time = "2026-02-23T00:19:53.238Z" },
+ { url = "https://files.pythonhosted.org/packages/35/e5/d6d0e51fc888f692a35134336866341c08655d92614f492c6860dc45bb2c/scipy-1.17.1-cp313-cp313-win_amd64.whl", hash = "sha256:37425bc9175607b0268f493d79a292c39f9d001a357bebb6b88fdfaff13f6448", size = 36510943, upload-time = "2026-02-23T00:20:50.89Z" },
+ { url = "https://files.pythonhosted.org/packages/2a/fd/3be73c564e2a01e690e19cc618811540ba5354c67c8680dce3281123fb79/scipy-1.17.1-cp313-cp313-win_arm64.whl", hash = "sha256:5cf36e801231b6a2059bf354720274b7558746f3b1a4efb43fcf557ccd484a87", size = 24545621, upload-time = "2026-02-23T00:20:55.871Z" },
+ { url = "https://files.pythonhosted.org/packages/6f/6b/17787db8b8114933a66f9dcc479a8272e4b4da75fe03b0c282f7b0ade8cd/scipy-1.17.1-cp313-cp313t-macosx_10_14_x86_64.whl", hash = "sha256:d59c30000a16d8edc7e64152e30220bfbd724c9bbb08368c054e24c651314f0a", size = 31936708, upload-time = "2026-02-23T00:19:58.694Z" },
+ { url = "https://files.pythonhosted.org/packages/38/2e/524405c2b6392765ab1e2b722a41d5da33dc5c7b7278184a8ad29b6cb206/scipy-1.17.1-cp313-cp313t-macosx_12_0_arm64.whl", hash = "sha256:010f4333c96c9bb1a4516269e33cb5917b08ef2166d5556ca2fd9f082a9e6ea0", size = 28570135, upload-time = "2026-02-23T00:20:03.934Z" },
+ { url = "https://files.pythonhosted.org/packages/fd/c3/5bd7199f4ea8556c0c8e39f04ccb014ac37d1468e6cfa6a95c6b3562b76e/scipy-1.17.1-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:2ceb2d3e01c5f1d83c4189737a42d9cb2fc38a6eeed225e7515eef71ad301dce", size = 20741977, upload-time = "2026-02-23T00:20:07.935Z" },
+ { url = "https://files.pythonhosted.org/packages/d9/b8/8ccd9b766ad14c78386599708eb745f6b44f08400a5fd0ade7cf89b6fc93/scipy-1.17.1-cp313-cp313t-macosx_14_0_x86_64.whl", hash = "sha256:844e165636711ef41f80b4103ed234181646b98a53c8f05da12ca5ca289134f6", size = 23029601, upload-time = "2026-02-23T00:20:12.161Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/a0/3cb6f4d2fb3e17428ad2880333cac878909ad1a89f678527b5328b93c1d4/scipy-1.17.1-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:158dd96d2207e21c966063e1635b1063cd7787b627b6f07305315dd73d9c679e", size = 33019667, upload-time = "2026-02-23T00:20:17.208Z" },
+ { url = "https://files.pythonhosted.org/packages/f3/c3/2d834a5ac7bf3a0c806ad1508efc02dda3c8c61472a56132d7894c312dea/scipy-1.17.1-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:74cbb80d93260fe2ffa334efa24cb8f2f0f622a9b9febf8b483c0b865bfb3475", size = 35264159, upload-time = "2026-02-23T00:20:23.087Z" },
+ { url = "https://files.pythonhosted.org/packages/4d/77/d3ed4becfdbd217c52062fafe35a72388d1bd82c2d0ba5ca19d6fcc93e11/scipy-1.17.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:dbc12c9f3d185f5c737d801da555fb74b3dcfa1a50b66a1a93e09190f41fab50", size = 35102771, upload-time = "2026-02-23T00:20:28.636Z" },
+ { url = "https://files.pythonhosted.org/packages/bd/12/d19da97efde68ca1ee5538bb261d5d2c062f0c055575128f11a2730e3ac1/scipy-1.17.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:94055a11dfebe37c656e70317e1996dc197e1a15bbcc351bcdd4610e128fe1ca", size = 37665910, upload-time = "2026-02-23T00:20:34.743Z" },
+ { url = "https://files.pythonhosted.org/packages/06/1c/1172a88d507a4baaf72c5a09bb6c018fe2ae0ab622e5830b703a46cc9e44/scipy-1.17.1-cp313-cp313t-win_amd64.whl", hash = "sha256:e30bdeaa5deed6bc27b4cc490823cd0347d7dae09119b8803ae576ea0ce52e4c", size = 36562980, upload-time = "2026-02-23T00:20:40.575Z" },
+ { url = "https://files.pythonhosted.org/packages/70/b0/eb757336e5a76dfa7911f63252e3b7d1de00935d7705cf772db5b45ec238/scipy-1.17.1-cp313-cp313t-win_arm64.whl", hash = "sha256:a720477885a9d2411f94a93d16f9d89bad0f28ca23c3f8daa521e2dcc3f44d49", size = 24856543, upload-time = "2026-02-23T00:20:45.313Z" },
+ { url = "https://files.pythonhosted.org/packages/cf/83/333afb452af6f0fd70414dc04f898647ee1423979ce02efa75c3b0f2c28e/scipy-1.17.1-cp314-cp314-macosx_10_14_x86_64.whl", hash = "sha256:a48a72c77a310327f6a3a920092fa2b8fd03d7deaa60f093038f22d98e096717", size = 31584510, upload-time = "2026-02-23T00:21:01.015Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/a6/d05a85fd51daeb2e4ea71d102f15b34fedca8e931af02594193ae4fd25f7/scipy-1.17.1-cp314-cp314-macosx_12_0_arm64.whl", hash = "sha256:45abad819184f07240d8a696117a7aacd39787af9e0b719d00285549ed19a1e9", size = 28170131, upload-time = "2026-02-23T00:21:05.888Z" },
+ { url = "https://files.pythonhosted.org/packages/db/7b/8624a203326675d7746a254083a187398090a179335b2e4a20e2ddc46e83/scipy-1.17.1-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:3fd1fcdab3ea951b610dc4cef356d416d5802991e7e32b5254828d342f7b7e0b", size = 20342032, upload-time = "2026-02-23T00:21:09.904Z" },
+ { url = "https://files.pythonhosted.org/packages/c9/35/2c342897c00775d688d8ff3987aced3426858fd89d5a0e26e020b660b301/scipy-1.17.1-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:7bdf2da170b67fdf10bca777614b1c7d96ae3ca5794fd9587dce41eb2966e866", size = 22678766, upload-time = "2026-02-23T00:21:14.313Z" },
+ { url = "https://files.pythonhosted.org/packages/ef/f2/7cdb8eb308a1a6ae1e19f945913c82c23c0c442a462a46480ce487fdc0ac/scipy-1.17.1-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:adb2642e060a6549c343603a3851ba76ef0b74cc8c079a9a58121c7ec9fe2350", size = 32957007, upload-time = "2026-02-23T00:21:19.663Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/2e/7eea398450457ecb54e18e9d10110993fa65561c4f3add5e8eccd2b9cd41/scipy-1.17.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eee2cfda04c00a857206a4330f0c5e3e56535494e30ca445eb19ec624ae75118", size = 35221333, upload-time = "2026-02-23T00:21:25.278Z" },
+ { url = "https://files.pythonhosted.org/packages/d9/77/5b8509d03b77f093a0d52e606d3c4f79e8b06d1d38c441dacb1e26cacf46/scipy-1.17.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:d2650c1fb97e184d12d8ba010493ee7b322864f7d3d00d3f9bb97d9c21de4068", size = 35042066, upload-time = "2026-02-23T00:21:31.358Z" },
+ { url = "https://files.pythonhosted.org/packages/f9/df/18f80fb99df40b4070328d5ae5c596f2f00fffb50167e31439e932f29e7d/scipy-1.17.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:08b900519463543aa604a06bec02461558a6e1cef8fdbb8098f77a48a83c8118", size = 37612763, upload-time = "2026-02-23T00:21:37.247Z" },
+ { url = "https://files.pythonhosted.org/packages/4b/39/f0e8ea762a764a9dc52aa7dabcfad51a354819de1f0d4652b6a1122424d6/scipy-1.17.1-cp314-cp314-win_amd64.whl", hash = "sha256:3877ac408e14da24a6196de0ddcace62092bfc12a83823e92e49e40747e52c19", size = 37290984, upload-time = "2026-02-23T00:22:35.023Z" },
+ { url = "https://files.pythonhosted.org/packages/7c/56/fe201e3b0f93d1a8bcf75d3379affd228a63d7e2d80ab45467a74b494947/scipy-1.17.1-cp314-cp314-win_arm64.whl", hash = "sha256:f8885db0bc2bffa59d5c1b72fad7a6a92d3e80e7257f967dd81abb553a90d293", size = 25192877, upload-time = "2026-02-23T00:22:39.798Z" },
+ { url = "https://files.pythonhosted.org/packages/96/ad/f8c414e121f82e02d76f310f16db9899c4fcde36710329502a6b2a3c0392/scipy-1.17.1-cp314-cp314t-macosx_10_14_x86_64.whl", hash = "sha256:1cc682cea2ae55524432f3cdff9e9a3be743d52a7443d0cba9017c23c87ae2f6", size = 31949750, upload-time = "2026-02-23T00:21:42.289Z" },
+ { url = "https://files.pythonhosted.org/packages/7c/b0/c741e8865d61b67c81e255f4f0a832846c064e426636cd7de84e74d209be/scipy-1.17.1-cp314-cp314t-macosx_12_0_arm64.whl", hash = "sha256:2040ad4d1795a0ae89bfc7e8429677f365d45aa9fd5e4587cf1ea737f927b4a1", size = 28585858, upload-time = "2026-02-23T00:21:47.706Z" },
+ { url = "https://files.pythonhosted.org/packages/ed/1b/3985219c6177866628fa7c2595bfd23f193ceebbe472c98a08824b9466ff/scipy-1.17.1-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:131f5aaea57602008f9822e2115029b55d4b5f7c070287699fe45c661d051e39", size = 20757723, upload-time = "2026-02-23T00:21:52.039Z" },
+ { url = "https://files.pythonhosted.org/packages/c0/19/2a04aa25050d656d6f7b9e7b685cc83d6957fb101665bfd9369ca6534563/scipy-1.17.1-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:9cdc1a2fcfd5c52cfb3045feb399f7b3ce822abdde3a193a6b9a60b3cb5854ca", size = 23043098, upload-time = "2026-02-23T00:21:56.185Z" },
+ { url = "https://files.pythonhosted.org/packages/86/f1/3383beb9b5d0dbddd030335bf8a8b32d4317185efe495374f134d8be6cce/scipy-1.17.1-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6e3dcd57ab780c741fde8dc68619de988b966db759a3c3152e8e9142c26295ad", size = 33030397, upload-time = "2026-02-23T00:22:01.404Z" },
+ { url = "https://files.pythonhosted.org/packages/41/68/8f21e8a65a5a03f25a79165ec9d2b28c00e66dc80546cf5eb803aeeff35b/scipy-1.17.1-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a9956e4d4f4a301ebf6cde39850333a6b6110799d470dbbb1e25326ac447f52a", size = 35281163, upload-time = "2026-02-23T00:22:07.024Z" },
+ { url = "https://files.pythonhosted.org/packages/84/8d/c8a5e19479554007a5632ed7529e665c315ae7492b4f946b0deb39870e39/scipy-1.17.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:a4328d245944d09fd639771de275701ccadf5f781ba0ff092ad141e017eccda4", size = 35116291, upload-time = "2026-02-23T00:22:12.585Z" },
+ { url = "https://files.pythonhosted.org/packages/52/52/e57eceff0e342a1f50e274264ed47497b59e6a4e3118808ee58ddda7b74a/scipy-1.17.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:a77cbd07b940d326d39a1d1b37817e2ee4d79cb30e7338f3d0cddffae70fcaa2", size = 37682317, upload-time = "2026-02-23T00:22:18.513Z" },
+ { url = "https://files.pythonhosted.org/packages/11/2f/b29eafe4a3fbc3d6de9662b36e028d5f039e72d345e05c250e121a230dd4/scipy-1.17.1-cp314-cp314t-win_amd64.whl", hash = "sha256:eb092099205ef62cd1782b006658db09e2fed75bffcae7cc0d44052d8aa0f484", size = 37345327, upload-time = "2026-02-23T00:22:24.442Z" },
+ { url = "https://files.pythonhosted.org/packages/07/39/338d9219c4e87f3e708f18857ecd24d22a0c3094752393319553096b98af/scipy-1.17.1-cp314-cp314t-win_arm64.whl", hash = "sha256:200e1050faffacc162be6a486a984a0497866ec54149a01270adc8a59b7c7d21", size = 25489165, upload-time = "2026-02-23T00:22:29.563Z" },
+]
+
+[[package]]
+name = "tensorrt-cu12"
+version = "10.8.0.43"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/90/db/1d1f49a1ea68022155da5cc9f910f1db1093bf983843bb92247e58565ac9/tensorrt_cu12-10.8.0.43.tar.gz", hash = "sha256:0efb7ba28afde0823e6502028da5acabf0f45d321e77a615fe64a6c1af568071", size = 18351, upload-time = "2025-01-24T01:00:29.303Z" }
+
+[[package]]
+name = "tensorrt-cu12-bindings"
+version = "10.8.0.43"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3c/52/43b0def0a97bbe887c4478cc266c40f9a77658f138642b1993e687b117f9/tensorrt_cu12_bindings-10.8.0.43-cp312-none-manylinux_2_28_x86_64.whl", hash = "sha256:496c1274a22719703ec9a1df18bb00d147cd7889295c8ea77337ae602af55ee3", size = 1132945, upload-time = "2025-01-24T00:47:58.741Z" },
+ { url = "https://files.pythonhosted.org/packages/8b/16/c616735478b7df1da92c5d08438ce9cdec255eec2d23e95f31720c650467/tensorrt_cu12_bindings-10.8.0.43-cp312-none-manylinux_2_31_aarch64.whl", hash = "sha256:ae5e7110c6e6337c7158684216a279f6a6baa74598699c779a31bef31418b63c", size = 1174698, upload-time = "2025-01-24T00:36:24.844Z" },
+ { url = "https://files.pythonhosted.org/packages/36/3e/b344360c71c332477dd814ebcf23a4032b36eaf2f3a646b873f1b7bcbc9a/tensorrt_cu12_bindings-10.8.0.43-cp312-none-win_amd64.whl", hash = "sha256:8821ab1386b7786ed3f3ffc3461bbfec30c1bc1fd9e1614a5f4541a9f4638411", size = 848209, upload-time = "2025-01-24T01:01:31.555Z" },
+]
+
+[[package]]
+name = "tensorrt-cu12-libs"
+version = "10.8.0.43"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "nvidia-cuda-runtime-cu12" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e7/6f/68e7568bf53251a88bbcdd114267b32dc5f96a4d4ca64869527f22b360b0/tensorrt_cu12_libs-10.8.0.43.tar.gz", hash = "sha256:dc8d9dd8708558164cb91b2982911d79de0141cc8bcb93fadf2602e2a9e10697", size = 704, upload-time = "2025-01-24T00:42:19.394Z" }
+
+[[package]]
+name = "trimesh"
+version = "5.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "numpy" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a8/45/5b9943631f265073bb96ca4cc2a9de05d151cd8c1a6896fcbaac132a1355/trimesh-5.0.0.tar.gz", hash = "sha256:0195003198baaf2550aebe612254ba2f01c385cec46c37ecc5beca8291f79a13", size = 864019, upload-time = "2026-08-01T00:05:25.042Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/37/82/19a03ba344ecb66ea8caab697b3059e0fbea576420f99945944c479caa78/trimesh-5.0.0-py3-none-any.whl", hash = "sha256:51ec67d7f9f74b918f2a695da5fd511b9c084e96307648ae83f45b58f13f8009", size = 745494, upload-time = "2026-08-01T00:05:23.172Z" },
+]
+
+[[package]]
+name = "usd-core"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a9/aa/817cb9873b10cc21d3666499823cee008fb62c0b832ae13ba4c771ddd758/usd_core-26.3-cp312-none-macosx_10_15_universal2.whl", hash = "sha256:23864f61b7ec9cc4ed04cc46c006190d6930f3663d6e324bd0b8b5ca85bdcc22", size = 39402081, upload-time = "2026-02-24T23:05:51.935Z" },
+ { url = "https://files.pythonhosted.org/packages/e1/90/bc0310887ce7d2d821a672ecaabb85f9c453c0f2dd180a9c27b6d4bdf963/usd_core-26.3-cp312-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:132433bb28f47f29907a41a90d36a3a7126189885088dd87d72dde9649991efa", size = 28468800, upload-time = "2026-02-24T23:05:54.731Z" },
+ { url = "https://files.pythonhosted.org/packages/34/21/e2a51a872dbf9af30dfd1a023f764c2171a453ce7327b966344b76d764ca/usd_core-26.3-cp312-none-win_amd64.whl", hash = "sha256:c436aef60e9e60e391dcd93f94565dda81137c6c91330aabed26653106cf0a35", size = 13396142, upload-time = "2026-02-24T23:05:57.545Z" },
+ { url = "https://files.pythonhosted.org/packages/05/51/003cae380540b6319b97b76404565daed917410c63a88224882a827670c7/usd_core-26.3-cp313-none-macosx_10_15_universal2.whl", hash = "sha256:8cad17c9649589b9113f1b3a03dc0497228e289c3852c4c13945ae13d7686a0e", size = 39402266, upload-time = "2026-02-24T23:06:00.343Z" },
+ { url = "https://files.pythonhosted.org/packages/6d/75/4c4c57f544acffa77743afc5c515bbe18e50d5262f7b9b5531028e252bce/usd_core-26.3-cp313-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:28d7003859cd98f6d9b0349198458c81f4caad204783fbc50c648669ac2c3041", size = 28469105, upload-time = "2026-02-24T23:06:03.761Z" },
+ { url = "https://files.pythonhosted.org/packages/5d/8d/85893369128deafccabcf45006fa94e2d6c806a6332d0ac43c1af092625b/usd_core-26.3-cp313-none-win_amd64.whl", hash = "sha256:e2195e1782f7673ba31d861602df8a6444cfe8425f1f3806c03702eea5047cf0", size = 13396170, upload-time = "2026-02-24T23:06:06.31Z" },
+]
+
+[[package]]
+name = "warp-lang"
+version = "1.17.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "numpy" },
+]
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/be/b0/9b1de407fa10b380f5ca4ed1c3e5b129be55ea26a927c7a49e45cdde14b0/warp_lang-1.17.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:f2fec43afb81caa2190c0b7fa3aaf4d869f3599839f0c40b9ead84331f91e993", size = 27544218, upload-time = "2026-08-31T05:52:29.177Z" },
+ { url = "https://files.pythonhosted.org/packages/a6/a1/e11aa6898e8bbb6910e89fe31a3338fb2566f038912010875c072e6dafd1/warp_lang-1.17.0-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:47cd93636828dd16e55eeb4e77a0e3547b5fb0f383000a3d228629df68f28fd8", size = 164347636, upload-time = "2026-08-31T05:53:14.441Z" },
+ { url = "https://files.pythonhosted.org/packages/6e/4f/a17b1f0ebfeabe37326f01afb6109961f20a0165c1258242f46d10a554f5/warp_lang-1.17.0-py3-none-manylinux_2_34_aarch64.whl", hash = "sha256:5051271048da956a8b94e2db9771ce60ce9591a3ac5bb49037f3d6812d1eea00", size = 172665443, upload-time = "2026-08-31T05:53:52.47Z" },
+ { url = "https://files.pythonhosted.org/packages/ff/7a/36306a503085cbfc79c35a28e441c59dd1d8070d2dd65152345ebf2dfec2/warp_lang-1.17.0-py3-none-win_amd64.whl", hash = "sha256:ca35c82242a7553046f09023bbe56750b5c3d9af72625bd1a905a56d3189771d", size = 151236515, upload-time = "2026-08-31T05:54:27.944Z" },
+]