substance module

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: 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: 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: SBSObject, Package, SBSMetaDataObject

Class used to get information on a .sbs file. It contains the full description of a substance, which correspond to the root node <package> 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 exist 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

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 (str) – identifier of the graph to create. ‘Substance_Model_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 allows to define whether this reference will be searched in the destination package by its identifier, to use this reference instead.

Returns:

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

getMDLGraphList()

Get the list of all MDL graphs identifiers defined in the .sbs file Warning: MDLGraph is not supported in SAT >= 16.0, only the identifiers are returned

Returns:

A list of strings

getMetaData(aName)

Get a MetaData by its name

Parameters:

aName (str)

Returns:

SBSMetaDataTreeUrl or SBSMetaDataTreeStr

getModelGraph(aGraphIdentifier) → 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=<uid>’ 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, 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=<uid>’ 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=<uid>’ 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=<uid>’ 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=<uid>’ 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