User Guide Cancel

mdlgraph | Substance 3D Automation ToolKit

Search
Substance 3D Automation Toolkit

Substance 3D Automation Toolkit

Open app
  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

mdlgraph

Module mdlgraph aims to define SBSObjects that are relative to a MDL graph, mostly MDLGraph and MDLInput.

 class mdl.mdlgraph.MDLGraph(aIdentifier='', aUID='', aAttributes=None, aAnnotations=None, aParamInputs=None, aNodes=None, aGUIObjects=None, aRoot='0', aMetaDataTree=None)

Bases: pysbs.common_interfaces.sbsobject.SBSObject, pysbs.common_interfaces.basegraph.BaseGraph, mdl.mdlcommon.MDLObjectWithAnnotations, pysbs.common_interfaces.metadata.SBSMetaDataObject

Class that contains information on a MDL 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
  • mAnnotations (list of MDLAnnotation): list of annotations.
  • mParamInputs (list of MDLInput): list of exposed parameters of the graph.
  • mNodes (list of MDLNode): the list of MDL node of the graph.
  • mGUIObjects (list of SBSGUIObject, optional): list of GUI specific objects (comments, …).
  • mRoot (str, optional): UID of the root node of the graph (the output) 
 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 
 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 (MDLNode or str) – Node to connect from, as a MDLNode or as a UID
  • aRightNode (MDLNode or str) – Node to connect to, as a MDLNode or as a UID
  • aLeftNodeOutput (str, optional) – Identifier of the output of the left node
  • aRightNodeInput (str, optional) – Identifier of the input of the right node
Returns:

