Xpresso Node

The Xpresso node enables you to program custom effects. It allows you to write mathematical expressions that define each pixel in the output image as a function of the input imagery being delivered to the Xpresso node.

The Xpresso node can have a single or multiple inputs. Each time you add an input to the Xpresso node, another input connector is automatically created. All inputs to an Xpresso node must be consistent in:

  • bit depth (8-bit; 16-bit; or floating point)
  • resolution (size in pixel dimensions)
  • number of channels

The input to an Xpresso node can have any number of channels, as long as the source image includes all channels named in the expression used.

When you use the Xpresso node to calculate an output image, all pixels and channels of the input imagery are available to you for inclusion in the mathematical expressions you devise.

Xpresso Parameter Tab

The Xpresso node parameter tab contains an Expression field in which you can enter a mathematical expression and several parameter menus.

Expression Field

This is the field in which you enter a mathematical expression. For long, complex expressions, you may prefer to use a text editor instead. To do so, click the cursor in the Expression field and press the Alt-e key combination. The contents of the field will be displayed in the window of the default text editor for your system (i.e., Jot or Notepad).

Math Menu

For an input image consisting of integer data (i.e., an 8-bit or 16-bit source image) the Math menu enables you to specify whether the expression is calculated in integer or converted to floating point. (Floating point pixels are always computed as float.)

When you specify "Floating Point," the Xpresso node

  • converts the integer data to floating point data (i.e., from the range of 0-255 for 8-bit imagery or 0-65535 for 16-bit imagery, to 0-1),
  • performs the calculations you specified in the Expression field in floating point, and
  • converts the result back to integer data for output.

Pixel Bounds Menu

The Pixel Bounds menu enables you to specify whether the Xpresso node should use Clamping or Modulo range delimiting methodologies when computing pixel values.

  • Clamp can be used with integer and floating point input data. It "clamps" or delimits values at the maximum or minimum of a specified range. For example, for 8-bit color imagery, which has a range of 0-255, values will be clamped at 0 when the result is zero or less, and at 255 when the result is 255 or greater (floating point data will clamp at 0 and 1).
  • Modulo can be used with integer input data only. It rolls over values when they reach the maximum of a specified range. For example, for 8-bit color imagery with its range of 0-255, a result of 256 will roll over to 0, 257 will be equal to 1, 258 will be equal to 2, and so on until 512 = 0, 513 = 1, etc.

XY Bounds Menu

The XY Bounds menu enables you to specify whether the Xpresso node should use Clamping or Modulo range delimiting methodologies when computing pixel coordinates. (See definitions of Clamp and Modulo, above.)

Y Increases

This menu enables you to specify the orientation of Xpresso. The default, "Y increases from bottom up," specifies that the 0,0 x,y coordinate is the lower left corner of the image. This is consistent with the orientation of all other Chalice monitors.

The other option, "Y increases from top down," puts the 0,0 point in the upper left corner. This option is provided for compatibility with previous versions of Chalice. When Chalice converts a 1.6 grail file containing an Xpresso node to version 2.0, this menu will be reset to "Y increases from top down," to match the previous behavior of Xpresso.

How the Xpresso Node Works

The Xpresso node functions by enabling you to specify the value of each pixel in each channel in the output image.

The Xpresso node processing begins at the first pixel of the output image plane 0 and continues until all pixels in the channel have been addressed and assigned a value. Then the Xpresso node addresses the subsequent channel of the output image, and so on until each pixel in each channel has been assigned a value.

You define this process of assigning values to pixels by keying a mathematical expression into the Expression data entry field in the Xpresso parameter tab.

Be sure to review the Guidelines for Using Xpresso and the examples that follow for more information.

System Variables

The following system variables are available to the Xpresso node:

Global Variables

The following globals are available to the Xpresso node:

The $MYGLOBAL variable represents a global you create in the Chalice Globals window, which is described in Setting Global Variables in chapter 6.

Chalice Expression Language Functions

The following expression language functions are available in the Xpresso node (See appendix B, "Chalice Expression Language ," for more information about how to use these functions):

Operators

The following is a list of operators that can be used in the Xpresso node. The order of precedence (the order in which they are evaluated in the expression) is similar to the C programming language. In this list, the order of precedence is from last to first.

Due to inherent round-off errors, you should avoid comparing floating point numbers for equality--do not use the "==" operator with floats.

Guidelines for Using Xpresso

Assume that there is one input to the Xpresso node. It occupies the number 1 buffer, which we will call [1]. The output image is specified by the zero buffer, or [0].

