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:
- A
=character - An optional
/-terminated target node specifier - 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.
Parameter Reference Expressions with string values also support the use of
string literals and concatenation using the + operator.
- A string literal must be surrounded by either single- or double-quotes, for
example
"literal"or'literal'. - If quotes are required in a string literal, they can be escaped with a
backslash, for example
"this is an \"example\"". - If a backslash character is required in a string literal, it must be escaped
with another backslash, for example
"\\". - Strings may be concatenated using
+, for example"prefix_" + user.static1. - Parameter Expressions may be build from a combination of string literals and parameter reference terms using the previously defined syntax.
- There is no limit on the number of strings that may be concatenated.
See the table below for examples of Parameter Expressions using literals and concatenation.
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") |
In this case, both “static1” and “static2” are string parameters, so may be concatenated with other values:
| Reference Expression | Equivalent Python Expression |
|---|---|
=GroupInner/user.static2 + "_suffix" |
getNode("GroupInner").user.static2 + "_suffix" |
="prefix_" + user.static2 |
"prefix_" + user.static2 |
="first" + "_" + "second" |
"first" + "_" + "second" |
=^/user.static1 + user.static2 |
getParent().user.static1 + user.static2 |
=user.static2 + "\\" + ^/user.static1 |
user.static2 + "\\" + getParent().user.static1 |
Graph State Queries¶
Graph State Variables¶
✨ New in Katana 4.5v1
Graph State Variables can be queried using the $ token followed by the name of the Graph State Variable.
This functionality is equivalent to getVar() in Python Expressions, though limited to string values.
Examples:
| Reference Expression | Equivalent Python Expression |
|---|---|
='/root/world/geo/shape_' + $shape |
'/root/world/geo/shape_' + getVar('shape') |
Frame Time¶
✨ New in Katana 4.5v1
The # symbol is used to query the integer frame time of the Local Graph State. If Local Graph State is not
available, it falls back to the Global Graph State.
Consecutive # symbols can be appended for padding the value with zeros.
This functionality matches the value that getFrameTime() in Python Expressions returns, with the exception that the value is rounded down to the nearest integer toward negative infinity.
Examples:
| Reference Expression | Equivalent Python Expression |
|---|---|
='/media/show/house_' + #### + '.abc' |
'/media/show/house_' + str(int(floor(frameTime))).zfill(4) + '.abc' |