From VFXWiki

[edit] Custom [Cu]

The Custom tool is quite likely the most complex, and the most powerful, tool in Fusion. Any user moderately experienced with scripting, or C++ programming, should find the structure and terminology used by the Custom tool to be familiar. The Custom tool is used to create custom expressions and filters to modify an image. In addition to providing three image inputs, the Custom tool will allow for the connection of up to eight numeric inputs and as many as four XY position values from other controls and parameters in the flow. Per-pixel calculations can be performed on the Red, Green, Blue, Alpha, Z, U, V, X Normal, Y Normal and Z Normal channels of the images.

Contents 1 Custom [Cu] 1.1 Custom Controls Tab 1.2 Custom Setup Tab 1.3 Custom Inter Tab 1.4 Custom Config Tab 1.5 Channels Tab 2 Custom Tool Syntax 3 Examples

[edit] Custom Controls Tab

These four controls are 2D X and Y center controls that are available to expressions entered in the Setup, Intermediate and Channels tabs as variables p1x, p1y, ...., p4x, p4y. They are normal positional controls and can be animated or connected to modifiers as any other tool might.

The values of these controls are available to expressions entered in the Setup, Intermediate and Channels tabs as variables n1, n2, n3, ..., n8. They are normal slider controls, and can be animated or connected to modifiers exactly as any other tool might.

These controls can be renamed using the options in the config tab to make their meanings more apparent, but expressions will still see the values as n1, n2, ..., n8.

[edit] Custom Setup Tab

Up to four separate expressions can be calculated in the Setup tab of the Custom tool. The Setup expressions are evaluated once per frame, before any other calculations are performed. The results are then made available to the other expressions in the Custom tool as variables s1, s2, s3 and s4.

[edit] Custom Inter Tab

An additional four expressions can be calculated in the Inter tab. The Inter expressions are evaluated once per pixel, after the Setup expressions are evaluated but before the Channel expressions are evaluated. Results are available as variables i1, i2, i3 and i4.

[edit] Custom Config Tab

Color Channel expressions (RGBA) should return Floating Point values between 0.0 and 1.0, and all other expression values must produce values between -1.0 and 1.0. The Channel expressions may use the results from both the Setup expressions (as variables s1-s4) and Inter expressions (as variables i1-i4).

[edit] Channels Tab

The Channel tab is used to set up one expression per each available channel of the image. Each expression is evaluated once per pixel, and the result is used to create the value for that pixel in the output of the image.

[edit] Custom Tool Syntax

,

Value Variables
n1..n8	Numeric Inputs
p1x..p4x	Position Values (X-axis)
p1y..p4y	Position Values (Y-axis)
s1..s4	Setup Expression Results
i1..i4	Inter Expression Results
time	Current Frame
w1..w3	Width of Input Images
h1..h3	Height of Input Images
ax1..ax3	Image Aspect X
ay1..ay3	Image Aspect Y
	Notes: Use ax and ay without a following number to access the aspect of the image.
Channel (Pixel) Variables
c (or c1..c3)	Current Channel (for image1..image3)
r (or r1..r3)	Red (for image1..image3)
g (or g1..g3)	Green (for image1..image3)
b (or b1..b3)	Blue (for image1..image3)
a (or a1..a3)	Alpha (for image1..image3)
z	Z-Buffer
u	U Coordinate
v	V Coordinate
nx	X Normal
ny	Y Normal
nz	Z Normal
	Notes: Use c1, c2, c3 to refer to the value of a pixel in the current channel. This makes copy/pasting expressions easier. For example, if c1/2 is typed as the red expression, the result would be half the value of the red pixel from image 1, but if the expression is copied to the blue channel, now it would have the value of the pixel from the blue channel. To refer to the red value of the current pixel in input one, type r1. For the image in input 2, it would be r2.
