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 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):

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

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:

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:

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:

The substance sample/resultDemoHelloWorld.sbs has been created, and the result displayed on the command prompt should be something like:

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:

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:

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

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:

The file sample/argsDemoIteration.xml contains the arguments to send to the function demos.demoIteration() (aFileAbsPath and aDestFileAbsPath):

To launch this demo, open a command prompt on the directory demos/, and enter the following command:

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:

In the argument file, the 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: