Expressioned Parameters¶

A parameter can have its value computed dynamically using a Python expression. Expressions are set using setExpression(), which takes a Python string representing the expression as its first argument and an optional enable parameter to specify whether to implicitly enable the expression.

A parameter expression must evaluate in the same way that a Python eval expression would (as a condition list). The global and local scopes of a parameter expression are sand-boxed so that it is not possible to make topological changes to the Node Graph whilst it is being resolved.

It is possible to write an expression that references a node by name and not break when the node name changes.

Note

You should avoid using the nodeName variable for parameter expressions that specify scene graph locations, and must take care when using them anywhere that a scene graph attribute is set. Node names are not namespaced and can therefore change unpredictably.

The following example script sets the expression on a parameter:

# Add a PrimitiveCreate node
rootNode = NodegraphAPI.GetRootNode()
primNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

# Add a number parameter called myNumber
rootParam = primNode.getParameters()
rootParam.createChildNumber("myNumber", 7.0)

# Link myNumber to the node's scale x parameter by expression
scaleXParam = primNode.getParameter('transform.scale.x')
scaleXParam.setExpression("getParam('%s.myNumber')" % primNode.getName())
# Alternatively:
# scaleXParam.setExpression("myNumber")

You can disable an expression with the setExpressionFlag() method:

scaleXParam.setExpressionFlag(False) # Disable
scaleXParam.setExpressionFlag(True) # Enable

Parameter.isExpression() → bool¶: True if the parameter defines an expression to compute the value.

Parameter.getExpression() → str¶: Returns the string of the expression that controls the parameter (when it is enabled).

Parameter.getExpressionError() → str¶: Returns a string description of any evaluation errors of the expression.

Parameter.setExpression(string, enable=True)¶: Defines a new string to control the parameter value.

Parameter.setExpressionFlag(bool)¶: Enables or disables the expression to control the parameter value.

Parameter.getReferences(time) → str or float¶: Returns a list of parameters evaluated during the process of evaluating this one (including itself).

Parameter.renameExpression(oldName, newName)¶: Performs node name string substitution on the expression. This usually happens automatically.

Parameter.reparentExpression(oldPath, newPath)¶: Performs parameter path string substitution on the expression. This usually happens automatically.