Expression

Allows you to apply complex mathematical formulas to a channel’s values using C-like syntax expressions. If necessary, you can apply different expressions to different sets of channels.

x or y is the pixel coordinate. If the input is a proxy image, then these are scaled and translated to the coordinate that would be in the full size image.

cx and cy can provide a more useful coordinate system. In this system 0,0 is the center of the picture.

-1,0 is the center of the left edge, 1,0, is the center of the right edge. 1,1 is a point 45 degrees up from the origin on the right edge (outside the top of the picture if the aspect ratio is greater than 1).

You can refer to any input channel by name, for example r for the red channel.

You can refer to any control on any node by its name. For example, Blur1.size returns the size of the blur. You can also evaluate animated controls, for example Blur1.size(t).

A blank expression is the same as zero.

All math is done with 32-bit floating point numbers.

See also MergeExpression.

Inputs and Controls

Connection Type

Connection Name

Function

Input

unnamed

The image sequence to which you want to apply expressions.

mask

An optional image to use as a mask. By default, the expressions are limited to the non-black areas of the mask.

At first, the mask input appears as triangle on the right side of the node, but when you drag it, it turns into an arrow labeled mask. If you cannot see the mask input, ensure that the mask control is disabled or set to none.

Control (UI)

Knob (Scripting)

Default Value

Function

Expression Tab

[variable name field]

temp_name0

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name here, and the expression on the right of the = sign. You can then use the variable to represent the expression in the = fields next to the channels.

=

temp_expr0

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name on the left side of the = sign, and the expression in this field. You can then use the variable to represent the expression in the = fields next to the channels.

[variable name field]

temp_name1

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name here, and the expression on the right of the = sign. You can then use the variable to represent the expression in the = fields next to the channels.

=

temp_expr1

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name on the left side of the = sign, and the expression in this field. You can then use the variable to represent the expression in the = fields next to the channels.

[variable name field]

temp_name2

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name here, and the expression on the right of the = sign. You can then use the variable to represent the expression in the = fields next to the channels.

=

temp_expr2

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name on the left side of the = sign, and the expression in this field. You can then use the variable to represent the expression in the = fields next to the channels.

[variable name field]

temp_name3

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name here, and the expression on the right of the = sign. You can then use the variable to represent the expression in the = fields next to the channels.

=

temp_expr3

N/A

If you need to use a long expression in several fields, you can use this row for assigning the expression temporarily to a variable. Enter the variable name on the left side of the = sign, and the expression in this field. You can then use the variable to represent the expression in the = fields next to the channels.

channels

channel0

red

The channel(s) to which you want to apply the expression in the below = field.

You can use the checkboxes on the right to select individual channels.

=

expr0

N/A

The expression to apply to the above channels.

For example, to assign noise to the above channel(s) and then boost the gain of that result by 20, you would type (random*r)*20 here.

To reference pixels in other channels, use layer.channel (for example, matte.garbage). If you don’t specify the layer name, the Expression node assumes the channel is in the current layer. As a shortcut, you can use r, g, b, and a to reference the red, green, blue, and alpha channels in the rgba layer.

channels

channel1

green

The channel(s) to which you want to apply the expression in the below = field.

You can use the checkboxes on the right to select individual channels.

=

expr1

N/A

The expression to apply to the above channels.

For example, to assign noise to the above channel(s) and then boost the gain of that result by 20, you would type (random*r)*20 here.

To reference pixels in other channels, use layer.channel (for example, matte.garbage). If you don’t specify the layer name, the Expression node assumes the channel is in the current layer. As a shortcut, you can use r, g, b, and a to reference the red, green, blue, and alpha channels in the rgba layer.

channels

channel2

blue

The channel(s) to which you want to apply the expression in the below = field.

You can use the checkboxes on the right to select individual channels.

=

expr2

N/A

The expression to apply to the above channels.

For example, to assign noise to the above channel(s) and then boost the gain of that result by 20, you would type (random*r)*20 here.

To reference pixels in other channels, use layer.channel (for example, matte.garbage). If you don’t specify the layer name, the Expression node assumes the channel is in the current layer. As a shortcut, you can use r, g, b, and a to reference the red, green, blue, and alpha channels in the rgba layer.

channels

channel3

alpha

The channel(s) to which you want to apply the expression in the below = field.

You can use the checkboxes on the right to select individual channels.

=

expr3

N/A

The expression to apply to the above channels.

For example, to assign noise to the above channel(s) and then boost the gain of that result by 20, you would type (random*r)*20 here.