Functions
get[ch][#]b(x, y)	Read pixel at x, y, or 0 if out of bounds. e.g. getr1b(0,0)
get[ch][#]d(x, y)	Read pixel at x,y or edge pixel if out of bounds. e.g. getr1d(0,0)
get[ch][#]w(x, y)	Read pixel at x,y or wrap if out of bounds e.g. getr1w(0,0)
	Notes: There are a variety of methods used to refer to pixels from other locations than the current one in an image. In the above description [ch] is a letter representing the channel to access, and [#] is a number representing the input image. So to access the value of the red pixel at 0, 0 on image 1 you would use getr1b(0,0). getr1b(x,y) output the red value of the pixel at position x, y, if there were a valid pixel present. It would output 0.0, if the position were beyond the boundaries of the image. getr1d(x,y) output the red value of the pixel at position x, y. If the position specified were outside of the boundaries of the image, the result would be from the outer edge of the image (RGBA only). getr1w(x,y) output the red value of the pixel at position x, y. If the position specified were outside of the boundaries of the image, the x and y co-ordinates would wrap around to the other side of the image and continue from there. (RGBA only) To access other channel values with these functions, substitute the r in the above examples with the correct channel variable. (r, g, b, a and, for the getr1b() functions only, z, etc...) as shown above. Substitute the 1 with either 2 or 3 in the above examples to access the images from the other image inputs.
Mathematical Expressions
pi	The value of pi
e	The value of e
log(x)	The base-10 log of x
ln(x)	The natural (base-e) log of x
sin(x)	The sine of x (x is degrees)
cos(x)	The cosine of x (x is degrees)
tan(x)	The tangent of x (x is degrees)
asin(x)	The arcsine of x, in degrees
acos(x)	The arccosine of x, in degrees
atan(x)	The arctangent of x, in degrees
atan2(x,y)	The arctangent of x,y, in degrees
abs(x)	The absolute (positive) value of x
int(x)	The integer (whole) value of x
frac(x)	The fractional value of x
sqrt(x)	The Square Root of x
rand(x,y)	A random value between x and y
rands(x,y,s)	A random value between x and y, based on seed s
min(x,y)	The minimum (lowest) of x and y
max(x,y)	The maximum (highest) of x and y
dist(x1,y1,x2,y2)	The distance between point x1,y2 and x2,y2
if(c, x, y)	returns x if c <> 0, otherwise y
Mathematical Operators
!x	1.0 if x = 0, otherwise 0.0
-x	(0.0 - x)
+x	(0.0 + x) i.e. effectively does nothing
x^y	x raised to the power of y
x*y	x multiplied by y
x/y	x divided by y
x%y	x modulo y, i.e. remainder of (x divided by y)
x+y	x plus y
x-y	x minus y
x<y	1.0 if x is less than y, otherwise 0.0
x>y	1.0 if x is greater than y, otherwise 0.0
x<=y	1.0 if x is less than or equal to y, otherwise 0.0
x>=y	1.0 if x is greater than or equal to y, otherwise 0.0
x=y	1.0 if x is exactly equal to y, otherwise 0.0
x==y	1.0 if x is exactly equal to y, otherwise 0.0, identical to above
x<>y	1.0 if x is not equal to y, otherwise 0.0
x!=y	1.0 if x is not equal to y, otherwise 0.0, i.e. identical to above
x & y	1.0 if both x and y are not 0.0, otherwise 0.0
x && y	1.0 if both x and y are not 0.0, otherwise 0.0, i.e. identical to above
x | y	1.0 if either x or y (or both) are not 0.0, otherwise 0.0
x || y	1.0 if either x or y (or both) are not 0.0, otherwise 0.0

[edit] Examples

The following example is intended to help you understand the various components of the Custom tool. Our example duplicates the functionality of a 3x3 Custom Filter tool set to averages the current pixel together with the eight pixels surrounding it. To duplicate it with a Custom tool, add a Custom tool to the Flow, and enter the following expressions into the Setup tab.

(Leave the tool disconnected to prevent it from updating until we are ready.)

S1

1.0/w1

S2

1.0/h1

These two expressions will be evaluated at the beginning of each frame. S1 divides 1.0 by the current width of the frame, and S2 divides 1.0 by the height. This provides a Floating Point value between 0.0 and 1.0 that represents the distance from the current pixel to the next pixel along each axis.

Now enter the following expression into the first text control of the Channel tab (r)

 (getr1w(x-s1, y-s2) + getr1w(x, y-s2) + getr1w(x+s1, y-s2) + 
  getr1w(x+s1, y) + getr1w(x-s1, y) + r1 + 
  getr1w(x-s1, y+s2) + getr1w(x, y+s2) + getr1w(x+s1, y+s2)) / 9

This expression adds the nine pixels above the current pixel together by calling the getr1w() function nine times and providing it with values relative to the current position. Note that we referred to the pixels by using x+s1, y+s2 rather than using x+1, y+1.

Fusion refers to pixels as Floating Point values between 0.0 and 1.0, which is why we created the expressions we used in the Setup tab. If we had used x+1, y+1 instead, the expression would have sampled the exact same pixel over and over again. (The function we used wraps the pixel position around the image if the offset values are out of range.)

That took care of the red channel, now use the following expressions for the green, blue and alpha channels.

 (getg1w(x-s1, y-s2) + getg1w(x, y-s2) + getg1w(x+s1, y-s2) + 
  getg1w(x+s1, y) + getg1w(x-s1, y) + g1 + 
  getg1w(x-s1, y+s2) + getg1w(x, y+s2) + getg1w(x+s1, y+s2)) / 9

 (getb1w(x-s1, y-s2) + getb1w(x, y-s2) + getb1w(x+s1, y-s2) + 
  getb1w(x+s1, y) + getb1w(x-s1, y) + b1 + 
  getb1w(x-s1, y+s2) + getb1w(x, y+s2) + getb1w(x+s1, y+s2)) / 9

 (geta1w(x-s1, y-s2) + geta1w(x, y-s2) + geta1w(x+s1, y-s2) + 
  geta1w(x+s1, y) + geta1w(x-s1, y) + a1 + geta1w(x-s1, y+s2) + 
  geta1w(x, y+s2) + geta1w(x+s1, y+s2)) / 9

It is time to view the results. Add a Background tool set to solid color and change the color to a pure red. Add a hard edged rectangular Effects Mask and connect it to the expression just created.

For comparison, add a Custom Filter tool and duplicate the settings from the image above. Connect a pipe to this tool from the background to the tool and view the results. Alternate between viewing the Custom tool and the Custom Filter while zoomed in close to the top corners of the Effects Mask.

Of course, the Custom Filter tool renders a lot faster than the Custom tool we created, but the flexibility of the Custom tool is its primary advantage. For example, you could use an image connected to input 2 to control the median applied to input one by changing all instances of getr1w, getg1w, and getb1w in the expression to getr2w, getg2w, and getb2w, but leaving the r1, g1, and b1's as they are.

This is just one example, the possibilities of the Custom tool are limitless.

The contents of this page are copyright by eyeon Software.