Getting started
Pysbs provides a way to generate or modify substances without using Substance Designer Application.
Installing prerequisites and the API ¶
Installing Python ¶
Installing Pysbs, the Substance Designer Scripting API package ¶
Once you have the Pysbs wheel package nstall it using pip (or pip2.7 or pip3.5 for an explicit Python version):
pip install Pysbs-<version>-py2.py3-none-<platform>.whl
In order to be able to run the demos provided with the API, you can unzip the wheel package:
unzip Pysbs-<version>-py2.py3-none-<platform>.whl -d .
- The extracted result comes with the following content:
- The API source code, in the folder /Pysbs-2020.2.0.data/purelib/pysbs/
- A set of demo scripts to test the API, in the folder /Pysbs-2020.2.0.data/purelib/pysbs_demos/, coming with with a set of samples
Or find pysbs_demos package inside your site-package location.
First steps with the API ¶
The API provides the module pysbs, which can be imported once the API is installed:
import pysbs
Script the declaration of the context ¶
The API need an execution context for its initialization, which is defined in the module context
.
Eventually, one may want to declare aliases for Substance Designer packages folder.
These simple lines allows to do that:
# Import context module from pysbs from pysbs import context # Creation of the context aContext = context.Context() # Declaration of alias 'myAlias' aContext.getUrlAliasMgr().setAliasAbsPath(aAliasName = 'myAlias', aAbsPath = '<myAliasAbsolutePath>')
The module demohelloworld
demonstrates the use of the API in this way. To launch this script, open a command prompt on the directory demos/, and enter the following command:
python demohelloworld.py
The substance sample/resultDemoHelloWorld.sbs has been created, and the result displayed on the command prompt should be something like:
Install path: C:\Program Files\Allegorithmic\Substance Automation Toolkit Default package: C:\Program Files\Allegorithmic\Substance Automation Toolkit\resources\packages => Resulting substance saved at <absolutePathToPackage>\pysbs_demos\sample\resultDemoHelloWorld.sbs
# Import context module from pysbs from pysbs import context # Set the Substance Automation Toolkit installation folder (it recomputes automatically the default package library path) context.Context.setAutomationToolkitInstallPath(automationToolkitInstallPath='<myAutomationToolkitInstallationFolder>')
Using an argument file ¶
demos
.if __name__ == "__main__": base.CommandLineArgsProcessor(__name__).call()
- In this case, the script must be called with two parameters:
- fct: the specific function to execute, contained in the executed module
- args: the arguments file to feed the function with, which can also contain the declaration of package aliases
python moduletocall.py -fct: functionToExecute -args: pathToArgumentFile
The execution context is created automatically by the API in this configuration, and is sent to the function to execute, as its first parameter.
For instance, look at the signature of the function demos.demoIteration()
, defined in the module demos
:
def demoIteration(aContext, aFileAbsPath = '', aDestFileAbsPath = '')
The file sample/argsDemoIteration.xml contains the arguments to send to the function demos.demoIteration()
(aFileAbsPath and aDestFileAbsPath):
<?xml version="1.0" encoding="UTF-8"?> <root> <context> <url_aliases/> </context> <fct_args> <arg name="aFileAbsPath" value="sample\DemoIteration.sbs"/> <arg name="aDestFileAbsPath" value="sample\resultDemoIteration.sbs"/> </fct_args> </root>
To launch this demo, open a command prompt on the directory demos/, and enter the following command:
python demos.py -fct: demoIteration -args: "sample/argsDemoIteration.xml"
The execution of this command has created the substance sample/resultDemoIteration.sbs, which provides an example of the modification of an existing substance to generate iterations (see section Iteration generation)
The result displayed on the command prompt should be something like:
Install path: C:\Program Files\Allegorithmic\Substance Automation Toolkit Default package: C:\Program Files\Allegorithmic\Substance Automation Toolkit\resources\packages Calling fct "demoIteration" with args {'aFileAbsPath': 'sample/DemoIteration.sbs', 'aDestFileAbsPath': 'sample/resultDemoIteration.sbs', u'aContext': <pysbs.context.Context instance at 0x040E1288>} => Resulting substance saved at sample/resultDemoIteration.sbs
For instance, if we want to create the alias named ‘myAlias’ that points to the sample/ folder, here is how to do:
<?xml version="1.0" encoding="UTF-8"?> <root> <context> <url_aliases> <url_alias name="myAlias" path="sample"/> </url_aliases> </context> <fct_args> <arg name="aFileAbsPath" value="myAlias://DemoIteration.sbs"/> <arg name="aDestFileAbsPath" value="myAlias://resultDemoIteration.sbs"/> </fct_args> </root>