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: Returns whether this parameter uses an expression to compute its value.

Parameter.getExpression() → str: Returns the string of the expression used to compute this parameter’s value.

Parameter.getExpressionError() → str: Returns a string describing any errors that occurred during evaluation of this parameter’s expression, if any.

Parameter.setExpression(expression: str, enable: bool = True) → None: Sets the expression used to compute this parameter’s value. Setting enable to True as the same effect as calling setExpressionFlag(True) after calling this method.

Parameter.setExpressionFlag(value: bool) → None: Sets whether to enable the expression used to compute this parameter’s value.

Parameter.getReferences(time: float) → List[str]: Returns a list of parameters evaluated during the process of evaluating this parameter’s value, including itself.

Parameter.renameExpression(oldNodeName: str, newNodeName: str) → None: Performs node name string substitution on this parameter’s expression. This usually happens automatically.

Parameter.reparentExpression(oldPath: str, newPath: str) → None: Performs parameter path string substitution on this parameter’s expression. This usually happens automatically.