- Substance 3D home
- User guide
- Glossary
- Getting started
- Interface
- Interface
- Customizing your workspace
- Home screen
- Main toolbar
- Preferences
- Explorer
- Graph view
- Library
- Properties
- 2D view
- 3D view
- Dependency manager
- Resources
- Resources
- Importing, linking and new resources
- Bitmap resource
- Vector graphics (SVG) resource
- 3D scene resource
- AxF (Appearance eXchange Format)
- Font resource
- Warnings from dependencies
- Substance graphs
- Substance graphs
- Substance graph key concepts
- Creating a Substance graph
- Exposing a parameter
- Graph parameters
- Inheritance in Substance graphs
- Output size
- Values in Substance graphs
- Publishing Substance 3D asset files (SBSAR)
- Exporting bitmaps
- Exporting PSD files
- Sample Substance graphs
- Warnings in Substance graphs
- Nodes reference for Substance graphs
- Nodes reference for Substance graphs
- Atomic nodes
- Node library
- Node library
- Texture generators
- Texture generators
- Noises
- Noises
- 3D Perlin noise
- 3D Perlin noise fractal
- 3D Ridged noise fractal
- 3D Simplex noise
- 3D Voronoi
- 3D Voronoi fractal
- 3D Worley noise
- Anisotropic noise
- Blue noise fast
- BnW spots 1
- BnW spots 2
- BnW spots 3
- Cells 1
- Cells 2
- Cells 3
- Cells 4
- Clouds 1
- Clouds 2
- Clouds 3
- Creased
- Crystal 1
- Crystal 2
- Directional noise 1
- Directional noise 2
- Directional noise 3
- Directional noise 4
- Directional scratches
- Dirt 1
- Dirt 2
- Dirt 3
- Dirt 4
- Dirt 5
- Dirt gradient
- Fluid
- Fractal sum 1
- Fractal sum 2
- Fractal sum 3
- Fractal sum 4
- Fractal sum base
- Fur 1
- Fur 2
- Fur 3
- Gaussian noise
- Gaussian spots 1
- Gaussian spots 2
- Grunge concrete
- Grunge Damas
- Grunge galvanic large
- Grunge galvanic small
- Grunge leaks
- Grunge leaky paint
- Grunge map 001
- Grunge map 002
- Grunge map 003
- Grunge map 004
- Grunge map 005
- Grunge map 006
- Grunge map 007
- Grunge map 008
- Grunge map 009
- Grunge map 010
- Grunge map 011
- Grunge map 012
- Grunge map 013
- Grunge map 014
- Grunge map 015
- Grunge rough dirty
- Grunge rust fine
- Grunge scratches dirty
- Grunge scratches fine
- Grunge scratches rough
- Grunge shavings
- Grunge splashes dusty
- Grunge spots
- Grunge spots dirty
- Liquid
- Messy fibers 1
- Messy fibers 2
- Messy fibers 3
- Microscope view
- Moisture noise
- Perlin noise
- Plasma
- Caustics
- Voronoi
- Voronoi fractal
- Waveform 1
- White noise
- White noise fast
- Patterns
- Patterns
- 3D linear gradient
- 3D volume mask
- Alveolus
- Arc pavement
- Brick 1
- Brick 2
- Brick generator
- Checker 1
- Cube 3D
- Cube 3D GBuffers
- Fibers 1
- Fibers 2
- Gaussian 1
- Gaussian 2
- Gradient axial
- Gradient axial reflected
- Gradient circular
- Gradient linear 1
- Gradient linear 2
- Gradient linear 3
- Gradient radial
- Height extrude
- Mesh 1
- Mesh 2
- Panorama shape
- Polygon 1
- Polygon 2
- Scratches generator
- Shape
- Shape extrude
- Shape mapper
- Shape splatter
- Shape splatter blend
- Shape splatter data extract
- Shape splatter to mask
- Splatter
- Splatter circular
- Star
- Starburst
- Stripes
- Tile generator
- Tile random
- Tile random 2
- Tile sampler
- Triangle grid
- Weave 1
- Weave 2
- Weave generator
- Filters
- Filters
- Adjustments
- Adjustments
- Apply color palette
- Auto levels
- Channel mixer
- Chrominance extract
- Clamp
- Color match
- Color to mask
- Contrast/Luminosity
- Convert to linear
- Convert to sRGB
- Create color palette (16)
- Grayscale conversion advanced
- Hald CLUT
- HDR range viewer
- Height map frequencies mapper
- Highpass
- Histogram compute
- Histogram equalize
- Histogram range
- Histogram render
- Histogram scan
- Non-uniform histogram scan
- Histogram select
- Histogram shift
- ID to mask grayscale
- Invert
- Lighting cancel high frequencies
- Lighting cancel low frequencies
- Luminance highpass
- Min max
- Modify color palette
- Pow
- Quantize color (Simple)
- Quantize color
- Quantize grayscale
- Replace color
- Replace color range
- Threshold
- View color palette
- Blending
- Blurs
- Channels
- Effects
- Effects
- 3D texture position
- 3D texture SDF
- 3D texture surface render
- 3D texture volume render
- Ambient occlusion (HBAO)
- Ambient occlusion (RTAO)
- Anisotropic Kuwahara color
- Anisotropic Kuwahara grayscale
- Bevel
- Bevel smooth
- Cross section
- Curvature
- Curvature smooth
- Curvature sobel
- Diffusion color
- Diffusion grayscale
- Diffusion UV
- Directional distance
- Edge detect
- Emboss with gloss
- Extend shape
- Flood fill
- Flood fill mapper
- Flood fill to Bbox size
- Flood Fill to gradient
- Flood Fill to grayscale/color
- Flood Fill to index
- Flood Fill to position
- Flood Fill to random color
- Flood Fill to random grayscale
- FXAA
- Glow
- Mosaic
- Multi directional warp
- Non-uniform directional warp
- Reaction diffusion fast
- RT irradiance
- RT shadow
- Shadows
- Shape drop shadow
- Shape glow
- Shape stroke
- Summed area table
- Swirl
- Uber emboss
- Vector morph
- Vector warp
- Normal map
- Tiling
- Transforms
- Material filters
- Material filters
- 1-click
- Effects (Material)
- Transforms (Material)
- Blending (Material)
- PBR utilities
- Scan processing
- Mesh-based generators
- Mesh-based generators
- Mask generators
- Weathering
- Utilities (Mesh-based generators)
- Spline & Path tools
- Spline & Path tools
- Working with Path & Spline tools
- Path tools
- Spline tools
- Spline tools
- Paths to Spline
- Point list
- Scatter on Spline color
- Scatter on Spline grayscale
- Spline 2D transform
- Spline (Cubic)
- Spline (Poly quadratic)
- Spline append
- Spline bridge (2 Splines)
- Spline bridge (List)
- Spline bridge mapper color
- Spline bridge mapper grayscale
- Spline circle
- Spline fill
- Spline flow mapper
- Spline mapper color
- Spline mapper grayscale
- Spline merge list
- Spline render
- Spline sample height
- Spline sample thickness
- Spline select
- Spline warp
- UV mapper color
- UV mapper grayscale
- 3D view (Library)
- 3D view (Library)
- HDRI tools
- Node library
- Substance function graphs
- Substance function graphs
- What is a Substance function graph?
- Create and edit a Substance function graph
- The Substance function graph
- Variables
- FX-maps
- FX-Maps
- How it works
- The Iterate node
- The Quadrant node
- Using Substance function graphs in FX-Maps
- Warnings in Substance function graphs
- Sample Substance function graphs
- Nodes reference for Substance function graphs
- MDL graphs
- Bakers
- Best practices
- Pipeline and project configuration
- Color management
- Package metadata
- Scripting
- Scripting
- Plugin basics
- Plugin search paths
- Plugins packages
- Plugin manager
- Python editor
- Accessing graphs and selections
- Nodes and properties
- Undo and redo
- Application callbacks
- Creating user interface elements
- Adding actions to the Explorer toolbar
- Using color management
- Using spot colors
- Logging
- Using threads
- Debugging plugins using Visual Studio Code
- Porting previous plugins
- Packaging plugins
- Scripting API reference
- Technical issues
- Release notes
Scripting API reference
This page describes the main concepts of the API.
For more detailed information please refer to the documentation shipped with the application that is accessible in Help > Python API Documentation.... In this documentation, do a Quick Search for the module names (in parentheses below) to easily find their definition.
Context
The context (Context) object is the main entry point to the API. It is created the first time the user get it by using the method 'getContext()' from the 'sd' module.
This object allows to essentially retrieve the application (SDApplication) object.
Application (SDApplication)
The application (SDApplication) is the object that allows access to the main API managers such as:
- the Package Manager (SDPackageMgr) that manages all of the application's packages;
- the Module Manager (SDModuleMgr) that manages all of the application's modules;
- the UI Manager (SDUIMgr) that can create menus and docks in the application's window.
You can register callbacks with the application that will be called when certain events happen.
Package Manager (SDPackageMgr)
This object manages all the application's packages. Packages are displayed in the 'Explorer' component.
It allows you to:
- create a new package;
- load/unload a package;
- save a package;
- find a package.
Package (SDPackage)
A package (SDPackage) is a collection of resources (SDResource).
The content of a package can be stored to a file with the .sbs extension through the 'SDPackageMgr' object. This object allows you to retrieve specific resources.
To create a specific resource, see the related object static methods (Ex: 'SDSBSCompGraph.sNew()').
A package also contains a metadata dictionary (SDMetadataDict). You can find more info on metadatas here.
Resource (SDResource)
A resource (SDResource) is an object that can be referenced by another resource.
There are multiple resource types:
- Folders (SDResourceFolder);
- Graphs (SDGraph);
- Bitmaps (SDResourceBitmap);
- SVG Images (SDResourceSVG);
- Fonts (SDResourceFont);
- Scenes (SDResourceScene);
- BSDF Measurements (SDResourceBSDFMeasurement);
- Light Profiles (SDResourceLightProfile).
A resource can be created from static method 'sNew()' under:
- a package;
- a folder.
A resource can have several properties (SDProperty).
UI Manager (SDUIMgr)
The UI manager allows creating user interface elements in Substance Designer's main window, such as menus, docks and allows registering callbacks to be called when user interface related events happen.
Additionally, the UI manager has access to the current active graph and the selection of the active graph.
Graphs (SDGraph)
A graph (SDGraph) is an object that contains:
- nodes (SDNode);
- graph objects (SDGraphObjects);
- properties (SDProperty).
There are 4 different graph types:
- Substance graph (SDSBSCompGraph)
- Substance function graph (SDSBSFunctionGraph)
- Substance FXMap graph (SDSBSFxMapGraph)
- MDL graph (SDMDLGraph)
A graph can have one or multiple output nodes. The output nodes represent the results of the graph.
All the available nodes for a graph can be retrieved with the method 'getNodeDefinitions()'.
A new node can be created with the method 'newNode()'.
A new instance node can be created from a resource (SDResource) with the method 'newInstanceNode()'.
Node (SDNode)
A node (SDNode) represents an operation carried out on an object.
It can be created from:
- a definition (SDDefinition) (see 'SDGraph.newNode()');
- a resource (SDResource) (see 'SDGraph.newInstanceNode()').
A node can have multiple properties.
There are multiple types of node:
- SDSBSCompNode: A node of the Substance Graph (SDSBSCompGraph);
- SDSBSFunctionNode: A node of the Substance Function Graph (SDSBSFunctionGraph);
- SDSBSFxMapNode: A node of the Substance FXMap Graph (SDSBSFxMapGraph);
- SDMDLNode: A node of the MDL Graph (SDMDLGraph). Note: Many other specific nodes inherit from this node.
Graph Objects (SDGraphObjects)
A graph object (SDGraphObject) is an object that adds additional information to the graph, but that is not taken into account during the graph evaluation process.
There are 3 types of graph objects:
- Pin (SDGraphObjectPin)
- Comment (SDGraphObjectComment)
- Frame (SDGraphObjectFrame)
See the static method 'sNew()' on these objects for more information regarding how to create them.
Properties (SDProperty)
A property (SDProperty) is an object that describes a property of another object (a graph, a node, a resource, and so on).
It belongs to a specific category (SDPropertyCategory):
- Input: classifies an object's input properties, which usually impact the operation carried out by the current object;
- Ex: the property 'color' of a Uniform Color node in a Substance graph is an input property;
- Output: classifies an object's output properties. It is used to identify a result of an object;
- Annotation: classifies properties that do not impact the operation carried out by an object;
- Ex: the 'label' of a graph is an annotation property, because it does not impact the graph computation.
It contains the following members:
- Id: The identifier of the property in the context of his category;
- Types: The types supported by the current property. Some properties can support multiple types: 'int', 'float', etc.;
- Ex: the input properties of an 'sbs::function::add' node can support different types: 'int', 'int2', 'int3', 'int4', 'float', 'float2', 'float3', 'float4', etc.;
- Category: The category the property belongs to (input, output, annotation);
- Label: The label of the property, used for display only;
- Description: The description of the property;
- DefaultValue: The default value;
- IsConnectable: Indicates if a connection (SDConnection) can be carried out on this property;
- isReadyOnly: Indicates if the property is read-only. If true, the value associated to it will not be modifiable;
- isVariadic: If true, this property will be represented as multiple properties on the object;
- isPrimary: Indicates whether the specified property is the principal property that controls some other properties. Note: this is specific to Substance Compositing Nodes (SDSBSCompNode)).
Examples:
- Properties of the 'sbs::compositing::input' node:
sbs::compositing::input | ||
---|---|---|
Input | Annotation | Output |
$outputsize | label | unique_filter_output (CONNECTABLE) |
$format | description | |
$pixelsize | identifier | |
$pixelratio | userdata | |
$tiling | group | |
$randomseed | visibleif | |
bitmapresourcepath | usages |
- Properties of the 'sbs::compositing::blend' node:
sbs::compositing::blend | ||
---|---|---|
Input | Annotation | Output |
$outputsize | unique_filter_output (CONNECTABLE) | |
$format | ||
$pixelsize | ||
$pixelratio | ||
$tiling | ||
$randomseed | ||
source.connector (CONNECTABLE) | ||
destination.connector (CONNECTABLE) | ||
opacity.connector (CONNECTABLE) | ||
opacitymult | ||
blendingmode | ||
colorblending | ||
maskrectangle |
Type (SDType)
A type (SDType) contains information of a value type, such as:
- Id: The identifier of the type;
- Modifier: The type modifier that can be one of the 'SDTypeModifier' enum values:
- Auto;
- Uniform: The value is evaluated once per operation;
- Varying: The value is evaluated multiple times per operation (ex: for each texel).
Multiple types are defined, such as:
- enums (SDTypeEnum): describes an enumeration type with all its properties;
- structures (SDTypeStruct): describes a structure type with all its properties;
- array (SDTypeArray): describes an array.
- etc.
See Substance Designer's Python API Documentation for the exhaustive list.
Values (SDValue)
A value (SDValue) is an object that encapsulates a base type value.
For instance:
- a 'SDValueInt' object encapsulates an 'int' value;
- a 'SDValueFloat4' object encapsulates a 'float4' value;
- etc.
The base type value can usually be retrieved with the 'get()' method, but this can depend on the type of 'SDValue' that has been returned.
Connection (SDConnection)
A connection (SDConnection) represents a link between two different properties of two different nodes.
It contains:
- The target node;
- The target property of the target node;
All connection operations are carried out on a node:
- creating a new connection, see 'SDNode.newPropertyConnection()'
- deleting an existing connection, see 'SDNode.deletePropertyConnection()'
- retrieving the connections of a property, see 'SDNode.getPropertyConnections()'
Module (SDModule)
A module is a collection of definitions and types.
It allows easy retrieval of all the information on the nodes that can be created, as well as on enumerations and structures.
It contains:
- an identifier (Id) that is unique in the context of the module manager (SDModuleMgr);
- a list of definitions (SDDefinition);
- a list of types (SDType).
Definition (SDDefinition)
A definition (SDDefinition) object contains information on the definition of a particular object based on properties ('SDNode', etc.).
It contains:
- Id: the identifier of the definition;
- Label: The label of the definition;
- Description: The description of the definition;
- Properties: The properties of all the available property categories (SDPropertyCategory).