To reference pixels in other channels, use layer.channel (for example, matte.garbage). If you don’t specify the layer name, the Expression node assumes the channel is in the current layer. As a shortcut, you can use r, g, b, and a to reference the red, green, blue, and alpha channels in the rgba layer.

mask

N/A

disabled

Enables the associated mask channel to the right. Disabling this checkbox is the same as setting the channel to none.

maskChannelInput

none

The channel to use as a mask. By default, the expressions are limited to the non-black areas of this channel.

inject

inject

disabled

Copies the mask input to the predefined mask.a channel. Injecting the mask allows you to use the same mask further downstream.

invert

invert_mask

disabled

Inverts the use of the mask channel so that the expressions are limited to the non-white areas of the mask.

fringe

fringe

disabled

When enabled, only apply the effect to the edge of the mask.

When disabled, the effect is applied to the entire mask.

(un)premult by

N/A

disabled

Enables the associated channel to the right. Disabling this checkbox is the same as setting the channel to none.

unpremult

none

The image is divided by this channel before being processed, and multiplied again afterwards.

If you are using premultiplied input images, you may want to check (un)premult by and select rgba.alpha here. This will simulate applying the expressions before the premultiplication was done. It is the same as adding an Unpremult node before this node and a Premult node after, but allows you to work faster if you’re only using one color correct node.

If you are using unpremultiplied input images, you should leave this set to none.

invert

invert_unpremult

disabled

Inverts the use of the (un)premultiply channel.

mix

mix

1

Dissolves between the original image at 0 and the full expressions effect at 1.

The following functions are supported:

Function

Purpose

Operator Usage

Related Functions

abs (x)

Returns the absolute value of a floating-point number x.

x

See also: fabs.

acos (x)

Calculates the arc cosine of x; that is the value whose cosine is x.

If x is less than -1 or greater 1, acos returns nan (not a number)

See also: cos, cosh, asin, atan.

asin (x)

Calculates the arc sine of x; that is the value whose sine is x.

If x is less than -1 or greater 1, asin returns nan (not a number)

See also: sin, sinh, acos, atan.

atan (x)

Calculates the arc tangent of x; that is the value whose tangent is x. The return value will be between -PI/2 and PI/2.

x

See also: tan, tanh, acos, asin, atan2.

atan2 (x, y)

Calculates the arc tangent of the two variables x and y. This function is useful to calculate the angle between two vectors.

x, y

See also: sin, cos, tan, asin, acos, atan, hypot.

ceil (x)

Round x up to the nearest integer.

x

See also: floor, trunc, rint.

clamp (x, min, max)

Return x clamped to the min and max values specified.

x, min, max

See also: min, max.

clamp (x)

Return x clamped to [0.0 ... 1.0].

x

See also: min, max.

cos (x)

Returns the cosine of x.

x in radians

See also: acos, sin, tan, cosh.

cosh (x)

Returns the hyperbolic cosine of x, which is defined mathematically as:
(exp(x) + exp(-x)) / 2.

x

See also: cos, acos, sinh, tanh.

degrees (x)

Convert the angle x from radians into degrees.

x

See also: radians.

exp (x)

Returns the value of e (the base of natural logarithms) raised to the power of x.

x

See also: log, log10.

exponent (x)

Exponent of x.

x

See also: mantissa, ldexp.

fBm (x, y, z, octaves, lacunarity, gain)

Fractional Brownian Motion. This is the sum of octave calls to noise(). The input point for each is multiplied by pow(lacunarity,i) and the result is multiplied by pow(gain,i). For normal use, lacunarity should be greater than 1 and gain should be less than 1.

x, y, z, octaves, lacunarity, gain

See also: noise, random, turbulence.

fabs (x)

Returns the absolute value of the floating-point number x.

x

See also: abs.

false ()

Always returns 0.

none

See also: true.

floor (x)

Round x down to the nearest integer.

x

See also: ceil, trunc, rint.

fmod (x, y)

Computes the remainder of dividing x by y. The return value is x - n y, where n is the quotient of x / y, rounded towards zero to an integer.

x, y

See also: ceil, floor.

frame ()

Return the current frame number.

none

See also: x.

from_byte (color component)

Converts an sRGB pixel value to a linear value.

color_component

See also: to_sRGB, to_rec709, from_rec709.

from_rec709 (color component)

Converts a rec709 byte value to a linear brightness.

color_component

See also: from_sRGB, to_rec709.

from_sRGB (color component)

Converts an sRGB pixel value to a linear value.

color_component

See also: to_sRGB, to_rec709, from_rec709.

hypot (x, y)

