Appendix C: Using Expressions in RAYZ

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.

In This Chapter

How to Enter an Expression

Writing Valid Expressions

Using Expressions to Reference Other Parameters

The Benefits of Using Expressions

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 Easy to Use

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.

How to Enter an Expression

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:

Using the Expression 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.)

 Image showing the Expression Editor.

C.1 Expression 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.

Expression Browser

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.

 Image showing the math function info readout in the Expression Editor.

C.2 Select any math function in the list to get a description.

Evaluate Button

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.

Entering Expressions in the Curve Editor

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:

  1. Display the parameter you want to modify in the Curve Editor graph and open the Keypoint Viewer panel, which is accessed from the Tools menu in the title bar of the Curve Editor.
  2. Ctrl-click on the curve to add a keypoint, which should be positioned one frame past the end of the frame range you want to affect. This defines the curve segment between the keypoints to which the expression will be applied.
  3. Right-hold on the curve and select "Expression" from the popup menu An Expression field will appear for the curve in the Keypoint Viewer.
  4. Type the expression into the field. When entering similar expressions in multiple fields, you can copy and paste (Ctrl-c, Ctrl-v) them, editing the copies as necessary.

Follow these steps to take advantage of the Expression Editor when working in the Curve Editor view:

  1. Display the parameter you want to modify in the Curve Editor graph.
  2. Ctrl-click on the curve to add a keypoint, which should be positioned one frame past the end of the frame range you want to affect. This defines the curve segment between the keypoints to which the expression will be applied.
  3. Right-hold on the curve and select "Expression" from the popup menu.
  4. Right-hold on the curve again, and the popup menu will now offer the "Edit Expression" option. Select it from the menu to open the Expression Editor.
  5. Type the expression in the field or use the Expression Browser to access valid math functions and node parameter syntax.

Tip:

 

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.

Writing Valid Expressions

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).

Note:

 

Floating point numbers can also be expressed in exponential notation, a shortcut you can use to express large numbers. For example, 3.2e-5 is equivalent to 0.000032. (To actually compute a number as an exponent, however, you would use the exponent operator or the pow function.)

Operators

Operations are evaluated in the following order:

( )

operations in parentheses are evaluated first

^

then exponents

* / %

* multiplication, / division, and % modulus next

+ -

+ addition, - subtraction last

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:

Sample Expression

Result

Description

3 * 4 / 5

2.4

Multiplication and division have the same priority, but the multiply operator occurs first in the expression, so 3 * 4 = 12, and 12 / 5 = 2.4.

3 + 4 * 5

23

The multiply operation, 4 * 5, is evaluated first and the result, 20, is added to 3.

(3 + 4) * 5

35

The add operation is evaluated first because it is in parentheses: 3 + 4 = 7, and 7 * 5 = 35.

2 * 3 ^ 2 + 4 * 6 / 2

30

Since the add operation is evaluated last, this expression is equivalent to 18 + 12. That is, 3 ^ 2 = 9, and 9 * 2 = 18. And on the other side of the plus sign, 4 * 6 = 24, and 24 / 2 = 12.

( (3 + 4) * 5 - 5) / 6

5

Innermost parentheses are evaluated first: 3 + 4 = 7. Then the operations in the outer parens: 7 * 5 = 35, and 35 - 5 = 30. Finally, 30 is divided by 6.

13 % 5 + 13 / 5

5.6

The result of 13 % 5, which is 3, is added to the result of 13 / 5, which is 2.6, to get 5.6.

Note: "13 % 5" is read as "13 modulo 5." This operator divides the first number by the second and returns the remainder: 3 is the remainder of dividing 13 by 5.

Variables

A variable is a name consisting of one or more uppercase letters, and each variable name starts with a dollar sign ($) to identify it as a variable. Variables are defined by the RAYZ system and often represent a value that changes.

You can use the $F variable in RAYZ 2.0, which represents the current frame number.

Functions

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.

Function

Description

Example

abs(val)

Returns the absolute value of val.

abs(-2.6) = 2.6

clamp(val, min, max)

Clamps the range to min through max. Used to prevent val from going outside the specified range. Val is usually a variable or a pointer to another parameter.

clamp(1.2, 0, 1) = 1

floor(val)

Returns the largest integer smaller than val.

floor(2.78136) = 2

min(val1, val2, ...)

Returns the smallest val in the list. Can be used to get min of two referenced parameters, or of a referenced parameter and a specific value.

min(2, 7, 1.6) = 1.6

max(val1, val2, ...)

Like min() function listed above, but returns the largest val in the list.

max(-1, 0.1) = 0.1

pulse(val, min, max)

Creates an on/off pulse. If val is less than min or greater than max, pulse returns 0, otherwise it returns 1.

pulse(1, 0, 0.5) = 0

trunc(val)

Truncates all digits to the right of the decimal in val.

trunc(4.567) = 4.0

Logarithmic/Exponential functions

Function

Description

Example

exp(val)

Logarithmic exponentiation function.

exp(2) = 7.38906

log(val)

Natural logarithm of val.

log(2.718281828) = 1

log10(val)

Logarithm base 10 of val.

log10(10)= 1

pow(base, exponent)

Computes base to power given.

pow(2, 3) = 8

Trigonometric Functions

All angles are in degrees unless otherwise noted.

Function

Description

Example

acos(val)

Trigonometric arc cosine of val.

acos(0) = 90

asin(val)

Trigonometric arc sine of val.

asin(0.866025) = 60

atan(val)

Trigonometric arc tangent of val.

atan(1.73205) = 60

atan2(float y, float x)

Compute the arc tangent of y and x.

This is more stable than atan() since it can use the signs of y and x to determine the quadrant the angle is in. It also handles correctly the case where x is zero, returning 90 or -90.

atan2(1, 0) = 90

atan2(0, 1) = 0

atan2(0, -1) = 180

cos(val)

Trigonometric cosine of val.

cos(60) = 0.5

cosh(val)

Hyperbolic cosine of val.

 

rad(val)

Convert val to radians (val is in degrees).

rad(180) = 3.1415926

sin(val)

Trigonometric sine of val.

sin(60) = 0.866025

sinh(val)

Hyperbolic sine of val.

 

tan(val)

Trigonometric tangent of val.

tan(60) = 1.73205

tanh(val)

Hyperbolic tangent of val.

 

Using Expressions to Reference Other Parameters

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.

Parameter Names Used in Expressions

The syntax used to reference parameters, at it simplest, is

/node:parameter

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

Tip:

 

The parameter name RAYZ recognizes is the same name listed for the parameter in the Keypoint Viewer of the Curve Editor. When in doubt, you can find out the correct name to use by viewing the node in a Curve Editor.

Image showing the Keypoint Editor with expression in expression field and parameter name reference indicated.

C.3 Expression field for a keypoint in the Keypoint Viewer panel of the Curve Editor.

Sub-parameters

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.

Parameters in the Same Node

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 Parameters

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:

/node:listentry[n].parameter

Note:

 

The name that you give the entry in the Node Panel, as when you give each track point a distinctive name such as "bottom_left_corner," does appear in the Curve Browser to help you identify the parameters. However, the name used to address the parameter in an expression is determined by RAYZ. This is the name used to label the corresponding parameter in the Keypoint Viewer.

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

Note:

 

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.

Parameters in Group Nodes

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:

/group_node/node:parameter

The following would reference the brightness parameter in a Brightness node named "brightness1" inside a Group node named "group1":

/group1/brightness1:brightness

Modifying Referenced parameter Values

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)

Specifying Values by Frame

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}