Skip to content
usdCharacterPublic

About

Character rigging engine for OpenUSD: RigExec evaluates controls, solvers and deformers live in the stage and renders via Hydra

Topics

Resources

Contributing

Stars

6 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

334 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

usdRig β€” character rigging for OpenUSD

CI Release v0.2.0 Docs License: MIT

Mech rig in the usdview viewport

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.

See the domain glossary for canonical project and engine terminology.

Status

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.

Features

  • 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 .rigexec export with a standalone binary runtime.
  • usdview tools 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.

Examples

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.

Documentation

The documentation is published at usdcharacter.github.io/usdRig.

Build and run

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.

Windows

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.usda

Linux and macOS

export USD=/path/to/usd-install
export PY=/path/to/python
bin/build_rigexec.sh
bin/usdview.sh examples/ArmShotAnim.usda

The 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-install

Link 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.

Repository layout

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

Development

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.

OpenExec usage

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:

OpenExec reference checks lists what is judged and where the code is. Other upstream and published sources are listed in the method references.

Integrations

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.

About

Character rigging engine for OpenUSD: RigExec evaluates controls, solvers and deformers live in the stage and renders via Hydra

Topics

Resources

Contributing

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages