User Guide Cancel

substance | 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

substance

Content included in substance module:

Module substance aims to define SBSObjects that are relative to a package, mostly SBSDocument, SBSContent and SBSResource.

 class substance.substance.FeatureVersionsOption(aName='', aValue='')

Bases: pysbs.common_interfaces.sbsobject.SBSObject

Members:
  • mName (str): feature name
  • mValue (str): value 
 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 
 class substance.substance.SBSDependency(aFilename='', aUID='', aType='', aFileUID='', aVersionUID='', aFileAbsPath=None)

Bases: pysbs.common_interfaces.sbsobject.SBSObject

Class that contains information on a package dependency as defined in a .sbs file

Members:
  • mFilename (str): name of the file.
  • mUID (str): unique identifier of this dependency in the package/ context (used as reference).
  • mType (str): type of dependency (fixed: package).
  • mFileUID (str): identifier of the file (package/header/fileUID).
  • mVersionUID (str): identifier of the current version of the file (package/header/versionUID). Used for changing repercussion purposes.
  • mFileAbsPath (str): file absolute path 
 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. 
 getRefPackage()

Get the reference to the SBSDocument pointed by this dependency

 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 
 isHimself()
Returns:True if the dependency references the document itself, False otherwise. 
 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 
 setRefPackage(aRefPackage)

Allows to set the reference to the SBSDocument pointed by this dependency

Parameters:aRefPackage (SBSDocument) – The package pointed by this dependency 
 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 substance.substance.SBSDocument(aContext, aFileAbsPath, aIdentifier='', aDescription=None, aFormatVersion='', aUpdaterVersion='', aFileUID='', aVersionUID='', aDependencies=None, aMetaDataTree=None, aContent=None, aFeatureVersions=None)

Bases: pysbs.common_interfaces.sbsobject.SBSObject, pysbs.common_interfaces.package.Package, pysbs.common_interfaces.metadata.SBSMetaDataObject

Class used to get information on a .sbs file. It contains the full description of a substance, which correspond to the root node of the .sbs file.

Members:
  • mIdentifier (str): unique string identifier
  • mDescription (str, optional): textual description
  • mFormatVersion (str): version number of the .sbs format of this file
  • mUpdaterVersion (str): version number of the .sbs format updater
  • mFileUID (str): unique identifier of this file (for buffering coherence). MS GUID-like format
  • mVersionUID (str): unique identifier of the current version of this file (different at each file save).
  • mDependencies (list of SBSDependency): list of external dependencies
  • mContent (SBSContent): content of the package, tree structure
  • mContext (Context): Execution context, with alias definition
  • mFileAbsPath (str): Absolute path of the package
  • mDirAbsPath (str): Absolute directory of the package
  • mFeatureVersions(FeatureVersionsOption) : handle features versions for internal use 
 addReferenceOnDependency(aDependencyPath, aRelPathToObject, outValues)

This function look for the given dependency and create it if it does not exists yet. In the case of a new dependency, parses the pointed package to resolve the dependency. Finally, look for the given object identified by its relative path inside the package. The return values are a tuple: (SBSObject (The pointed object), str (The resolved relative path))

Parameters:
  • aDependencyPath (str) – The path of the dependency
  • aRelPathToObject (str) – The path to the referenced object, relatively to its parent package
Returns:

Tuple (SBSObject (The pointed object), str (The resolved relative path))

 
 buildAbsPathFromRelToMePath(aRelPathFromPackage)

Build a path starting from the current package absolute directory and complete it with the given relative path

Parameters:aRelPathFromPackage (str) – The relative path from the current package
Returns:The complete path, as a string 
 changeDocumentPath(aNewFileAbsPath)

Modify the document absolute path and modify the relative paths of the referenced resources and dependencies. This function does not modify physically the location of the .sbs file on the disk, it just updates the content of the .sbs file considering a new location.

Parameters:aNewFileAbsPath (string) – The new location of the document. 
 convertToAbsolutePath(aPath)

Convert the given path into an absolute path.

Parameters:aPath (str) –

