Using Expressions
If the parameter supports expressions, an = icon appears to the right of the parameter.
Once enabled, an Expression Editor (code editor) opens.
Single Line Display
In single line mode, press Enter or Tab to set the entered expression.
Note: When an expression is enabled, the Animate (clock) icon to the left of the label is grayed out, the value field is disabled, and the evaluated value is displayed.
Multi-Line Display
If you need more than one line for scripting, click the down icon
and a multi-line display opens.
In multi-line mode, press Esc to set the entered expression.
Linking Parameters
By linking variables and parameters, you can access information in any node and use it in a different node.
Link A Parameter In The Same Node
• Drag and drop from one parameter name to another.
or
• Type the script id into the Expression Editor and press Enter or Tab. When using a multi-line display, press Esc to enter the expression.
Note: To determine the script id, hover over the parameter name and the script id is displayed in the status bar at the bottom left of the user interface.
Link A Parameter From A Different Node
• With a parameter window open for each node, drag and drop a parameter name in one node to another parameter name in the other node.
or
• Select Copy Expression Reference from the node source parameter options (... icon), activate Enable Expression on the target node parameter, click in the expression field and paste the result.
or
• Enter the node name followed by a period, followed by the script id. For instance, if you want to use the Brightness parameter from the Color Correct 1 node, your expression would be Color_Correct_1.brightness.
Linking A Parameter At A Different Frame
Ordinarily, links to another parameter produce that parameter’s value at the current frame. If the parameter is animated and you want to obtain a value at a specific frame, you can use the following syntax to view a value at a different frame: self.property('saturation').getValue(frame+1). This fetches the value of saturation at the next frame.
Show Which Nodes Are Connected Via Expressions
Click the = icon at the top of the Trees window to show which nodes are connected via expressions.
Display Expression As A Curve
You can visualize the expression as a curve by enabling keyframing for the parameter prior to enabling its expression and then activating the parameter’s Curve icon in the Timeline.
Motion Blur Controller Expression Action
The Create > Motion Blur Controller action creates a Motion Blur node which controls all other node’s motion blur settings using expressions. The controller includes Enable, Angle, Phase, and Samples parameters, with values defaulting to the first motion blur enabled node settings it finds. It then creates expressions for all nodes in the tree that have motion blur parameters.
Operators, Variables and Samples
Arithmetic Operators
Keyword | Description |
|---|---|
* | Multiply |
/ | Divide |
+ | Add |
- | Subtract |
See Python Mathematical Functions for a complete list of supported arithmetic operators.
Variables
Variable | Description |
|---|---|
self | The current object |
time | The current time in seconds |
frame | The current frame |
parent | The parent object (same as self.parent) |
node | The current node |
session.width, session_height | The session width and height |
random() | Returns a random number in the range 0–1 |
gaussRandom(min=0, max=1, seed=<current_frame>) | Returns a random number. The results have a Gaussian (bell-shaped) distribution. |
wiggle(frequency, amplitude, octaves=1, amp_mult=0.5, lacunarity=1.0, time=<current_time>) | Wiggles an object across random values |
Noise Functions
Function | Description |
|---|---|
noise(t) | Generates 1D simplex noise, the building block of Perlin noise |
noise2D(point) | Generates 2D simplex noise, the building block of Perlin noise |
noise3D(point) | Generates 3D simplex noise, the building block of Perlin noise |
Point 3D Functions
Functions | Description |
|---|---|
Point3D.angle(point) | Returns angle in degrees between self and point |
Point3D.cross(point) | Returns the cross product with point as a Point3D |
Point3D.dot(point) | Returns the dot product with point as a float |
Point3D.lerp(p, t) | Returns the interpolated position along (self, p) at t |
Point3D.normalize() | Returns the normalized Point3D |
Point3D.perpendicular() | Returns a perpendicular vector to self |
Point3D.rotate(angle, origin=(0,0,0)) | Returns a new Point3D |
Sample expressions
Expression | Description |
|---|---|
saturation | Uses the value of the current object’s saturation property at the current time |
self.property('saturation').getValue(frame+1) | Fetches the value of saturation at the next frame |
Roto_1.alpha_invert | Fetches the value of the Alpha > Invert property for the node named Roto 1 |
Transform_1.scale.x | Uses the X value from the Transform 1 node Scale parameter |