MaterialX Elements

Python MaterialX

MaterialX release distributions include Python sub-modules for editing documents, code generation, and rendering. The sub-modules are wrappers for C++ libraries also shipped with releases.

For content on this site the minimum requirement is MaterialX version 1.38.7 is and Python 3.9.

A Visual Studio Code environment has been chosen to provide tutorials and utilities written in Python. Published content can be directly accessed in .

The following videos and corresponding text instructions can be followed to set up an appropriate environment.

Using MaterialX version 1.38.8 or later As of version 1.38.8, MaterialX Python package can be downloaded and install from PyPi. The easiest way to do this is to use call `pip install MaterialX`. If a a particular distribution is not pre-built, an attempt will be made to build the package locally as a convenience.	Using MaterialX versions prior to 1.38.8 For users who wish to use earlier versions they can: Download releases from the MaterialX Github Use packages included with application integrations or other distributions such as Usd, or Use custom builds.

Prerequisites

The basic requirements are:

Installation of a version of Python that matches the Python version of the MaterialX package.
Installation of pip
Installation of the VSCode Python extension with the interpreter referencing the installed version.
Setup of a virtual environment following the instructions found here. Basically:
- ⌘/Ctrl+Shift+P can be used to run the command Python: Create Environment.
- Choose to create a virtual environment> (versus a Conda environment).
- Choose the Python interpreter that matching the MaterialX Python version.
Once setup a .venv folder will be created within the workspace.
Installation of the Jupyter extension for VScode if using the Notebook tutorials.

Installing MaterialX Python

We will use a simple example file called hello_materialx.py. Add this file to your workspace and attempt to run it.

This will result in an import error if MaterialX is not installed yet.

import MaterialX as mx
ModuleNotFoundError: No module named 'MaterialX'

To install the MaterialX package into the virtual environment a VSCode workspace terminal ⁽¹⁾ can be opened and pip used to install from

The MaterialX package location using: python -m pip install .
the PyPi distribution using: pip install MaterialX

This will add the MaterialX modules to the virtual environment under .venv/Lib/site-packages. The modules installed will depend on the ones found in the package location.

Other dependent packages can be added using pip or other means as necessary.

^{(1) A security alert may show up when running from the terminal. If so, follow the
the
instructions provided
to to set up appropriate permissions}

Import Example

Importing MaterialX will include all sub-modules. This differs from C++ where individual sub-modules can be loaded. Shown below is how to import MaterialX with the module name mx.

import MaterialX as mx

At a minimum a document must be created as all operations are based on documents.

To test that the environment works properly the test example creates a document and checks the version of MaterialX.

doc = mx.createDocument()
print('Hello MaterialX (Version %s)' % doc.getVersionString())

Minimal "Useful" Example

To do any useful operations, the standard MaterialX libraries need to be loaded. The load_libraries.py example shows this minimal setup.

import MaterialX as mx

# Create library document and load in default data libraries
stdlib = mx.createDocument()
libFiles = mx.loadLibraries(mx.getDefaultDataLibraryFolders(), mx.getDefaultDataSearchPath(), stdlib)

# Create main document and import the library document
doc = mx.createDocument()
doc.importLibrary(stdlib)

print('Loaded library file: %d' % len(libFiles))

Note that the "standard" libraries are in the libraries folder in the Python package location. The key interfaces used are:

the loadLibraries to load in the standard library definitions.
the Document importLibrary to import the libraries into a working / main document.

From here, the learning notebooks can be used to discover how to do something useful with MaterialX.

Learning Notebooks

A series of Jupyter learning notebooks are regularly being added and updated. User can clone or copy the repo to run locally, or as of MaterialX 1.38.8, remotely using `Github Codespaces` or `Google Colab`.

See the Hosting page for more details.

Any contribution requests or comments can be posted as pull requests on .

It is recommended to use the MaterialX packages which are available via PyPi which are available starting with version 1.38.8.

For those which may not have access to the execution environment or simply wish to read the notebook pre-evaluated, the results of executing the notebooks are provided in the Examples page. These pages are generated directly from the sample notebooks.

Available Notebooks

A Python file (with markdown), a notebook and a link to content on Github is given below.
Note that it is possible to start with the Python itself and convert to a notebook in VSCode or export from a notebook to Python.

Notebook	Raw Python (py)	Raw Notebook (ipynb)	Notebook in Github

Basics Import MaterialX Create Document and load definitions Read and Write Documents Create, find and delete nodes Connect nodes
NodeGraph Basics Creating Graph Containers Adding Nodes to a Graph Connecting Nodes Adding Input and Output Interfaces
NodeGraph Traversal Basic Graph Traversal
NodeGraph Connectivity Graph Node and Connectivity Inspection Exporting Connectivity Node Graph Building: Mermaid Diagrams
Library Comparison Comparing Documents Library Definition Comparison Detailed Element Comparison
Node Libraries Loading in custom definition libraries Using custom exported content Creating / editing graphs using custom definitions Definitions implemented with source code
Creating Definitions Create Nodegraph Implementations Create Source Code Implementations Updating Standard Libraries
ShaderGen Generators Generation Context CMS and Units Source Code Introspection
Rendering Determining "renderable" items Creating "renderable" graphs Rendering "roots": nodes, outputs, shaders, materials Accessing uniform sources and binding Accessing geometric sources and binding
Targets and Implementations Defining Targets and Inheritance Setting Targets on Implementations and Definitions Definitions w/o Targets Inheritance issues
JSON / MaterialX Extracting Node Graphs JSON Serialization JSON Schemas and Validation
Using Copilot With MaterialX Copilot for Source Key Factors Setup
Google Bard Basic knowledge and source testing.
USD and MaterialX Graphs USD setup Shade tree traversal of Usd Stage Mapping Usd to MaterialX and back
Blender and MaterialX Graphs MaterialX Python in Blender Mapping Blender to MaterialX