Warning: work in progress. usdRig is an early AI-generated prototype under active development. Its APIs, behavior, and file formats may change without notice. See layer readiness for per-layer status.
usdRig is an OpenUSD character-rigging project β for animation artists and
for AI agents that build rigs programmatically. Its engine, RigExec,
evaluates controls, constraints, solvers, and geometry deformers by running the
compiled operation graph in memory, without changing the source stage, then
publishes the result through Hydra for playback in usdview. OpenUSD
describes the rig; RigExec is the rigging layer that computes it.
- π¦ Try it now: download a self-contained release bundle (no OpenUSD, Python,
or Qt install needed) from the latest release β
Windows
.zip, macOS (Apple Silicon) and Linux (Ubuntu x86-64).tar.gz. - π Documentation: usdcharacter.github.io/usdRig
- π§© Engine integrations: Godot, Unreal, Maya, Blender
- π€ Contributing: see CONTRIBUTING.md β issues labeled
good first issueare a great entry point.
See the domain glossary for canonical project and engine terminology.
usdRig runs end to end and is MIT-licensed; the v0.2.0 release ships runnable bundles for Windows, macOS and Linux, and later releases follow the bundle policy; per-layer readiness is tracked in STATUS.md (see the warning above for volatility details).
Project-authored code and documentation are MIT licensed; bundled and derived third-party material keeps its own terms. See the licensing guide, the third-party notices, and the distribution NOTICE.
Authors: Nick Burkard and Squarebit Studios' Walt Yoder and Matt Schiller.
- FK, two-bone and single-chain IK, spline IK, twist, and transform constraints.
- Ordered deformation operations called movers, including skinning, blend shapes, lattices, smoothing, and Delta Mush.
- External mover plugins built from separate repositories through a public registration API and CMake helper.
- Scalar, vector, and matrix operations; painted and procedural weight fields.
- Native and frozen evaluation through a shared operation graph, plus
experimental
.rigexecexport with a standalone binary runtime. usdviewtools for controls, curves, layers, picking, and node graphs.
RigExec builds against an OpenUSD installation with OpenExec. The architecture guide explains the evaluation layers; the node reference describes authoring and parameters.
The evaluation guide describes the shared operation graph, frozen execution, binary playback, and independent checks.
Start with the smallest rig, the animated reference arm, or the example catalog. The biped is the full character example.
More motion demos in docs/gifs: Smooth Mover, blend shapes, cloth, position constraints, and more.
The documentation is published at usdcharacter.github.io/usdRig.
- Node reference and tutorials
- Animator tools: picker, hover picker, marking menu, TouchPose and limbs
- Architecture and repository boundaries
- Viewport tools and graph editor
- Bake and inverse APIs
- Build and register external movers
- Inspect the live evaluator graph and thread trace
- Standalone runtime
- Format and plugin API compatibility matrix
- Public method references
- Agent and contributor guide
- Release bundles: self-contained
usdviewdownloads built for everyv<major>.<minor>.0tag
Install OpenUSD 26.08 with OpenExec and usdview, CMake 3.26+, Ninja,
and a C++17 compiler. Use the same Python version and architecture as your
OpenUSD build. See the upstream build instructions.
The helpers default to a sibling ../usd-install installation. Set USD
to use another prefix and PY to select its compatible Python interpreter.
VENV optionally selects a Python virtual environment. On Windows, the build
helper discovers Visual Studio; RIGEXEC_VCVARS can override its toolchain script.
RIGEXEC_BUILD_DIR selects another build tree in place of build/; a
relative value is taken from the checkout root.
bin/_env.sh and bin\_env.bat then put that tree on PATH, the loader path,
PYTHONPATH and PXR_PLUGINPATH_NAME; the build and launch helpers and
bin/test_changed.sh --run build and test it.
Run these commands in Command Prompt:
set USD=C:\path\to\usd-install
set PY=C:\path\to\python.exe
bin\build_rigexec.bat
bin\launch_usdview.bat examples\ArmShotAnim.usdaexport USD=/path/to/usd-install
export PY=/path/to/python
bin/build_rigexec.sh
bin/usdview.sh examples/ArmShotAnim.usdaThe build helper configures the project, builds it, and runs enabled CTest
tests with four concurrent test processes. Set CTEST_PARALLEL_LEVEL to adjust
test concurrency (1 runs serially); JOBS separately controls compilation.
CTest schedules tests as workers become available and respects fixture
dependencies, including bake-before-playback tests.
CI builds and tests the C++ libraries on Ubuntu 24.04, Windows 2022 and macOS 15 with OpenUSD 26.08. It also checks installed scene and oracle consumers. Python bindings and interactive viewer tests remain local checks. See fixture checks for floating-point reference configuration and cross-platform backend parity.
CMake options: RIGEXEC_BUILD_TESTS, RIGEXEC_BUILD_PYTHON (on when pybind11
is found), RIGEXEC_BUILD_USDNOODLES, RIGEXEC_MOVER_PLUGIN_DIRS (see
external movers), RIGEXEC_GOLDEN_SUITE_DIR
and RIGEXEC_TEST_USD_DIR.
For manual configuration in an initialized compiler environment:
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DUSD_INSTALL_DIR=/path/to/usd-install -DCMAKE_PREFIX_PATH=/path/to/usd-install
cmake --build build
ctest --test-dir build --parallel 4 --output-on-failure
cmake --install build --prefix /path/to/rigexec-installLink the installed scene target when compiling rigs from USD stages:
find_package(rigExec CONFIG REQUIRED)
target_link_libraries(myApplication PRIVATE rigExec::rigExecScene)This target retains and registers scene translation in build and installed
consumers. With a manual linker setup, link rigExecScene and call
RigExecRegisterScene() from rigExecScene/registerScene.h before compiling
or evaluating. Once registered, keep that library loaded for the process
lifetime. Missing scene support returns a compile error or an invalid pose with
diagnostics. rigExec::rigExec alone supplies the evaluator core.
For optional CPU reference checks or golden capture, also link
rigExec::rigExecOracle. That target retains and registers oracle support in
build and installed consumers. Manual linker users call RigExecRegisterOracle()
from rigExecOracle/registerOracle.h and keep the library loaded for the process
lifetime. Missing support reports an error; golden APIs without an error channel
throw std::runtime_error.
| Directory | Purpose |
|---|---|
libs/rigExecMath |
Solver, deformation, interpolation, and weight math |
libs/rigExecSchema |
Authored USD schema definitions |
libs/rigExec |
Evaluator, compiled evaluation, invalidation, and caches |
libs/rigExecScene |
USD scene translation into the shared operation graph |
libs/rigExecGraph |
Shared operation compiler, typed values, and executor |
libs/rigExecOracle |
Optional independent reference checks and golden capture |
libs/rigExecAuthoring |
C++ authoring API |
libs/rigExecImaging |
Hydra scene indices and viewport publication |
libs/rigExecGpu |
OpenGL compute path for per-vertex deformation and cloth |
libs/rigExecBake, libs/rigExecBinary, libs/rigExecRuntime |
Binary export, format, and playback |
libs/rigExecSampler |
Stage values copied into binary-runtime inputs |
libs/rigExecStandalone |
Experimental stage-free scene runtime and rigpack backend |
python |
Python bindings and authoring helpers |
plugin |
Schema resources and optional viewer tools |
tests, examples, docs |
Verification, sample stages, and documentation |
bin, tools |
Environment helpers and command-line programs |
packaging |
Release-bundle launcher, assembly, and signing scripts |
Run the build helper after native changes. For Python interaction math, use
bin/test/run_python_tests.sh or bin\test\run_python_tests.bat. Viewer integration
checks are available through the bin/test/run_testusdview* helpers and require a
working graphics context.
After loading bin/_env.sh or bin\_env.bat, run testusdview --testScript tests/testUsdviewPlayback.py docs/examples/tutorial_rolling_ball.usda to check
first-loop and steady playback at the stage rate, then measure completed paints
at 1280 Γ 720 with playback requested at 120 fps. RIGEXEC_PLAYBACK_MIN_FPS
sets the throughput requirement (24 by default).
Node pages are generated from libs/rigExecSchema/schema.usda and
docs/operator_notes.py by python docs/build_pages.py. Generate the optional
HTML reference with python docs/build_html.py (requires markdown). Generated
HTML and local sizzle material are ignored by Git.
The documentation site is built with MkDocs from docs/ and mkdocs.yml:
python -m pip install -r docs/requirements.txt, then python -m mkdocs serve
to preview it. .github/workflows/docs.yml publishes it to GitHub Pages.
The standalone backends support a subset of the authoring/runtime surface. Check their guides before integration. Changes to OpenUSD versions or binary formats require explicit compatibility testing.
RigExec builds against OpenExec
from an unmodified OpenUSD 26.08 installation: the rigExec target links exec,
execUsd, ef and vdf in CMakeLists.txt. Native, frozen,
.rigexec and standalone-scene evaluation run the shared operation graph, and the
binary runtime links no USD or OpenExec library. No option selects OpenExec
evaluation and no failure falls back to it.
OpenExec runs in these places:
- libs/rigExec/types.cpp registers the value types with
ExecTypeRegistry; libs/rigExec/computations.cpp and libs/rigExec/moverKernels.cpp register the schema computations against the production kernels. - libs/rigExec/tapSet.cpp owns the one
ExecUsdSystemper stage and builds its batched requests. rigExecPose --exec-crosscheckcompares each eligible native row, bit for bit, with a one-key request fed that operation's captured inputs as overrides: tools/rigExecPose.cpp, libs/rigExecOracle/bakedExecCrossCheck.cpp, libs/rigExecOracle/bakedExecCrossCheckRows.cpp. The registrations share the production kernels, so this checks input binding, not arithmetic.- Tests ask the same registrations for reference values, for example tests/testRigExecArm.cpp and tests/testRigExecExecCrossCheck.cpp.
OpenExec reference checks lists what is judged and where the code is. Other upstream and published sources are listed in the method references.
RigExec's evaluation and playback layers are consumed outside this repository.
| Integration | What it does | Availability |
|---|---|---|
| usdRig_godot | Godot 4.7+ plugin that plays a baked .rigexec character with no USD installation; see the Godot tutorial |
public |
| usdRig_unreal | Unreal Engine plugin that re-poses a baked rig in the editor through Control Rig and Sequencer | public |
| usdRig_maya | Maya plug-in animating a rig baked outside Maya, plus a read-only OpenUSD file format for Maya ASCII | public |
| usdRig_blender | Read-only OpenUSD file format that opens Blender .blend files as RigExec rigs |
public |
usdRig_ios |
usdview for iPad with the RigExec viewer plugins and rigExecImaging on Storm over HgiMetal |
closed source |
usdRig_android |
Android port of that viewer on Storm over HgiVulkan | closed source |
Godot, Unreal and the Maya plug-in play baked rigs with the USD-free runtime in
libs/rigExecRuntime, the same operation graph the viewport runs; see
evaluation and checks and
the standalone runtime. The Blender and
Maya ASCII file formats work on the other side of that bake: they translate
source files into native USD rigs that RigExec compiles in this repository.
The mobile rows carry the Hydra path in libs/rigExecImaging and the
plugin/rigExecUsdview tools into their own viewer shells. Which .rigexec
format versions and mover plugin API versions each of these speaks, and where
they currently drift, is listed in the
compatibility matrix.
