graph | Substance 3D Automation ToolKit

Search
Substance 3D Automation Toolkit

Substance 3D Automation Toolkit

Open app
Note

Documentation for Substance Automation Toolkit is now included in the SAT package. You can access the documentation by opening html-doc.zip inside your downloaded SAT package.

graph

Content included in graph module:

Module graph aims to define SBSObjects that are relative to a graph or a function, mostly SBSGraph, SBSFunction, SBSParamInput and SBSGraphOutput.

 class graph.graph.SBSGraph(aIdentifier='', aUID='', aAttributes=None, aParamInputs=None, aPrimaryInput=None, aGraphOutputs=None, aCompNodes=None, aBaseParameters=None, aGUIObjects=None, aOptions=None, aRoot=None, aPresets=None, aMetaDataTree=None, aGraphType=None)

Bases: pysbs.common_interfaces.sbsobject.SBSObject, pysbs.common_interfaces.basegraph.Graph, pysbs.common_interfaces.metadata.SBSMetaDataObject

Class that contains information on a compositing graph as defined in a .sbs file

Members:
  • mIdentifier (str): name of the graph (name of the definition and the instance if applicable).
  • mUID (str): unique identifier in the package/ context.
  • mAttributes (SBSAttributes): various attributes
  • mParamInputs (list of SBSParamInput): list of parameters and compositing inputs of the graph.
  • mPrimaryInput (str, optional): The uid of the primary (image) input (paramInputs/uid).
  • mGraphOutputs (list of SBSGraphOutput): list of compositing outputs of the graph.
  • mCompNodes (list of SBSCompNode): compositing nodes, the graph definition.
  • mBaseParameters (list of SBSParameter): common authoring parameters.
  • mGUIObjects (list of SBSGUIObject, optional): GUI specific objects.
  • mOptions (list of SBSOption): list of specific options.
  • mRoot (SBSRoot, optional): Appears when the graph is a root (root graphs outputs are directly computed at runtime, cooking always needed).
  • mPresets (SBSPreset, optional): list of user-defined presets
  • mMetaDataTree (SBSMetaDataTree, optional): metadata tree
  • mGraphType (str, optional): graph type 
 addInputParameter(aIdentifier, aWidget, aDefaultValue, aOptions = None, aDescription = None, aLabel = None, aGroup = None, aUserData = None, aVisibleIf = None)

Create a SBSParamInput with the given parameters and add it to the ParamsInput of the graph.

Parameters:
  • aIdentifier (str) – identifier of the input parameter
  • aWidget (WidgetEnum) – widget to use for this parameter
  • aDefaultValue (str, optional) – default value
  • aIsConnectable (bool, optional) – Whether this parameter can be connected for value computation
  • aOptions (dictionary in the format {WidgetOptionEnum: value(str)}, optional) – options
  • aDescription (str, optional) – textual description
  • aLabel (str, optional) – GUI label for this input parameter
  • aGroup (str, optional) – string that contains a group name. Can uses path with ‘/’ separators.
  • aUserData (str, optional) – user tags
  • aVisibleIf (str, optional) – string bool expression based on graph inputs values
Returns:

The created SBSParamInput object, or None if this input parameter is already defined

 
 changeInputParameterIdentifier(aDoc, aInputParamIdentifier, aNewInputParamIdentifier)

changeParamInputIdentifier(aDoc, aInputParamIdentifier, aNewInputParamIdentifier)

Change the param’s identifier and update its dependencies, function’s paramnode, visibleIf… Raise error if aNewInputIdentifier already exist graph’s input parameter identifiers. :param aDoc: the current substance document SBSDocument :type aDoc: SBSDocument :param aIdentifier: the new identifier value :type aIdentifier: str :return:

 computeUniqueInputIdentifier(aIdentifier, aSuffixId = 0)

Check if the given identifier is already used in the graph inputs and generate a unique identifier if necessary

Returns:A unique identifier, which is either the given one or a new one with a suffix: identifier_id 
 computeUniqueOutputIdentifier(aIdentifier, aSuffixId = 0)

Check if the given identifier is already used in the graph outputs and generate a unique identifier if necessary

Returns:A unique identifier, which is either the given one or a new one with a suffix: identifier_id 
 connectNodes(aLeftNode, aRightNode, aLeftNodeOutput = None, aRightNodeInput = None)

Connect the given nodes together: aLeftNode(on the output aLeftNodeOutput) -> aRightNode(on the input aRightNodeInput). If the right node input is None, the connection will be done on the first input of the right node. If the left node output is None, the connection will be done on the first compatible output of the left node.

Parameters:
  • aLeftNode (SBSCompNode or str) – Node to connect from, as a SBSCompNode or given its UID
  • aRightNode (SBSCompNode or str) – Node to connect to, as a SBSCompNode or given its UID
  • aLeftNodeOutput (OutputEnum or str, optional) – Identifier of the output of the left node
  • aRightNodeInput (InputEnum or str, optional) – Identifier of the input of the right node
Returns:

The connection if success, None otherwise (in case of type incompatibility for instance)
Raise:

api_exceptions.SBSImpossibleActionError

 
 contains(aNode)

Check if the given node belongs to this graph

Parameters:aNode (SBSCompNode or str) – The node to check, as a, object or an UID
Returns:True if the given node belongs to the node list, False otherwise 
 copyCompNode(aCompNode)

Create a simple copy of the given CompNode with a new UID.

Parameters:aCompNode (SBSCompNode) – the node to copy
Returns:The new SBSCompNode object 
 createBitmapNode(aSBSDocument, aResourcePath, aGUIPos = None, aParameters = None, aInheritance = None, aResourceGroup = 'Resources', aCookedFormat = None, aCookedQuality = None)

