Expression

Brief Description

This generator allows to type a Javascript expression to produce a resulting value. The expression can be dependent on the value of the parameters that are added to the User Params list. The name of the variable for each parameter is the script-name set in the cog-wheel menu of the user parameter. The full API is available in the detailed description below.

If Multi-Line is checked, the expression is wrapped in a javascript function and requires a return statement. When unchecked, the value on the last line of the expression is the output value, which is useful when writing one-liners.

Examples:

1D expression returning a noise based on the current time:

turbulence1D(time)

2D expression returning a position based on an "angle" and "distance" parameter:

var angleVal = angle.getValue();
var distVal = distance.getValue();
return [Math.cos(angleVal) * distVal, Math.sin(angleVal) * distVal];

Controls

Parameter / Script Name	Type	Default	Function
`Expression / expression`
`Multi-Line / wrap_in_function`	Boolean	Off	When checked, the expression is wrapped in a javascript function and requires a return statement. When unchecked, the value on the last line of the expression is the output value, which is useful when writing one-liners.
`User Params / userParams`		-

Description

Global Properties

time

The current time (in seconds) at which the expression is evaluated. This is local to the Param and may not necessarily be the value displayed on the timeline, as it takes into account time offsets, remap etc...

compositionFormat

An array of 4 float with the left, bottom, right, top edges of the current Composition format, in pixel coordinates

compositionPixelAspectRatio

The pixel aspect ratio of the Composition format

globalIndex

The unique instance index when the expression is invoked on a Param that is used by an Instancer. This is the same as instanceIndex[0] * instanceCount[0] + instanceIndex[1] * instanceCount[1] + instanceIndex[2] * instanceCount[2] + instanceIndex[3] * instanceCount[3]

instanceIndex

Array of dimension 4 indicating the instance index across each dimension of the Instancer that invokes this expression

instanceCount

Array of dimension 4 indicating the number of instances across each dimension of the Instancer that invokes this expression

Global Functions

Interpolation Functions

float boxtep(float x, float a)

Returns 1 if x >= a, otherwise 0

float mix(float x, float y, float alpha)

Linear interpolation: x * (1 - alpha) + y * alpha

float linearstep(float x, float a, float b)

Returns (x - a) / (b - a) if x >= a && x <= b Otherwise 0 if x < a, 1 if x > b NB if a < b, a and b are swapped and 1 minus the result is returned. If a == b, this returns the same as boxstep(x,a)

float smoothstep(float x, float a, float b)

Perform Hermite interpolation between a and b.

float gaussstep(float x, float a, float b)

Same as smoothstep, but uses the standard gaussian "bell" curve which is based on an exponential curve.

float remap(float x, float source, float range, float falloff, RemapType interp)

General remapping function. When x is within +/- range of source, the result is one. The result falls to zero beyond that range over falloff distance. The falloff shape is controlled by interp

Random and Noise Functions

float perlin1D(float time, float amplitude = 1, bool signedRange = false)

"Improved Perlin Noise", based on Ken Perlin's 2002 Java reference code. signedRange: If true, the function returns a value centered around 0 instead of above 0

float fbm1D(float time, int octaves = 6, float lacunarity = 2, float gain = 0.5, float amplitude = 1, bool signedRange = false)

fbm (Fractal Brownian Motion) is a multi-frequency noise function. The total number of frequencies is controlled by octaves. The lacunarity is the spacing between the frequencies - a value of 2 means each octave is twice the previous frequency. The gain controls how much each frequency is scaled relative to the previous frequency. signedRange: If true, the function returns a value centered around 0 instead of above 0

float turbulence1D(float time, int octaves = 6, float lacunarity = 2, float gain = 0.5, float amplitude = 1, bool signedRange = false)

Turbulence is a variant of fbm where the absolute value of each noise term is taken. This gives a more billowy appearance.

float cellNoise1D(float time, float amplitude = 1, bool signedRange = false)

cellnoise generates a field of constant values based on the integer location

float periodicNoise1D(float time, int period = 1, float amplitude = 1, bool signedRange = false)

random function that smoothly blends between samples at integer locations. This is Ken Perlin's original noise function.

array perlinND(array time, float amplitude = 1, bool signedRange = false)

Same as perlin1D but returns an array of different values for each time given in the input array

array fbmND(array time, int octaves = 6, float lacunarity = 2, float gain = 0.5, float amplitude = 1, bool signedRange = false)

Same as fbmND but returns an array of different values for each time given in the input array

array turbulenceND(array time, int octaves = 6, float lacunarity = 2, float gain = 0.5, float amplitude = 1, bool signedRange = false)

Same as turbulence1D but returns an array of different values for each time given in the input array

array cellNoiseND(float time, float amplitude = 1, bool signedRange = false)

Same as cellNoise1D but returns an array of different values for each time given in the input array

array periodicNoiseND(array time, int period = 1, float amplitude = 1, bool signedRange = false)

Same as periodicNoise1D but returns an array of different values for each time given in the input array

float random(float seed, float mini = 0, float maxi = 1)

Pseudo-random function between mini and maxi.

int randomInt(int seed, int mini = 0, int maxi = 100)

