Chalice Expression Language

Using Expressions in Chalice

Chalice enables you to use expressions, rather than a fixed numerical value, to modify the output of many nodes. You can apply functions to modify parameter values, animate values over time, and access channel data from other nodes.

You can use expressions in any node that features an Expressions checkbox in its node panel. When "Expressions" is checked, you can key expressions into the data entry fields of the node parameters.

Expressions are a very powerful way to customize and extend the capabilities of the Chalice system, but even novice users can take advantage of expressions by following the examples given in this manual.

For example, the Track node generates tracking data that can be accessed throughout the Chalice system whenever you need to reference selected pixel coordinates across a range of frames. You can use expressions to reference tracking data in a Corner Pin node to set the position of each corner. The basic steps for performing a four-corner pin using track data, including the exact expressions you need to use, are enumerated in the description of the Corner Pin Node in chapter 17, "Movement Nodes ."

Another instance in which you could reference tracking data is in the Pixel Meter node. To obtain the average RGBA values for the area tracked in a Track node, you would key an expression into the Pixel Meter node that accesses the track data to drive the pixel metering function. Then the resulting pixel meter data, too, could be referenced in other nodes by using the appropriate expression. For more information, see the Pixel Meter Node description in chapter 13, "Tool Nodes ."

Note:
Chalice also includes an Xpresso Node , in which you write expressions using Xpresso node syntax. The information you need to write Xpresso expressions is included in the node description in chapter 19, "Effects Nodes ."

Writing Expressions

As stated above, this manual includes complete expressions that you can use for several common operations. However, you can adapt these expressions or write other expressions by following the guidelines given in this appendix.

You can use numbers, variables, arithmetic operators, and functions to write Chalice expressions. Essentially, an expression tells Chalice how to modify an input or inputs to produce an output at that node in the network. 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.

Numbers

You can use the integers and floating point numbers in Chalice expressions:

  • Integers are the whole numbers: -1, 1, 2, 3, etc.
  • Floating point numbers are the decimal fractions: -1.1, 0.5, 1.25, etc.

Note:
Floating point numbers can also be expressed in exponential notation. Exponential notation refers to 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, you would use the exponent operator or the "pow" function.)

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.

You can use variables in Chalice expressions in place of specific numbers or other values. A variable is defined by the Chalice system and can represent a value that changes. For example, the $F variable represents the number of the current frame in a sequence.

You can use the following list of variables in Chalice expressions:

$F current frame number
$T current time, in seconds
$W current image width
$H current image height
$E value of e (2.7182818284590452354)
$PI value of pi (3.1415926535897932384)
$JOB Job directory (this variable is user definable)
$OP name of current node (used in Disk Output and Text nodes only)

$F and $T

$F is perhaps the most commonly used variable. It is typically used in numeric expressions to specify frames for modification, but it can also be used in the Disk Output node to embed frame numbers into filenames (see the description of the Disk Output Node in chapter 12, "I/O Nodes ," for more information).

Instead of $F, you may occasionally need to use the $T variable, which is suitable for subframe (floating point) operations. Using a frame rate of 30 fps as an example, at frame 60 the $T variable would represent 2 seconds.

$JOB

This variable is used in the Disk Input and Disk Output nodes to help define the directory path of source imagery and output imagery.

The default location of the Job directory is the directory from which you started Chalice. Unlike the other variables listed here, you can change the definition of $JOB. For more information, see "Setting Global Variables " in chapter 6.

$OP

This variable is used only by the Disk Output and Text nodes. It represents the name of the current node and is used as part of the filepath specification (in Disk Output) or for diagnostic display purposes in the Text node.

Refer to the relevant node descriptions for more information.

Arithmetic Operators

Following is a list of the arithmetic operators available for writing Chalice expressions and some examples that illustrate their use.

The operators are listed in order of precedence; that is, in the order by which they are evaluated in the expression, from first to last.

Operations in parentheses are evaluated first; logical operations are evaluated last. All operators with the same priority are evaluated from left to right.