Create a new ‘bitmap’ node and add it to the CompNodes of the graph. Create the referenced resource if necessary, as a Linked resource. If you want to import the resource, use first SBSDocument.createImportedResource() and then SBSGraph.createBitmapNode() with the internal path to the imported resource (pkg:///…).

Parameters:
  • aSBSDocument (SBSDocument) – current edited document
  • aResourcePath (str) – internal (pkg:///MyGroup/MyResourceIdentifier), relative (to the current package) or absolute path to the bitmap resource to display in the bitmap
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the Bitmap node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(sbsenum.ParamInheritanceEnum)}, optional) – Inheritance of the parameters
  • aResourceGroup (SBSGroup or str, optional) – SBSGroup or identifier of the group where the resource will be added (the group is created if necessary). Default to ‘Resources’. Put None to create the resource at the root of the package.
  • aCookedFormat (BitmapFormatEnum, optional) – if a resource is created, it will be used to set the cooked format of the resource. Default value is RAW
  • aCookedQuality (float, optional) – if a resource is created, it will be used to set the cooked quality of the resource. Default value is 0
  • aAttributes (dictionary in the format {AttributesEnum : value(str)}, optional) – if a resource is created, will be set as the attributes of the resource
  • aAutodetectImageParameters (bool) – Autodetect and set resolution and bitdepth for the bitmap.
Returns:

The new SBSCompNode object

 
 createComment(aCommentText='Comment', aGUIPos=None, aLinkToNode=None)

Create a new comment. If aLinkToNode is not None, this comment will be linked to the given node, and the given GUI position must be relative to this node.

Parameters:
  • aCommentText (str, optional) – The text of the comment. Default to ‘Comment’
  • aGUIPos (list of 3 float, optional) – The comment position in the graph. Default to [0,0,0]
  • aLinkToNode (SBSCompNode or str, optional) – The node to associate to this comment, as a SBSCompNode or given its UID
Returns:

The SBSGUIObject created

 
 createCompFilterNode(aFilter, aGUIPos = None, aParameters = None, aInheritance = None)

Create a new compositing node filter and add it to the CompNodes of the graph.

Note:
Parameters:
  • aFilter (FilterEnum) – filter type among the list defined in sbsenum.FilterEnum
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the filter node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
Returns:

The new SBSCompNode object

 
 createCompInstanceNode(aSBSDocument, aGraph, aGUIPos = None, aParameters = None, aInheritance = None)

Create a new compositing node instance which references the given graph, and add it to the CompNodes of the current graph.

Note:
Parameters:
  • aSBSDocument (SBSDocument) – current edited document
  • aGraph (SBSGraph) – graph that will be referenced by the instance node
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the filter node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
Returns:

The new SBSCompNode object
Raise:

api_exceptions.SBSImpossibleActionError

 
 createCompInstanceNodeFromPath(aSBSDocument, aPath, aGUIPos = None, aParameters = None, aInheritance = None)

Create a new compositing node instance which references the graph pointed by the given path, and add it to the CompNodes of the graph.

