inputparameters module

Module inputparameters provides the definition of SBSWidget and SBSParamInput, which allow the definition of the Input Parameters of a graph in Substance Designer.

class graph.inputparameters.SBSParamInput(aIdentifier='', aUID='', aAttributes=None, aDisabled=None, aIsConnectable=None, aUsages=None, aType='', aDefaultValue=None, aDefaultWidget=None, aGroup=None, aVisibleIf=None, aSpotColorInfo=None, aMetaDataTree=None)

Bases: SBSObject, ParamInput, SBSMetaDataObject

Class that contains information on an input parameter of a graph, as defined in a .sbs file

Members:

  • mIdentifier (str): identifier of this input.

  • mUID (str): unique identifier in the /graph/ context.

  • mAttributes (SBSAttributes): various attributes

  • mDisabled (str, optional): this input is NOT used (“1” / None)

  • mUsages (list of SBSUsage): usages of this input

  • mType (str): type of the input

  • mDefaultValue (SBSConstantValue): default value, depend on the type.

  • mWidget (SBSWidget): default widget used to visualize the entry.

  • mGroup (str, optional): string that contains a group name. Can uses path with ‘/’ separators.

  • mVisibleIf (str, optional): string boolean expression based on graph inputs values

  • mIsConnectable (str, optional): Flag saying whether the input is possible to connect to the input

addUsage(aUsage, aComponents=sbsenum.ComponentsEnum.RGBA)

Add the given usage on this param input

Parameters:

  • aUsage (str or UsageEnum) – The usage to set

  • aComponents (ComponentsEnum, optional) – The components associated to this usage. Default to sbsenum.ComponentsEnum.RGBA

Returns:

the create SBSUsage 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

deleteMetaData(aName)

Delete a metadata, return True if success.

Parameters:

aName (str)

Returns:

bool

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.

formatValueToType(aValue)

Return the given value formatted in the appropriate type for this parameter (bool, int or float)

Parameters:

aValue (string, bool, int, or float) – The value to format

Returns:

The value as a bool, int of float depending on the parameter type

getAllMetaData()

Get all MetaData under dictionary form.

Returns:

dict

getAllowedAttributes()

Get the attributes allowed on a SBSParamInput

Returns:

the list of attribute enumeration allowed (AttributesEnum)

getAttribute(aAttributeIdentifier)

Get the given attribute value

Parameters:

aAttributeIdentifier (AttributesEnum) – the attribute identifier

Returns:

the attribute value if defined, None otherwise

getClamp()
Returns:

the clamp as a boolean if defined for this parameter, None if not defined

getDefaultValue()
Returns:

the default value as a value or a list of values in the type of the parameter (bool, int or float), None if not defined

getDimension()

Get the dimension of the parameter type (1, 2, 3, or 4 values)

Returns:

The dimension as an integer

getDropDownList()
Returns:

the map{value(int):label(str)} corresponding to the drop down definition if defined for this parameter, None otherwise.

getGroup()

Get the group associated to this parameter

Returns:

the group of this parameter as a string if it has one, None otherwise

getIsConnectable()
Returns:

bool

getLabels()
Returns:

the list of all labels defined for this parameter, in the right order, as a list of strings. None if not defined

getMaxValue(asList=False)
Returns:

the maximum parameter value in the type of the parameter (int or float), None if not defined

getMetaData(aName)

Get a MetaData by its name

Parameters:

aName (str)

Returns:

SBSMetaDataTreeUrl or SBSMetaDataTreeStr

getMinValue(asList=False)
Returns:

the minimum parameter value in the type of the parameter (int or float), None if not defined

getSBSMetaDataTree()

Get the SBSMetaDataTree structure.

Returns:

class .SBSMetaDataTree

getSpotColorInfo()
getStep()
Returns:

the step value (in the type of the parameter) of the widget for this parameter, None if not defined

getType()

Get the type of the input among the list defined in ParamTypeEnum

Returns:

The type of the parameter as a ParamTypeEnum

getUID()
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

getUsages()

Get the usages of this param input

Returns:

the list of SBSUsage defined on this param input

getValueInterpretation()
Returns:

the value interpretation as a string if defined for this parameter, None otherwise.

getWidget()
Returns:

The widget used for this parameter, as a SBSDefaultWidget. None if not defined

getWidgetType()
Returns:

the kind of widget used for this parameter, as a WidgetTypeEnum. None if not defined

hasUsage(aUsage)

Check if the given usage is defined on this param input

Parameters:

aUsage (str or UsageEnum) – The usage to look for

Returns:

True if the given usage is defined on this param input, False otherwise

isAnInputImage()

Return True if this input is an input Entry (kind ENTRY_COLOR | ENTRY_GRAYSCALE | ENTRY_VARIANT)

Returns:

True if it is an input entry, False otherwise

isAnInputParameter(exposedOnly=False)

Return True if this input is a parameter (numeric value)

