SeExprSimple node

This documentation is for version 2.0 of SeExprSimple (fr.inria.openfx.SeExprSimple).

Description

Use the SeExpr expression language (by Walt Disney Animation Studios) to process images.

What is SeExpr?

SeExpr is a very simple mathematical expression language used in graphics software (RenderMan, Maya, Mudbox, Yeti).

See the SeExpr Home Page and SeExpr Language Documentation for more information.

SeExpr is licensed under the Apache License, Version 2.0, and is Copyright Disney Enterprises, Inc.

SeExpr vs. SeExprSimple

The SeExpr plugin comes in two versions:

  • SeExpr has a single vector expression for the color channels, and a scalar expression for the alpha channel. The source color is accessed through the Csvector, and alpha through the As scalar, as specified in the original SeExpr language.
  • SeExprSimple has one scalar expression per channel, and the source channels may also be accessed through scalars (r, g, b, a).

SeExpr extensions

A few pre-defined variables and functions were added to the language for filtering and blending several input images.

The following pre-defined variables can be used in the script:

  • x: X coordinate (in pixel units) of the pixel to render.
  • y: Y coordinate (in pixel units) of the pixel to render.
  • u: X coordinate (normalized in the [0,1] range) of the output pixel to render.
  • v: Y coordinate (normalized in the [0,1] range) of the output pixel to render.
  • sx, sy: Scale at which the image is being rendered. Depending on the zoom level of the viewer, the image might be rendered at a lower scale than usual. This parameter is useful when producing spatial effects that need to be invariant to the pixel scale, especially when using X and Y coordinates. (0.5,0.5) means that the image is being rendered at half of its original size.
  • par: The pixel aspect ratio.
  • cx, cy: Shortcuts for (x + 0.5)/par/sx and (y + 0.5)/sy, i.e. the canonical coordinates of the current pixel.
  • frame: Current frame being rendered
  • SeExprSimple only: r, g, b, a: RGBA channels (scalar) of the image from input 1.
  • SeExprSimple only: rN, gN, bN, aN: RGBA channels (scalar) of the image from input N, e.g. r2 and a2 are red and alpha channels from input 2.
  • Cs, As: Color (RGB vector) and alpha (scalar) of the image from input 1.
  • CsN, AsN: Color (RGB vector) and alpha (scalar) of the image from input N, e.g. Cs2 and As2 for input 2.
  • output_width, output_height: Dimensions of the output image being rendered.
  • input_width, input_height: Dimensions of image from input 1, in pixels.
  • input_widthN, input_heightN: Dimensions of image from input N, e.g. input_width2 and input_height2 for input 2.

The following additional functions are available:

  • color cpixel(int i, int f, float x, float y, int interp = 0): interpolates the color from input i at the pixel position (x,y) in the image, at frame f.
  • float apixel(int i, int f, float x, float y, int interp = 0): interpolates the alpha from input i at the pixel position (x,y) in the image, at frame f.

The pixel position of the center of the bottom-left pixel is (0., 0.).

The first input has index i=1.

interp controls the interpolation filter, and can take one of the following values:

  • 0: impulse - (nearest neighbor / box) Use original values
  • 1: bilinear - (tent / triangle) Bilinear interpolation between original values
  • 2: cubic - (cubic spline) Some smoothing
  • 3: Keys - (Catmull-Rom / Hermite spline) Some smoothing, plus minor sharpening (*)
  • 4: Simon - Some smoothing, plus medium sharpening (*)
  • 5: Rifman - Some smoothing, plus significant sharpening (*)
  • 6: Mitchell - Some smoothing, plus blurring to hide pixelation (*)(+)
  • 7: Parzen - (cubic B-spline) Greatest smoothing of all filters (+)
  • 8: notch - Flat smoothing (which tends to hide moire’ patterns) (+)

Some filters may produce values outside of the initial range (*) or modify the values even at integer positions (+).

