MaterialX USD Utilities

This is a Github repository of utilities related to MaterialX and USD. The corresponding web site is here

The utilities and results use the 25.05 version of OpenUSD which is sync'ed to MaterialX version 1.39.3.

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)

Available Components

• 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:

  • Preprocess the MaterialX file to attempt to produce valid USD shading network (See Support Utilities)
  • Input geometry (USD file)
  • Input camera (USD file)
  • Skydome light (A latlong HDR file)
  • Perform USD validation
  • Export just the materials to a USD file.
  • Render the corresponding USD file. This uses usdrecord currently. Render arguments can be passed in to specify the render delegate to use for instance. The default is GL.
  • Misc options for output for test suite compatibility:
    • Use material name for file name
    • Create in subfolder with name being the input MaterialX name

• Preprocessing Utilities:

  • preprocess_mtlx.py : Tries to preprocess a MaterialX document so that it considered valid by USD. Currently this includes logic to:
    • Encapsulate top level nodes in a MaterialX document into a nodegraph but preserve connections. Only materials and shading model nodes are valid at the top level in USD.
    • Resolve any implicit geometry stream bindings on 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.
    • Add a material node per surface shader which is not connected to any downstream material. USD only examines materials and not shaders so these shaders are skipped during conversion.
    • Extract out any surface shaders inside a nodegraph to be outside the graph as this is considered invalid by USD.
    • If a surface shader input is connected to a nodegraph, add in an explicit output qualifier. Seems out is assumed to be the name of the output when there is no explicit qualifier which can be incorrect.
    • "Flatten" (resolve) all image asset references using the existing MaterialX utilities for path resolve. This is needed as the MaterialX render tests have assumed search paths which are not explicitly defined -- thus requiring the paths to be passed in as part of preprocessing.
      • There is probably a better way to do this using USD asset resolvers, but have not tried. ( Input is welcome on this. )
    • Remove any value attributes on inputs with connections to avoid ambiguity and MaterialX validation errors.

Issues

Issue logging is being tracked under these "master" issues: - MaterialX - OpenUSD

Usage

Installation and Usage

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

Documentation

An overview MaterialX->USD presentation can be found here

Python API documentation can be found here

Acceptance

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:

Gallery of Example Materials

Render Test Suite material Renderings

Unit Test Renderings

Physically Based Material Library Renderings

Comparison: GLSL vs GLSLFX

Comparison: GLSL vs OSL vs GLSLFX

Design

An overview of the current package design is shown below. Boxes / lines which are dotted are optional logic which may be executed as desired.