Scripting: Material Graph

On this page

Material Graph Manipulation ^{(GUI and Headless)}

Manipulating the Material Graph via Scripting is an advanced feature that has been added in KeyShot 11.

The following will go through the basic functions to manipulate the Material Graph. To see a full list of functions available, type help(lux) in the Scripting Console or visit the online documentation, for GUI or Headless scripting.

Access material graph

You can access the material graph like this:

graph = lux.getMaterialGraph("name")

The graph is an instance is of the type lux.MaterialGraph which you can interact with.

Access root node

You can access the root node with the following:

rootNode = graph.getRoot()

The rootNode is an instance is of the type lux.ShaderNode which you can interact with.

Get input edges of a node

However a node instance was obtained, you can get the edges from a Material Graph by typing:

edges = node.getInputEdges()

Each edge instance is of the type lux.ShaderEdge that you can be interact with.

A specific edge can be obtained via:

edge = node.getInputEdge("parameter name")

This will yield lux.ShaderEdge or an error if the name is unknown.

Get output edges of a node

However a node instance was obtained, you can get the edges from a Material Graph by typing:

edges = node.getOutputEdges()

Each edge instance is of the type lux.ShaderEdge that you can be interact with.

Get parameters of a node

However a node instance was obtained, you can get the parameters from a Material Graph by typing:

parameters = node.getParameters()

Each parameter instance is of the type lux.ShaderParameter that you can be interact with.

A specific parameter can be obtained via:

parameter = node.getParameter("parameter name")

This will yield lux.ShaderParameter or error if unknown name.

Change parameter value

A parameter, parameter, obtained via lux.SceneNode.getParameter() or lux.SceneNode.getParameters(), can have its value modified via lux.ShaderParameter.setValue().

If, for example, the parameter’s type was a boolean (true or false), you could change the value via:

parameter.setValue(True)

Is the value supported as input but entered incorrectly it will be shown in a python exception.

If, for example, the parameter was an RGB color and you applied the boolean value, it would yield the error:

Color parameter only accepts values of type tuple or list of size 3 containing floats or 
ints within range [0.0,1.0], or a color name!

The following would therefore be the correct input for a color parameter:

parameter.setValue((0.5, 0, 0))  # Red, (0x7F, 0x00, 0x00)
parameter.setValue("Amber")      # Color known by the color library in KeyShot

You can obtain a Python value via lux.ShaderParameter.getValue() to get an understanding of what’s supported or you can print a representation of the instance (str() or repr()).

Remove a node

You can remove a node, either via the instance:

graph.removeNode(node)

Or its ID:

graph.removeNode(node.getID())

Create a new node

You can for example create a metal node like this:

metalNode = graph.newNode(lux.SHADER_TYPE_METAL)

Remove an edge

You can remove an edge, either via the instance:

graph.removeEdge(edge)