In Substance Designer, the values of the “Input Value” Node are not exposed to the graph public interface: - in the UI they belong to the “Inputs” panel and not the “Input Parameters” - when graph is used as an instance node: they are set through the subgraph node inputs and are not tweakable through the UI panel “Instance parameters” - when graph is published/cooked to SBSAR: they are kept internal and not exposed in the SBSAR’s input parameters In SAT, isAnInputParameter(exposedOnly=False) returns any graph input numeric value (“Input Value” Nodes + exposed parameters), and isAnInputParameter(exposedOnly=True) filters those considered as “Input Parameters” in the Substance Designer

Parameters:

exposedOnly (boolean) – option to filter only the parameters that are exposed to the graph public interface

Returns:

True if it is an input parameter, 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

setAttribute(aAttributeIdentifier, aAttributeValue)

Set the given attribute

Parameters:

  • aAttributeIdentifier (AttributesEnum) – The attribute identifier to set

  • aAttributeValue (str) – The attribute value to set

setAttributes(aAttributes)

Set the given attributes

Parameters:

aAttributes (dictionary in the format {AttributesEnum : value}) – The attributes to set

setClamp(aClamp)

Set the clamp option for the widget of this parameter

Parameters:

aClamp (boolean) – The clamp option for the parameter widget (True to clamp)

Raise:

SBSImpossibleActionError

setDefaultValue(aDefaultValue)

Set the default value of the widget

Parameters:

aDefaultValue (depend on the widget type (single value or list)) – The default value for the parameter widget

Raise:

SBSImpossibleActionError

setDropDownList(aValueMap)

Set the drop down value map for a DropDown widget.

Parameters:

aValueMap (dictionary in the format {key(int):value(string)}) – The drop down values as a map

Raise:

SBSImpossibleActionError

setIdentifier(aDoc, aIdentifier)

Be careful! if aIdentifier is already used by another input param of this graph, the file risks to be corrupted. It safer to use graph.changeInputParameterIdentifier()

Change the param’s identifier and update its dependencies, function’s paramnode, visibleIf… :param aDoc: the current substance document SBSDocument :type aDoc: SBSDocument :param aIdentifier: the new identifier value :type aIdentifier: str :return:

setIsConnectable(aIsConnectable)

Set whether the input is connectable

Parameters:

aIsConnectable (bool or None) – Whether the input is connectable or not

Raise:

SBSImpossibleActionError

setLabels(aLabels)

Set the labels associated to the different values for the widget of this parameter

Parameters:

aLabels (list of string) – The labels for the parameter widget

Raise:

SBSImpossibleActionError

setMaxValue(aMaxValue)

Set the maximum value for the widget of this parameter

Parameters:

aMaxValue (int or float) – The maximum value to set

Raise:

SBSImpossibleActionError

setMetaDataName(aMetadata, aName)

Set name of a metadata if name is valid

Parameters:
setMetaDataValue(aMetadata, aValue)

Set value of a metadata

Parameters:
setMinValue(aMinValue)

Set the minimum value for the widget of this parameter

Parameters:

aMinValue (int or float) – The minimum value to set

Raise:

SBSImpossibleActionError

setSpotColorFromIds(aBookId, aColorId)

If the input widget is a color, a new color value and spot color info will be set.

Parameters:

  • aBookId (str) – The book id

  • aColorId (str) – The color id

setSpotColorFromNames(aBookName, aColorName)

If the input widget is a color, a new color value and spot color info will be set.

Parameters:

  • aBookName (str) – The book name of the color

  • aColorName (str) – The color name

setStep(aStep)

Set the step option for the widget of this parameter

Parameters:

aStep (int or float) – The step value for the parameter widget

Raise:

SBSImpossibleActionError

setUID(aUID)
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 graph.inputparameters.SBSPreset(aLabel=None, aUsertags=None, aPresetInputs=None, aRefGraph=None)

Bases: SBSObject, Preset

Class for manipulating embedded user-defined presets inside a .sbs file

Members:

  • mLabel (str): label of the preset

  • mUsertags (str): user-defined tags

  • mPresetInputs (list of SBSPresetInput): list of preset inputs

deletePresetInput(aInputParam)

Delete the preset input associated to the given input parameter.

Parameters:

aInputParam (SBSParamInput or str) – the input parameter to delete in this preset, as a SBSParamInput object or a UID

Returns:

True if the preset input has been found and deleted, False otherwise

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.

getInputValue(aInputUID)

Get the value of the given ParamInput in this preset

Parameters:

aInputUID (str) – UID of the input to get

Returns:

the input value in this preset if defined, None otherwise

getPresetInput(aInputParam)

Get the preset input corresponding to the given input parameter.

Parameters:

aInputParam (SBSParamInput or str) – the input parameter to get in this preset, as a SBSParamInput object or a UID

Returns:

a SBSPresetInput if found, None otherwise

getPresetInputFromIdentifier(aInputParamIdentifier)

