Building MaterialX Python Bindings for DCC Tools

While writing my MaterialX to Blender3D addon, I ran into the task of building MaterialX python bindings with the right version of python for it to work with Blender. After getting it to work properly, I realized that this is something which will have to be done for every DCC that needs to interact with MaterialX through python. I figured this is something which might be useful to other developers, so I decided to create a quick post about it. I hope some of you find this post useful.

Note: For the rest of this post I will be using Blender3D, but these instructions should apply to any DCC which supports python. Another important note is that Blender uses Python3, so all of the code and workflow laid out here is for Python3 in an OSx environment.

If you rather view this content in video form, here is a quick video which explains the whole process.

What's My Python Version?

The first thing you will have to do in building MaterialX bindings is to figure out which version of python is being used by your DCC application. To do this in Blender all you need to do is launch Blender and change one of the view panes to the python console. The first line displayed in the python console will contain the exact version that we need to use. In the example below, you can clearly see that the embedded python version is 3.5.1.

PYTHON INTERACTIVE CONSOLE 3.5.1 (default, Feb 1 2016, 13:40:14) [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]

Once you know what is the python version that you need, you will need to make sure your system has such version of python. Since it is highly unlikely that the default python version will match what you need, you will most likely have to download and install the necessary version. You can easily find out which version of python is the default one used by your system by typing

python3 -V

If your version does not match exactly, things might still work, but its best to build the bindings with the exact one. If you get a command not found error, then you will need to install the required python3 version.

I tried installing python3 using homebrew, but I had a hard time installing legacy versions of python. I searched around for a while but had no luck finding a suitable solution. Since I am really pressed for time, I decided to just install the official Python3 binaries from https://www.python.org/. Once you have installed the right version of python, you will need to configure the MaterialX package to build the python bindings. 

Configure the MaterialX CMake File

The folks that maintain the MaterialX package have made it pretty straightforward to configure the build setting for their libraries. The project uses CMake as its build manager. To get things to build properly, you will need to open the CMakeList.txt file which is at the root of the MaterialX project folder. Inside this file, you will find configuration entries for MATERIALX_PYTHON_EXECUTABLE, MATERIALX_PYTHON_INCLUDE_DIR, MATERIALX_PYTHON_LIBRARY. I updated the CMakeList configuration with the specific paths to the matching version of python.

set(MATERIALX_PYTHON_EXECUTABLE "/Library/Frameworks/Python.framework/Versions/3.5/bin/python3" CACHE FILEPATH
    "Path to the Python executable (e.g. 'C:/Python27/python.exe').")
set(MATERIALX_PYTHON_INCLUDE_DIR "/Library/Frameworks/Python.framework/Versions/3.5/include/python3.5m/" CACHE PATH
    "Path to the headers of the Python installation (e.g. 'C:/Python27/include').")
set(MATERIALX_PYTHON_LIBRARY "/Library/Frameworks/Python.framework/Versions/3.5/lib/libpython3.5.dylib" CACHE FILEPATH
    "Path to the Python library file (e.g. 'C:/Python27/libs/python27.lib').")

You should also make sure to enable the building of the python bindings by setting the MATERIALX_BUILD_PYTHON option to ON.

option(MATERIALX_BUILD_PYTHON "Build the MaterialX Python package from C++ bindings. Requires Python 2.6 or greater." ON)

Once you complete this, is time to tell CMake to build our Makefiles by typing cmake . from the root of the MaterialX project. Before I do so, I always rm CMakeCache.txt so that CMake creates a brand new cached file with the config changes we made. If you have all of the required dependencies, you should see CMake complete the process without any hiccups.

Next, you need to run make to start building MaterialX libraries and it's python bindings. Finally, you can call make install to install the libraries. In the output of the install command, you will see a line like this one

copying build/lib/MaterialX/PyMaterialX.1.35.4.so -> /Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/MaterialX

This line tells us where MaterialX was installed. Make sure to add the containing directory (/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages) to your PYTHONPATH environment variable.  Once this is done, you should be able to start blender and type import MaterialX in the python console and receive no errors.