The path to convert to an absolute path.

  • If the path is relative to the current document, convert it to an absolute path
  • If the path contains an alias, convert it to an absolute path using the alias absolute path
  • If the path contains a reference to a dependency, use the absolute path of this dependency
  • If the path references an object contained in the current package (pkg:///ObjectIdentifier), use the current document absolute path
Returns:The absolute path corresponding to the given path, with ‘/’ separator 
 copyDependencyFromPackage(aPackage, aDependencyUID)

Copy the dependency with the given UID from the given package, and paste it in this package. This method calls declareDependencyUIDChanged() at the end in case this dependency was already referenced but was missing.

Parameters:
  • aPackage (SBSDocument) – The package where to find the dependency to copy
  • aDependencyUID (str) – The new dependency UID
Returns:

the copied dependency as a SBSDependency
Raise:

SBSImpossibleActionError in case the dependency is not found in the given package

 
 copyResourceFromPackage(aPackage, aResourceUID)

Copy the resource with the given UID from the given package, and paste it in this package. This method calls declareResourcePathChanged() at the end in case this resource was already referenced but was missing.

Parameters:
  • aPackage (SBSDocument) – The package where to find the dependency to copy
  • aResourceUID (str) – The new resource UID
Returns:

the copied dependency as a SBSResource
Raise:

SBSImpossibleActionError in case the resource is not found in the given package

 
 createDependency(aPath)

Create a new dependency to the given path.

Parameters:aPath (str) – the path (absolute, relative or with an alias) to the dependency
Returns:The SBSDependency object 
 createFunction(aFunctionIdentifier = 'Untitled_Function', aParentFolder = None)

Create a new Function with the given identifier inside the given ParentFolder.

Parameters:
  • aFunctionIdentifier (str, optional) – identifier of the function to create. ‘Untitled_Function’ by default
  • aParentFolder (SBSGroup or str, optional) – identifier of the folder in which the function should be created. If None, the new function will be added to the root content of the SBSDocument
  • aTemplate (str, optional) –

    the template to use to initialize this function, as the a path to a function inside a package:

    • 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.
  • searchForExistingReferenceByIdentifier (bool, optional) – if a template is given, for the nodes that are referencing a graph/function inside the template document, allows to define whether this reference will be searched in the destination package by its identifier, to use this reference instead. This parameter has priority against copyInternalReferencedObjects.
  • copyInternalReferencedObjects (bool, optional) – if a template is given, determine if the objects internal to the original package must be copied in the document or not. If True, the Functions defined in the original package can be copied also in this package if they are referenced. If False, these references will be updated to point to the original package. It may add a new dependency. Default to True
Returns:

the new SBSFunction object

 
 createGraph(aGraphIdentifier='New_Graph', aParentFolder=None, aParameters=None, aInheritance=None, aTemplate=None, searchForExistingReferenceByIdentifier=True, copyInternalReferencedObjects=True)

Create a new graph with the given identifier inside the given ParentFolder.

Parameters:
  • aGraphIdentifier (str, optional) – identifier of the graph to create. ‘New_Graph’ by default
  • aParentFolder (SBSGroup or str, optional) – identifier of the folder in which the graph should be created. If None, the new graph will be added to the root content of the SBSDocument
  • aParameters (dictionary with the format {parameterName(CompNodeParamEnum) : parameterValue(str)}, optional) – parameters of the graph (among the sbslibrary.sbslibclasses.BaseParameters only)
  • aInheritance (dictionary with the format {parameterName(CompNodeParamEnum) : parameterInheritance(ParamInheritanceEnum)}, optional) – Inheritance of the parameters
  • aTemplate (GraphTemplateEnum or str, optional) –

    the template path to use to initialize this graph. Can be an enumeration value from GraphTemplateEnum or a path to a graph inside a package:

    • 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.
  • searchForExistingReferenceByIdentifier (bool, optional) – if a template is given, for the nodes that are referencing a graph/function inside the template document, allows to define whether this reference will be searched in the destination package by its identifier, to use this reference instead. This parameter has priority against copyInternalReferencedObjects. Default to True
  • copyInternalReferencedObjects (bool, optional) – if a template is given, determine if the objects internal to the original package must be copied in the document or not. If True, the Graph or Functions defined in the original package can be copied also in this package if they are referenced. If False, these references will be updated to point to the original package, thus adding a dependency over the template. Default to True
Returns:

the new SBSGraph object

 
 createGroup(aGroupIdentifier = 'Untitled_Folder', aParentFolder = None)

Create a new group with the given identifier inside the given ParentFolder.

Parameters:
  • aGroupIdentifier (SBSGroup or str, optional) – identifier of the group to create. ‘Untitled_Folder’ by default
  • aParentFolder (str, optional) – identifier of the folder in which the graph should be created. If None, the new graph will be added to the root content of the SBSDocument
Returns:

the new SBSGroup object

 
 createHimselfDependency()

Add the ‘?himself’ dependency to the package, which allows referencing objects in the package.

Returns:The SBSDependency object 
 createImportedResource(aResourcePath, aResourceTypeEnum, aParentFolder = 'Resources', aIdentifier = None, aAttributes = None, aCookedFormat = None, aCookedQuality = None)

Add an external Resource from the given path in the given ParentFolder. Equivalent to ‘Link resource’ in Substance Designer)

