Getting started


Pysbs provides a way to generate or modify substances without using Substance Designer Application.

Installing prerequisites and the API

Installing Python

Pysbs is compatible with Python 2.7 and Python 3.5, so the first thing to do is to check if one of these versions is already installed or to install Python.

You may need to install pip also, the Python package installer. If so, you can follow the pip installation procedure.
Make sure to have python and its script folder added to your path.

Installing Sphinx

This documentation has been generated using Sphinx, so if you wish to complete this API with new functions and generate the documentation for them, you need to install Sphinx.

The Sphinx project used to generate this documentation is in the folder doc/.
A Makefile is available, which allows to generate the documentation in many format, such as html, latex and many others.
To rebuild the documentation in html format, open a command prompt, set the directory to the doc/ folder, and enter:
make clean
make html

Installing Pysbs, the Substance Designer Scripting API package

Once you have downloaded the zip file containing the API, in a folder that we will call <apiDir>, install it using pip (or pip2.7 or pip3.5 for an explicit Python version):

pip install Pysbs-x.y.z.zip --find-links <apiDir>

In order to be able to run the demos provided with the API, you must unzip the package:

unzip <apiDir>/Pysbs-x.y.z.zip -d .
This API comes with the following content:
  • The API source code, in the folder pysbs/
  • The documentation and its build system, in the folder doc/
  • A set of demo scripts to test the API, in the folder pysbs_demos/, coming with with a set of samples

First steps with the API

The API provides the module pysbs, which can be imported once the API is installed:

import pysbs
To be able to read or write a .sbs file using the API, a Context object must be created first.
The API provides two ways to create the context, either by explicitly creating it in the script, as described just below, or if your script requires arguments, they can be provided by an argument file and in this case the API creates the Context object automatically.

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
The API tries first to locate the Substance Automation Toolkit installation folder, to have access to the Batchtools executables, to the psdparse tool and also to the default Substance Designer packages library.
The result of this search is displayed on the first lines output by the API (see above): ‘Install path’ and ‘Default package’.
If the API fails to locate this folder (it may be the case with Linux in particular), or if you want to work with another installation folder, you can specify it explicitly on the Context:
# 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

If a script needs input parameters (for instance, the path of the substance to use as the source and the path of the resulting substance to create), an argument file can be used to provide the input parameters to the function to call, as it is the case for all the functions in the module demos.
As soon as the __main__ of the module calls the CommandLineProcessor, an argument file can be used:
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
In the argument file, the <context><url_aliases> tag allows you to specify a substance package folder, which will be aliased.
This should correspond to the Project Preferences you have setup in Substance Designer application, in the section Aliases.

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>
The default package alias ‘sbs://’ corresponding to Substance Designer installation folder is added by default to the execution context by the API.