Sample scripts

Add green channel to red, keep green, and apply a 50% gain on blue

SeExprSimple:

r+g
g
0.5*b

SeExpr:

[Cs[0]+Cs[1], Cs[1], 0.5*Cs[2]]

“Multiply” merge operator on inputs 1 and 2

SeExprSimple:

r*r2
g*g2
b*b2
a+a2-a*a2

SeExpr:

Cs * Cs2
As + As2 - As * As2

“Over” merge operator on inputs 1 and 2

SeExprSimple:

r+r2*(1-a)
g+g2*(1-a)
b+b2*(1-a)
a+a2-a*a2

SeExpr:

Cs + Cs2 * (1 -  As)
As + As2 - As * As2

Generating a time-varying colored Perlin noise with size x1

cnoise([cx/x1,cy/x1,frame])

Average pixels over the previous, current and next frame

SeExpr:

prev = cpixel(1,frame - 1,x,y);
cur = Cs;
next = cpixel(1,frame + 1,x,y);
(prev + cur + next) / 3;

“Wave” - displace columns of pixels vertically according to a sine wave function

SeExpr:

cpixel(1,frame,x,y+x2*sy*sin(2*3.1416*(x/sx - x3)/x1),2)

Set the No. of scalar params to 3.

  • x1 is the horizontal wavelength in pixels.
  • x2 is the vertical amplitude in pixels.
  • x3 is the horizontal shift in pixels.

Custom parameters

To use custom variables that are pre-defined in the plug-in (scalars, positions and colors) you must reference them using their script-name in the expression. For example, the parameter x1 can be referenced using x1 in the script:

Cs + x1

Multi-instruction expressions

If an expression spans multiple instructions (usually written one per line), each instruction must end with a semicolon (‘;’). The last instruction of the expression is considered as the final value of the pixel (a RGB vector or an Alpha scalar, depending on the script), and must not be terminated by a semicolon. More documentation is available on the SeExpr website.

Accessing pixel values from other frames

The input frame range used to render a given output frame is computed automatically if the following conditions hold:

  • The frame parameter to cpixel/apixel must not depend on the color or alpha of a pixel, nor on the result of another call to cpixel/apixel

  • A call to cpixel/apixel must not depend on the color or alpha of a pixel, as in the following:

    if (As > 0.1) { src = cpixel(1,frame,x,y); } else { src = [0,0,0]; }

If one of these conditions does not hold, all frames from the specified input frame range are asked for.

Inputs

Input Description Optional
1   Yes
2   Yes
3   Yes
4   Yes

Controls

