Chalice Expression LanguageUsing Expressions in ChaliceChalice 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 ."
Writing ExpressionsAs 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. NumbersYou can use the integers and floating point numbers in Chalice expressions:
VariablesA 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 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. $JOBThis 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. $OPThis 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 OperatorsFollowing 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.
For example, in the following expression...
...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:
Other Examples
Math FunctionsYou 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.) Logarithmic / Exponential functions:Value Type Functions:These functions allow you to work with positive/negative, even/odd, and integer/floating point values. Dataflow Control Functions:These functions allow you to control the order in which commands are executed in Chalice. Interpolation FunctionsThe following interpolation functions generate smooth values between 1 and 0: Data Channel Access FunctionsYou 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) FunctionsThe 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:
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:
Similarly, the chf and cht functions are used to access animated parameter data or data from specific frames:
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:
Parameter (prm) FunctionsThe 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).
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:
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.
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):
To access the brightness value of frame 6 only, replace "$F" with "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):
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:
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":
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:
List Parameter (lprm) FunctionsThe 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:
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:
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 FunctionThe 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 .")
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":
Track FunctionsThe 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.
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":
The tracka function returns the difference between two frames of the angle formed by the track data.
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":
The tracksr function computes the difference in scale factors of track data between two frames, which you specify.
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:
|