Reference Expressions

A reference expression is a form of parameter expression that can be evaluated without the overhead of a Python interpreter. These types of expressions are particularly useful when building custom SuperTools where performance is key. Reference expressions can be added using the usual parameter expression user interface, and are identified by the first character of the expression being either @ (for a node reference) or = (for a parameter reference)

Node References

Parameter expressions beginning with @ evaluate to the text following the @. The text is considered to be the name of a node, and Katana retargets node references when a referenced node is renamed.

Parameter References

Parameter Expressions beginning with = are used to retrieve the value of another parameter. The general format of a parameter reference is:

  1. A = character
  2. An optional /-terminated target node specifier
  3. A target parameter specifier

If a target node specifier is not given, the target parameter is looked up on the current node, i.e. the node that owns the expressioned parameter. Otherwise, the target node specifier can take one of three forms:

  • The name of a node followed by / looks up the target parameter on the node with the given name.
  • At least one ^ character followed by / looks up the target parameter on an ancestor (enclosing) node. Each instance of ^ moves up one ancestor.
  • ~/ looks up the target parameter on the current node. This is equivalent to omitting the target node specifier.

The target parameter specifier can take one of three forms:

  • A dotted path to the target parameter looks it up relative to the root parameter of the target node.
  • At least one ^ character followed by . and the dotted path looks up the target parameter relative to an enclosing group parameter. Each instance of ^ moves up one parameter ancestor.
  • ~ looks up the target parameter using the same path as the expressioned parameter. To avoid cyclical expressions when using this form, ensure that the target node specifier points to another node.

Examples

In these examples we assume the node graph consists of two Group nodes - “GroupOuter” and “GroupInner”, where the former encloses the latter. Both of these nodes have user parameters set as follows:

GroupOuter
`-- user
    `-- static1 = "foo"

GroupInner
`-- user
    |-- static2 = "bar"
    `-- expr1

To reference the “static1” parameter from “expr1”, we could use either of the following:

Reference Expression Equivalent Python Expression
=GroupOuter/user.static1 getNode("GroupOuter").user.static1
=^/user.static1 getParent().user.static1

To reference the “static2” parameter from “expr1”, we could use any of the following:

Reference Expression Equivalent Python Expression
=GroupInner/user.static2 getNode("GroupInner").user.static2
=~/user.static2 getNode(self.getNodeName()).user.static2
=user.static2 user.static2
=^.static2 getParamRelative(self, "../static2")