The connection as a SBSConnection 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 (MDLNode 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 
 copyNode(aNode)

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

Parameters:aNode (MDLNode) – the node to copy
Returns:The new MDLNode object 
 createComment(aCommentText='Comment', aGUIPos=None)

Create a new comment.

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

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

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

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

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

 
 createMDLNodeConst(aConstTypePath, aName = None, aValue = None, aParameters = None, aExposed = False, aTypeModifier = mdlenum.MDLTypeModifierEnum, aGUIPos = None)

Create a new MDL node constant and add it to the node list of the graph.

Parameters:
  • aConstTypePath (str) – mdl path of the type of constant to create
  • aName (str, optional) – name of the constant
  • aValue (any type, optional) – value of the constant to set, in case of a simple constant type
  • aParameters (dictionary in the format {paramPath(str),paramValue(any type)}, optional) – parameters to set, allowing to set sub members of more complex constant type
  • aAnnotations (dictionary in the format {annotation(MDLAnnotationEnum),annotationValue(str)}, optional) – annotations of the mdl constant
  • aExposed (bool, optional) – defines if the constant must be exposed as an input parameter. Default to False
  • aTypeModifier (MDLTypeModifierEnum, optional) – type modifier associated to the constant output. Default to MDLTypeModifierEnum.AUTO
  • 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 MDLNode object

 
 createMDLNodeInstance(aPath, aParameters = None, aGUIPos = None)

Create a new native MDL node instance and add it to the node list of the graph.

Parameters:
  • aPath (str) – mdl path of the instance to create
  • aParameters (dictionary of parameters to set, in the format {paramPath(str),paramValue(any type)}, optional) – parameters of the instance to set
  • 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 MDLNode object

 
 createMDLNodeMDLGraphInstance(aSBSDocument, aGraph, aParameters = None, aGUIPos = None)

Create a new instance of the given MDL Graph, and add it to the node list of the current graph.

Note:
Parameters:
  • aSBSDocument (SBSDocument) – current edited document
  • aGraph (MDLGraph) – graph that will be referenced by the instance node
  • aParameters (dictionary of parameters to set, in the format {paramPath(str),paramValue(any type)}, optional) – parameters of the filter node
  • 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 MDLNode object
Raise:

api_exceptions.SBSImpossibleActionError

 
 createMDLNodeMDLGraphInstanceFromPath(aSBSDocument, aPath, aParameters = None, aGUIPos = None)

Create a new instance of the MDL Graph pointed by the given path, and add it to the node list of the graph.

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

    path of the MDL graph definition (absolute, relative to the current .sbs file, or given with an alias, for instance myalias:/myMdlFile.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.
  • aParameters (dictionary of parameters to set, in the format {paramPath(str),paramValue(any type)}, optional) – parameters of the instance to set
  • 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 MDLNode object

 
 createMDLNodeOutput(aParameters = None, aGUIPos = None)

Create a MDL Node instance of mdl::material and set it as the output of the graph

Parameters:
  • aParameters (dictionary of parameters to set, in the format {paramPath(str),paramValue(any type)}, optional) – parameters of the instance to set
  • aGUIPos (list of 3 float, optional) – position of the node in the graph: [x,y,z]. default value is [0,0,0]
Returns:

 
 createMDLNodePassThrough(aConstTypePath, aName = None, aTypeModifier = mdlenum.MDLTypeModifierEnum, aGUIPos = None)

Create a new MDL node passthrough (dot) and add it to the node list of the graph.

Parameters:
  • aName (str, optional) – name of the constant
  • aParameters – parameters to set, allowing to set sub members of more complex constant type
  • aTypeModifier (MDLTypeModifierEnum, optional) – type modifier associated to the constant output. Default to MDLTypeModifierEnum.AUTO
  • 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 MDLNode object

 
 createMDLNodeSBSGraphInstance(aSBSDocument, aGraph, aParameters = None, aGUIPos = None)

Create a new instance of the given Substance Graph, and add it to the node list of the current graph.

Note:
Parameters:
  • aSBSDocument (SBSDocument) – current edited document
  • aGraph (SBSGraph) – Substance graph that will be referenced by the instance node
  • aParameters (dictionary of parameters to set, in the format {paramPath(str),paramValue(any type)}, optional) – parameters of the filter node
  • 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 MDLNode object
Raise:

api_exceptions.SBSImpossibleActionError

 
 createMDLNodeSBSGraphInstanceFromPath(aSBSDocument, aPath, aParameters = None, aGUIPos = None)

Create a new instance of the Substance Graph pointed by the given path, and add it to the node list of the graph.

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

    path of the Substance graph definition (absolute, relative to the current .sbs file, or given with an alias, for instance myalias:/myMdlFile.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.
  • aParameters (dictionary of parameters to set, in the format {paramPath(str),paramValue(any type)}, optional) – parameters of the instance to set
  • 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 MDLNode object

 
 createMDLNodeSelector(aConnectToNode = None, aOutput = None, aMember = None, aGUIPos = None)

Create a new MDL node constant and add it to the node list of the graph.

Parameters:
  • aConnectToNode (MDLNode or str, optional) – the mdl node to connect to, as a MDLNode or a uid
  • aOutput (str, optional) – the output identifier of the node to connect to. Can be None if the node to connect to has only one output
  • aMember (str, optional) – name of the member to select. Will be used only if a node to connect to is provided
  • 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 MDLNode object

 
 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

 
 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 (MDLNode or str) – The input parameter to remove, as a MDLNode or as an input identifier
  • aRemoveConstantNode (bool, optional) – True to remove the constant node associated to this input. False to only make this constant not exposed. Default to False
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 MDL node list, and delete all the connection from and to that node in the graph.

Parameters:aNode (MDLNode or str) – The node to remove, as a MDLNode or an UID.
Returns:True if success
Raise:api_exceptions.SBSImpossibleActionError 
 disconnectNodes(aLeftNode, aRightNode, aRightNodeInput = None)

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

Parameters:
  • aLeftNode (MDLNode or str) – Left node, as a MDLNode or a UID
  • aRightNode (MDLNode or str) – Right node, as a MDLNode or a UID
  • aRightNodeInput (str, optional) – Identifier of the input of the right node
Returns:

Nothing
Raise:

api_exceptions.SBSImpossibleActionError

 
 duplicateNode(aNode, aGUIOffset = None)

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

Parameters:
  • aNode (MDLNode 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 MDLNode 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 MDL graph

Returns:a list of UIDs as strings 
 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 
 getAllInputIdentifiers()

Get the list of all input identifiers

Returns:the list of identifiers as strings 
 getAllInputs()

Get the list of all nodes that has been exposed as input parameters (images and variables) of this graph

Returns:a list of MDLNode 
 getAllInputsInGroup(aGroup)

Get the list of all input nodes (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 (can be ‘group/subgroup/subsubgroup’)
Returns:a list of MDLNode 
 getAllMDLConstants()

Search for all MDLNode which are constants (MDLImplConstant implementation).

Returns:a list of MDLNode that are constants. 
 getAllMDLConstantsOfType(aType)

Search for all MDLNode which are constants (MDLImplConstant implementation) of the given type.

Parameters:aType (str) – the type of constant to search
Returns:a list of MDLNode that are constants of the given type. 
 getAllMDLConstantsWithName(aName)

Search for all MDLNode which are constants (MDLImplConstant implementation) with the given name.

Parameters:aName (str) – the constant name to search
Returns:a list of MDLNode that are constants with the given name. 
 getAllMDLGraphInstances()

Search for all MDLNode which are instances of a MDL graph (MDLImplMDLGraphInstance implementation).

Returns:a list of MDLNode that are instances of a MDL graph. 
 getAllMDLGraphInstancesOf(aSBSDocument, aPath)

Search for all MDLNode with a MDLImplMDLGraphInstance implementation, which reference the given MDL 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 MDLNode that are instances of the given MDL graph.

 
 getAllMDLInstances()

Search for all MDLNode which are instances of a native MDL function/material (MDLImplMDLInstance implementation).

Returns:a list of MDLNode that are native MDL instances. 
 getAllMDLInstancesOf(aPath)

Search for all MDLNode which are instances of the given MDL function/material (MDLImplMDLInstance implementation), given its path.

Parameters:aPath (str) – the MDL path to search
Returns:a list of MDLNode that are MDL instances of the given MDL function/material. 
 getAllMDLSelectors()

Search for all MDLNode which are selectors (MDLImplSelector implementation).

Returns:a list of MDLNode that are selectors. 
 getAllMDLSelectorsOfType(aType)

Search for all MDLNode which are selectors (MDLImplSelector implementation) of the given type.

Parameters:aType (str) – the selected member type to search
Returns:a list of MDLNode that are selectors of the given type. 
 getAllMDLSelectorsWithName(aName)

Search for all MDLNode which are selectors (MDLImplSelector implementation) of the given member name.

Parameters:aName (str) – the selected member name to search
Returns:a list of MDLNode that are selectors of the given member name. 
 getAllMetaData()

Get all MetaData under dictionary form.

Returns:dict 
 getAllNavigationPins()

Get all the navigation pins defined in the graph

Returns:a list of SBSGUIObject 
 getAllReferencesOnDependency(aDependency)

Get all the MDLNode that are referencing the given dependency

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

Get all the MDLNode 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 MDLNode 
 getAllResourcesUsed()

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

Returns:the list of resources used in this graph as a list of paths relative to the package (pkg:///…) 
 getAllSBSInstances()

Search for all MDLNode which are an instance of a Substance graph (MDLImplSBSInstance implementation).

Returns:a list of MDLNode that are instances of a Substance graph. 
 getAllSBSInstancesOf(aSBSDocument, aPath)

Search for all MDLNode with a MDLImplSBSInstance implementation, which reference the given Substance 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 MDLNode that are instances of the given Substance graph.

 
 getAllowedAttributes()

Get the attributes allowed on a MDLGraph

Returns:the list of attribute enumeration allowed (AttributesEnum) 
 getAnnotation(aAnnotation)

Get the given annotation.

Parameters:aAnnotation (MDLAnnotationEnum or str) – The annotation to look for, as an enumeration or a mdl path
Returns:The annotation as a MDLAnnotation 
 getAnnotationValue(aAnnotation)

Get the value of the given annotation.

Parameters:aAnnotation (MDLAnnotationEnum or str) – The annotation to look for, as an enumeration or a mdl path
Returns:The annotation value as a string or list of string if found, None otherwise 
 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 (MDLNode or str) – The node to consider, as a MDLNode 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 (MDLNode or str) – the node to consider, as a MDLNode or given its uid
  • aLeftNodeOutput (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 (MDLNode or str) – the node to consider, as a MDLNode or given its uid
  • aRightNodeInput (str, optional) – the pin input identifier to consider. If let None, all the inputs will be considered
Returns:

a list of SBSConnection

 
 getFirstInputOfType(aType)

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

Parameters:aType (str) – The required type
Returns:a MDLNode object if found, None otherwise 
 getGraphOutput()

Get the graph output node (root node)

Returns:a MDLNode object if found, None otherwise 
 getGraphOutputNode()

Get the graph output node (root node)

Returns:a MDLNode object if found, None otherwise 
 getGraphOutputType()

Get the graph output type

Returns:the output type as a string if defined, None otherwise 
 getGroup()

Get the ‘in_group’ annotation value

Returns:The group/subgroup/subsubgroup value if found, None otherwise 
 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 input MDLNode with the given identifier, among the input images and input parameters

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

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

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

Get the input image with the given identifier

Parameters:aInputImageIdentifier (str) – input image identifier
Returns:a MDLNode if found, None otherwise 
 getInputImageWithUsage(aUsage)

Get the first input image which has the given usage defined (can be an enum value or a custom string)

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

Get the list of input MDLNode of kind image (e.g. texture_2D node)

Returns:a list of MDLNode 
 getInputIndex(aInput)

Get the index of the given input, among the list of MDLInput in this graph.

Parameters:aInput (MDLNode or str) – input to search, as a MDLNode or a identifier
Returns:the index of the input as an integer if found, -1 otherwise 
 getInputParameter(aInputIdentifier)

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

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

Get the MDLInput with the given UID

Parameters:aInputParamUID (str) – input parameter UID
Returns:the corresponding MDLInput object if found, None otherwise 
 getInputParameters()

Get the list of inputs parameters that are not input images

Returns:a list of MDLInput 
 getInputWithUsage(aUsage)

Get the first input which has the given usage defined (can be an enum value or a custom string)

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

Get the MDLInput pointing to the given node uid

Parameters:aUID (str) – The node uid to look for
Returns:a MDLInput object 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 (MDLNode or str) – node to get, identified by its uid or as a MDLNode
Returns:A MDLNode object if found, None otherwise 
 getNodeList(aNodesList = None)

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

Parameters:aNodesList (list of str or list of MDLNode, optional) – list of node to look for
Returns:a list of MDLNode 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 (MDLNode or str) – the node to consider
  • aLeftNodeOutput (str, optional) – the output identifier to take in account
Returns:

a list of MDLNode

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

a list of MDLNode

 
 getNodesDockedTo(aNode)

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

Parameters:aNode (MDLNode) – the node to consider
Returns:a list of MDLNode 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 SBSNode 
 getRect(aNodeList = None)

Get all the GUI rectangle of this graph, or look for the given nodes if aNodeList is not None

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

Get the ‘sampler_usage’ annotation value

Returns:The ‘sampler_usage’ value if found, None otherwise 
 hasUsage(aUsage)

Check if the given usage is defined on this constant node

Parameters:aUsage (str or UsageEnum) – The usage to look for (can be an enum value or a custom string)
Returns:True if the given usage is defined on this param input, False otherwise 
 isAPathBetween(self, aLeftNode, aRightNode)

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

Parameters:
  • aLeftNode (MDLNode or str) – The left node
  • aRightNode (MDLNode or str) – The right node
Returns:

True if a path is found, 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 (MDLNode or str) – the node initially connected, as an object or given its uid
  • aTargetNode (MDLNode or str) – the target node, which should be connected after this function, as an object or given its uid
  • aInitialNodeInput (str, optional) – the identifier of the input initially connected in aInitialNode. If None, the first input will be considered
  • aTargetNodeInput (str, optional) – the identifier of the input targeted on aTargetNode. If None, the first input will be considered
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 (MDLNode or str) – the node initially connected, as an object or given its uid
  • aTargetNode (MDLNode or str) – the target node, which should be connected after this function, as an object or given its uid
  • aInitialNodeOutput (str, optional) – the identifier of the output initially connected in aInitialNode. If None, the first output will be considered
  • aTargetNodeOutput (str, optional) – the identifier of the output targeted on aTargetNode. If None, the first output will be considered
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:.MDLNode) – The nodes to include in the frame
Raise:

SBSImpossibleActionError

 
 removeAnnotation(aAnnotation)

Remove the given annotation from the list of annotations

Parameters:aAnnotation (MDLAnnotationEnum or str) – The annotation to look for, as an enumeration or a mdl path 
 setAnnotation(aAnnotation, aAnnotationValue)

Set the given attribute

Parameters:
  • aAnnotation (MDLAnnotationEnum) – The annotation to set, as an enumeration or a mdl path
  • aAnnotationValue (str or list of str) – The value to set
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 
 setConstantAsInputParameter(aMDLNode)

Set the given MDLNode with a MDLImplConstant implementation as an input parameter of the graph

Parameters:aMDLNode (MDLNode or str) – The constant node to expose, as a MDLNode object or given its uid
Raise:SBSImpossibleActionError 
 setGroup(aGroup, aSubGroup=None, aSubSubGroup=None)

Set the ‘in_group’ annotation value with the given group and subgroups

Parameters:
  • aGroup (str) – The main group
  • aSubGroup (str, optional) – The sub-group
  • aSubSubGroup (str, optional) – The sub-sub-group 
 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 
 setInputIndex(aInput, aIndex)

Set the index of the given input.

Parameters:
  • aInput (MDLNode or str) – input to search, as a MDLNode or a identifier
  • aIndex (int) – index to set, in the range [0 ; nbInputs[
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: 
 setOutputNode(aMDLNode)

Set the given node as the output node of the graph

Parameters:aMDLNode (MDLNode or str) – the MDLNode, which must be a material
Raise:SBSImpossibleActionError in case the node is not found in the graph or if it is not a material 
 setUsage(aUsage)

Set the ‘sampler_usage’ annotation value with the given usage

Parameters:aUsage (str) – The usage to set 
 sortNodesAsDAG()

Sort the MDL node list of the graph to order them as a DAG. The member mNodes 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 
 class mdl.mdlgraph.MDLInput(aNodeUID='')

Bases: pysbs.common_interfaces.sbsobject.SBSObject

Class that contains the uid of an MDL input as saved in a .sbs file

Members:
  • mNodeUID (str): UID of the MDL Node corresponding to this input 
 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. 
 getUidIsUsed(aUID)

Check if the given uid is already used in the context of this SBSObject.

Parameters:aUID (str) – UID to check
Returns:True if the uid is already used, False otherwise
Raise:AttributeError if the function getUidIsUsed in not properly overloaded on this SBSObject 
 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 
 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

Get help faster and easier

New user?

Quick links

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

Legal Notices    |    Online Privacy Policy