Parameters:
  • aResourcePath (str) – relative or absolute path to the resource
  • aResourceTypeEnum (ResourceTypeEnum) – type of the resource (BITMAP/SVG/FONT/M_BSDF/LIGHT_PROFILE). Resource SCENE cannot be imported.
  • aParentFolder (SBSGroup or str, optional) – folder where the resource will be added (the group is created if necessary). ‘Resources’ by default. Put None to create the resource at the root of the package.
  • aIdentifier (str, optional) – Identifier of the resource. If None, the identifier is taken from the resource path
  • aAttributes (dictionary in the format {AttributesEnum : value(str)}, optional) – attributes of the resource
  • aCookedFormat (BitmapFormatEnum, optional) – bitmap format (JPEG/RAW) (only for BITMAP). Default value is RAW
  • aCookedQuality (float between 0 and 1, optional) – bitmap compression quality (only for BITMAP and SVG). Default value is 0
Returns:

the new SBSResource object
Raise:

api_exceptions.SBSImpossibleActionError

 
 createLinkedResource(aResourcePath, aResourceTypeEnum, aParentFolder = 'Resources', aIdentifier = None, aAttributes = None, aCookedFormat = None, aCookedQuality = None, aForceNew = False)

Add an external Resource from the given path in the given ParentFolder. Equivalent to ‘Link resource’ in Substance Designer)

Parameters:
  • aResourcePath (str) – relative or absolute path to the resource
  • aResourceTypeEnum (ResourceTypeEnum) – type of the resource (BITMAP/SVG/FONT/SCENE)
  • aParentFolder (SBSGroup or str, optional) – folder where the resource will be added (the group is created if necessary). ‘Resources’ by default. Put None to create the resource at the root of the package
  • aIdentifier (str, optional) – Identifier of the resource. If None, the identifier is taken from the resource path
  • aAttributes (dictionary in the format {AttributesEnum : value(str)}, optional) – attributes of the resource
  • aCookedFormat (BitmapFormatEnum, optional) – bitmap format (JPEG/RAW) (only for BITMAP). Default value is RAW
  • aCookedQuality (float between 0 and 1, optional) – bitmap compression quality (only for BITMAP and SVG). Default value is 0
  • aForceNew (bool, optional) – True to force the resource creation even if it is already included in the package. Default to False
  • isRelToPackage (bool, optional) – the given path is relative, if isRelToPackage is True it is relative to the sbs package otherwise it is relative to cwd.
Returns:

the new SBSResource object

 
 createMDLGraph(aGraphIdentifier = 'MDL_Material', aParentFolder = None)

Create a new graph with the given identifier inside the given ParentFolder.

Parameters:
  • aGraphIdentifier (str) – identifier of the graph to create. ‘New_Graph’ by default
  • aParentFolder (str) – identifier of the folder in which the graph should be created. If None, the new graph will be added to the root content of the SBSDocument
  • aCreateOutputNode (bool) – True to create the output node. Default to True
  • aTemplate (MDLGraphTemplateEnum or str, optional) –

    the template path to use to initialize this graph. Can be an enumeration value from MDLGraphTemplateEnum or a path to a graph inside a package:

    • 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.
  • searchForExistingReferenceByIdentifier (bool, optional) – if a template is given, for the nodes that are referencing a graph inside the template document, allows to define whether this reference will be searched in the destination package by its identifier, to use this reference instead. This parameter has priority against copyInternalReferencedObjects. Default to True
  • copyInternalReferencedObjects (bool, optional) – if a template is given, determine if the objects internal to the original package must be copied in the document or not. If True, the Graph or Functions defined in the original package can be copied also in this package if they are referenced. If False, these references will be updated to point to the original package, thus adding a dependency over the template. Default to True
