Skip to content

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

set USD=C:\path\to\usd-install
set PY=C:\path\to\python.exe
bin\build_rigexec.bat

The helper finds Visual Studio on its own; RIGEXEC_VCVARS overrides the toolchain script it uses.

export USD=/path/to/usd-install
export PY=/path/to/python
bin/build_rigexec.sh

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

bin\launch_usdview.bat examples\biped\Biped_stack.usda
bin/usdview.sh examples/biped/Biped_stack.usda

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.

    Animator tools

  • Play it


    Scrub or play the timeline. Frames warm in the background and play from the cache.

    What warming does

  • See the rig


    Turn on Display ▸ Display Purposes ▸ Guide to draw joints and solvers as guide geometry.

    Control guides

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