Getting started¶
usdRig builds against an unmodified OpenUSD 26.08 installation with
OpenExec, and its RigExec engine loads into usdview as a set of plugins.
This page takes you from a checkout to a character playing in the viewport.
What you need¶
| OpenUSD | 26.08, built with OpenExec and usdview (upstream build instructions) |
| Build tools | CMake 3.26+, Ninja, a C++17 compiler |
| Python | The same version and architecture your OpenUSD was built with |
The helper scripts look for a sibling ../usd-install by default. Set USD
to point at another OpenUSD prefix and PY at its Python interpreter;
VENV optionally selects a virtual environment.
Build¶
The helper configures, builds and runs the enabled CTest suites. To configure by hand instead:
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 --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)
The target registers scene translation automatically. Manual linker users link
rigExecScene and call RigExecRegisterScene() from
rigExecScene/registerScene.h before compiling or evaluating. Once registered,
keep the library loaded for the process lifetime. Missing scene
support is reported through compile errors and pose diagnostics.
Optional CPU reference checks and golden capture also require
rigExec::rigExecOracle. This target registers oracle support automatically;
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.
Open a character¶
The plugins activate on their own for any stage carrying a RigExecRoot and
re-evaluate on every timeline change. Everything RigExec adds to usdview
lives under the RigExec menu.
-
Pose it
Select a control in the viewport and drag the gizmo, or open RigExec ▸ Animation Editors ▸ Control Picker.
-
Play it
Scrub or play the timeline. Frames warm in the background and play from the cache.
-
See the rig
Turn on Display ▸ Display Purposes ▸ Guide to draw joints and solvers as guide geometry.
One evaluation path¶
RigExec compiles each rig into one operation graph. The viewport, the
background frame-cache workers and .rigexec playback all run that graph;
there is no evaluator mode to choose. A rig that cannot compile reports the
reason instead of falling back to another evaluator. OpenExec answers only
optional reference checks.
Evaluation and independent checks explains the compiled rig, frozen evaluation and those checks.
Run the tests¶
| Suite | Command |
|---|---|
| C++ and Python bindings | run by the build helper, or ctest --test-dir build |
| Viewer models (no display) | bin/test/run_python_tests.sh or bin\test\run_python_tests.bat |
usdview integration |
the bin/test/run_testusdview_* helpers (need a graphics context) |
Next¶
- Examples: the stages that ship with the repository.
- How operators fire: the mental model behind every rig.
- Node reference: every node, its wiring and parameters.