Returns:

the new MDLGraph 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

 
 createModelGraph(aGraphIdentifier = 'Substance_Model_graph', aParentFolder = None)

Create a new graph with the given identifier inside the given ParentFolder.

Parameters:
  • aGraphIdentifier – identifier of the graph to create. ‘Substance_Model_graph’ by default
  • aParentFolder – identifier of the folder in which the graph should be created. If None, the new graph will be added to the root content of the SBSDocument

allows to define whether this reference will be searched in the destination package by its identifier, to use this reference instead. :type aGraphIdentifier: str :type aParentFolder: str :return: the new ModelGraph object

 createSceneResource(aResourcePath, aParentFolder = 'Resources', aIdentifier = None, aAttributes = None, isUDIM = False, aForceNew = False)

Add a new Scene Resource from the given path in the given ParentFolder.

Parameters:
  • aResourcePath (str) – relative or absolute path to the resource
  • aParentFolder (SBSGroup or str, optional) – folder where the resource will be added (the group is created if necessary). ‘Resources’ by default. Put None to create the resource at the root of the package
  • aIdentifier (str, optional) – Identifier of the resource. If None, the identifier is taken from the resource path
  • aAttributes (dictionary in the format {AttributesEnum : value(str)}, optional) – attributes of the resource
  • isUDIM (bool, optional) – True to use UDIMs on this scene resource. Default to False
  • aForceNew (bool, optional) – True to force the resource creation even if it is already included in the package. Default to False
Returns:

the new SBSResource object

 
 declareDependencyUIDChanged(oldDependencyUID, newDependencyUID)

Declare a change of UID of a dependency. All the references to the old UID will be replaced by the new UID. Warning: no check is done on the name of the referenced object inside the dependency (Graph identifier for instance)

Parameters:
  • oldDependencyUID (str) – The previous dependency UID
  • newDependencyUID (str) – The new dependency UID 
 declareInternalPathChanged(aObject, oldPath, newPath)

Declare a change in the internal path of the given object, so that all its references are updated in the current package.

