An expression is a combination of numbers, symbols, and/or words that represent a numerical value. An expression can be used in a parameter, in place of a fixed numerical value, to animate values across time or to reference values in another parameter.
Expressions are not just for performing esoteric or complex modifications, although they can certainly be used for that purpose. Rather, expressions are also an easy way to get common tasks done faster and more consistently. This is because an expression can access the values in any other parameter, updating automatically to reflect any change in the referenced value. The value referenced can be used as is, or it can be further modified.
Say, for example, that you've animated a change in brightness in a foreground element to match the fluctuating light levels in a background plate. You can use an expression to access that same brightness curve to adjust other foreground layers. And you can modify the expression to raise or lower the overall brightness level of any image layer without affecting the relative change in brightness from frame to frame specified in the referenced animation curve.
Expressions are a powerful way to control node operations, but even the most math-phobic user can learn to write basic expressions by reviewing the guidelines in the section on Writing Valid Expressions. All you need to know are some of the symbols used (the vocabulary) and the order in which they are strung together to create meaningful expressions (the syntax). Then you can use the procedure described in See How to Enter an Expression to modify a parameter.
In fact, you don't have to memorize a lot of math functions and parameter syntax. The Expression Editor automates part of the process as described next.
You can use expressions in any node parameter in RAYZ that features an Animation menu. Expressions can be specified in the Expression Editor, a floating panel that you can access from the Node Panel or from the Curve Editor:
To access the Expression Editor in the Node Panel, select Edit Expression from the parameter Animation menu or use the hotkey equivalent, Shift-e, while the cursor is over the parameter you want to modify. (See also Entering Expressions in the Curve Editor.)
The Expression Editor consists of a text entry field at the top, in which you can type an expression, and the Expression Browser at the bottom.
You can use the rules outlined in Writing Valid Expressions to type an expression into the field. However, you can also use the Expression Browser to help build the expression for you.
The Expression Browser lets you choose valid math functions, variables, and node parameters to use in an expression. When you select a category in the browser, a corresponding list appears in the middle pane.
When you select Math Functions, a list of math functions appears; when you select Variables, a list of variables appears, and when you select Node Parameters (as illustrated in Fig. C.1), a list of all nodes in the file appears.
When you select a node from the list in the middle pane, a list of all parameters in that node appears in the pane on the right.
C.2 Select any math function in the list to get a description.
Press the Evaluate button to find out if an expression is valid before closing the editor. If there is an error, you can modify the expression and press Evaluate again to check your changes.
There are two methods you can use to enter expressions in the Curve Editor. You can type expressions directly into fields in the Keypoint Viewer, which shows all animated curves in the graph, or you can use the same Expression Editor that is accessed from the Node Panel.
Follow these steps to use the Keypoint Viewer to enter expressions:
Follow these steps to take advantage of the Expression Editor when working in the Curve Editor view:
You can still open the Keypoint Viewer to view and edit expressions created in the Expression Editor, which is helpful when using expressions to control multiple parameter curves. |
You can use numbers, arithmetic operators, functions, variables, and parameter names to write expressions. Numbers and variables can be thought of as the "nouns" of the expression, while operators and functions act as the "verbs" that express the action to be performed. The numbers can be positive or negative, integers or decimal fractions (i.e., floating point notation).
Operations are evaluated in the following order:
Operators that have the same priority, such as multiplication and division, are evaluated in order, reading from left to right, as illustrated in the following examples:
A global variable is a name consisting of one or more uppercase letters, and each name starts with a dollar sign ($) to identify it as a variable.
Variables often represent a value that changes. The $F variable, for example, represents the current frame number. Many variables, like $F, are defined by the RAYZ system and cannot be changed.
The $JOB variable, on the other hand, which represents a directory path, can be redefined in Edit > Project Settings > Globals. You can also create your own global variables in the Project Settings panel, which will subsequently appear in the Expression Browser Variables list.
Global variables available in expressions include:
A number of other variables, including $PATH, $USER, $SHELL, $HOME, and $PWD, are also available. Refer to the list in the Expression Editor (click Variables in the Expression Browser) for the most up-to-date listing.
You can use any of the following functions in an expression by typing the function name followed by parentheses. Within the parentheses, you can put any numerical value, or any expression or variable that evaluates to a numerical value.
You can also use a parameter address in a function when you want to reference the values in another parameter (see Using Expressions to Reference Other Parameters). Some functions require multiple values, which are separated by commas.
All angles are in degrees unless otherwise noted.
You can use expressions to address other parameters, that is, to access the current value in another parameter. The referenced parameter can be in the same node or a different node, and the other node can be of the same type or a different type. You can enter the parameter name alone to use the value as is, or you can modify it using the operators and functions described previously.
The syntax used to reference parameters, at it simplest, is
That is, the unique name of the node, as specified in the Name field of the Node Panel, followed by the parameter name. Note the slash preceding the node name and the colon that separates the node name from the parameter name.
Assume, for example, that you have animated the brightness value of an image in a node named "bright_fix1" and you want to apply the same correction to another node image. You have connected the second image to a new Brightness node that you have named "bright_fix2." You would enter the following expression in the Brightness parameter of "bright_fix2" (see How to Enter an Expression if you need instructions):
/bright_fix1:brightness
C.3 Expression field for a keypoint in the Keypoint Viewer panel of the Curve Editor.
Now let's assume that you want to reference the brightness value of the Blue channel only. To reference an individual channel parameter within a parameter group, you would type the name of the master parameter followed by the sub-parameter name:
/bright_fix1:brightness.blue
This holds true for any type of parameter group, or any parameter with multiple value fields. To address a sub-parameter, type the master parameter name followed by the sub-parameter name, separated by a period.
There is a shortcut you can use when addressing another parameter in the same node. Leave out the node name and type the parameter name alone. For example, if you want to use the Blue channel brightness value in the brightness parameter for the Red channel:
brightness.blue
Dynamic parameter entries in Node Panel lists, such as track point entries in the Track node and input entries in Multi-comp are named according to the type of list, with each entry numbered in order of creation, starting from 0:
To reference the x coordinate data in the first track point in a node named "track1":
/track1:points[0].position.x
The following expression would reference the opacity parameter of the second input to a Multi-comp node named "multicomp1":
/multicomp1:inputlist[1].opacity
RAYZ uses the order of connection to number the input layers to Multi-comp. This means that the parameter name referenced will not change if you change the order of the layers in the composite. |
If you wanted to reference a node that is inside a Group node, add the name of the Group node to the front of the parameter address:
The following would reference the brightness parameter in a Brightness node named "brightness1" inside a Group node named "group1":
/group1/brightness1:brightness
As previously mentioned, you can modify the parameter value being referenced; that is, you can treat the parameter address like any other value in an expression that uses the operators and functions described above.
To reduce the overall brightness specified in the "bright_fix1" node example cited earlier, while still retaining the shape of the animation curve, you could modify the expression as follows (this would reduce the amount of change by 10 percent):
/bright_fix1:brightness * 0.9
To get the inverse of the brightness curve:
Fig. 1.0 - /bright_fix1:brightness
When referencing tracking or other position data, you can offset the position by adding or subtracting the distance of the offset, expressed as a percentage of total width or height:
/track1:points[0].position.x - 0.263
/track1:points[0].position.y + 0.387
Or you could use the min() function to get the smaller of two referenced parameter values:
min(/track1:points[0].position.x, /track1:points[1].position.x)
The $F variable, which returns the current frame number, can be used in a parameter address to specify that the values from specific frames be referenced. The variable should be in braces (curly brackets) at the end of the parameter name:
/bright_fix1:brightness{$F}
/bright_fix1:brightness.blue{$F}
/track1:points[0].position.x{$F}
The expressions above illustrate the syntax to use; in these cases, the result is the same as if the "{$F}" had not been appended. It becomes useful, however, when you want to specify a frame offset.
This expression, for example, would use the referenced parameter value from the previous frame as the current frame value in the parameter being modified:
/bright_fix1:brightness{$F-1}
This next example shows how you could use frame offsets to create a triangle filter to smooth the values of a track point:
(/track1:points[0].position.x{$F-1} * 0.25 + /track1:points[0].position.x{$F} * 0.5 + /track1:points[0].position.x{$F+1} * 0.25)
It adds a percentage (25%) of the values of the previous and next frame to (50 percent of) the current frame value to generate the smoothed value.
To access the parameter value from a specific frame, replace the $F variable with a specific frame number. This would return the brightness value at frame 6:
/bright_fix1:brightness{6}