Parameters:
  • aSBSDocument (SBSDocument) – current edited document
  • aPath (str) –

    path of the graph definition (absolute, relative to the current .sbs file, or given with an alias, for instance sbs://anisotropic_noise.sbs)

    • If the graph is included in the current package, use: pkg:///MyGraphIdentifier
    • If the path uses an alias, use: myalias://MyFileName.sbs/MyGraphIdentifier
    • If the path is relative to the current package or absolute, use MyAbsoluteOrRelativePath/MyFileName.sbs/MyGraphIdentifier
    • Note that if the graph identifier is equivalent to the filename, the part /MyGraphIdentifier may be omit.
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the filter node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
Returns:

The new SBSCompNode object

 
 createCurveNode(aGUIPos = None, aParameters = None, aInheritance = None, aCurveDefinitions = None)

Create a new Curve filter and add it to the CompNodes of the graph.

Parameters:
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the filter node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – inheritance of the parameters
  • aCurveDefinitions (list of CurveDefinition, optional) – curve definitions
Returns:

The new SBSCompNode object

 
 createFrame(aSize, aFrameTitle='Frame', aCommentText='', aGUIPos=None, aColor=None, aDisplayTitle=True)

Create a new framed comment.

Parameters:
  • aSize (list of 2 float) – The frame size
  • aFrameTitle (str, optional) – The title of the frame. Default to ‘Frame’
  • aCommentText (str, optional) – The text of the frame. Empty by default
  • aGUIPos (list of 3 float, optional) – The frame position in the graph. Default to [0,0,-100]
  • aColor (list of 4 float between 0 and 1, optional.) – The frame color. Default to [0.196, 0.196, 0.509, 0.196]
  • aDisplayTitle (boolean, optional) – True to display the frame title. Default to True
Returns:

The SBSGUIObject created

 
 createFrameAroundNodes(aNodeList, aFrameTitle='Frame', aCommentText='', aColor=None, aDisplayTitle=True)

Create a new framed comment around the given nodes.

Parameters:
  • aNodeList (list of class:.SBSCompNode) – The nodes to include in the frame
  • aFrameTitle (str, optional) – The title of the frame. Default to ‘Frame’
  • aCommentText (str, optional) – The text of the frame. Empty by default
  • aColor (list of 4 float between 0 and 1, optional.) – The frame color. Default to [0.196, 0.196, 0.509, 0.196]
  • aDisplayTitle (boolean, optional) – True to display the frame title. Default to True
Returns:

The SBSGUIObject created
Raise:

api_exceptions.SBSImpossibleActionError

 
 createGradientMapNode(aGUIPos = None, aParameters = None, aInheritance = None, aKeyValues = None)

Create a new Gradient Map filter and add it to the CompNodes of the graph.

Parameters:
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the filter node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
  • aKeyValues (list of GradientKey, optional) – gradient key values
Returns:

The new SBSCompNode object

 
 createInputNode(aIdentifier, aColorMode = sbsenum.ColorModeEnum.COLOR, aGUIPos = None, aAttributes = None, aUsages = None, aSetAsPrimary = False, aParameters = None, aInheritance = None)

Create a new compositing node input with the appropriate color and add it to the CompNode list of the graph. Declare it as PrimaryInput if this is the first input node. Declare the new SBSParamInput

Parameters:
  • aIdentifier (str) – input identifier. It may change to ensure having a unique identifier.
  • aColorMode (ColorModeEnum, optional) – color or grayscale. Default is COLOR
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aAttributes (dictionary {AttributesEnum : AttributeName(str)}, optional) – output attributes list
  • aUsages (dictionary {UsageEnum : ComponentsEnum}, optional) – usage of this output
  • aSetAsPrimary (bool, optional) – True to define this input as the PrimaryInput of the graph. Even if False, the input will be set as the PrimaryInput if this is the first input of the graph
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the input node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
  • aGroup (str, optional) – GUI group name. Can uses path with ‘/’ separators.
  • aVisibleIf (str, optional) – Condition of visibility of this input
Returns:

The new SBSCompNode object

 
 createInputValueNode(aIdentifier, aInputValueTypeEnum = sbsenum.InputValueTypeEnum.FLOAT1, aGUIPos = None, aAttributes = None, aUsages = None, aSetAsPrimary = False, aParameters = None, aInheritance = None)

Create a new input value node with the appropriate value type and add it to the CompNode list of the graph. Declare it as PrimaryInput if this is the first input node. Declare the new SBSParamInput

Parameters:
  • aIdentifier (str) – input identifier. It may change to ensure having a unique identifier.
  • aInputValueTypeEnum (InputValueTypeEnum, optional) – value type from sbsenum.InputValueTypeEnum
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aAttributes (dictionary {AttributesEnum : AttributeName(str)}, optional) – output attributes list
  • aUsages (dictionary {UsageEnum : dictionary {UsageDataEnum : ComponentsEnum}}, optional) – usage of this output
  • aSetAsPrimary (bool, optional) – True to define this input as the PrimaryInput of the graph. Even if False, the input will be set as the PrimaryInput if this is the first input of the graph
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the input node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
  • aGroup (str, optional) – GUI group name. Can uses path with ‘/’ separators.
  • aVisibleIf (str, optional) – Condition of visibility of this input
Returns:

The new SBSCompNode object

 
 createIterationOnNode(aNbIteration, aNodeUID, aForceRandomSeed = False, aIncrementIteration = False, aGUIOffset = None)

Duplicate NbIteration times the given node, and connect each node with the previous one to create this kind of connection:

Node -> Node_1 -> Node_2 -> … -> Node_N

Parameters:
  • aNbIteration (positive integer) – number of time the node must be duplicated
  • aNodeUID (str) – the UID of the node to duplicate
  • aForceRandomSeed (bool, optional) – specify if a different random seed must be generated for each iteration. Default to False
  • aIncrementIteration (bool, optional) – specify if the parameter ‘iteration’ must be incremented at each iteration. Default to False
  • aGUIOffset (list of 2 float, optional) – pattern position offset. Default to [150, 0]
Returns:

The list of SBSCompNode objects created (including the nodes given in aNodeUIDs_NextPatternInput), None if failed

 
 createIterationOnPattern(aNbIteration, aNodeUIDs, aNodeUIDs_NextPattern = None, aForceRandomSeed = False, aIncrementIteration = False, aGUIOffset = None)

Duplicate NbIteration times the given pattern of compositing nodes, and connect each pattern with the previous one to create this kind of connection:

Pattern -> Pattern_1 -> Pattern_2 -> … -> Pattern_N

It allows to completely define the way two successive patterns are connected.

For instance, provide aNodeUIDs = [A, B, C] and aNodeUIDs_NextPatternInput = [A’], if the pattern is A -> B -> C, and if C is connected to A’.

If aNodeUIDs_NextPatternInput is let empty, the function will try to connect the successive patterns by the most obvious way, respecting the input / output type (color / grayscale)

Parameters:
  • aNbIteration (positive integer) – number of time the pattern must be duplicated
  • aNodeUIDs (list of str) – list of node’s UID that constitute the pattern to duplicate
  • aNodeUIDs_NextPattern (list of str, optional) – list of node’s UID that correspond to the next pattern, which must be connected to the given pattern. Default to []
  • aForceRandomSeed (bool, optional) – specify if a different random seed must be generated for each iteration. Default to False
  • aIncrementIteration (bool, optional) – specify if the parameter ‘iteration’ must be incremented at each iteration. Default to False
  • aGUIOffset (list of 2 float, optional) – pattern position offset. Default to [150, 0]
Returns:

The list of SBSCompNode objects created (including the nodes given in aNodeUIDs_NextPatternInput), None if failed

 
 createMetaDataStr(aName, aValue)

Create a metadata of type Str.

Parameters:
Returns:

A SBSMetaDataUrl object

 
 createMetaDataUrl(aName, aResource)

Create a metadata of type Url.

Parameters:
Returns:

A SBSMetaDataUrl object

 
 createNavigationPin(self, aPinText, aGUIPos)

Create a new navigation pin.

Parameters:
  • aPinText (str) – The text of the navigation pin
  • aGUIPos (list of 3 float) – The navigation pin position in the graph
Returns:

The SBSGUIObject created

 
 createOutputNode(aIdentifier, aGUIPos = None, aAttributes = None, aOutputFormat = sbsenum.TextureFormatEnum.DEFAULT_FORMAT, aMipmaps = None, aUsages = None, aGroup = None)

Create a new compositing node output and add it to the CompNodes of the graph. Declare the new RootOutput and GraphOutput

Parameters:
  • aIdentifier (str) – output identifier
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aAttributes (dictionary {AttributesEnum : AttributeName(str)}, optional) – output attributes list
  • aOutputFormat (TextureFormatEnum, optional) – output format. Default value is DEFAULT_FORMAT
  • aMipmaps (sbsenum.MipmapEnum, optional) – mipmaps level. default value is FULL_PYRAMID
  • aUsages (dictionary {UsageEnum : ComponentsEnum}, optional) – usage of this output
  • aGroup (str) – GUI group of this output
  • aVisibleIf (str, optional) – Condition of visibility of this output
Returns:

The new SBSCompNode object

 
 createPreset(aLabel, aUsertags=None, setCurrentDefaultValues=False)

Create a new preset with the given label and usertags and add it to the preset list of this graph.

Parameters:
  • aLabel (str) – The label of this preset
  • aUsertags (str, optional) – The usertags of this preset
  • setCurrentDefaultValues (bool, optional) – True to automatically create one SBSPresetInput by input parameter in the graph, initialized with the default value. Default to False.
Returns:

the created preset as a SBSPreset

 
 createSvgNode(aSBSDocument, aResourcePath, aGUIPos = None, aParameters = None, aInheritance = None, aResourceGroup = 'Resources', aCookedQuality = None)

Create a new ‘svg’ node and add it to the CompNodes of the graph. Create the referenced resource if necessary, as a Linked resource. If you want to import the resource, use first SBSDocument.createImportedResource() and then SBSGraph.createSvgNode() with the relative path to the imported resource.

Parameters:
  • aSBSDocument (SBSDocument) – current edited document
  • aResourcePath (str) – internal (pkg:///MyGroup/MyResourceIdentifier), relative (to the current package) or absolute path to the SVG resource to display in the node
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the Bitmap node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(sbsenum.ParamInheritanceEnum)}, optional) – Inheritance of the parameters
  • aResourceGroup (SBSGroup or str, optional) – SBSGroup or identifier of the group where the resource will be added (the group is created if necessary). Default to ‘Resources’. Put None to create the resource at the root of the package.
  • aCookedQuality (float, optional) – default value is 0