( ) Operations in parentheses
- Negation (i.e. 3 + -3, which evaluates to 0)
* / ^ % Multiplication, division, exponent and modulus
+ - Addition and subtraction
Logical operators:
> greater than or equal to
< less than or equal to
!= not equal to
== equal to
|| or
&& and
! not; negation
Note:
In general, you should avoid comparing floating point numbers for equality--do not use the conditional operator " ==" with floats. Round-off errors can cause very small (10e-8) inaccuracies in floating point calculations.

For example, in the following expression...

Expression: Result:
3 + 4 * 5 23

...the "multiply," 4 * 5, is evaluated first; then the result, 20, is added to 3.

To multiply the result of 3 + 4, or 7, by 5--that is, to evaluate the add operation first--you would enclose the addition operation in parentheses, as follows:

Expression: Result:
(3 + 4) * 5 35

Other Examples

Expression: Result:
2 * 3 ^ 2 + 4 * 6 / 2 48

That is, 36 plus 12:
2 * 3 = 6, and 6 ^ 2 = 36
4 * 6 = 24, and 24 / 2 = 12
36 + 12 = 48

Expression: Result:
( (3 + 4) * 5 - 5) / 6 5

That is, 30 divided by 6:
3 + 4 = 7, and 7 * 5 = 35
35 - 5 = 30, and 30 / 6 = 5

Expression: Result:
13 % 5 + 13 / 5 5.6

That is, 3 plus 2.6:
13 % 5 = 3 , and 13 / 5 = 2.6
3 + 2.6 = 5.6
Note that "13 % 5" is read as "13 modulo 5"; 3 is the remainder of dividing 13 by 5.

Math Functions

You can use the following math functions in Chalice. Input can be a numerical value or an expression that, when evaluated, will result in a numerical value. Unless otherwise specified, a value can be in integer or floating point form.

Trigonometric Functions:

(All angles are in degrees unless otherwise noted.)

acos(val) Trigonometric arccosine of val.
e.g. acos(0) = 90
asin(val) Trigonometric arcsine of val.
e.g. asin(0.866025) = 60
atan(val) Trigonometric arctangent of val.
e.g. atan(1.73205) = 60
atan2(float y, float x) Compute the arctangent of y/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 the case where x is zero correctly, returning 90 or -90.
e.g. atan2(1, 0) = 90
atan2(0, 1) =0
atan2(0, -1) = 180
asin(val) Trigonometric arcsine of val.
e.g. asin(.866025) = 60
cos(val) Trigonometric cosine of val.
e.g. cos(60) =.5
cosh(val) Hyperbolic cosine of val.
rad(val) Convert val to radians (val is in degrees).
e.g. rad(180) = 3.1415926
sin(val) Trigonometric sine of val.
e.g. sin(60) = 0.866025
sinh(val) Hyperbolic sine of val.
sqrt(val) Square root of val.
e.g. sqrt(144) = 12
tan(val) Trigonometric tangent of val.
e.g. tan(60) = 1.73205
tanh(val) Hyperbolic tangent of val.
deg(val) Convert val to degrees (val is in radians).
e.g. deg($PI) = 180

Logarithmic / Exponential functions:

exp(val) Logarithmic exponentiation function (eval).
e.g. exp(2) = 7.38906
log(val) Natural logarithm of val.
e.g. log(2.718281828) = 1
log10(val) Logarithm base 10 of val.
e.g. log10(10)= 1
pow(float base, float exponent) This computes the base to the power given.
e.g. pow(2, 3) = 8

Value Type Functions:

These functions allow you to work with positive/negative, even/odd, and integer/floating point values.

