- Substance 3D home
- Home
- Command Line Tools
- Command Line overview
- sbsbaker
- sbscooker
- sbsmtools
- sbsmutator
- sbsrender
- sbsupdater
- Command Line overview
- Pysbs - Python API
- Pysbs - Python API overview
- Getting started
- General topics
- Examples
- API Content
- API Content overview
- Substance definitions
- Common interfaces
- compnode
- context projectmgr
- graph
- mdl
- modelgraphindex
- modelannotationnames
- modelgraph
- modelgraphgenerator
- modelgraphimplementation
- modelnodenames
- modeloperand
- modulegraphindex
- moduleannotation
- moduleconnection
- modulegraph
- modulegraphgenerator
- modulegraphimplementation
- modulegraphlibrary
- modulegraphregister
- modulenode
- modulenodeimplementation
- modulenodeinstance
- moduleoperand
- moduleoutputbridging
- moduleparaminput
- params
- projectmgrdoc
- sbsarchive
- sbscommon
- sbspreset
- sbsproject
- substance
- Libraries
- sbsenum
- sbslibrary
- sbsbakerslibrary
- Helpers
- Execution context
- API Change log
- Samples
- Setup and Getting Started
- Integrations
- Substance Maya toolset
- Changelog overview
function
Module function provides the definition of the class SBSFunction
: which allows to define a function graph.
class graph.function.SBSFunction(aIdentifier='', aUID='', aAttributes=None, aParamInputs=None, aType='', aParamValue=None)
Bases: pysbs.common_interfaces.sbsobject.SBSObject
Class that contains information on a function as defined in a .sbs file
- Members:
- mIdentifier (str): name of the function definition.
- mUID (str): unique identifier in the package/ context.
- mAttributes (
SBSAttributes
): various attributes - mParamInputs (list of
SBSParamInput
, optional): list of parameters inputs of the function. - mType (str): type of the function return.
- mParamValue (
SBSParamValue
): definition of the function.
addInputParameter(aIdentifier, aWidget, 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 function.
Parameters: |
|
---|---|
Returns: | The created |
computeUniqueInputIdentifier(aIdentifier, aSuffixId = 0)
Check if the given identifier is already used in the function 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 |
---|
connectNodes(aLeftNode, aRightNode, aRightNodeInput = sbsenum.FunctionInputEnum.VALUE)
Connect the given nodes together: aLeftNode -> aRightNode(on the input aRightNodeInputIdentifier)
Parameters: |
|
---|---|
Returns: | The connection if success, None otherwise (in case of type incompatibility for instance) |
Raise: |
|
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 |
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: |
|
---|---|
Returns: | The |
createFrame(aSize, aFrameTitle='Frame', aCommentText='', aGUIPos=None, aColor=None, aDisplayTitle=True)
Create a new framed comment.
Parameters: |
|
---|---|
Returns: | The |
createFrameAroundNodes(aNodeList, aFrameTitle='Frame', aCommentText='', aColor=None, aDisplayTitle=True)
Create a new framed comment around the given nodes.
Parameters: |
|
---|---|
Returns: | The |
Raise: |
|
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: |
|
---|---|
Returns: | The new |
createFunctionInstanceNodeFromPath(aSBSDocument, aPath, aGUIPos = None)
Create a new function node of kind ‘instance’ which references the function pointed by the given path.
Parameters: |
|
---|---|
Returns: | The new |
createFunctionNode(aFunction, aGUIPos = None, aParameters = None)
Create a new function node and add it to the ParamNodes of the function.
Parameters: |
|
---|---|
Returns: | The new |
createIterationOnPattern(aNbIteration, aNodeUIDs, aNodeUIDs_NextPatternInput = None, aGUIOffset = None)
Duplicate NbIteration times the given pattern of function 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 (float / integer / …)
Parameters: |
|
---|---|
Returns: | The list of |
Raise: |
|
createNavigationPin(self, aPinText, aGUIPos)
Create a new navigation pin.
Parameters: |
|
---|---|
Returns: | The |
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.
Parameters: | aInputParameter (SBSParamInput or str) – The input parameter to remove. |
---|---|
Returns: | True if success |
Raise: | api_exceptions.SBSImpossibleActionError |
deleteNode(aNode)
Allows to delete the given node from the function 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: |
|
---|---|
Returns: | Nothing |
Raise: |
|
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.
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 |
---|
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: |
|
---|---|
Returns: | a list of |
getAllReferencesOnDependency(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 |
getAllowedAttributes()
Get the attributes allowed on a SBSFunction
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 |
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 SBSParamNode 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: |
|
---|---|
Returns: | a list of |
getDynamicValue()
Get the function definition
Returns: | The SBSDynamicValue object that defines this function |
---|
getInputParameter(aInputParamIdentifier)
Get the SBSParamInput definition associated to the given identifier
Parameters: | aInputParamIdentifier (str) – input parameter identifier |
---|---|
Returns: | the corresponding SBSParamInput object if found, None otherwise |
getInputParameterIndex(aInputParamIdentifier)
Get the index of the given input parameter
Parameters: | aInputParamIdentifier (str) – input parameter identifier |
---|---|
Returns: | the index of the input entry as an integer if found, -1 otherwise |
getInputParameters()
Get the list of inputs parameters
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 |
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 the 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: |
|
---|---|
Returns: | a list of |
getNodesDockedTo(aNode)
Get all the nodes that are docked to the given node.
Parameters: | aNode (SBSParamNode ) – 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 object corresponding to the output node if defined, None otherwise. |
---|
getOutputType()
Get the output type of the function. The output type can be VOID_TYPE or FUNCTION_ALL if the output node is not set.
Returns: | The output type, as a ParamTypeEnum . |
---|
getRect(aNodeList = None)
Get the rectangle occupied by all the nodes of this function graph, 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)
Check if the given uid is already used in the context of the function
Parameters: | aUID (str) – UID ti check |
---|---|
Returns: | True if the uid is already used, False otherwise |
initFunction()
Init the function with default value
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 |
Raise: |
|
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: |
|
---|---|
Returns: |
|
Raise: |
|
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: |
|
---|---|
Returns: |
|
Raise: |
|
parse(aContext, aDirAbsPath, aSBSParser, aXmlNode)
Parse recursively the given xml node to retrieve the content of the SBSObject.
reframeAroundNodes(aFrame, aNodeList)
Move and resize a frame to be around the given nodes.
Parameters: |
|
---|---|
Raise: | SBSImpossibleActionError |
setAttribute(aAttributeIdentifier, aAttributeValue)
Set the given attribute
Parameters: |
|
---|
setInputParameterIndex(aInputParamIdentifier, aIndex)
Set the index of the given input parameter
Parameters: |
|
---|---|
Raise: |
|
setOutputNode(aNode)
Set the output node of the function. This may change the type of the function
Parameters: | aNode (SBSParamNode or str) – The node to set as output, as an object or identified by its UID |
---|
sortNodesAsDAG()
Sort the ParamNode list of the function to order them as a DAG. The member mParamNodes of the DynamicValue is updated.
Returns: | the sorted node list. |
---|---|
Raise: | api_exceptions.SBSImpossibleActionError |
write(aSBSWriter, aXmlNode)
Write recursively the content of the SBSObject into the given xml node.
Parameters: |
|
---|