Returns:

The new SBSCompNode object

 
 createTextNode(aGUIPos = None, aParameters = None, aInheritance = None, aCurveDefinitions = None)

Create a new Curve filter and add it to the CompNodes of the graph.

Parameters:
  • aFontFamily (str, optional) – font family to use for this text. It can be the name of a font, for instance ‘Arial’, or an internal path to a font resource (pkg:///myFontResourceIdentifier). Default to ‘Arial’
  • aFontSubFamily (str, optional) – font subfamily to use for this text. Default to None, which corresponds to the Regular font. For instance: ‘Bold’,’Italic’, … Beware of the compatibility of the font subfamily with the provided font.
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
  • aParameters (dictionary {parameter(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the filter node
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – inheritance of the parameters
Returns:

The new SBSCompNode object

 
 deleteComment(aComment)

Allows to delete the given comment from the graph.

Parameters:aComment (SBSGUIObject or str) – The comment to remove, as a Comment or an UID.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 deleteFrame(aFrame)

Allows to delete the given frame from the graph.

Parameters:aFrame (SBSGUIObject or str) – The frame to remove, as a Frame or an UID.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 deleteInputParameter(aInputParameter)

Allows to delete the given input parameter. If this is an input image, remove the corresponding Input node.

Parameters:aInputParameter (SBSParamInput or str) – The input parameter to remove.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 deleteMetaData(aName)

Delete a metadata, return True if success.

Parameters:aName (str) –
Returns:bool 
 deleteNavigationPin(aNavigationPin)

Allows to delete the given navigation pin from the graph.

Parameters:aNavigationPin (SBSGUIObject or str) – The navigation pin to remove, as a NavigationPin or an UID.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 deleteNode(aNode)

Allows to delete the given node from the graph. It removes it from the CompNode list, and delete all the connection from and to that node in the graph.

Parameters:aNode (SBSCompNode or str) – The node to remove, as a SBSCompNode or an UID.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 deletePreset(aPreset)

Allows to delete the given preset.

Parameters:aPreset (SBSPreset or str) – The preset to remove, as a SBSPreset object or identified by its label.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 disconnectNodes(aLeftNode, aRightNode, aLeftNodeOutput = None, aRightNodeInput = None)

Disconnect the given nodes: aLeftNode(on the output aLeftNodeOutput) -> aRightNode(on the input aRightNodeInput). If the left node output and the right node input are None, all the connections will be removed.

Parameters:
  • aLeftNode (SBSCompNode or str) – Left node, as a SBSCompNode or given its UID
  • aRightNode (SBSCompNode or str) – Right node, as a SBSCompNode or given its UID
  • aLeftNodeOutput (OutputEnum or str, optional) – Identifier of the output of the left node
  • aRightNodeInput (InputEnum or str, optional) – Identifier of the input of the right node
Returns:

Nothing
Raise:

api_exceptions.SBSImpossibleActionError

 
 duplicateNode(aCompNode, aGUIOffset = None)

Duplicate the given node, generate a new UID and add the node to the same node list than the source node.

Parameters:
  • aCompNode (SBSCompNode or str) – the node to copy (may be identified by its UID)
  • aGUIOffset (list of 2 float, optional) – node position offset. Default to [150, 0]
Returns:

The new SBSCompNode object

 
 equals(other)

Check if this SBSObject is equivalent to the other SBSObject. Some members may be excluded from this check, the UIDs or GUILayout for instance.

Parameters:other (SBSObject) – The SBSObject to compare to
Returns:True if the two SBSObject are similar according to their definition. 
 exposeAsInputParameter(aDoc, aNode, aIdentifier, useIfExist=True)

exposeParamInput(aDoc, aNode, aIdentifier) Expose the parameter input identifier from a node to the current graph. The returned parameter will get the same identifier and default value will be the current value of the node’s input parameter.

Parameters:
  • aDoc (SBSDocument) – the current doc SBSDocument needed to generated the dynamic parameter
  • aNode (SBSCompNode) – the input parameter’s node
  • aIdentifier (str) – the identifier of the input parameter to expose
Returns:

bool

 
 exposeParamInput(**kwargs)  
 getAllComments()

Get all comments defined in the graph

Returns:a list of SBSGUIObject 
 getAllDependencyUID()

Get the UIDs of the dependencies used by this graph

Returns:a list of UIDs as strings 
 getAllFiltersOfKind(aFilter)

Search for all SBSCompNode which represents the given filter kind.

Parameters:aFilter (FilterEnum str) – kind of filters to look for
Returns:a list of SBSCompNode containing all filters of the given kind. 
 getAllFrames()

Get all frames defined in the graph

Returns:a list of SBSGUIObject 
 getAllGUIObjects()

Get all the GUI objects defined in the graph (Comments, Frames, Navigation Pins)

Returns:a list of SBSGUIObject 
 getAllInputGroups()

Get the list of all groups used for the inputs of the graph.

Returns:a list of groups as strings 
 getAllInputNodes()

Search for all SBSCompNode with a CompInputBridge implementation.

Returns:a list of SBSCompNode containing all input nodes of the graph. 
 getAllInputs()

Get the list of all input parameters (images and variables) defined on this graph

Returns:a list of SBSParamInput 
 getAllInputsInGroup(aGroup)

Get the list of all inputs (images and parameters) contained in the given group.

If aGroup is None, returns all the parameters that are not included in a group.

Parameters:aGroup (str) – The group of parameter to consider
Returns:a list of SBSParamInput 
 getAllMetaData()

Get all MetaData under dictionary form.

Returns:dict 
 getAllNavigationPins()

Get all the navigation pins defined in the graph

Returns:a list of SBSGUIObject 
 getAllNodeInstancesOf(aSBSDocument, aPath)

Search for all SBSCompNode with a CompInstance implementation, which reference the given graph path.

Parameters:
  • aSBSDocument (SBSDocument) – current SBSDocument
  • aPath (str) –

    path of the graph definition (absolute, relative to the current .sbs file, or given with an alias, for instance sbs://anisotropic_noise.sbs)

    • If the graph is included in the current package, use: pkg:///MyGraphIdentifier
    • If the path uses an alias, use: myalias://MyFileName.sbs/MyGraphIdentifier
    • If the path is relative to the current package or absolute, use MyAbsoluteOrRelativePath/MyFileName.sbs/MyGraphIdentifier
    • Note that if the graph identifier is equivalent to the filename, the part /MyGraphIdentifier may be omit.
Returns:

a list of SBSCompNode containing all instance nodes of the given graph.

 
 getAllNodes()

Search for all SBSCompNode.

Returns:a list of SBSCompNode. 
 getAllOutputNodes()

Search for all SBSCompNode with a CompOutputBridge implementation.

Returns:a list of SBSCompNode containing all output nodes of the graph. 
 getAllPresets()

Get all the presets defined on this graph

Returns:a list of Preset 
 getAllReferencesOnDependency(aDependency)

Get all the SBSCompNode that are referencing the given dependency

Parameters:aDependency (str or SBSDependency) – The dependency to look for (UID or object)
Returns:A list of SBSCompNode 
 getAllReferencesOnResource(aResource)

Get all the SBSCompNode that are referencing the given resource

Parameters:aResource (str or SBSResource) – The resource to look for (object or path internal to the package (pkg:///myGroup/myResource)
Returns:A list of SBSCompNode 
 getAllResourcesUsed(aParentDocument)

Get the list of resources used in this graph as a list of paths relative to the package

Parameters:aParentDocument (SBSDocument) – Parent SBSDocument containing this graph
Returns:the list of resources used in this graph as a list of paths relative to the package (pkg:///…) 
 getAllowedAttributes()

Get the attributes allowed on a SBSGraph

Returns:the list of attribute enumeration allowed (AttributesEnum) 
 getAttribute(aAttributeIdentifier)

Get the given attribute value

Parameters:aAttributeIdentifier (AttributesEnum) – the attribute identifier
Returns:the attribute value if defined, None otherwise 
 getBaseParameterValue(aParameter)

Find a parameter with the given name/id among the overloaded parameters and the default graph parameters, and return its value.

Parameters:aParameter (CompNodeParamEnum or str) – Parameter identifier
Returns:The parameter value if found (string or SBSDynamicValue, None otherwise 
 getCommentsAssociatedToNode(aNode)

Get the list of comments associated to the given node

Parameters:aNode (SBSCompNode or str) – The node to consider, as a SBSCompNode or given its UID
Returns:a list of SBSGUIObject 
 getConnectionsFromNode(self, aLeftNode, aLeftNodeOutput=None)

Get the connections starting from the given left node, from a particular output or for all its outputs.

Parameters:
  • aLeftNode (SBSCompNode or str) – the node to consider, as a SBSCompNode or given its uid
  • aLeftNodeOutput (OutputEnum or str, optional) – the pin output identifier to consider. If let None, all the outputs will be considered
Returns:

a list of SBSConnection

 
 getConnectionsToNode(self, aRightNode, aRightNodeInput=None)

Get the connections incoming to the given right node, to a particular input or for all its inputs.

Parameters:
  • aRightNode (SBSCompNode or str) – the node to consider, as a SBSCompNode or given its uid
  • aRightNodeInput (InputEnum or str, optional) – the pin input identifier to consider. If let None, all the inputs will be considered
Returns:

a list of SBSConnection

 
 getDefaultParentSize()

Get the default parent size option of this graph.

Returns:The parent size, as a list of two OutputSizeEnum: [width,height]. If not defined, return the default value [SIZE_256,SIZE_256] 
 getFirstInputOfType(aType)

Get the first ParamInput with the given type. This considers the variant types as compatible types.

Parameters:aType (sbsenum.ParamTypeEnum) – The required type
Returns:a SBSParamInput object if found, None otherwise 
 getFirstOutputOfType(aType)

Get the first GraphOutput with the given type. This considers the variant types as compatible types.

Parameters:aType (sbsenum.ParamTypeEnum) – The required type
Returns:a SBSGraphOutput object if found, None otherwise 
 getGraphInputNode(aInputImageIdentifier)

Get the input node which corresponds to the input image with the given identifier

Parameters:aInputIdentifier (str) – identifier of the input
Returns:a SBSCompNode object if found, None otherwise 
 getGraphOutput(aOutputIdentifier)

Get the graph output with the given identifier

Parameters:aOutputIdentifier (str) – identifier of the output
Returns:a SBSGraphOutput object if found, None otherwise 
 getGraphOutputFromOutputNode(aOutput)

Get the graph output corresponding to the given output node

Parameters:aOutputNode (SBSCompNode or str) – The output node, as a SBSCompNode or given its UID
Returns:the corresponding SBSGraphOutput if found, None otherwise 
 getGraphOutputFromUID(aOutputUID)

Get the graph output with the given UID

Parameters:aOutputUID (str) – UID of the output to get
Returns:a SBSGraphOutput object if found, None otherwise 
 getGraphOutputNode(aOutputIdentifier)

Get the output node which corresponds to the graph output with the given identifier

Parameters:aOutputIdentifier (str) – identifier of the output
Returns:a SBSCompNode object if found, None otherwise 
 getGraphOutputType(aOutputIdentifier)

Get the output type of the GraphOutput with the given identifier

Parameters:aOutputIdentifier (str) – identifier of the output
Returns:the output type in the format ParamTypeEnum if found, None otherwise 
 getGraphOutputWithUsage(aUsage)

Get the first GraphOutput which has the given usage defined

Parameters:aUsage (UsageEnum or str) – usage to look for
Returns:a SBSGraphOutput if found, None otherwise 
 getGraphOutputs()

Get all the graph outputs

Returns:the list of SBSGraphOutput defined on this graph 
 getGraphType()
Returns:str 
 getGraphTypeName()
Returns:str 
 getIcon()

Get the icon associated to this graph

Returns:The icon as a SBSIcon if it exists, None otherwise 
 getIconBytes()

Get the icon stream bytes

Returns:The icon image data as bytes if possible, None otherwise 
 getIdentifier()

getIdentifer()

Returns:str identifier 
 getInput(aInputIdentifier)

Get the SBSParamInput with the given identifier, among the input images and input parameters

Parameters:aInputIdentifier (str) – input parameter identifier
Returns:the corresponding SBSParamInput object if found, None otherwise 
 getInputFromUID(aInputUID)

Get the SBSParamInput with the given UID, among the input images and parameters

Parameters:aInputUID (str) – input parameter UID
Returns:the corresponding SBSParamInput object if found, None otherwise 
 getInputImage(aInputImageIdentifier)

Get the input image with the given identifier

Parameters:aInputImageIdentifier (str) – input image identifier
Returns:a SBSParamInput if found, None otherwise 
 getInputImageFromInputNode(aInputNode)

Get the input image associated to the given input node

Parameters:aInputNode (SBSCompNode or str) – the input node as a SBSCompNode or a UID
Returns:The input image as a SBSParamInput if found, None otherwise 
 getInputImageIndex(aInputImageIdentifier)

Get the index of the given input image, among the list of ParamInput of kind image.

Parameters:aInputImageIdentifier (str) – input image identifier
Returns:the index of the input image as an integer if found, -1 otherwise 
 getInputImageWithUsage(aUsage)

Get the first input image which has the given usage defined

Parameters:aUsage (UsageEnum or str) – usage to look for
Returns:a SBSParamInput if found, None otherwise 
 getInputImages()

Get the list of input images (inputs of kind ENTRY_COLOR | ENTRY_GRAYSCALE | ENTRY_VARIANT)

Returns:a list of SBSParamInput 
 getInputNode(**kwargs)  
 getInputParameter(aInputIdentifier)

Get the SBSParamInput with the given identifier, among the input parameters

Parameters:aInputParamIdentifier (str) – input parameter identifier
Returns:the corresponding SBSParamInput object if found, None otherwise 
 getInputParameterFromUID(aInputParamUID)

Get the SBSParamInput with the given UID

Parameters:aInputParamUID (str) – input parameter UID
Returns:the corresponding SBSParamInput object if found, None otherwise 
 getInputParameterIndex(aInputParamIdentifier)

Get the index of the given input parameter, among the list of ParamInput of kind variable.

Parameters:aInputParamIdentifier (str) – input parameter identifier
Returns:the index of the input parameter as an integer if found, -1 otherwise 
 getInputParameters()

Get the list of inputs parameters that are not input entries but numerical values

Returns:a list of SBSParamInput 
 getInputParametersInVisibleIfExpression(aVisibleIf)

Get the list of inputs parameters referenced in the given VisibleIf expression

Parameters:aVisibleIf (str) – the VisibleIf expression
Returns:a list of SBSParamInput 
 getInputValueParamFromInputNode(aInputNode)

Get the input value parameter associated to the given input node

Parameters:aInputNode (SBSCompNode or str) – the input node as a SBSCompNode or a UID
Returns:The input value parameter as a SBSParamInput if found, None otherwise 
 getMetaData(aName)

Get a MetaData by its name

Parameters:aName (str) –
Returns:SBSMetaDataTreeUrl or SBSMetaDataTreeStr 
 getNode(aNode)

Search for the given compositing node in the node list

Parameters:aNode (SBSCompNode or str) – node to get, identified by its uid or as a SBSCompNode
Returns:A SBSCompNode object if found, None otherwise 
 getNodeAssociatedToComment(aComment)

Get the node associated to the given comment.

Parameters:aComment (SBSGUIObject) – The comment to consider
Returns:the SBSCompNode if found, None otherwise 
 getNodeList(aNodesList = None)

Get all the compositing nodes of this graph, or look for the given nodes if aNodesList is not None

Parameters:aNodesList (list of str or list of SBSCompNode, optional) – list of node to look for, might be identifiers or .SBSNode
Returns:a list of SBSCompNode included in the graph 
 getNodesConnectedFrom(aLeftNode, aOutputIdentifier=None)

Get all the nodes connected to the given output of the given node. If aOutputIdentifier is let None, consider all the outputs of the node.

Parameters:
  • aLeftNode (SBSCompNode or str) – the node to consider
  • aLeftNodeOutput (OutputEnum or str, optional) – the output to take in account
Returns:

a list of SBSCompNode

 
 getNodesConnectedTo(aRightNode, aRightNodeInput=None)

Get all the nodes connected to the given input of the given node. If aInputIdentifier is let None, consider all the inputs of the node.

Parameters:
  • aRightNode (SBSCompNode or str) – the node to consider, as an object or given its uid
  • aRightNodeInput (InputEnum or str, optional) – the input to take in account
Returns:

a list of SBSCompNode

 
 getNodesDockedTo(aRightNode)

Get all the nodes that are docked to the given node.

Parameters:aRightNode (SBSCompNode) – the node to consider, as an object or given its uid
Returns:a list of SBSCompNode corresponding to the nodes that are docked to the given node. 
 getNodesInFrame(aFrame)

Get all the nodes included or partially included in the given frame. The frame must be included in this graph, otherwise SBSImpossibleActionError is raised

Parameters:aFrame (SBSGUIObject) – The frame to consider
Returns:a list of SBSCompNode 
 getOption(aOptionName)

Get the option with the given name.

Parameters:aOptionName (str) – the name of the option to get, as saved in the .sbs file
Returns:the corresponding SBSOption object if found, None otherwise 
 getOptions()

Get the list of options defined in this graph.

Returns:a list of SBSOption 
 getOutputFormat()

Get the output format of this GraphOutput.

Parameters:aOutputNode – an Identifier
Returns:the output format TextureFormatEnum or ParamTypeEnum if Value output, None otherwise. 
 getOutputMipmaps()

Get the output Mipmaps of this GraphOutput.

Parameters:aOutputNode – an Identifier
Returns:the output format TextureFormatEnum or ParamTypeEnum if Value output, None otherwise. 
 getPreset(aPresetLabel)

Get the preset with the given label

Returns:a Preset object if found, None otherwise 
 getPrimaryInput()

Get the UID of the primary input of the graph

Returns:The UID of the primary input as a string if it exists, None otherwise 
 getPsdExporterOptions()

Get the list of options related to the PSD exporter defined in this graph.

Returns:a list of SBSOption 
 getRect(aNodeList = None)

Get the rectangle occupied by all the nodes of this graph, or use only the given nodes if aNodeList is not None

Parameters:aNodeList (list of str or list of SBSCompNode, optional) – The list of node to take in account for the GUI rectangle. None to consider the node list pointed by itself.
Returns:A Rect 
 getSBSMetaDataTree()

Get the SBSMetaDataTree structure.

Returns:class .SBSMetaDataTree 
 getUidIsUsed(aUID)

Check if the given uid is already used in the context of the graph

Parameters:aUID (str) – UID to check
Returns:True if the uid is already used, False otherwise 
 getUserData(aNode)

Easy way to get userData / userTags associated to an outputCompNode or an inputCompNode. :param aNode: the associated node or UID node. :type aNode: SBSCompNode or str :return:the userTags value as str

 isAPathBetween(self, aLeftNode, aRightNode)

Check if there is a path from the left node to the right node with the current connections.

Parameters:
Returns:

True if a path is found, False otherwise

 
 isPrimaryInput(aInput)

Check if the given input is the primary input for this graph or not

Parameters:aInput (SBSParamInput) – The input to check
Returns:True if this is the primary input, False otherwise 
 moveConnectionOnPinInput(aInitialNode, aTargetNode, aInitialNodeInput=None, aTargetNodeInput=None)

Allows to move the connection connected to the given pin input of the given node to the target pin input of the target node.

Parameters:
  • aInitialNode (SBSCompNode or str) – the node initially connected, as an object or given its uid
  • aTargetNode (SBSCompNode or str) – the target node, which should be connected after this function, as an object or given its uid
  • aInitialNodeInput (InputEnum or str, optional) – the identifier of the input initially connected in aInitialNode. If None, the first input will be considered
  • aTargetNodeInput (InputEnum or str, optional) – the identifier of the input targeted on aTargetNode. If None, the first input will be considered
Returns:
Raise:

SBSImpossibleActionError

 
 moveConnectionsOnPinOutput(aInitialNode, aTargetNode, aInitialNodeOutput=None, aTargetNodeOutput=None)

Allows to move all the connections connected to the given pin output of the given node to the target pin output of the target node.

Parameters:
  • aInitialNode (SBSCompNode or str) – the node initially connected, as an object or given its uid
  • aTargetNode (SBSCompNode or str) – the target node, which should be connected after this function, as an object or given its uid
  • aInitialNodeOutput (OutputEnum or str, optional) – the identifier of the output initially connected in aInitialNode. If None, the first output will be considered
  • aTargetNodeOutput (OutputEnum or str, optional) – the identifier of the output targeted on aTargetNode. If None, the first output will be considered
Returns:
Raise:

SBSImpossibleActionError

 
 parse(aContext, aDirAbsPath, aSBSParser, aXmlNode)

Parse recursively the given xml node to retrieve the content of the SBSObject.

Parameters:
  • aContext (Context) – execution context
  • aDirAbsPath (str) – the absolute directory containing the current parsed package (.sbs file)
  • aSBSParser (SBSParser) – the substance parser
  • aXmlNode (xml.etree.ElementTree) – the xml node to parse 
 reframeAroundNodes(aFrame, aNodeList)

Move and resize a frame to be around the given nodes.

Parameters:
  • aFrame (SBSGUIObject) – The frame to edit
  • aNodeList (list of class:.SBSCompNode) – The nodes to include in the frame
Raise:

SBSImpossibleActionError

 
 setAttribute(aAttributeIdentifier, aAttributeValue)

Set the given attribute

Parameters:
  • aAttributeIdentifier (AttributesEnum) – The attribute identifier to set
  • aAttributeValue (str) – The attribute value to set 
 setAttributes(aAttributes)

Set the given attributes

Parameters:aAttributes (dictionary in the format {AttributesEnum : value}) – The attributes to set 
 setBaseParameterValue(aParameter, aParamValue, aRelativeTo = sbsenum.ParamInheritanceEnum.ABSOLUTE)

Set the value of the given parameter to the given value.

Parameters:
Returns:

True if succeed, False otherwise
Raise:

api_exceptions.SBSLibraryError

 
 setDefaultParentSize(aWidth, aHeight)

Set the default parent size option on this graph.

Parameters: 
 setDynamicBaseParameter(aParameter, aRelativeTo = None)

Set the given parameter as dynamic, to init its params.SBSDynamicValue. If Inheritance is None, the default Inheritance is set.

Parameters:
Returns:

the SBSDynamicValue object if succeed, None otherwise
Raise:

api_exceptions.SBSLibraryError

 
 setGraphOutputType(aGraphOutputUID, aType)

Set the output channel type of the SBSGraphOutput with the given uid

Parameters:
  • aGraphOutputUID (str) – UID of the graph output to consider
  • aType (ParamTypeEnum) – type to set 
 setGraphType(aGraphTypeEnum)

Set the graph type :param aGraphTypeEnum: the enum value to set :type aGraphTypeEnum: GraphTypeEnum

 setIcon(aIconAbsPath)

Set the given image as the icon of the graph. The provided image won’t be re-sized to get a thumbnail, so we strongly recommend that you provide the path to a 128x128 image.

Parameters:aIconAbsPath (str) – The absolute path of the image to set
Returns:The SBSIcon object created 
 setInputImageIndex(aInputImageIdentifier, aIndex)

Set the index of the ParamInput of kind image with the given identifier

Parameters:
  • aInputImageIdentifier (str) – input image identifier
  • aIndex (int) – index to set, in the range [0 ; nbInputImages[
Raise:

api_exceptions.SBSImpossibleActionError if failed

 
 setInputParameterIndex(aInputParamIdentifier, aIndex)

Set the index of the given input parameter among the list of ParamInput of kind variable

Parameters:
  • aInputParamIdentifier (str) – input parameter identifier
  • aIndex (int) – index to set, in the range [0 ; nbInputParameters[
Raise:

api_exceptions.SBSImpossibleActionError if failed

 
 setMetaDataName(aMetadata, aName)

Set name of a metadata if name is valid

Parameters: 
 setMetaDataValue(aMetadata, aValue)

Set value of a metadata

Parameters: 
 setOption(aOptionName, aOptionValue)

Set the given option with the given value.

Parameters:
  • aOptionName (str) – the name of the option to set, as saved in the .sbs file
  • aOptionValue (str) – the value of the option to set, as saved in the .sbs file
Returns:

the created or modified SBSOption object

 
 setOutputChannel(**kwargs)  
 setPrimaryInput(aUID)

Set the UID of the primary input of the graph

Parameters:aUID (str) – UID of the input to set as primary 
 setUserData(aNode, data)

Easy way to set userData / userTags associated to an outputCompNode or an inputCompNode. :param aGraph: the graph where live the node. :type aGraph: SBSGraph :param aData: the data to set as value :type aData: str :return: bool

 sortNodesAsDAG()

Sort the CompNode list of the graph to order them as a DAG. The member mCompNodes is updated.

Returns:the sorted node list. 
 write(aSBSWriter, aXmlNode)

Write recursively the content of the SBSObject into the given xml node.

Parameters:
  • aSBSWriter (SBSWriter) – the substance writer
  • aXmlNode (xml.etree.ElementTree) – the xml node to fill

Adobe, Inc.

Get help faster and easier

New user?

Quick links

View all your plans Manage your plans
View quick links
Hide quick links

Legal Notices    |    Online Privacy Policy