Blender USD Hydra Addon
With Pixar's USD system emerging as a powerful tool for 3D graphics pipelines and interchange, this addon is meant to add first class support for USD and the USD Hydra rendering system to Blender. This allows:
- Importing USD files into Blender as "references". That USD file can be imported as part of the USD node tree, but not loaded into Blender's memory.
- Assembling Blender data and USD data to form a complex scene.
- Exporting assembled USD stages for use in other applications.
- Rendering in Blender via the USD Hydra Framework. This is a middle layer for renderers, meaning that once a renderer is adapted to Hydra, it can work in many places including this addon for rendering. Known Hydra render delegates are:
- AMD's Radeon ProRender (included)
- Hydra's default Storm delegate (included)
- Intel Embree (cpu) delegate
- Pixar RenderMan delegate.
- Autodesk Arnold
- Otoy Octane
- Intel Ospray
- Importing, exporting and editing materials using ILM's MaterialX standard.
In short, this addon will allow an artist or studio to assembled and compose USD data with Blender data, and render it all using various renderers via Hydra.
Currently, this addon works only with Blender 2.93+ in Windows and Linux. We hope to remove the restriction in the future, but there are a few things preventing this.
On the releases page are prebuilt versions of the addon. These include a copy of the USD library, as well as the Radeon ProRender Hydra delegate (under the directory
Download the add-on from the releases page releases. Open Blender preferences and got to the Add-ons section click Install button and pick the add-on in File Browser. Enable the add-on from the Add-ons section.
WINDOWS USERS: Please note that old versions need to be disabled and uninstalled, and then Blender restarted. This is the case with many Blender addons that use C++ extenstions: https://developer.blender.org/T77837
For users who wish to install 3rd party render delegates (see above), they should be installed to the
libs/plugins/usd directory in the addon folder similar to a regular USD installation.
At a simple level, this functions similar to any render addon to Blender, like Cycles or EEVEE which are included in Blender. Simply select the render engine (in this case "USD Hydra") and render using the
F12 key or starting a viewport render. However, Hydra allows the added benefit of selecting a "Render Delegate". The default is using Radeon ProRender, AMD's cross device GPU path tracer.
Select a different render delegate in the render settings. Each render delegate may have it's own render settings.
By default, when rendering the plugin exports the Blender data to USD and passes through Hydra to the render delegate. This has the benefit of not having to write any renderer specific code for export.
However, more complex behavior is possible. Let's say you are animating a character in Blender and want to import a USD background scene that was created in another application. Normally these would be done via Blender's "linked libraries", but USD offers more powerful possibilities. Opening an editor window in Blender to the "USD" Nodegraph type will allow referencing in the background scene and merging with the Blender scene character for example.
Materials via MaterialX
The correct way to interchange materials via USD is an open-ended question. The only built-in material nodes to USD are a simple USDPreviewSurface (very similar to Blender's Principled BSDF) and nodes to read textures. This is insufficient of course for complex materials. However, the MaterialX standard has emerged as a good interchange format for node-based materials with support from various applications such as Adobe Substance and various Autodesk Applications. Many renderers use their own nodes, but many can also support OSL shaders, which MaterialX can produce.
Therefore the material solution in the USD Hydra addon uses MaterialX. Here's a quick guide to materials:
- By default, when rendering any Blender materials with just Principled BSDF nodes will be converted automatically.
- There is a MaterialX based nodegraph available under the "MaterialX" editor.
- A handy conversion script is included to convert Blender Cycles nodegraphs to MaterialX (via the "Tools" panel in the material tab).
- MaterialX networks can be assembled in the editor (and exported for usage elsewhere).
- MaterialX networks from other applications can be imported here as well.
Python 3.9 x64 (Blender 2.93+ uses 3.9)
- numpy -
pip install numpy
- requests -
pip install requests
- PyOpenGL -
pip install PyOpenGL
- PySide2 -
pip install PySide2
- numpy -
Visual Studio 2017 Community (Windows only)
Not recommended to use for build Visual Studio 2019.
- CMake 3.x. Make sure it's added to the PATH environment variable
- epydoc - enable PyCharm to parse Core's documentation. Use
py -m pip install epydocwith your selected python interpreter or install it from PyCharm.
- PyCharm Community Edition - recommended for coding, possible to enable intellisense(limited) for Blender code.
- Visual Studio 2019 Community - has a powerful python extension, possible to enable intellisense for Blender, provides remote debugging in Blender.
Aim is to conform to pep8.
At minimum it's 4 spaces for indentation, sources are utf-8, there's
.gitconfig in the root of the project - please set you editor to use it (for most simplicity). PyCharm default setting are fine and seems that it also picks up
.editorconfig automatically also, Tortoise Merge has a checkbox 'Enable EditorConfig', for Visual Studio there's EditorConfig extension.
We try to avoid merge commits, the easiest way to do it. This one rejects merges that would result in merge commit:
> git config [--global] merge.ff only
Converts pull to do, essentially, fetch&rebase:
> git config [--global] pull.rebase true
Also, make more meaningful commits(one commit per feature) the easy way. This will create a single change set from multiple commits coming from
> git merge <branch> --squash
There is ThirdParty repositories included to the project as a submodules. Please update submodules:
All of them are included via SSH protocol. You will need to create and install SSH keys.
Once SSH keys are installed update/checkout submodules for active branch:
> git submodule update --init -f --recursive
python 3.9 to be set by default.
Use Open x64 Native Tools Command Prompt for Visual Studio 2017 Community and run.
> git clone https://github.com/GPUOpen-LibrariesAndSDKs/BlenderUSDHydraAddon > cd BlenderUSDHydraAddon > git submodule update --init --recursive > python tools/build.py -all -bin-dir bin -G "Visual Studio 15 2017 Win64"
> git clone https://github.com/GPUOpen-LibrariesAndSDKs/BlenderUSDHydraAddon > cd BlenderUSDHydraAddon > git submodule update --init --recursive > python tools/build.py -all -bin-dir bin
You can build project using
tools/build.py with different flag combinations. It allows you to create a folder with binaries and copy all the necessary files for development to
/libs folder. Also
tools/build.py provides a verity of ways to make a project builds:
-all- builds all binaries, equals to
-usd -hdrpr -mx -libs -mx-classes -addon
-usd- builds usd binaries
-hdrpr- builds HdRPR plugin binaries
-mx- builds binaries for MaterialX library
-bin-dir <bin dir>- define folder to build binaries
-libs- copies all the necessary for development libraries to
libfolder, needs to be passed with
-clean- removes binaries folder before build, for example:
-all -clean ...remove all folders in
-usd -hdrpr -cleanremoves only
-mx-classes- generates classes for MaterialX nodes
-G "Visual Studio 15 2017 Win64"- set builder, passing with
-addon- generates zip archive with plugin to
Arguments are mostly used to skip build unneeded binaries. For example, you want switch to prebuild binary folder
> python tools/build.py -libs -mx-classes -bin-dir bin/dir_01
Visual Studio 2019
Recommended software for debugging, has really nice mixed python and C stack debugging. Provides to you ability of interactive code evaluation. You can make breakpoints move step by step, watch variables and etc.
1. Run Blender with the Add-on
Make sure you have no installed addon for Blender version you want to use; remove installed version if needed.
> set BLENDER_EXE="C:\Program Files\Blender Foundation\Blender 2.93\blender.exe" > python tools\run_blender_test_addon.py --window-geometry 0 0 1920 1080
2. Attach Visual Studio to process
Press menu Debug -> Attach to Process... or use hotkey
Ctrl+Alt+P. In opened window choose Blender process, now you connected and allowed to debug.
Also use build-in Python debugger in realtime. Turn on with `Debug -> Windows -> Python Debug Interactive.
The easiest way to build Blender in Release or RelWithDebInfo and add
#pragma optimize( "", off ).
import pydevd pydevd.settrace('localhost', port=52128, stdoutToServer=True, stderrToServer=True, suspend=False)
logging module underneath, hdusd.utils.logging has functions similar to logging. It also includes callable class Log which provides simplified interface to do logging.
from hdusd.utils import logging log = logging.Log(tag='export.mesh') log("sync", mesh, obj)
logging.debug(*argv, tag) where argv is what is printed (same as with print) and tag is string suffix for logger name, for filtering, so that
logging.limit_log(name, level_show_always) will allow to filter out what doesn't start with
name(expect levels equal or above
Configure your session
configdev.py (loaded very early) can be used to include code like
from .utils import logging logging.limit_log('default', logging.DEBUG) # set debug level from . import config config.engine_use_preview = False # turn off preview of materials