Expressions

Expressions

Time

Expressions related to time & frame counts

Image

Expressions related to the size of images. Note that not every node uses the ID Input for its image inputs.

Point

Expressions related to the size of images

If

Conditional expression patterns

Scripts

You can embed full lua scripts in expressions with the : syntax.

:                                    -- begin script
local str = "Hello Lua!";            -- define a local variable
return Text(str);                    -- the "output" of the expression script

Linear Interpolation

Linear Interpolation (lerp) blends betwen two numbers. Wikipedia

:
-- lerp function:
-- a = first number
-- b = second number
-- t = [0..1] where 0=a and 1=b
local function lerp(a,b,t) return a + (b-a)*t; end;

-- use lerp() to blend between two values based on a Blend slider
local result = lerp(LowValue, HighValue, Blend);

-- output result
return result;

Quick copy & paste snippet

local function lerp(a,b,t) return a + (b-a)*t; end;                                      -- Number Interpolation
local function lerpxy(a,b,t) return Point(a.X + (b.X-a.X)*t, a.Y + (b.Y-a.Y)*t); end;    -- Point Interpolation

Inverse Linear Interpolation

Find a position t between two numbers.

:
-- unlerp function:
-- a = first number
-- b = second number
-- c = a number typically between a and b
local function unlerp(a,b,c) return (c-a)/(b-a); end;

-- use unlerp() to find the current time as a percentage from start to end
local percent = unlerp(comp.RenderStart, comp.RenderEnd, time);

-- output percent
return percent;

Quick copy & paste snippet

local function unlerp(a,b,c) return (c-a)/(b-a); end;

Wave Functions

You can interpolate the sin() function to create a repeating wave over a range of values.

:
-- setup
local lo = 0.0;         -- lowest value
local hi = 1.0;         -- highest value
local rate = 1.0;       -- cycles per second
local phase = -0.25;    -- offset relative to one cycle

-- function definitions
local function unlerp(a,b,c) return (c-a)/(b-a); end;
local function lerp(a,b,t) return a + (b-a)*t; end;

-- calculations
local seconds = time/comp:GetPrefs("Comp.FrameFormat.Rate");
local theta = 2 * math.pi * (phase + rate * seconds);
local t = unlerp(-1.0, 1.0, sin(theta));
return lerp(lo, hi, t);

Format Strings

You can use the string.format(str, ...) function to present multiple variables as text in a more readable way.

:
-- a basic clock
local framerate = comp:GetPrefs("Comp.FrameFormat.Rate");
local seconds = time/framerate;
local minutes = floor(seconds/60);
seconds = seconds - (minutes * 60);

-- format the minutes and seconds variables
local str = string.format("%i minutes, %.1f seconds", minutes, seconds);
return Text(str);

Debugging

You can use the print() function to see what your expression is doing each frame.

:
-- load some values
local r = TopLeftRed;
local g = TopLeftGreen;
local b = TopLeftBlue;

-- check the values of the variables by printing them to the console
print("red:", r, ", green:", ", blue:", b);             -- "red: 0.5000, green: 0.1000, blue: 1.0000"

-- we can clean this up a bit with a format string
print(string.format("rgb(%.2f, %.2f, %.2f)", r,g,b));     -- "rgb(0.50, 0.12, 1.00)"

-- output anything
return r+g+b;

You can use the trace() function to print something inline.

:
local a = time/2;
local b = trace(time/2); -- this is the same, but it prints the result

trace() is very helpful for one-line expressions because it can easily be inserted anywhere without effecting the result.

sin(trace(time/comp:GetPrefs("Comp.FrameFormat.Rate")) * 90)

Types

Parameter Constructors

Math

Common math functions

Trig

Common trigonometry functions

Lua

Because Expressions are Lua code, you can take advantage of the built in Lua math library.