To set the red, green, and blue (RGB) channels so that the output image is equal to the input image, we could state [0] = [1] for each channel.

However, certain rules governing implied behavior that apply when addressing pixels enable us to simplify the resultant expression. Since setting the output buffer is one such implied behavior, another way to express this would be simply [1].

The following are a few guidelines (see also the examples that follow this list):

  • You can reference an entire image by specifying only the image number (e.g., [1], which represents the first input image).
  • You can reference a specific pixel at address x,y on channel c in image 1 by specifying [1,x,y,c].
  • The expression [1,x,y] enables you to define the channel implicitly.
  • The brackets do not need to contain a number; they may instead contain an expression.
  • You can use more than one expression to define the output buffer. Expressions must be separated by a semicolon (;).
  • The full form for addressing pixels is: [image number,x,y,c] or {image number,r,a,c}.
    • "Image number" refers to either the output buffer [0] or one of the input buffers ([1] to [n]).
    • The first instance, in brackets [], references the x and y address of the pixel, followed by the channel number.
    • The second instance, in braces {}, replaces the Cartesian coordinates x and y with the polar coordinates for current radius (r) and current angle (a).

Example 1

Let's say that we want all the red channel output data to be 10 units higher than the red channel input data, and we wish to make no change to the blue and green channel data. The expressions required to define this process would be:

[1]; [0,x,y,0] = [1,x,y,0] + 10

In other words, set the output image buffer to equal the input image; then check the red channel of the current input pixel and make the red channel of the current output pixel equal the input value plus 10.

Example 2

Let's say that we want to make the output contain black everywhere except where x=10, at which point the pixels should be yellow. The required expression would be:

[0] = 0; [0,x,y,0] = ((x==10) ? Z:0); [0,x,y,1] = ((x==10) ? Z:0)

In other words, set the entire output buffer to 0 (black); then check to see if the current x is equal to 10, and if so, then set the red channel to Z; and repeat this step for the green channel.

Example 3

In this example, the Xpresso node takes two inputs. Assume we want to make the top half of the output image display the input 1 image, and the bottom half display the input 2 image. Use this expression:

(y > (Y/2)) ? [2] : [1]

In other words, check to see if the current y (height) is greater than half of Y (maximum height), and if so, set current pixel to input 2; if not, set it to input 1.

Example 4

In this example, the Xpresso node takes two inputs. Assume we want to perform an operation similar to an "inside" composite and make the output image black (transparent) everywhere except where input 2 has some alpha channel (c=3) coverage, at which points we want to display the input 1 image:

[0] = [2,x,y,3] != 0 ? [1] : 0

In other words, check to see if the current alpha of input 2 is nonzero, and if so, set to input 1; if not, set to 0 (black).

Example 5: Pattern Generators

Here are several patterns you can generate easily in the Xpresso node for testing and other purposes. The input image for these patterns is required only to set the size of the output.

Tip:
It is a good idea to create and use a color node, for example, rather than an image that is connected to a large network, so that the all the upstream nodes do not need to be processed.

Grid Pattern

This example creates a square grid on tens (you can change the value to vary the size of the grid):

x % 10 == 0 || y % 10 == 0 ? Z : 0

Checkerboard

You must use the Integer setting in the Math menu for this example, which creates a checkerboard (you can change the values to make the squares larger or smaller):

(x/20) % 2 - (y/20) % 2 ? Z : 0

Zone Plate

This example will create a moire-type pattern. For this pattern you must use the Float setting in the Math menu.

sin ((360 * x * y) / X) * 0.5 + 0.5

Example 6: Alpha Max

This expression combines the alpha channels of two inputs, using the higher value of the two for the output.

[1]; [0,x,y,3] = [1,x,y,3] > [2,x,y,3] ? [1,x,y,3] : [2,x,y,3]

To get the "alpha min" of two inputs, replace the greater than (>) operator with the less than (<) operator in the above expression.

Example 7: Flip X

This expression will flip an image along the X axis (to create a mirror image):

[0,x,y] = [1, X - (x + 1), y]

To flip an image along the Y axis (to turn it upside down), use this variation on the above expression:

[0,x,y] = [1, x, Y - (y + 1)]

Tip:
Use the "Save As" command in the Presets menu in the Xpresso node panel to save the current expression under a unique name, which will then appear in the Presets menu of every Xpresso node.
You can create a library of presets that you can select in any Xpresso node, without retyping the expression each time .



Table of Contents | Index



Copyright 1996-1999 by Silicon Grail Corporation