graph module

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: SBSObject, Graph, 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(exposedOnly=False)

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

In Substance Designer, the values of the “Input Value” Node are not exposed to the graph public interface: - in the UI they belong to the “Inputs” panel and not the “Input Parameters” - when graph is used as an instance node: they are set through the subgraph node inputs and are not tweakable through the UI panel “Instance parameters” - when graph is published/cooked to SBSAR: they are kept internal and not exposed in the SBSAR’s input parameters In SAT, getInputParameters(exposedOnly=False) returns all the graph input numerical values (“Input Value” Nodes + exposed parameters), and getInputParameters(exposedOnly=True) returns only those considered as “Input Parameters” in the Substance Designer

Parameters:

exposedOnly (boolean) – option to filter only the parameters that are exposed to the graph public interface

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