Returns the sqrt(x*x + y*y). This is the length of the hypotenuse of a right-angle triangle with sides of length x and y.

x, y

See also: atan2.

int (x)

Round x to the nearest integer not larger in absolute value.

x

See also: ceil, floor, trunc, rint.

ldexp (x, exp)

Returns the result of multiplying the floating-point number x by 2 raised to the power exp.

x, exp

See also: exponent.

lerp (a, b, x)

Returns a point on the line f(x) where f(0)==a and f(1)==b.

Matches the lerp function in other shading languages.

a, b, x

See also: step, smoothstep.

log (x)

Returns the natural logarithm of x.

x

See also: log10, exp.

log10 (x)

Returns the base-10 logarithm of x.

x

See also: log, exp.

logb (x)

Same as exponent().

x

See also: mantissa, exponent.

mantissa (x)

Returns the normalized fraction. If the argument x is not zero, the normalized fraction is x times a power of two, and is always in the range 1/2 (inclusive) to 1 (exclusive). If x is zero, then the normalized fraction is zero and exponent() returns zero.

x

See also: exponent

max (x, y, ... )

Return the greatest of all values.

x, y, (...)

See also: min, clamp.

min (x, y, ... )

Return the smallest of all values.

x, y, (...)

See also: max, clamp

mix (a, b, x)

Same as lerp().

a, b, x

See also: step, smoothstep, lerp

noise (x, y, z)

Creates a 3D Perlin noise value - a signed range centered on zero. The absolute maximum range is from -1.0 to 1.0.

This produces zero at all integers, so you should rotate the coordinates somewhat (add a fraction of y and z to x, etc.) if you want to use this for random number generation.

x, optional y, optional z

See also: random, fBm, turbulence

pi ()

Returns the value for pi (3.141592654...).

none

none

pow (x, y)

Returns the value of x raised to the power of y.

x, y

See also: log, exp, pow

pow2 (x)

Returns the value of x raised to the power of 2.

x, y

See also: pow

radians (x)

Convert the angle x from degrees into radians.

x

See also: degrees

random (x, y, z)

Creates a pseudo random value between 0 and 1 - it always generates the same value for the same x, y and z.

Calling random with no arguments creates a different value on every invocation.

optional x, optional y, optional z

See also: noise, fBm, turbulence

rint (x)

Round x to the nearest integer.

x

See also: ceil, floor, int, trunc

sin (x)

Returns the sine of x.

x in radians

See also: asin, cos, tan, sinh

sinh (x)

Returns the hyperbolic sine of x, which is defined mathematically as:
(exp(x) - exp(-x)) / 2.

x

See also: sin, asin, cosh, tanh

smoothstep (a, b, x)

Returns 0 if x is less than a, returns 1 if x is greater or equal to b, returns a smooth cubic interpolation otherwise.

Matches the smoothstep function in other shading languages.

a, b, x

See also: step, lerp

sqrt (x)

Returns the non-negative square root of x.

x

See also: pow, pow2

step (a, x)

Returns 0 if x is less than a, returns 1 otherwise.

Matches the step function other shading languages.

a, x

See also: smoothstep, lerp

tan (x)

Returns the tangent of x.

x in radians

See also: atan, cos, sin, tanh, atan2

tanh (x)

Returns the hyperbolic tangent of x, which is defined mathematically as:
sinh(x) / cosh(x).

x

See also: tan, atan, sinh, cosh

to_byte (color component)

Converts a floating point pixel value to an 8-bit value that represents that number in sRGB space.

color_component

See also: from_sRGB, to_rec709, from_rec709

to_rec709 (color component)

Converts a floating point pixel value to an 8-bit value that represents that brightness in the rec709 standard when that standard is mapped to the 0-255 range.

color_component

See also: from_sRGB, from_rec709

to_sRGB (color component)

Converts a floating point pixel value to an 8-bit value that represents that number in sRGB space.

color_component

See also: from_sRGB, to_rec709, from_rec709

true ()

Always Returns 1.

none

See also: false

trunc (x)

Round x to the nearest integer not larger in absolute value.

x

See also: ceil, floor, int, rint

turbulence (x, y, z, octaves, lacunarity, gain)

This is the same as fBm() except the absolute value of the noise() function is used.

x, y, z, octaves, lacunarity, gain

See also: fBm, noise, random

x ()

Return the current frame number.

none

See also: frame

y (frame)

Evaluates the y value for an animation at the given frame.

optional: frame, defaults to current frame

none

Step-by-Step Guides

Applying Expressions to Channel Values

Example Nuke Scripts

Expression nodes for despilling greenscreen and bluescreen footage