- Substance 3D home
- Home
- Command Line Tools
- Command Line overview
- sbsbaker
- sbscooker
- sbsmtools
- sbsmutator
- sbsrender
- sbsupdater
- Command Line overview
- Pysbs - Python API
- Pysbs - Python API overview
- Getting started
- General topics
- Examples
- API Content
- API Content overview
- Substance definitions
- Common interfaces
- compnode
- context projectmgr
- graph
- mdl
- modelgraphindex
- modelannotationnames
- modelgraph
- modelgraphgenerator
- modelgraphimplementation
- modelnodenames
- modeloperand
- modulegraphindex
- moduleannotation
- moduleconnection
- modulegraph
- modulegraphgenerator
- modulegraphimplementation
- modulegraphlibrary
- modulegraphregister
- modulenode
- modulenodeimplementation
- modulenodeinstance
- moduleoperand
- moduleoutputbridging
- moduleparaminput
- params
- projectmgrdoc
- sbsarchive
- sbscommon
- sbspreset
- sbsproject
- substance
- Libraries
- sbsenum
- sbslibrary
- sbsbakerslibrary
- Helpers
- Execution context
- API Change log
- Samples
- Setup and Getting Started
- Integrations
- Substance Maya toolset
- Release notes
Version 11.3.0
Edit and integrate the Substance 3D Designer model graph into your pipeline thanks to the new PySBS ModelGraph API.
This new version of SAT offers a new extension to PySBS API to edit and create your Substance model graph. The Substance model graph is the new Substance 3D Designer procedural graph to build complex parametric geometry objects.
PySBS provides a new module modelgraph to deal with the Designer model graph type.
Create a new Model Graph
Once you have created or read a .sbs document, simply call SBSDocument’s method createModelGraph like this:
from pysbs import sbsgenerator, context
# create or read a sbs file
doc = sbsgenerator.createSBSDocument(context.Context(), 'myPackage.sbs')
# create a new model graph with an identifier name
graph = doc.createModelGraph('myFirstModelGraph')
To create a node with the ModelGraph, the API needs a node path id -- the identifier for a node definition. It can look like 'Structure::NodeIntToBool'. If you’d rather avoid a path id like this, you can use the module modelgraph.nodenames and create nodes like this:
from pysbs.modelgraph import modelnodenames # create a new import scene node scene_node = graph.createNode(modelnodenames.Scene)
Connect nodes
A ModelGraph node has outputs and can have inputs; in the ModelGraph terminology a node input is called operand. All node parameters are also operand and any of this operand can become a connectable operand, and therefore be considered as a node input.
By default, a node can have a connectable operand. In this case, these connectable operand will be chosen as a priority during two nodes connection if one of these is free (not have a connection already on it). If you want to connect an operand that is not connectable by default you need to give the name of the desired operand during the connection.
The following instructions show different connection cases:
cube_node = graph.createNode(modelnodenames.NodePrimitive) bend_node = graph.createNode(modelnodenames.NodeBend) float_node = graph.createNode(modelnodenames.NodeFloat) # connect two nodes with their default connectable operands graph.connectNodes(cube_node, bend_node) # connect a float node to an operand attribute: the angle operand graph.connectNodes(float_node, bend_node, aInputIdentifer='angle')
Get or set operand values
Once a ModelGraph node is created, it’s possible to retrieve or set the values of its operands. Operand objects lie inside the implementation of the node. Today, ModelGraph has only one kind of implementation node so simply get it with node.getImplementation() and use its method implementation.getOperand(“operandname”). Once the operand object is retrieved you can set or get corresponding values. Each operand is typed:you must give the correct type and you will get a typed result.
# get the float node's value operand and set it a value of 15.0
operand = float_node.getImplementation().getOperand('value')
operand.setValue(15.0)
# get back the new value
operand_value = operand.getValue()
If you don’t know the operand name, you can list them with node.getImplementation().listOperandNames()
Expose node as input graph parameter
Like for other graph types, it’s possible to create input graph parameters. With the ModelGraph, only constant nodes can be exposed --constant nodes have a single operand. If you want to expose an operand from a non-constant node, first create then connect a constant node of the right operand type to the desired operand and finally expose the constant node.
The following instructions show you how to do that:
bend_node = graph.createNode(modelnodenames.NodeBend) float_node = graph.createNode(modelnodenames.NodeFloat) # connect a float node to an operand attribute: the angle operand graph.connectNodes(float_node, bend_node, aInputIdentifer='angle') # expose the constant float node as graph input parameter and add a description to it graph.exposeNode(float_node, 'myExposedParam', aDescription="Float parameter to drive bend angle")
Set graph annotations
ModelGraph has predefined annotations like “Author”, “Description” which you can use easily edit with dedicated methods like graph.setDescription("my description") . If you need a custom annotation you can create one defining an annotation name and its content.
The following instructions show you these two ways:
# add a description annotation to a graph
graph.setDescription("This is my first model graph")
# create a custom annotation called ExtraInfo
graph.addGraphAnnotation("ExtraInfo", "simple, bend")
Go further
Don’t hesitate to look at the Python file : pysbs_demo/modelgraphgeneratescatter.py : it’s a pretty complete example of how to generate a scatter from a given geometry files folder.
The PySBS ModelGraph module is new and hasn’t been used in a production context yet. Please don’t hesitate to give us feedback, missing features, or issues.
What next
Currently, only graph creation and editing are available. We plan to add to SAT the possibility to cook a ModelGraph as an sbsm file, as well a particularly important feature: export a geometry file from a cooked graph!
With these tools collection a full ModelGraph automation could be set up.
This new ModelGraph API is under beta form, keep in mind that there may be definition changes in future versions.
Look at the change log to get the list of changes : https://substance3d.adobe.com/documentation/sat/pysbs-python-api/api-change-log
Known issue with MacOS Big Sur:
The MacOS Big Sur GateKeeper protocol for SAT is not totally complete. If you are experiencing problems launching SAT’s commandlines, remove the quarantine flags from the SAT parent directory by following these instructions:
- Launch the terminal application
Type the following command replacing [PATH_TO_YOUR_SAT_PARENT_DIRECTORY] by your SAT install directory path:
xattr -r -d com.apple.quarantine [PATH_TO_YOUR_SAT_PARENT_DIRECTORY]
Example:
xattr -r -d com.apple.quarantine /Applications/Substance\ Automation\ Toolkit
Adobe MAX
The Creativity Conference
Oct 14–16 Miami Beach and online
Adobe MAX
The Creativity Conference
Oct 14–16 Miami Beach and online