- Substance 3D home
- Home
- Command Line Tools
- Command Line overview
- sbsbaker
- sbscooker
- sbsmtools
- sbsmutator
- sbsrender
- sbsupdater
- Command Line overview
- Pysbs - Python API
- Pysbs - Python API overview
- Getting started
- General topics
- Examples
- API Content
- API Content overview
- Substance definitions
- Common interfaces
- compnode
- context projectmgr
- graph
- mdl
- modelgraphindex
- modelannotationnames
- modelgraph
- modelgraphgenerator
- modelgraphimplementation
- modelnodenames
- modeloperand
- modulegraphindex
- moduleannotation
- moduleconnection
- modulegraph
- modulegraphgenerator
- modulegraphimplementation
- modulegraphlibrary
- modulegraphregister
- modulenode
- modulenodeimplementation
- modulenodeinstance
- moduleoperand
- moduleoutputbridging
- moduleparaminput
- params
- projectmgrdoc
- sbsarchive
- sbscommon
- sbspreset
- sbsproject
- substance
- Libraries
- sbsenum
- sbslibrary
- sbsbakerslibrary
- Helpers
- Execution context
- API Change log
- Samples
- Setup and Getting Started
- Integrations
- Substance Maya toolset
- Changelog overview
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.
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.
write(aSBSWriter, aXmlNode)
Write recursively the content of the SBSObject into the given xml node.
Parameters: |
|
---|
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.
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.
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: |
|
---|
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: |
|
---|---|
Returns: | Tuple ( |
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.
|
---|---|
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: |
|
---|---|
Returns: | the copied dependency as a |
Raise: |
|
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: |
|
---|---|
Returns: | the copied dependency as a |
Raise: |
|
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: |
|
---|---|
Returns: | the new |
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: |
|
---|---|
Returns: | the new |
createGroup(aGroupIdentifier = 'Untitled_Folder', aParentFolder = None)
Create a new group with the given identifier inside the given ParentFolder.
Parameters: |
|
---|---|
Returns: | the new |
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: |
|
---|---|
Returns: | the new |
Raise: |
|
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: |
|
---|---|
Returns: | the new |
createMDLGraph(aGraphIdentifier = 'MDL_Material', aParentFolder = None)
Create a new graph with the given identifier inside the given ParentFolder.
Parameters: |
|
---|---|
Returns: | the new |
createMetaDataStr(aName, aValue)
Create a metadata of type Str.
Parameters: |
|
---|---|
Returns: | A |
createMetaDataUrl(aName, aResource)
Create a metadata of type Url.
Parameters: |
|
---|---|
Returns: | A |
createModelGraph(aGraphIdentifier = 'Substance_Model_graph', aParentFolder = None)
Create a new graph with the given identifier inside the given ParentFolder.
Parameters: |
|
---|
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: |
|
---|---|
Returns: | the new |
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: |
|
---|
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: |
|
---|
declareResourcePathChanged(oldPath, newPath)
Declare a change of resource path. All the references to the resource will be replaced by the new path.
Parameters: |
|
---|
deleteMetaData(aName)
Delete a metadata, return True if success.
Parameters: | aName (str) – |
---|---|
Returns: | bool |
deleteSBSGraph(aGraph)
Remove the given object from this package.
Parameters: |
|
---|---|
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: |
|
---|---|
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.
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: |
|
---|
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: |
|
---|---|
Returns: | A |
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: |
|
---|---|
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: |
|
---|---|
Returns: | the internal path of the object if found, None otherwise |
getOrCreateDependency(self, aPath, aAllowSBSAR=False)
Get the
Parameters: |
|
---|---|
Returns: | The list of outputs: [Referenced object, object relative path, Dependency object] |
Raise: |
|
getOrCreateGroup(aGroup)
Search for the given group, and create it if not found
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|---|
Returns: | A |
getSBSResourceFromUID(aUID)
Get the resource with the given UID
Parameters: |
|
---|---|
Returns: | A |
getSBSResourceInternalPath(aUID, addDependencyUID=False)
Get the path of the given resource relatively to the current package (pkg:///…/aResourceIdentifier)
Parameters: |
|
---|---|
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: |
|
---|---|
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.
parse(aContext, aDirAbsPath, aSBSParser, aXmlNode)
Parse recursively the given xml node to retrieve the content of the SBSObject.
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: |
|
---|---|
Returns: | True if success |
Raise: |
|
removeDependency(aDependency)
Remove the dependency from the SBSDocument, if there is no more reference on it in the content.
Parameters: |
|
---|---|
Returns: | True if success, False if the dependency was not used by this Substance |
Raise: |
|
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|
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: |
|
---|---|
Returns: | True if succeed |