Parameter / script name Type Default Function
Region of Definition / rod Choice Union
Region of definition (extent) of the output.
Union (union): The output region is the union of the regions of definition of all connected inputs.
Intersection (intersection): The output region is the intersection the regions of definition of all connected inputs.
Size (size): The output region is the size of the rectangle overlay.
Format (format): The output region is the specified format.
Project (project): The output region is the size of the project.
Input1 (input1): The output region is the region of definition of input 1
Input2 (input2): The output region is the region of definition of input 2
Input3 (input3): The output region is the region of definition of input 3
Input4 (input4): The output region is the region of definition of input 4
Input5 (input5): The output region is the region of definition of input 5
Input6 (input6): The output region is the region of definition of input 6
Input7 (input7): The output region is the region of definition of input 7
Input8 (input8): The output region is the region of definition of input 8
Input9 (input9): The output region is the region of definition of input 9
Input10 (input10): The output region is the region of definition of input 10
Output components / outputComponents Choice RGBA
Specify what components to output. In RGB only, the alpha script will not be executed. Similarly, in alpha only, the RGB script will not be executed.
RGBA
RGB
Alpha
Format / format Choice PC_Video 640x480
The output format
PC_Video 640x480 (PC_Video)
NTSC 720x486 0.91 (NTSC)
PAL 720x576 1.09 (PAL)
NTSC_16:9 720x486 1.21 (NTSC_16:9)
PAL_16:9 720x576 1.46 (PAL_16:9)
HD_720 1280x1720 (HD_720)
HD 1920x1080 (HD)
UHD_4K 3840x2160 (UHD_4K)
1K_Super35(full-ap) 1024x778 (1K_Super35(full-ap))
1K_Cinemascope 914x778 2 (1K_Cinemascope)
2K_Super35(full-ap) 2048x1556 (2K_Super35(full-ap))
2K_Cinemascope 1828x1556 2 (2K_Cinemascope)
2K_DCP 2048x1080 (2K_DCP)
4K_Super35(full-ap) 4096x3112 (4K_Super35(full-ap))
4K_Cinemascope 3656x3112 2 (4K_Cinemascope)
4K_DCP 4096x2160 (4K_DCP)
square_256 256x256 (square_256)
square_512 512x512 (square_512)
square_1K 1024x1024 (square_1K)
square_2K 2048x2048 (square_2K)
Bottom Left / bottomLeft Double x: 0 y: 0 Coordinates of the bottom left corner of the size rectangle.
Size / size Double w: 1 w: 1 Width and height of the size rectangle.
Interactive Update / interactive Boolean Off If checked, update the parameter values during interaction with the image viewer, else update the values when pen is released.
No. of Scalar Params / doubleParamsNb Integer 0 Use this to control how many scalar parameters should be exposed to the SeExpr expression.
x1 / x1 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x1
x2 / x2 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x2
x3 / x3 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x3
x4 / x4 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x4
x5 / x5 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x5
x6 / x6 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x6
x7 / x7 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x7
x8 / x8 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x8
x9 / x9 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x9
x10 / x10 Double 0 A custom 1-dimensional variable that can be referenced in the expression by its script-name, x10
No. of 2D Params / double2DParamsNb Integer 0 Use this to control how many 2D (position) parameters should be exposed to the SeExpr expression.
pos1 / pos1 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos1
pos2 / pos2 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos2
pos3 / pos3 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos3
pos4 / pos4 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos4
pos5 / pos5 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos5
pos6 / pos6 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos6
pos7 / pos7 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos7
pos8 / pos8 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos8
pos9 / pos9 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos9
pos10 / pos10 Double x: 0 y: 0 A custom 2-dimensional variable that can be referenced in the expression by its script-name, pos10
No. of Color Params / colorParamsNb Integer 0 Use this to control how many color parameters should be exposed to the SeExpr expression.
color1 / color1 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color1
color2 / color2 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color2
color3 / color3 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color3
color4 / color4 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color4
color5 / color5 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color5
color6 / color6 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color6
color7 / color7 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color7
color8 / color8 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color8
color9 / color9 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color9
color10 / color10 Color r: 0 g: 0 b: 0 A custom RGB variable that can be referenced in the expression by its script-name, color10
Input Frame Range / frameRange Integer min: 0 max: 0 Default input frame range to fetch images from (may be relative or absolute, depending on the “frameRangeAbsolute” parameter). Only used if the frame range cannot be statically computed from the expression. This parameter can be animated.
Absolute Frame Range / frameRangeAbsolute Boolean Off If checked, the frame range is given as absolute frame numbers, else it is relative to the current frame.
R= / rExpr String   Expression to compute the output red channel. If empty, the channel is left unchanged.
G= / gExpr String   Expression to compute the output green channel. If empty, the channel is left unchanged.
B= / bExpr String   Expression to compute the output blue channel. If empty, the channel is left unchanged.
A= / aExpr String   Expression to compute the output alpha channel. If empty, the channel is left unchanged.
Help… / helpButton Button   Display help about using SeExpr.
Invert Mask / maskInvert Boolean Off When checked, the effect is fully applied where the mask is 0.
Mix / mix Double 1 Mix factor between the original and the transformed image.