This is a Github repository of utilities related to MaterialX and USD.
This can be hooked into the larger interoperability picture with glTF / MaterialX and USD as shown in the example below:
Figure: MaterialX material from AMD GPUOpen library. Converted to USD and displayed in
usdview
(top left), converted to glTF and display in ThreeJS editor (top right). Display in MaterialX Viewer (bottom left), and Web editor (bottom right)
mtlx2usd.py
: Utility which takes a MaterialX document and creates a corresponding USD document with scene geometry, lights, and camera.
The main intent is currently to be able to consume documents from the MaterialX render test suite but any MaterialX file can be used as input.
Options Include:
usdrecord
currently. Render arguments can be passed in to specify the render delegate to use for instance. The default is GL. Preprocessing Utilities:
preprocess_mtlx.py
: Tries to preprocess a MaterialX document so that it considered valid by USD. Currently this includes logic to:inputs
and make them explicit by adding geometric stream nodes and binding them to any inputs with implicit bindings. Note that this requires loading in the standard library to get node definitions.output
qualifier. Seems out
is assumed to be the name of the output when there is no explicit qualifier which can be incorrect.value
attributes on input
s with connections to avoid ambiguity and MaterialX validation errors.Issue logging is being tracked under these "master" issues: - MaterialX - OpenUSD
Install from the root folder:
pip install .
Run using the materialxusd
command.
Currently there are two commands for:
- MaterialX to USD conversion which can be run using
materialxusd m2u
and preprocessing MaterialX documents which can be run using
materialxusd pmtlx
The tests
folder has a script with some command line calls to process an examples subfolder (run_examples.sh
)
echo Convert sample MaterialX files to USD and render
materialxusd m2u -pp -v -sf -mn ./examples/no_materials.mtlx
materialxusd m2u -pp -v -f -sf -mn -r -m ./examples/standard_surface_carpaint.sphere.mtlx
materialxusd m2u -pp -v -sf -mn -r -m ./examples/standard_surface_marble_solid.mtlx
materialxusd m2u -pp -v -sf -mn -r -m ./examples/linepattern.mtlx
echo Preprocess and convert sample MaterialX files to USD
materialxusd pmtlx ./examples/linepattern_orig.mtlx
materialxusd m2u -pp -v -sf -mn -r -m ./examples/linepattern_orig_converted.mtlx
echo Convert ZIP file
materialxusd m2u -pp -v -sf -mn -r -m ./examples/TH_Cathedral_Floor_Tiles_1k_8b_JRHrQHt.zip
Some rendering of resulting USD files are shown below:
Material | Pre-processing Required | USD Rendering |
---|---|---|
Line Pattern | Generate Materials for outputs on NodeGraph | ![]() |
Marble | Add downstream material + explicit stream bindings | ![]() |
Car Paint | Add downstream material | ![]() |
AMD GPUOpen Wood (Zip) | Unzip and resolve asset paths | ![]() |
Adobe pattern | Wrap top level nodes, create explicit output port connections | ![]() |
There is additionally a sample script that will traverse a local copy of the MaterialX test suite (render_rts.sh
). The script calls the package's Python commands directly.
folders=(
"./resources/Materials/Examples"
"./resources/Materials/TestSuite/stdlib/convolution"
"./resources/Materials/TestSuite/stdlib/color_management"
"./resources/Materials/TestSuite/stdlib/procedural"
"./resources/Materials/TestSuite/pbrlib/surfaceshader"
"./resources/Materials/TestSuite/nprlib"
)
for folder in "${folders[@]}"; do
echo "Rendering $folder"
python ../source/materialxusd/mtlx2usd.py -pp -mn -sf "$folder" -r -g ./data/sphere.usd -c ./data/camera_sphere.usda -e ./data/san_giuseppe_bridge.hdr
done
An overview MaterialX->USD presentation can be found here
Python API documentation can be found here
An initial acceptance criteria is to be able to run MaterialX to USD conversion against the MaterialX render test suite files. Preliminary results are show below:
An overview of the current package design is shown below. Boxes / lines which are dotted are optional logic which may be executed as desired.