abs(val) Absolute value of val.
e.g. abs(-2.6) = 2.6
clamp(val, min, max) Clamps the value between min and max. Used to prevent val from going outside the specified range.
even(val) Returns 1 if val is even, 0 if val is odd
odd(val) Returns 0 if val is odd, 1 if val is even.
floor(val) Returns the largest integer smaller than val.
e.g. floor(2.78135) = 2
int(val) Integer value of val by truncating.
e.g. int(2.6) = 2
int(-2.6) = -2
min(val1, val2, ...) Returns the smallest value listed.
max(val1, val2, ...) Returns the largest value received.
pulse(val, min, max) Creates an on/off pulse. If the value is less than min or greater than max, pulse returns 0, otherwise it returns 1.
sign(val) Returns -1 if the val is negative and +1 if val is positive.
smooth(val, min, max) Returns a smooth interpolation between 0 and 1. If val is less than min it returns 0, if val is greater than max it returns 1.
e.g. smooth($F, 12, 55)
This generates an ease-type curve between values 0 and 1 starting at frame 12, and ending at frame 55.
trunc(val) Truncates all digits to the right of the decimal
e.g. trunc(4.5678) = 4
wrap(val, min, max) Resulting value always falls between min and max. It creates a sawtooth wave for continuously increasing and decreasing values of the value.

Dataflow Control Functions:

These functions allow you to control the order in which commands are executed in Chalice.

if(exp, true_val, false_val) Returns true_val if exp is true, and false_val if exp is false.
e.g. if($F > 12, $F, 12)
This will send back the value 12 unless $F is greater than 12, in which case it will return the current frame number.
block(exp1; exp2; ...) The block function instructs Chalice to execute the series of expressions sequentially at each pixel. Chalice normally executes a command at all pixels in the screen before moving to the next expression

Interpolation Functions

The following interpolation functions generate smooth values between 1 and 0:

bezier() Interpolates the in and out point by fitting a bezier curve using the slopes and accelerations.
cubic() Interpolates the in and out point using the slopes. This results in a cubic polynomial.
constant() Constant value of the in point.
ease() Values ease in smoothly starting at 1 and ease out smoothly at 0.
easein() Ease in smoothly at the start only.
easeout() Ease out at the end only.
easep(val) An ease-in/ease-out curve which is weighted by the power. This weighting has the effect of shifting the inflection point.
easinp(val) Same as easep() but it is an ease-in curve.
easeoutp(val) Same as easep() but it is an ease-out curve.
linear() Straight line interpolation from 1 to 0.
noise(x,y,z) Generates random value given a position in space. Nearby positions will have similar values.
quintic() Interpolates the in and out point using slopes and accelerations. This results in a quintic (degree 5) polynomial.
rand() Generates random values between 0 and max at random locations in an image.
smooth(float val, float min, float max) The return value is a smooth interpolation between 0 and 1. When the value is less than the minimum, the return value is 0. If the value is greater than the maximum, the return value is 1.
e.g. smooth($F, 12, 55)
This will generate an ease-type curve between values 0 and 1, starting at frame 12 and ending at frame 55.
turb(x,y,z, depth) Like the noise function, but allows for fractalization of the noise. Thus, at a depth of three, the noise will be fractalized three times.

Data Channel Access Functions

You can use these functions to access parameter data from another node. Some function types, such as the ch (channel) and prm (parameter) functions, can be used generally; others, such as the meters function, the track functions, and the lprm functions, enable you to reference parameters specific to a particular node type.

Items in brackets indicate available choices; for example, in the track function, "[xv|yv]" indicates that you can use "xv" or "yv." Also, be aware that if you use the ch functions, you must enclose the node/channel name in quotes, as shown in the examples. (This is not necessary for the other data channel access functions.)

Channel (ch) Functions

The ch functions have been included in Chalice since the first version of the software was released. They have since been augmented by the parameter functions, which offer more flexibility in data access. The ch functions are still a fast and easy way to access node data from nodes that do not offer multiple datasets.

The ch, chf, and cht functions allow you to reference parameter data from any other node:

ch("node_name/channel_name")
chf("node_name/channel_name", frame#)
cht("node_name/channel_name", time)

For example, you might want to use the "brightness" value from a node called "brightness1" in other Brightness nodes. Using the ch function you would enter the following to access the data:

ch("brightness1/brightness")

Similarly, the chf and cht functions are used to access animated parameter data or data from specific frames:

chf("brightness1/brightness", $F)

To access a specific value from a parameter with more than one associated value field ( x and y coordinates, e.g.), use the exact parameter field names as listed in the STED. Using the Translate parameter in the Transform node as an example, the following would access the x value:

ch("transform1/translatex")

Tip:
To find out the exact parameter field name to use, refer to the name used in the STED window list for the parameter.

Parameter (prm) Functions

The prm functions allow you to reference parameter data from any node in the network, including parameters that contain more than one entry (unlike the ch functions).

prm(node_name, parm_name, value_index)
prmf(node_name, parm_name, value_index, frame#)
prmt(node_name, parm_name, value_index, time)

The parm_name refers to the name of the specific node parameter to be referenced, e.g., "brightness." (Chalice recognizes the same parameter name that is used in STED for that parameter.)

The value_index refers to a specific type of value within that parameter, as when you need to specify the x value in a parameter consisting of a pair of x,y coordinate values. For parameters that have only a single value to reference, 1 is always used as the value index. (Multiple-field parameters are explained later in this description.)

Notice that the prm functions use a slightly different syntax than the ch functions. The names of the node and parameter being accessed are not enclosed in quotation marks. Additionally, they are separated by a comma instead of a slash. Using the same brightness parameter example from the ch function description above, to access this data using the prm function you would enter the following:

prm(brightness1, brightness, 1)

In the above example, "brightness1" is the node name and "brightness" is the name of the parameter that holds the brightness value. Note that if the node name includes spaces, you must surround the node name with quotation marks.

Correct: prm("very bright", brightness, 1)
Wrong: prm(very bright, brightness, 1)

Data channel access functions offer several advantages. First, if you need to tweak values later, any change you make to the referenced Brightness node settings will be reflected in all other nodes that access the data.

Second, the prmf and prmt functions allow you to access parameter values that have been animated, or to access a parameter value at a specific frame. The following example will access the brightness parameter value for the current frame ($F):

prmf(brightness1, brightness, 1, $F)

To access the brightness value of frame 6 only, replace "$F" with "6":

prmf(brightness1, brightness, 1, 6)

Third, you can adjust the brightness level in the other Brightness nodes by modifying the prm function and still maintain the shape of the curve over time, perhaps to give different layers of a composite slightly higher or lower brightness levels (this example lowers the brightness by 20 percent):

prmf(brightness1, brightness, 1, $F) * 0.8

The prmf and prmt functions also allow you to create a frame offset for the accessed data. The next example creates a six-frame delay by specifying the current frame using the $F variable and then adding 6:

prmf(brightness1, brightness, 1, $F + 6)

Note:
It is recommended that you use either the prmf or prmt function consistently in a grail file, but not both. Due to the nature of floating point math, two expressions that are the same, except that one uses prmt and one uses prmf, may produce different results. (The same holds true for the chf and cht functions.)

The brightness parameter, which has been used in the examples so far, only holds one value. However, to access a Sample Color parameter that holds separate values for R, G, and B, sequential value index numbers are used to indicate the value field to access. In this case, "sample, 1" would be used to reference the Red channel data, "sample, 2" to reference the Green channel, and "sample, 3" for the Blue.

In the Transform node, the Scale, Translate, and Pivot parameters each contain value fields for x and y coordinates. To reference x and y values for a parameter, use 1 as the value index for the x value and 2 as the value index for the y value. The following obtains the y value from the Translate parameter in a node named "transform1":

prm(transform1, translate, 2)

Note:
For multiple-field parameters that hold a pair of coordinate values, the STED will list the parameter name as (using the above Transform parameter example) "translatex" or "translatey." To reference these or any similar parameters in prm functions, use the name as it appears in the STED, but without the "x" or "y" appended. To indicate which coordinate value to reference, use the appropriate value index number instead.

To specify the frame for which to obtain the value, you would use prmf. In this case, the prmf function would return the y translate value at the current frame:

prmf(transform1, translate, 2, $F)

List Parameter (lprm) Functions

The lprm functions allow you to reference parameter values from nodes that create a list of entries with the same parameter options, such as Mcomp, which lists its inputs. These functions allow you to specify which entry in the list Chalice should reference:

lprm(node_name, list_name, list_index, parm_name, value_index)
lprmf(node_name, list_name, list_index, parm_name, value_index, frame#)
lprmt(node_name, list_name, list_index, parm_name, value_index, time)

The list_name refers to the type of list entry, such as "inputs" for the Mcomp, Zcomp, Sequence or Exec nodes; "points" for the Track node; or "pixelMeters" for the Pixel Meter node. (The table below shows the specific names to use for each type of list.)

The list_index refers to the index number of the list entry you have selected. For example, the fourth input to an Mcomp node would have a list index of 4. The list index has a range of 1-n, where n represents the total number of entries in the list.

The parm_name refers to a specific parameter of the list entry to access, such as "start" for a Sequence node input or "pos" (position) for a pixel meter in a Pixel Meter node. For example, an expression that obtains the transparency value from the second input to a node titled "mcomp1" would be written as follows:

lprm(mcomp1, inputs, 2, transp, 1)

In some cases, the parameter may include more than one value. For example, the "pos" parameter for each "pixelMeters" entry contains both x and y values. You use the value_index to specify which value to use. For the "pos" parameter, you would specify "pos, 1" for the x coordinate or "pos, 2" for the y coordinate.

The index values for each parameter type are given in the table below:

Meters Function

The meters function allows you to reference a specific channel of pixel meter data from a Pixel Meter node. Pixel meter data consists of averaged RGBA values for a specified area in an image. (See also the Pixel Meter Node description in chapter 13, "Tool Nodes .")

meters(meters_node_name, pixel_meter#, channel#, frame#)

The following example would reference the red channel data (0) at the current frame ($F) from the first pixel meter (1) of a node named "meters1":

meters(meters1, 1, 0, $F)

Track Functions

The Track functions--track, tracka, and tracksr--enable you to access pixel coordinates from track point data, or to compute the difference in angle or vector described by track point coordinates.

The track function allows you to reference pixel coordinate data from a Track node in the current expression.

track(track_node_name, [xv|yv], point#, frame#)

To use the track function, specify the name of the Track node, the X-axis (xv) or Y-axis (yv) values, the track point from which to take the values, and the frame number. The following example references the X-axis values (xv) for the current frame ($F) of the first track point (1) in a node named "track1":

track(track1, xv, 1, $F)

The tracka function returns the difference between two frames of the angle formed by the track data.

tracka(track_node_name, point1#, point2#, ref_frame#, cur_frame#)

The Track node being referenced must have at least two track points to obtain the vector used in the comparison. You specify which two track points to use to obtain the vector as well as the reference frame and the current frame to be compared.

The following example computes the difference in angle of the vectors formed by track points 2 and 3 between frame 1 and the current frame ($F) of a node named "track1":

tracka(track1, 2, 3, 1, $F)

The tracksr function computes the difference in scale factors of track data between two frames, which you specify.

tracksr(track_node_name, [scale|xscale|yscale], ref_frame#, cur_frame#)

  • If you use "scale," the tracksr function measures the distance between the two track points at each of the two frames you specify in the expression and computes the difference.
  • "Xscale" uses the distance between track points along the horizontal axis.
  • "Yscale" uses the distance between track points along the vertical axis.

The Track node being referenced must have two track points to obtain the distance used in the comparison. If the node has more than two track points, the tracksr function will use the first two points.

The following example, which assumes a Track node named "track1," would calculate the distance between the first two track points at frame 1 and again at frame 25 and return the difference between the two distance values:

tracksr(track1, scale, 1, 25)




Table of Contents | Index



Copyright 1996-1999 by Silicon Grail Corporation