dynamicvalue module

Module dynamicvalue provides the definition of the class SBSDynamicValue: which allows to represent all the function graph in Substance Designer: - A function graph - A function defining the value of a dynamic parameter - The Pixel processor function

class params.dynamicvalue.SBSDynamicValue(aGUILayoutParam=None, aRootNode=None, aParamNodes=None, aGUIObjects=None, aOptions=None, aValueProcessorRef=None)

Bases: SBSObject

Class that contains information on a dynamic value as defined in a .sbs file. A dynamic value allows to define a function, for a dynamic parameter, a pixel processor or a function graph.

Members:

mGUILayoutParam (SBSGUILayoutComp): GUI flags and options.
mRootNode (str, optional): uid of the output node of the function.
mParamNodes (list of SBSParamNode): function nodes list.
mGUIObjects (list of SBSGUIObject): GUI specific objects.
mOptions (list of SBSOption): list of specific options.
mValueProcessorRef (weakref): Weak Reference to a value processor to keep output type in sync or None

connectNodes(aLeftNode, aRightNode, aRightNodeInput=None)

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

Parameters:

aLeftNode (SBSParamNode or str) – Node to connect from, as a SBSParamNode or given its UID
aRightNode (SBSParamNode or str) – Node to connect to, as a SBSParamNode or given its UID
aRightNodeInput (FunctionInputEnum 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 function graph

Parameters:: aNode (SBSParamNode 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

copy()

Get deep copy of this SBSDynamicValue

Returns:: A SBSDynamicValue object, identical to this object

copyNode(aCompNode)

Create a copy of the given node and generate a new uid for it

Parameters:: aCompNode (SBSParamNode) – the node to copy
Returns:: The new SBSParamNode 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 (SBSParamNode or str, optional) – The node to associate to this comment, as a SBSParamNode or given its UID

Returns:

The SBSGUIObject created

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:.SBSParamNode) – 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

createFunctionInstanceNode(aSBSDocument, aFunction, aGUIPos=None)

Create a new function node of kind ‘instance’ which references the given function.

Note:

The function must be defined in the given SBSDocument.
Use createFunctionInstanceNodeFromPath() to add an instance of a function included in an external package.

Parameters:

aSBSDocument (SBSDocument) – current edited document
aFunction (SBSFunction) – Function of which this node will be an instance of
aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]

Returns:

The new SBSParamNode object

Raise:

api_exceptions.SBSImpossibleActionError

createFunctionInstanceNodeFromPath(aSBSDocument, aPath, aGUIPos=None)

Create a new function node of kind ‘instance’ which references the function pointed by the given path.

Parameters:

aSBSDocument (SBSDocument) – current edited document
aPath (str) –
path of the function definition (absolute, relative to the current .sbs file, or given with an alias, for instance sbs://functions.sbs/Functions/Math/Pi)
- If the function is included in the current package, use: pkg:///MyFunctionIdentifier
- If the path uses an alias, use: myalias://MyFileName.sbs/MyFunctionIdentifier
- If the path is relative to the current package or absolute, use MyAbsoluteOrRelativePath/MyFileName.sbs/MyFunctionIdentifier
- Note that if the function identifier is equivalent to the filename, the part /MyFunctionIdentifier 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]

Returns:

The new SBSParamNode object

Raise:

api_exceptions.SBSImpossibleActionError

createFunctionNode(aFunction, aGUIPos=None, aParameters=None)

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

Parameters:

aFunction (FunctionEnum or str) – kind of function to create, among the list defined in FunctionEnum
aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
aParameters (dictionary {sbsenum.FunctionEnum : parameterValue(str)}, optional) – parameters of the function node

Returns:

The new SBSParamNode object

createIterationOnNode(aNbIteration, aNodeUID, aGUIOffset=None)

Duplicate NbIteration times the given node, and connect each created node to the previous one

Parameters:

aNbIteration (positive integer) – number of time the pattern must be duplicated
aNodeUID (str) – list of node’s UID that constitute the pattern to duplicate
aGUIOffset (list of 2 float, optional) – pattern position offset. Default to [150, 0]

Returns:

The last SBSParamNode object created

createIterationOnPattern(aNbIteration, aNodeUIDs, aNodeUIDs_NextPatternInput=None, aGUIOffset=None)

Duplicate NbIteration times the given pattern of parameters nodes, and connect each pattern with the previous one.
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) – list of node’s UID that correspond to the next pattern, which must be connected to the given pattern.
aGUIOffset (list of 2 float) – pattern position offset. Default to [150, 0]

Returns:

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

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

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

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 ParamNode list, and delete all the connection from and to that node in the function graph.

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

disconnectNodes(self, aLeftNode, aRightNode, aRightNodeInput=None)

Disconnect the given nodes: aLeftNode -> aRightNode(on the input aRightNodeInputIdentifier). If the right node input is None, all connections will be removed.

Parameters:

aLeftNode (SBSParamNode or str) – Left node, as a SBSParamNode or given its UID
aRightNode (SBSParamNode or str) – Right node, as a SBSParamNode or given its UID
aRightNodeInput (FunctionInputEnum 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 (SBSParamNode or str) – the node to duplicate
aGUIOffset (list of 2 float, optional) – the offset to apply in the positioning of the new node. Default to [150, 0]

Returns:

The new SBSParamNode 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.

getAllComments()

Get all comments defined in the graph

Returns:: a list of SBSGUIObject

getAllDependencyUID()

Get the UIDs of the dependencies used by this dynamic function

Returns:: a list of UIDs as strings

getAllFrames()

Get all frames defined in the graph

Returns:: a list of SBSGUIObject

getAllFunctionsOfKind(aFunction)

Search for all SBSParamNode which represents the given filter kind.

Parameters:: aFunction (FunctionEnum str) – kind of filters to look for
Returns:: a list of SBSParamNode containing all functions of the given kind.

getAllGUIObjects()

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

Returns:: a list of SBSGUIObject

getAllNavigationPins()

Get all the navigation pins defined in the graph

Returns:: a list of SBSGUIObject

getAllNodeInstancesOf(aSBSDocument, aPath)

Search for all SBSParamNode of kind ‘instance’, which reference the given function path.

Parameters:

aSBSDocument (SBSDocument) – current SBSDocument
aPath (str) –
path of the function definition (absolute, relative to the current .sbs file, or given with an alias, for instance sbs://functions.sbs/Functions/Math/Pi)
- If the function is included in the current package, use: pkg:///MyFunctionIdentifier
- If the path uses an alias, use: myalias://MyFileName.sbs/MyFunctionIdentifier
- If the path is relative to the current package or absolute, use MyAbsoluteOrRelativePath/MyFileName.sbs/MyFunctionIdentifier
- Note that if the function identifier is equivalent to the filename, the part /MyFunctionIdentifier may be omit.

Returns:

a list of SBSParamNode containing all instance nodes of the given function.

getAllReferencesOnDependency(self, (aDependency)

Get all the SBSParamNode that are referencing the given dependency

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

getCommentsAssociatedToNode(aNode)

Get the list of comments associated to the given node

Parameters:: aNode (SBSParamNode or str) – The node to consider, as a SBSParamNode or given its UID
Returns:: a list of SBSGUIObject

getConnectionsFromNode(self, aLeftNode)

Get the connections starting from the output of the given left node.

Parameters:: aLeftNode (SBSParamNode or str) – the node to consider, as a SBSCompNode or given its uid
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

getNode(aNode)

Search for the given function node in the node list

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

getNodeAssociatedToComment(aComment)

Get the node associated to the given comment.

Parameters:: aComment (SBSGUIObject) – The comment to consider
Returns:: the SBSParamNode if found, None otherwise

getNodeList(aNodesList=None)

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

Parameters:: aNodesList (list of str or list of SBSParamNode, optional) – list of node to look for
Returns:: a list of SBSParamNode included in the function graph

getNodesConnectedFrom(aLeftNode)

Get all the nodes connected to an output of the given node.

Parameters:: aLeftNode (SBSParamNode or str) – the node to consider
Returns:: a list of SBSParamNode

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 (SBSParamNode or str) – the node to consider, as an object or given its uid
aRightNodeInput (FunctionInputEnum or str, optional) – the input to take in account

Returns:

a list of SBSParamNode

getNodesDockedTo(aNode)

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

Parameters:: aNode (SBSParamNode or str) – the node to consider
Returns:: a list of SBSParamNode 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 function, otherwise SBSImpossibleActionError is raised

Parameters:: aFrame (SBSGUIObject) – The frame to consider
Returns:: a list of SBSParamNode

getOutputNode()

Get the output node of the function.

Returns:: The SBSParamNode corresponding to the output node, None if there is no output node

getOutputType()

Get the type of output node of the function.

Returns:: The type to the output node, in the format ParamTypeEnum. VOID_TYPE if there is no output node

getRect(aNodeList=None)

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

Parameters:: aNodeList (list of str or list of SBSParamNode, 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

getUidIsUsed(aUID)

Parse the node list to find a node with the given uid

Parameters:: aUID (str) – UID to check
Returns:: True if a node has this uid

getUsedParameters(aParameters)

Get all the input parameters used in the this dynamic value among the given list, meaning the ones that are get by the function.

Parameters:: aParameters (list of SBSParamInput) – the input parameters to look for
Returns:: the list of useless SBSParamInput

isAPathBetween(self, aLeftNode, aRightNode)

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

Parameters:

aLeftNode (SBSParamNode or str) – The left node
aRightNode (SBSParamNode or str) – The right node

Returns:

True if a path is found, False otherwise

moveConnectionOnPinInput(self, 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 (SBSParamNode or str) – the node initially connected, as an object or given its uid
aTargetNode (SBSParamNode or str) – the target node, which should be connected after this function, as an object or given its uid
aInitialNodeInput (FunctionInputEnum or str, optional) – the identifier of the input initially connected in aInitialNode. If None, the first input will be considered
aTargetNodeInput (FunctionInputEnum or str, optional) – the identifier of the input targeted on aTargetNode. If None, the first input will be considered

Returns:

Raise:

SBSImpossibleActionError

moveConnectionsOnPinOutput(self, aInitialNode, aTargetNode)

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

Parameters:

aInitialNode (SBSParamNode or str) – the node initially connected, as an object or given its uid
aTargetNode (SBSParamNode or str) – the target node, which should be connected after this function, as an object or given its uid

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:.SBSParamNode) – The nodes to include in the frame

Raise:

SBSImpossibleActionError

setOutputNode(aNode)

Set the output node of the function.

Parameters:: aNode (SBSParamNode or str) – the node to set as output, or its UID
Returns:: The SBSParamNode corresponding to the output node, False if not found
Raise:: api_exceptions.SBSImpossibleActionError

setToInputParam(aParentGraph, aInputParamIdentifier)

This function will be set to return the value of the given input parameter defined on the given graph

Parameters:

aParentGraph (SBSGraph) – graph in which the input parameter is defined.
aInputParamIdentifier (str) – input parameter identifier

Returns:

True if succeed

Raise:

api_exceptions.SBSImpossibleActionError

sortNodesAsDAG()

Sort the ParamNode list of the function to order them as a DAG. The member mParamNodes is updated.

Returns:: the sorted node list.

updateValueProcessorType()

Updates the value processor type so it represents what is in the dynamic value if there is one

Returns:: None

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