Simple Expressions
To set up a Simple Expression just right-click on the tool's input you'd like to modify and select 'Expression'. Or type '=' in the field and hit 'Return'.
Simple Expressions are written in LUA like InTool-scripts but are limited to a single line of code.
Syntax
Get Value from specific time / frame
To connect the value of a control (like BC1's Brightness) to another tool's control value (like CC1's Gamma in our example), but only want to use CC1's Gamma from one specific frame, put the following into the simple expression on BC1's Brightness:
To get the X-coordinate of a point from the previous frame:
To get the X-coordinate of a 3D ImagePlane node from the previous frame (works with all 3D-Ops)
To get the text from a Text+ tool at time 0:
To get the value of a control on the same tool at a different time, use the self notation:
Using if-then-else
To toggle a value based on a condition (e.g. an if-then-else expression), use the iif() function. This will set the input's value to 1 if Merge1.Blend is greater than 0.5 and to 0 if otherwise:
Alternatively, the following Lua conditional expression also works:
Using expressions on point controls
Point controls (e.g. Center) require a two-dimensional value. To assign a single value to either the X or Y axis, use the Point(x,y) syntax. This will connect BC1.Gain to the X coordinate:
Some typical examples when you want not only connect, but modify the coordinates you use for a point:
Point(Transform.Center.X, Transform.Center.Y)
Point(Path.Position.X, Path.Position.Y)
Point(Tracker.SteadyPosition.X, Tracker.SteadyPosition.Y)
Point(Tracker.UnsteadyPosition.X, Tracker.UnsteadyPosition.Y)
If the value you want to reference is already a point, you do not need to specify .X and .Y:
Disabling or commenting
"--" in the string will prevent evaluation of anything to the left. This is good for commenting or disabling a part of a simple expression.
Avoiding name clashes
It is a bit unlikely that you run into this, but it might happen, so here is how to get around it. Imagine a comp with a BG tool, followed by a Transform and a Text+, merged over the Transform. You want to use the Text+ to display the Transform's angle value. So you would set up an expression in the Text+'s Styled Text saying
Unfortunately the Text+ will fail. This is because you're running in a name clash. There's actually an input on Text+ tools called "Transform1". It's the "Transform" twirly control on the Element 1 page in the Shading tab. If you try Text(Transform1), you'll get "0", and when you open the twirly you'll get "1". Input names always get priority, this is why Transform1 (through to Transform8) don't deliver the expected result. If you rename the transform tool to e.g. "Xf1",
works just fine.Math-related Expressions
Linear Interpolation (LERP)
Did you ever feel the need to place a 3D element in between two other elements in X, Y and Z? And even better use a slider to specify the exact position of the middle element in between the start and end element? Check out the Lerp_Distance comp and play with the position slider on the myMiddle shape. Given the positions of the myStart and myEnd shape the LERP expression looks like this:
myStart.Transform3DOp.Translate.X * (1 - Position) + myEnd.Transform3DOp.Translate.X * Position
myStart.Transform3DOp.Translate.Y * (1 - Position) + myEnd.Transform3DOp.Translate.Y * Position
myStart.Transform3DOp.Translate.Z * (1 - Position) + myEnd.Transform3DOp.Translate.Z * Position
For X, Y and Z respectively. This could e.g. be used to roll your own customizable 3D Lensflare as in this very basic example.
If you want smoothstep instead, try:
myStart.Transform3DOp.Translate.X * (1 - (Position * Position * (3 - 2 * Position))) + myEnd.Transform3DOp.Translate.X * (Position * Position * (3 - 2 * Position))
Differentiate (slope of a spline)
If you want to know the slope of a spline at a certain time, the speed of an animation if you will, then use a formular similar to these:
TimeStretcher1:GetValue("SourceTime", time+0.5)-TimeStretcher1:GetValue("SourceTime", time-0.5)
self:GetValue("SourceTime", time+1)-self:GetValue("SourceTime", time)
As stated in the example, this is especially useful to determine the speed of a speed ramp. They can easily be added to a user input that has been added to the tool via the User Controls tool script.
Orient towards the pivot
Use this expression on a transform tool's angle to automatically rotate the image towards the pivot when you drag the center around:
(1280/720 is the input image's aspect ratio. Of course this needs to be adjusted if your input image has a different resolution).
2D Track to 3D Nodal Pan
These expressions on a Camera3D's rotation inputs will turn a 2D track (called "Tracker1" in this example) into a nodal pan. Works for pan and tilt moves. Focal length can be set arbitrarily. Same for the film back, although the ratio of horizontal and vertical aperture has to match the image aspect ratio!
-- X Rotation:
math.atan(25.4 * ApertureH * (Tracker1.SteadyPosition.Y-0.5) / FLength) * (180 / math.pi)
-- Y Rotation:
-math.atan(25.4 * ApertureW * (Tracker1.SteadyPosition.X-0.5) / FLength) * (180 / math.pi)
Metadata
Retrieving Composition Settings for Slates
Almost all of the composition attributes available through the comp:GetAttrs() function are also available to simple expressions. Values like the render start and end, global start and end, quality, comp name, and comp path are enormously valuable for creating slates and informative overlays.
For example, the attribute COMPS_Name is accessible to a simple expression as comp.Name. The current Render Start Time (COMPN_RenderStart) would be comp.RenderStart in a simple expression. Simply remove the start of the COMP?_ part of the attributes name.
For example, to set a Text tool to print the start and end render frames
All of the standard eyeonscript library functions are available as well. So a more complex example might print the name of a composition in lowercase using the following expression;
Of course you can also access environment variables. This can be used to create a watermark with the name of the render slave that rendered a frame:Show Metadata
To display KeyCode info from a DPX, Cineon or OpenEXR files in a Text+, select Expression on the Text+'s textfield and enter the following into the expression field (assuming your files are in Loader1):
Show Metadata II
Sometimes you want to access non-standard (as opposed to standard DPX) metadata embedded in e.g. RED files. To display these in your Text+, enable your metadata subview, look for the entry you need (like e.g. "TimeCode") and enter the following into the expression field (assuming your files are in Loader1):
However, this only works for simple expressions, as in these cases the current time of the composition is implied. If you want to extract the MetaData in a script you have to somehow specify the time:Get the pixel aspect ratio of a tool
The aspect ratio of a tool is found in the XScale and YScale parameters of the input's image object. For example you can apply this expression to Text.PixelAspect on a Text tool:
Get the bit depth of an input
If you're writing macros you might want to convert the image to float internally using a ChangeDepth node and back to the original bit depth at the end of your macro. A tool's bit depth can be retrieved with tool.Input.Depth in an expression. Values range from 5 to 8 (int8, int16, float16 and float32 respectively). ChangeDepth's "Depth" multibutton counts from 1 to 4, so use this expression on the buttons to set the bit depth to that of another tool:
Setting the Gamut Source Space from the metadata
A Gamut tool can set the Source Space automatically from the input using this expression set to the Source Space input.
Miscellaneous
Correctly scale your ImagePlanes
You want to scale your ImagePlanes according to the size of the image feeding them? Easy to do. Just add a simple Expression to your ImagePlane's Scale saying
Assuming your reference size is a PAL image, all other imageplanes will scale according to that size. Check out the comp: SE_3Im_SizeImage width and height
You can use the input image's width and height in your expressions. But take care! The width and height attributes contain the actual pixel size of the image in the current proxy resolution. If you want to create a Background with the dimensions of another tool, for example, you should use OriginalWidth and OriginalHeight instead. They contain the unproxied resolution.
Input.OriginalWidth -- for example 1920
Input.OriginalHeight -- for example 1080
Input.Width -- in proxy 2 mode this would contain 960
Input.Height -- and this would contain 540
Getting the savers filename as text
Obtaining the Saver tool's filename can be done using the Clip object's FileName member. For example, the following Simple Expression could be applied to a Text tool's StyledText input.
Proxy testing
Some tools process a number of iterations or some other parameter that you might want to adjust based on Proxy/AutoProxy. Testing the Proxy state of a comp can give you a per-control proxy setting.
orCropping to the DoD
The DoD of an image can be found using the DataWindow table. This can be used to set a Crop to the DoD.