Parameters:
  • aObject (SBSObject) – The object (group, graph, function, resource) that has a new internal path (pkg:///…)
  • oldPath (str) – The previous internal path of the object
  • newPath (str) – The new internal path of the object 
 declareResourcePathChanged(oldPath, newPath)

Declare a change of resource path. All the references to the resource will be replaced by the new path.

Parameters:
  • oldPath (str) – The previous path to the resource (path internal to the package pkg:///myGroup/myResource?dependency=1234567890)
  • newPath (str) – The new path to the resource (path internal to the package pkg:///myGroup/myResource?dependency=1234567890) 
 deleteMetaData(aName)

Delete a metadata, return True if success.

Parameters:aName (str) –
Returns:bool 
 deleteSBSGraph(aGraph)

Remove the given object from this package.

Parameters:
  • aGraph (SBSGraph or UID) – The sbs graph to delete
  • force (bool) – Whether to remove the object even if there are references to it or not
Returns:

True if success

 
 deleteSBSResource(self, aResourceIdentifier)

Delete the Resource object with the given identifier, if recursive all resources with same identifier will be deleted.

Parameters:
  • aResourceIdentifier (str) – Identifier of the resource to get
  • recursive (bool) – If True resources will be search in all groups recursively, and all resources with same identifier will be deleted
Returns:

 
 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. 
 generateThumbnail(aGraphIdentifier=None)

Generate a 512x512 icon and embeds it to the substance doc. Be sure to write the substance doc with doc.writeDoc() if you do some modifications on it. Use pysbs.batchtools so be sure to have setup correctly your system paths. The thumbnail generation is based on Usage output, if the graph has not the right Usages the thumbnail result can be unexpected.

Parameters:
  • aGraphIdentifier – the identifier of the graph to be thumbnail rendered, if None thumbnail will be generated for all the graph
  • saveThumbnailAs – give a correct directory path to save the thumbnail somewhere otherwise thumbnail file will be deleted
  • kwargs – arguments to pass to the batchtools.thumbnail.generate, quiet, aSize, aThumbnailSize… 
 getAllInternalReferences(aInternalPath=None)

Get all the SBSNode that are referencing the given internal path (graph, function, resource), or the current package (e.g. pointing to ‘himself’ dependency) if aInternalPath is let None

Parameters:aInternalPath (str, optional) – the internal path to look for. Default to None to search all the references of ?himself dependency
Returns:A list of SBSNode 
 getAllMetaData()

Get all MetaData under dictionary form.

Returns:dict 
 getAllReferencesOnDependency(aDependency)

Get all the SBSNode that are referencing the given dependency

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

Get all the SBSNode that are referencing the given resource

Parameters:aResource (SBSResource or str) – The resource to look for (object or path internal to the package (pkg:///myGroup/myResource)
Returns:A list of SBSNode 
 getContent()

Get the content of the package

Returns:the package content as a SBSContent object
Raise:api_exceptions.SBSUninitializedError in case where the package is not initialized (not parsed yet or not well created) 
 getDependency(aUID)

Get the dependency with the given UID

Parameters:aUID (str) – Uid of the dependency to get
Returns:A SBSDependency object if it exist, None otherwise 
 getDependencyContainingInternalPath(self, aPath)

Try to find a dependency containing an object of the given class with the given identifier.

Parameters:aPath (str) – The object internal path (pkg:///…) to look for
Returns:The dependency containing the given identifier if found, None otherwise 
 getDependencyFromPath(aPath)

Get the dependency that refers to the given path

Parameters:
  • aPath – The path of the dependency to look for
  • aPath – str
Returns:

A SBSDependency object if it exist, None otherwise

 
 getDependencyPathList(self, aRecurseOnPackages = False)

Get the list of the dependencies absolute path of this SBSDocument. If aRecurseOnPackages is True, look into the referenced packages to get the list of dependencies recursively.

Parameters:aRecurseOnPackages (bool, optional) – True to build the full list of dependencies recursively. Default to False
Returns:The list of absolute paths as strings 
 getDescription()

Get the substance description

Returns:The textual description of the substance 
 getHimselfDependency()

Look for the dependency identified by ‘himself’

Returns:A SBSDependency object if it exist, None otherwise 
 getMDLGraph(aGraphIdentifier)

Get the MDLGraph object with the given identifier

Parameters:aGraphIdentifier (str) – Identifier of the graph to get
Returns:A MDLGraph object 
 getMDLGraphInternalPath(aUID, addDependencyUID=False)

Get the path of the given MDL graph relatively to the current package (pkg:///…/aGraphIdentifier)

Parameters:
  • aUID (str) – the UID of the MDL graph to search
  • addDependencyUID (bool, optional) – True to add the tag ‘?dependency=’ at the end of the internal path. Default to False
Returns:

A string containing the relative path from the root content to the given graph, None otherwise

 
 getMDLGraphList()

Get the list of all graphs defined in the .sbs file

Returns:A list of MDLGraph object 
 getMetaData(aName)

Get a MetaData by its name

Parameters:aName (str) –
Returns:SBSMetaDataTreeUrl or SBSMetaDataTreeStr 
 getModelGraph(aGraphIdentifier) → pysbs.modelgraph.modelgraph.ModelGraph

getSBSGraph(aGraphIdentifier) Get the Graph object with the given identifier

Parameters:aGraphIdentifier (str) – Identifier of the graph to get
Returns:A SBSGraph object 
 getModelGraphList()

Get the list of all graphs defined in the .sbs file

Returns:A list of ModelGraph object 
 getObject(aObject)

Find the given object (Group, Graph, Function or Resource) if this package.

Parameters:aObject (SBSObject or str) – The object to search, as a SBSObject, a UID, or an internal path (pkg:///myGroup/myObjectIdentifier)
Returns:The object if found, None otherwise 
 getObjectFromInternalPath(aPath)

Get the object pointed by the given path, which must reference the current package.

Parameters:aPath (str) – the relative path, starting with ‘pkg:///’
Returns:the pointed SBSObject if found, None otherwise 
 getObjectFromUID(aUID)

Parse recursively the content of the package to find the Group, Graph, Resource or Function with the given uid.

Parameters:aUID (str) – The UID of the object (group, graph, resource or function) to look for
Returns:The SBSObject if found, None otherwise 
 getObjectInternalPath(aUID, aObjectClass=None, addDependencyUID=False)

Get the internal path (pkg:///myGroup/myObject) of the object with the given UID

Parameters:
  • aUID (str) – the UID of the object to search
  • aObjectClass (class, optional) – class of the object to look for.
  • addDependencyUID (bool, optional) – True to add the tag ‘?dependency=’ at the end of the internal path. Default to False
Returns:

the internal path of the object if found, None otherwise

 
 getOrCreateDependency(self, aPath, aAllowSBSAR=False)

Get the

Parameters:
  • aPath (str) –

    path of the object (graph, mdlgraph, function) to reference (absolute, relative to the current .sbs file, or given with an alias, for instance myalias:/myMdlFile.sbs)

    • If the object 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 object identifier is equivalent to the filename, the part /MyGraphIdentifier may be omit.
  • aAllowSBSAR (bool, optional) – True to allow creating a dependency on a .sbsar file. Default to False
Returns:

The list of outputs: [Referenced object, object relative path, Dependency object]
Raise:

api_exceptions.SBSImpossibleActionError

 
 getOrCreateGroup(aGroup)

Search for the given group, and create it if not found

Parameters:aGroup (SBSGroup or str) – the group to look for, as a group object, an identifier or a path relative to the package (pkg:///myFolder/myGroup)
Returns:The group as a SBSGroup 
 getParentGroupContent(aObject)

Get the parent group content of the given object (Group, Graph, Function, or Resource).

Parameters:aObject (SBSObject or str) – The object to consider, as a SBSObject, a UID or an internal path (pkg:///myGroup/myObjectIdentifier)
Returns:The parent group content, as a SBSContent object 
 getResourcePathList(aRecurseOnPackages=False, aIncludeSceneResources=True)

Get the list of all the resources path defined in this SBSDocument. If aRecurseOnPackage is True, look into the referenced packages to get the list of resources recursively.

Parameters:
  • aRecurseOnPackages (bool, optional) – True to build the full list of dependencies recursively. Default to False
  • aIncludeSceneResources (bool, optional) – True to include Scene/Mesh resources. Default to True
Returns:

The list of resource paths as strings

 
 getSBSDependencyList(aIncludeHimself = False)

Get the list of dependencies directly referenced by this SBSDocument.

Parameters:aIncludeHimself (bool, optional) – True to include ?himself dependency to the result. Default to False
Returns:A list of SBSDependency objects
Raise:api_exceptions.SBSUninitializedError in case where the package is not initialized (not parsed yet or not well created) 
 getSBSFunction(aFunctionIdentifier)

Get the Function object with the given identifier

Parameters:aFunctionIdentifier (str) – Identifier of the function to get
Returns:A SBSFunction object 
 getSBSFunctionInternalPath(aUID, addDependencyUID=False)

Get the path of the given function relatively to the current package (pkg:///…/aFunctionIdentifier)

Parameters:
  • aUID (str) – the UID of the function graph to search
  • addDependencyUID (bool, optional) – True to add the tag ‘?dependency=’ at the end of the internal path. Default to False
Returns:

A string containing the relative path from the root content to the given function, None otherwise

 
 getSBSFunctionList()

Get the list of all functions defined in the .sbs file

Returns:A list of SBSFunction object 
 getSBSGraph(aGraphIdentifier)

Get the Graph object with the given identifier

Parameters:aGraphIdentifier (str) – Identifier of the graph to get
Returns:A SBSGraph object 
 getSBSGraphInternalPath(aUID, addDependencyUID=False)

Get the path of the given graph relatively to the current package (pkg:///…/aGraphIdentifier)

Parameters:
  • aUID (str) – the UID of the Substance graph to search
  • addDependencyUID (bool, optional) – True to add the tag ‘?dependency=’ at the end of the internal path. Default to False
Returns:

A string containing the relative path from the root content to the given graph, None otherwise

 
 getSBSGraphList()

Get the list of all graphs defined in the .sbs file

Returns:A list of SBSGraph object 
 getSBSGraphPkgUrl(aGraph)

Get the path of the given graph relatively to the current package (pkg:///…/aGraphIdentifier)

Parameters:aGraph (A SBSGraph object) – Identifier of the graph to get
Returns:A string containing the relative path from the root content to the given graph, None otherwise 
 getSBSGroup(aGroupIdentifier)

Get the Group object with the given identifier

Parameters:aGroupIdentifier (str) – Identifier of the group (=folder) to get
Returns:A SBSGroup object 
 getSBSGroupInternalPath(aUID, addDependencyUID=False)

Get the path of the given group relatively to the current package (pkg:///…/aGroupIdentifier)

Parameters:
  • aUID (str) – the UID of the group to search
  • addDependencyUID (bool, optional) – True to add the tag ‘?dependency=’ at the end of the internal path. Default to False
Returns:

A string containing the relative path from the root content to the given group, None otherwise

 
 getSBSGroupList()

Get the list of all groups defined in the .sbs file

Returns:A list of SBSGroup object 
 getSBSMetaDataTree()

Get the SBSMetaDataTree structure.

Returns:class .SBSMetaDataTree 
 getSBSResource(self, aResourceIdentifier)

Get the Resource object with the given identifier

Parameters:aResourceIdentifier (str) – Identifier of the resource to get
Returns:A SBSResource object 
 getSBSResourceFromPath(aPath)

Get the first resource that refers to the given path, with the given link/imported status

Parameters:
  • aPath (str) – The path of the resource to look for
  • isLinkedResource (bool) – allows to specify if the resource to find is linked or imported, or if it does not matter (e.g. None). Default to None
Returns:

A SBSResource object if it exist, None otherwise

 
 getSBSResourceFromUID(aUID)

Get the resource with the given UID

Parameters:
  • aUID – The UID of the resource to look for
  • aUID – str
Returns:

A SBSResource object if it exist, None otherwise

 
 getSBSResourceInternalPath(aUID, addDependencyUID=False)

Get the path of the given resource relatively to the current package (pkg:///…/aResourceIdentifier)

Parameters:
  • aUID (str) – the UID of the resource to search
  • addDependencyUID (bool, optional) – True to add the tag ‘?dependency=’ at the end of the internal path. Default to False
Returns:

A string containing the relative path from the root content to the given resource, None otherwise

 
 getSBSResourceList(aIncludeSceneResources=True)

Get the list of all the resources directly referenced by this SBSDocument.

Parameters:aIncludeSceneResources (bool, optional) – True to include Scene/Mesh resources. Default to True
Returns:A list of SBSResource objects 
 getSBSResourcesFromPath(aPath)

Get all the resources that refers to the given path

Parameters:aPath (str) – The path of the resource to look for
Returns:A SBSResource object if it exist, None otherwise 
 getUidIsUsed(aUID)

Parse the Dependencies and Content to find a SBSObject with the given uid

Returns:True if an object has this uid 
 hasADependencyOn(aPath)

Check if this package has a dependency on the given path

Parameters:
  • aPath – The path of the dependency to look for
  • aPath – str
Returns:

True if the package has this dependency, False otherwise

 
 static isAPackage(aFilePath)

Check if the given filename is a .sbs file or .sbsar file.

Parameters:aFilePath (str) – Path of the package
Returns:True if the given path ends with .sbs or .sbsar, False otherwise 
 static isAnArchive(aFilePath)

Check if the given filename is a .sbsar package or a .sbs package

Parameters:aFilePath (str) – Path of the package
Returns:True if the given path refers to an archive (.sbsar), False otherwise 
 isInitialized()

Check if the package is correctly initialized (parsed or well setup for future usage)

Returns:True if the package is initialized, False otherwise 
 moveObjectUnderGroup(aObject, aGroup=None)

Moves the given object under the given group. If aGroup is let None, moves the object under the root content.

Parameters:
  • aObject (SBSObject or str) – The object to move, as a SBSObject, a UID or an internal path
  • aGroup (SBSGroup or str, optional) – The destination group, as a SBSGroup, a UID or an internal path. Can be None to put the object at the root of the package 
 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 
 parseDoc(aResolveDependencies = True)

Parse the SBS File content

Returns:True if succeed 
 relocateResource(aResource, aNewPath)

Relocate the given linked resource to the given path (absolute or relative to this document).

Parameters:
  • aResource (SBSResource or str) – the resource to relocate, as a SBSResource object or an internal path (pkg:///myGroup/myResource)
  • aNewPath (str) – the new path to the resource
  • checkPathExists (bool, optional) – whether to check the existence of the path. Default to True
Returns:

True if success
Raise:

SBSImpossibleActionError

 
 removeDependency(aDependency)

Remove the dependency from the SBSDocument, if there is no more reference on it in the content.

Parameters:
  • aDependency (str or SBSDependency) – The dependency to remove (UID or object)
  • aCheckUsage (bool, optional) – True check if the dependency is used in the package, and raise an exception if it is the case. False to remove without checking. Default to True
Returns:

True if success, False if the dependency was not used by this Substance
Raise:

api_exceptions.SBSImpossibleActionError if the dependency is still used by the Substance content

 
 removeObject(aObject)

Remove the given object from this package. Warning, no check is done to ensure that this object is referenced in this package. You can use getAllInternalReferences() to get the internal references of this object.

Parameters:aObject (SBSObject or UID) – The object (group, graph, function, resource) to remove from this content, as a SBSObject or given its UID
Returns:True if success 
 static removePackageExtension(aFilePath)

Remove the package extension to the given path (.sbs or .sbsar)

Parameters:aFilePath (str) – Path of the package
Returns:The same path without the package extension 
 setDescription(aDescription)

Set the given description

Parameters:aDescription (str) – the textual substance description 
 setInitialized()

Set the package as initialized.

Raise:api_exceptions.SBSUninitializedError in case where the Content or the Format Version are not defined 
 setMetaDataName(aMetadata, aName)

Set name of a metadata if name is valid

Parameters: 
 setMetaDataValue(aMetadata, aValue)

Set value of a metadata

Parameters: 
 setObjectIdentifier(aObject, aIdentifier)

Set the identifier of the given object (Group, Graph, Function or Resource), and update all internal references to this object with the new identifier.

Parameters:
  • aObject (SBSObject or UID) – The object to rename, as a SBSObject, a UID or an internal path (pkg:///myGroup/myObjectIdentifier)
  • aIdentifier (str) – The new identifier to set
Returns:

the identifier set, as it can be modified to ensure uniqueness of identifiers

 
 splitPackageObjectPath(aPath, aAllowSBSAR=False)

Split the given path to a path to a package (.sbs/.sbsar) and a relative to the object pointed into it.

Parameters:
  • aPath (str) –

    path of an object inside a package (absolute, relative to the current .sbs file, or given with an alias, for instance sbs://anisotropic_noise.sbs)

    • If the object is included in the current package, use: pkg:///MyObjectIdentifier
    • If the path uses an alias, use: myalias://MyFileName.sbs/MyObjectIdentifier
    • If the path is relative to the current package or absolute, use MyAbsoluteOrRelativePath/MyFileName.sbs/MyObjectIdentifier
    • Note that if the object identifier is equivalent to the filename, the part /MyObjectIdentifier may be omit.
  • aAllowSBSAR (bool, optional) – True to allow considering a sbsar package. Default to False
Returns:

a tuple (packagePath, objectRelativePath), where packagePath is the absolute path to the package, and objectRelativePath is the path of the object as an internal path (pkg:///MyObjectIdentifier)

 
 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 
 writeDoc(aNewFileAbsPath = None, aUpdateRelativePaths = False)

Write the SBS document in Element Tree structure and write it on the disk. If aNewFileAbsPath is provided, the document is saved at this location, otherwise it is save on the current file location.

Parameters:
  • aNewFileAbsPath (string, optional) – The final location of the document. By default, the document is saved at the same location that the one provided when creating the document.
  • aUpdateRelativePaths (boolean, optional) – Set to True to update the relative paths of the resources and dependencies of this document when saving on a new location. Default to False
Returns:

True if succeed

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