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.


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.