User Guide Cancel

function | Substance 3D Automation ToolKit

  1. Substance 3D home
  2. Home
  3. Command Line Tools
    1. Command Line overview
    2. sbsbaker
      1. sbsbaker overview
      2. sbsbaker command line options
      3. sbsbaker Example Command Lines
    3. sbscooker
      1. sbscooker overview
      2. sbscooker command line options
      3. sbscooker pattern variables
    4. sbsmtools
      1. sbsmtools overview
      2. sbsmtools command line options
    5. sbsmutator
      1. sbsmutator overview
      2. sbsmutator command line options
      3. sbsmutator Example Command Lines
    6. sbsrender
      1. sbsrender overview
      2. sbsrender base parameters and pattern variables
      3. sbsrender command line options
      4. sbsrender example command lines
    7. sbsupdater
      1. sbsupdater overview
      2. sbsupdater command line options
  4. Pysbs - Python API
    1. Pysbs - Python API overview
    2. Getting started
    3. General topics
      1. Basic manipulation
      2. Substance creation
      3. Substances modification
      4. Dependencies management
      5. PySbs batchtools module
      6. metadata manipulation
      7. SAT demos
      8. Edit sbsar with SBSARManager
      9. Spot Colors
      10. Thumbnail creation with SAT
    4. Examples
      1. demohelloworld
      2. demos
      3. demos_batchtools
      4. script_update_with_sbsupdater
    5. API Content
      1. API Content overview
      2. Substance definitions
        1. Common interfaces
          1. basegraph
          2. package
          3. sbsarobject
          4. sbsobject
        2. compnode
          1. compnode overview
          2. common
          3. compimplementation
          4. paramgraph
        3. context projectmgr
        4. graph
          1. graph overview
          2. function
          3. inputparameters
          4. output
        5. mdl
          1. mdlannotation
          2. mdlcommon
          3. mdldictionaries
          4. mdlenum
          5. mdlgraph
          6. mdllibclasses
          7. mdlmanager
          8. mdlnode
          9. mdlnodeimpl
          10. mdloperand
          11. mdlsbsbridge
        6. modelgraphindex
          1. modelannotationnames
          2. modelgraph
          3. modelgraphgenerator
          4. modelgraphimplementation
          5. modelnodenames
          6. modeloperand
          7. modulegraphindex
          8. moduleannotation
          9. moduleconnection
          10. modulegraph
          11. modulegraphgenerator
          12. modulegraphimplementation
          13. modulegraphlibrary
          14. modulegraphregister
          15. modulenode
          16. modulenodeimplementation
          17. modulenodeinstance
          18. moduleoperand
          19. moduleoutputbridging
          20. moduleparaminput
        7. params
          1. params overview
          2. dynamicvalue
          3. paramnode
        8. projectmgrdoc
        9. sbsarchive
          1. sbsarchive overview
          2. sbsarenum
          3. sbsargraph
          4. sbsargui
          5. sbsarguiwidgets
          6. sbsarmanager
        10. sbscommon
          1. connections
          2. gui
          3. nodes
          4. values
        11. sbspreset
        12. sbsproject
        13. substance
          1. substance overview
          2. content
          3. resource
      3. Libraries
        1. sbsenum
        2. sbslibrary
          1. sbslibrary overview
          2. sbsdictionaries
          3. sbsfilters
          4. sbsfunctions
          5. sbsfxmapnodes
          6. sbslibclasses
          7. sbswidgets
        3. sbsbakerslibrary
          1. sbsbakerslibrary overview
          2. sbsbakersdef
          3. sbsbakersdefaultprops
          4. sbsbakersdictionaries
          5. sbsbakersenum
          6. sbsbakingconverter
          7. sbsbakingconverterparam
          8. sbsbakingparameters
          9. sbsdialogstate
          10. sbsscenedata
        4. Helpers
          1. sbscleaner
          2. sbsexporter
          3. sbsgenerator
          4. sbsparser
          5. sbswriter
          6. qtclasses
            1. qtclasses overview
            2. qtvariantreader
            3. qtvariantwriter
          7. psdparser
          8. sbsimpactmanager
          9. batchtools
          10. autograph
            1. ag_functions
            2. ag_layout
            3. ag_types
          11. info_mesh_parser
          12. sbsbaker_info_handlers
          13. sbsrender_render_handlers
          14. output_handlers
          15. spotcolorinfo_handler
          16. thumbnail
          17. batchtools overview
        5. Execution context
          1. context
          2. functions
        6. API Change log
  5. Samples
    1. Samples overview
    2. Texturing Template Demo
    3. Batch Tools Demo
    4. Variations
    5. Texture Mat
    6. Pixel Processor Ray tracer
  6. Setup and Getting Started
    1. Setup and Getting Started overview
    2. Compatibility
    3. Frequently asked Questions
    4. Known issues
    5. SAT Cookbook
    6. Use Pysbs in different python interpreter (maya, sd, blender...)
  7. Integrations
    1. Substance Maya toolset
      1. Substance Maya Toolset overview
      2. Installing
      3. Launching
      4. Baking
        1. Baking overview
        2. Export parameters
        3. Baker parameters
        4. Mesh setup
        5. Using a template
      5. Changelog
  8. 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:
  • aIdentifier (str) – identifier of the input parameter. It may change to ensure having a unique identifier.
  • aWidget (WidgetEnum) – widget to use for this parameter
  • 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

 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:
  • 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
 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:
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

 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

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

Create a new function node and add it to the ParamNodes of the function.

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

 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:
  • 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 []
  • aGUIOffset (list of 2 float, optional) – pattern position offset. Default to [150, 0]
Returns:

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

Raise:

api_exceptions.SBSImpossibleActionError

 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
 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:
  • 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

 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 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:
  • 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(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:
  • aRightNode (SBSParamNode or str) – the node to consider, as a SBSParamNode or given its uid
  • aRightNodeInput (FunctionInputEnum or str, optional) – the pin input identifier to consider. If let None, all the inputs will be considered
Returns:

a list of SBSConnection

 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:
  • 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) – 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:

api_exceptions.SBSImpossibleActionError

 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
  • aTargetNodeInput (FunctionInputEnum or str, optional) – the identifier of the input targeted on aTargetNode
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
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:.SBSParamNode) – 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
 setInputParameterIndex(aInputParamIdentifier, aIndex)  

Set the index of the given input parameter

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

api_exceptions.SBSImpossibleActionError if failed

 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:
  • aSBSWriter (SBSWriter) – the substance writer
  • aXmlNode (xml.etree.ElementTree) – the xml node to fill

 Adobe

Get help faster and easier

New user?