Pseudo-random integer function between mini and maxi.

array randomND(array seed, float mini = 0, float maxi = 1)

Pseudo-random function between mini and maxi for an array of different seed values

array randomIntND(array seed, int mini = 0, int maxi = 100)

Pseudo-random function between mini and maxi for an array of different seed values

Utility Functions

The KeyFrame class

A small object describing a Keyframe, that is used by the API of Param. It has the following properties: time: The time of the keyframe in seconds. The keyframe is considered invalid if time is equal to invalidTime(). This can also be checked with the function isValid()

value: The value of the keyframe, generally a float, string or bool.

right: The right derivative of the keyframe

rightAmount: The amount of the right derivative, in the range 0-3

left: The left derivative of the keyframe

leftAmount: The amount of the left derivative, in the range 0-3

interpolation: One of the following value of enum Interpolation.Mode:

Constant,
Linear,
Smooth,
CatmullRom,
Cubic,
Horizontal,
Free,
Broken,
None,
EasingLinear,
InQuad,
OutQuad,
InOutQuad,
OutInQuad,
InCubic,
OutCubic,
InOutCubic,
OutInCubic,
InQuart,
OutQuart,
InOutQuart,
OutInQuart,
InQuint,
OutQuint,
InOutQuint,
OutInQuint,
InSine,
OutSine,
InOutSine,
OutInSine,
InExpo,
OutExpo,
InOutExpo,
OutInExpo,
InCirc,
OutCirc,
InOutCirc,
OutInCirc,
InElastic,
OutElastic,
InOutElastic,
OutInElastic,
InBack,
OutBack,
InOutBack,
OutInBack,
InBounce,
OutBounce,
InOutBounce,
OutInBounce,
InCurve,
OutCurve,
SineCurve,
CosineCurve,
VelocityBounce

easingAmplitude: Value of easing amplitude if interpolation is an easing function that uses it

easingPeriod: Value of easing period if interpolation is an easing function that uses it

easingOvershoot: Value of easing overshoot if interpolation is an easing function that uses it

Param API

Each Param is pre-declared to the JS interpreter with a variable that has the script-name define in the properties of Param. The following functions are available on the Param:

int getNDims()

Returns the number of dimensions of the Param

var getValue(int dimension = -1, float time = invalidTime(), ExpressionInstanceIndex instance = makeInstanceIndex())

Returns the value of the Parameter. The return value depends on the Param type and p, the value of the dimension parameter. If the Param is numeric and dimension is >= 0 or the Param has a single dimension, a float is returned. If the Param is numeric and dimension is -1 and the Param has multiple dimension, an array is returned of the size of dimension. If the Param is string, the return value is always a string. If the Param is boolean, the return value is always a bool. dimension: For multi-dimensional parameters (such as a Color selector), indicate whether to return an array of all dimensions or just a specific dimension time: If set to invalidTime() (the default), returns the value of the Param at the current time passed to the expression, otherwise evaluates the Param at the given time instance: If set to makeInstanceIndex() (the default), returns the value of the Param at the current instanceIndex passed to the expression, otherwise evaluates the Param at the given instance.

var getNearestKeyFrame(int dimension = -1, float time = invalidTime())

Returns the nearest KeyFrame of the Parameter. Check the isValid() function of the KeyFrame to determine if it sucessfully returned a KeyFrame or not.

dimension: If -1, returns the nearest keyframe across all dimensions of the Param, otherwise just of the givn dimension time: If set to invalidTime() (the default), returns the value of the Param at the current time passed to the expression, otherwise check at the given time

var getPreviousKeyFrame(int dimension = -1, float time = invalidTime())

Returns the nearest previous KeyFrame of the Parameter. Check the isValid() function of the KeyFrame to determine if it sucessfully returned a KeyFrame or not.

dimension: If -1, returns the nearest keyframe across all dimensions of the Param, otherwise just of the givn dimension time: If set to invalidTime() (the default), returns the value of the Param at the current time passed to the expression, otherwise check at the given time

var getNextKeyFrame(int dimension = -1, float time = invalidTime())

Returns the nearest next KeyFrame of the Parameter. Check the isValid() function of the KeyFrame to determine if it sucessfully returned a KeyFrame or not.

dimension: If -1, returns the nearest keyframe across all dimensions of the Param, otherwise just of the givn dimension time: If set to invalidTime() (the default), returns the value of the Param at the current time passed to the expression, otherwise check at the given time

var getKeyFrameAt(int dimension = -1, float time = invalidTime())

Returns the KeyFrame at the given time if it exists. Check the isValid() function of the KeyFrame to determine if it sucessfully returned a KeyFrame or not.

dimension: If -1 and Param is multi-dimensional, returns an array of KeyFrame for each dimension time: If set to invalidTime() (the default), returns the value of the Param at the current time passed to the expression, otherwise check at the given time

var getKeyFrames(int dimension = -1, float minTime = invalidTime(), float maxTime = invalidTime())

Returns an array of KeyFrame in the range [minTime, maxTime]

dimension: If -1 and Param is multi-dimensional, returns an array of array of KeyFrame for each dimension