User Guide Cancel

Getting started | Substance 3D Automation ToolKit

  1. Substance 3D home
  2. Home
  3. Command Line Tools
    1. Command Line overview
    2. sbsbaker
      1. sbsbaker overview
      2. sbsbaker command line options
      3. sbsbaker Example Command Lines
    3. sbscooker
      1. sbscooker overview
      2. sbscooker command line options
      3. sbscooker pattern variables
    4. sbsmtools
      1. sbsmtools overview
      2. sbsmtools command line options
    5. sbsmutator
      1. sbsmutator overview
      2. sbsmutator command line options
      3. sbsmutator Example Command Lines
    6. sbsrender
      1. sbsrender overview
      2. sbsrender base parameters and pattern variables
      3. sbsrender command line options
      4. sbsrender example command lines
    7. sbsupdater
      1. sbsupdater overview
      2. sbsupdater command line options
  4. Pysbs - Python API
    1. Pysbs - Python API overview
    2. Getting started
    3. General topics
      1. Basic manipulation
      2. Substance creation
      3. Substances modification
      4. Dependencies management
      5. PySbs batchtools module
      6. metadata manipulation
      7. SAT demos
      8. Edit sbsar with SBSARManager
      9. Spot Colors
      10. Thumbnail creation with SAT
    4. Examples
      1. demohelloworld
      2. demos
      3. demos_batchtools
      4. script_update_with_sbsupdater
    5. API Content
      1. API Content overview
      2. Substance definitions
        1. Common interfaces
          1. basegraph
          2. package
          3. sbsarobject
          4. sbsobject
        2. compnode
          1. compnode overview
          2. common
          3. compimplementation
          4. paramgraph
        3. context projectmgr
        4. graph
          1. graph overview
          2. function
          3. inputparameters
          4. output
        5. mdl
          1. mdlannotation
          2. mdlcommon
          3. mdldictionaries
          4. mdlenum
          5. mdlgraph
          6. mdllibclasses
          7. mdlmanager
          8. mdlnode
          9. mdlnodeimpl
          10. mdloperand
          11. mdlsbsbridge
        6. modelgraphindex
          1. modelannotationnames
          2. modelgraph
          3. modelgraphgenerator
          4. modelgraphimplementation
          5. modelnodenames
          6. modeloperand
          7. modulegraphindex
          8. moduleannotation
          9. moduleconnection
          10. modulegraph
          11. modulegraphgenerator
          12. modulegraphimplementation
          13. modulegraphlibrary
          14. modulegraphregister
          15. modulenode
          16. modulenodeimplementation
          17. modulenodeinstance
          18. moduleoperand
          19. moduleoutputbridging
          20. moduleparaminput
        7. params
          1. params overview
          2. dynamicvalue
          3. paramnode
        8. projectmgrdoc
        9. sbsarchive
          1. sbsarchive overview
          2. sbsarenum
          3. sbsargraph
          4. sbsargui
          5. sbsarguiwidgets
          6. sbsarmanager
        10. sbscommon
          1. connections
          2. gui
          3. nodes
          4. values
        11. sbspreset
        12. sbsproject
        13. substance
          1. substance overview
          2. content
          3. resource
      3. Libraries
        1. sbsenum
        2. sbslibrary
          1. sbslibrary overview
          2. sbsdictionaries
          3. sbsfilters
          4. sbsfunctions
          5. sbsfxmapnodes
          6. sbslibclasses
          7. sbswidgets
        3. sbsbakerslibrary
          1. sbsbakerslibrary overview
          2. sbsbakersdef
          3. sbsbakersdefaultprops
          4. sbsbakersdictionaries
          5. sbsbakersenum
          6. sbsbakingconverter
          7. sbsbakingconverterparam
          8. sbsbakingparameters
          9. sbsdialogstate
          10. sbsscenedata
        4. Helpers
          1. sbscleaner
          2. sbsexporter
          3. sbsgenerator
          4. sbsparser
          5. sbswriter
          6. qtclasses
            1. qtclasses overview
            2. qtvariantreader
            3. qtvariantwriter
          7. psdparser
          8. sbsimpactmanager
          9. batchtools
          10. autograph
            1. ag_functions
            2. ag_layout
            3. ag_types
          11. info_mesh_parser
          12. sbsbaker_info_handlers
          13. sbsrender_render_handlers
          14. output_handlers
          15. spotcolorinfo_handler
          16. thumbnail
          17. batchtools overview
        5. Execution context
          1. context
          2. functions
        6. API Change log
  5. Samples
    1. Samples overview
    2. Texturing Template Demo
    3. Batch Tools Demo
    4. Variations
    5. Texture Mat
    6. Pixel Processor Ray tracer
  6. Setup and Getting Started
    1. Setup and Getting Started overview
    2. Compatibility
    3. Frequently asked Questions
    4. Known issues
    5. SAT Cookbook
    6. Use Pysbs in different python interpreter (maya, sd, blender...)
  7. Integrations
    1. Substance Maya toolset
      1. Substance Maya Toolset overview
      2. Installing
      3. Launching
      4. Baking
        1. Baking overview
        2. Export parameters
        3. Baker parameters
        4. Mesh setup
        5. Using a template
      5. Changelog
  8. Release notes
    1. Version 11.3.0
    2. Version 11.2.0
    3. Version 11.1.0

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 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 /
  • A set of demo scripts to test the API, in the folder /, 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

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:


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

Install path: C:Program FilesAllegorithmicSubstance Automation Toolkit 
Default package: C:Program FilesAllegorithmicSubstance Automation Toolkitresourcespackages 
=> Resulting substance saved at <absolutePathToPackage>

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) 

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__": 
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 -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"?> 
        <arg name="aFileAbsPath" value=""/> 
        <arg name="aDestFileAbsPath" value=""/> 

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

python -fct: demoIteration -args: "sample/argsDemoIteration.xml"

The execution of this command has created the substance sample/, 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 FilesAllegorithmicSubstance Automation Toolkit 
Default package: C:Program FilesAllegorithmicSubstance Automation Toolkitresourcespackages 
Calling fct "demoIteration" with args {'aFileAbsPath': 'sample/', 'aDestFileAbsPath': 'sample/', u'aContext': <pysbs.context.Context instance at 0x040E1288>} 
=> Resulting substance saved at sample/

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:

<?xml version="1.0" encoding="UTF-8"?> 
            <url_alias name="myAlias" path="sample"/> 
        <arg name="aFileAbsPath" value="myAlias://"/> 
        <arg name="aDestFileAbsPath" value="myAlias://"/> 
The default package alias ‘sbs://’ corresponding to Substance Designer installation folder is added by default to the execution context by the API.


Get help faster and easier

New user?

Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX 2024

Adobe MAX
The Creativity Conference

Oct 14–16 Miami Beach and online

Adobe MAX

The Creativity Conference

Oct 14–16 Miami Beach and online