Get the preset input with the given input UID defined in this preset

Parameters:

aInputParamIdentifier (str) – the identifier of the input parameter to get in this preset

Returns:

a SBSPresetInput if found, None otherwise

getPresetInputs()

Get all the preset inputs defined in this preset

Returns:

a list of SBSPresetInput

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

setPresetInput(aInputParam, aPresetValue)

Set the preset value for the given graph input parameter.

Parameters:

  • aInputParam (SBSParamInput or str) – the input parameter to set in this preset, as a SBSParamInput object or a UID

  • aPresetValue (any type) – the value of this input parameter in this preset

setRefGraph(aRefGraph)

Set the parent graph of this preset

Parameters:

aRefGraph (SBSGraph) – The parent graph

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 graph.inputparameters.SBSPresetInput(aUID='', aIdentifier='', aValue=None, aType='')

Bases: SBSObject, PresetInput

Class for manipulating embedded user-defined preset input inside a .sbs file

Members:

  • mUID (str): uid of the input parameter targeted by this preset input

  • mIdentifier (str): identifier of the input parameter targeted by this preset input

  • mType (str): type of the input

  • mValue (SBSParamValue): value, depend on the type.

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.

getType()

Get the type of the input among the list defined in ParamTypeEnum.

Returns:

The type of the parameter as a ParamTypeEnum

getTypedValue()

Get the value of this preset input correctly formatted in the type of this preset (e.g. bool, int, float, list of int, …)

Returns:

The input value in the appropriate type

getUID()
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

getValue()

Get the value of this preset input as it is saved in the file

Returns:

the input value in this preset input

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

setType(aType)

Set the type of this preset input

Parameters:

aType (ParamTypeEnum) – The type to set

setUID(aUID)
setValue(aValue)

Set the value of the input parameter in the preset

Parameters:

aValue (any type) – The value to set

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 graph.inputparameters.SBSWidget(aName='', aOptions=None)

Bases: SBSObject

Class that contains information on a Widget as defined in a .sbs file. A widget describes the way an input parameter will be displayed in Substance Designer.

Members:

  • mName (str): name of the widget used to visualize the entry, among the list defined in sbslibrary.__dict_WidgetTypes

  • mOptions (list of SBSOption): list of specific options of the widget type.

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.

getClamp()
Returns:

the clamp as a boolean if defined for this widget, None otherwise

getDefaultValue()
Returns:

the default value as a string or a list of strings if defined for this widget, None otherwise

getDropDownList()
Returns:

the map{value(int):label(str)} corresponding to the drop down definition if defined in this widget, None otherwise.

getLabels()
Returns:

the list of all labels defined for this widget, in the right order, as a list of strings.

getMaxValue()
Returns:

the maximum value as a string if defined for this widget, None otherwise

getMinValue()
Returns:

the minimum value as a string if defined for this widget, None otherwise

getOption(aOptionId)
Parameters:

aOptionId (WidgetOptionEnum) – The option to look for, among the list defined in WidgetOptionEnum

Returns:

the requested option as a SBSOption if found, None otherwise

getOptions()
Returns:

all the options of this widget as a list of SBSOption

getStep()
Returns:

the step as a string if defined for this widget, None otherwise

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

getValueInterpretation()
Returns:

the value interpretation as a string if defined for this widget, None otherwise

getWidgetType()
Returns:

the kind of widget, as a WidgetTypeEnum

isInRange(aValue)
Parameters:

aValue (int or float) – The value to check

Returns:

True if the given value is allowed for this widget. Will return True if there is no range, or if the clamping is disabled.

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

setClamp(aClamp)
Parameters:

aClamp (boolean) – The clamp option for this widget (True to clamp)

setDefaultValue(aDefaultValue, aType)
Parameters:

  • aDefaultValue (list of int or list of float) – The default values for this widget

  • aType (ParamTypeEnum) – The type of this widget (BOOL , INT1 .. INT4 , FLOAT1 .. FLOAT4)

setDropDownList(aValueMap)
Parameters:

aValueMap (a dictionary in the format {key(int):value(string)}) – The drop down values, as a map in the format key(int):value(string)

Raise:

SBSImpossibleActionError

setLabels(aLabels)
Parameters:

aLabels (list of string) – The labels for this widget

setMaxValue(aMaxValue, aType)
Parameters:

  • aMaxValue (int or float) – The maximum value to set on this widget

  • aType (ParamTypeEnum) – The type of the values for this widget (int or float)

setMinValue(aMinValue, aType)
Parameters:

  • aMinValue (int or float) – The minimum value to set on this widget

  • aType (ParamTypeEnum) – The type of the values for this widget (int or float)

setOption(aOptionId, aValue)
Parameters:
setStep(aStep, aType)
Parameters:

  • aStep (int or float) – The step value for this widget

  • aType (ParamTypeEnum) – The type of the values for this widget (int or float)

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