Appendix D: Scripting

You can use scripting commands to execute common operations from the command line without opening the RAYZ interface. In addition, you can write scripts to create RAYZ project files that will be opened and further modified in the interface.

In This Chapter

Command-Line Execution of Scripting Commands

Generating RAYZ Files

Command-Line Execution of Scripting Commands

RAYZ 2.2 adds a wealth of new command-line capabilities, allowing Technical Directors and others to execute common activities without opening up the RAYZ interface. Apart from being simpler and quicker to do some things, this also has the advantage of only using a render license, instead of the full interface license.

The basic form of command-line execution of RAYZ is as follows:

rayz <input_images> [operation(s)]

where the <input_images> argument is required, and all the [operations] are optional. In general, <> angle brackets indicate required parameters, and [] square brackets indicate optional values.

Usually, one of the operations will be to write out the processed images, though that is also optional. The minimal command of

% rayz image.tiff

will launch the RAYZ interface with the single "image.tiff" image as input. In general, without the -write command, the command-line version will launch the GUI with the listed operations as nodes. This can be useful for debugging or just getting started on a RAYZ session without having to use the file browser or node menus.

Specifying Input Image Sequences

The input image(s) must be specified in RAYZ format, in which $F indicates a frame number, such as 34, 6, and 195. The format $F4 indicates a padded frame number, such as 0034, 0006, and 0195. The `4' indicates how many digits are in the frame number, so that $F1 is equivalent to $F; $F2 will return 34, 06, and 195; $F3 will give you 034, 006, and195; and $F4, 0034, 0006, and 0195.

Generally, the $ symbol must be `escaped' from the IRIX or Linux shell that you are using, with the backslash character, as in

% rayz images.\$F4.tiff

If you are constructing a shell script which will issue the commands, you will probably need multiple escape characters, because the shell script is itself interpreted before being passed to the shell. So inside a shell script, you will end up with something like this:

#!/bin/csh -f
rayz images.\\\\$F4.tiff

When this line is passed to the shell, it is turned into this

rayz images.\$F4.tiff

which is then received by RAYZ as

images.$F4.tiff

Frame Ranges

RAYZ will scoop up all the images that match the input pattern, regardless of their numbering scheme. So in a directory of images which start at frame 120 and go to 125, that is

image.0120.tiff

image.0121.tiff

image.0122.tiff

image.0123.tiff

image.0124.tiff

image.0125.tiff

the command

% rayz image.\$F4.tiff

would read in the 6 frames, one at a time, from 120 to 125. It is not currently possible to specify a range of frames on the command line. For example, it would not be possible to only process frames 121-124 in the above range; it is all or nothing. This will be addressed in a future release of RAYZ.

Saving the Results

The command -write is used to copy the results of the processing to some new disk files. The syntax of this command is

-write <format> <namestring>

where <format> is one of jpeg, sgi, tiff, or any of the other formats RAYZ supports. You can discover all the currently supported formats by typing

% rayz -help-file-types

As of this writing, the list is:

adobe

alias

aliasdepth

cdi

cinedepth

com

dpx

fido

frp

icon

jpeg

maya

msbmp

null

pgm

png

quicktime

raw

sgi

softimage

targa

tiff

wavefront

yuv

The <namestring> is a formatted name string just the same as the input file string. So an example of the -write command would be

-write yuv video\$F4.yuv

Some Simple Examples

You can use the simple tools we have so far to do file format conversion. For example, to convert from .tiff to .jpeg, the command would be:

% rayz inputs.\$F.tiff -write jpeg outputs.\$F4.jpeg

To blur the contents of a directory, the command would be:

% rayz dino.\$F.sgi -blur 5p -write sgi dino_blurred.\$F.sgi

This uses the -blur command, which takes a single parameter, the blur width.

Specifying Pixel or Float Values

The blur width in the example above is given as "5p," which means 5 pixels.The alternative would be a value of 0.01f, which means a blur size of (0.01 * image_size). The `f' stands for `float,' which means that the value is relative to the size of the incoming image.

The `f' or `p' character is optional; but if not specified, then `pixels' is assumed. So the above example could also have been written as

% rayz dino.\$F.sgi -blur 5 -write sgi dino_blurred.\$F.sgi

Similarly, doing -resize to change the size of an image can be done to an absolute pixel size, like this:

-resize 320 243

Or it can do a relative resizing, for example, making the image 50% of its original size, like this:

-resize 0.5f 0.5f

You can also mix these within the same command, so that the following is completely valid:

-resize 320 0.25f

Note that 0.25 might be an obvious fraction to you, but without the `f' character at the end, RAYZ will assume that you want to size to 1/4 of a pixel! To be safe, always specify `p' or `f.'

Adding Complexity

Commands can be chained together to form an assembly line of processes. This is especially useful when constructing a shell script which does several things at once to a series of images. For example, say you want to take a series of images, flip them horizontally, scale them down, and convert them to jpeg. You can do this all in a single command, which would look like

% rayz images.\$F.sgi -flipflop horizontal -resize 320 243 -write jpeg stamps.\$F.jpeg

The operations are applied to the images in left-to-right order.

You can also do limited compositing operations on the command line. To do A over B, for example, looks like this:

% rayz imagesA.\$F.sgi -over imagesB.\$F.sgi -write sgi comp.\$F.sgi

The syntax for the -over (and -add, -atop, -difference, -inside, -multiply, -outside, -subtract and -under) operation is

-over <b_input_files>

You can also do a dissolve, with the added parameter of the dissolve amount:

% rayz imageA.sgi -dissolve 0.5 imageB.sgi -write sgi out.sgi

When using commands with long names, you can use the shortest string which uniquely identifies that command. So instead of -dissolve, you could write -dis, and instead of -difference you could write -dif.

Full Command List

The full list of possible commands can be obtained by typing

% rayz -file -help

When you type the help command, the options will be listed with the syntax "--name"; but in this document, as you may have noticed, the single dash is used, as in "-name." Either will work.

Here is a list of current commands, with examples where useful. Again, note that the syntax is <required_parameter> and [optional_parameter]:

Sources

Color

-color <width> <height> <8|16|32> <a[lpha]|rgb|rgba> <color_values...>

Color values are given in floating point, in the range 0 to 1.0

-color 720 486 8 rgb 0.5 0.6 0.25
Color Bars

-colorbars <ntsc|pal> <75|100> <8|16|32> <rgb|rgba>

-colorbars pal 75 8 rgb
Image In

-read <image_file> image_file

is the same syntax as for other input, and for -write, namely

images.\$F4.sgi
Image Out

-write <file_type> <output_path>

Color Ops

Brightness

-brightness <brightness> [<offset>]

This only allows a single overall brightness (and offset) value, which is given in the range from 0.0 to 1.0

Channel Swap

-channelswap <channels> [<film|ntsc|pal>]

The channels are listed as input channels (r, g, b, etc.) and placed in the position where they are to be swapped to. For example:

-channelswap bgr 

would put the incoming blue channel into the outgoing red channel, the incoming green into the outgoing green, and the incoming red into the outgoing blue.

Channels can be reused, so that this is allowed

-channelswap rrr 

which would set all channels to the incoming red values.

The full list of valid channels is

r

red

g

green

b

blue

a

alpha

l

luminance

0 (zero)

black

z

white

Channels can also be listed by number, so 1 == red, 2 == blue, etc., which allows channels 5 through 9 (assuming they exist) to be specified.

-channelswap 50z 

sets the red channel to the fifth incoming channel, sets the green channel to black, and the blue channel to white.

Contrast

-contrast <contrast> [<pivot>]

Gamma

-gamma <gamma>

Invert

-invert

Monochrome

-monochrome [<amount> [<film|ntsc|pal>]]

The simplest use of this would be

-mono 

If the type of monochrome calculation is not given, the default is "film," which is just an averaging of the 3 color channels. As in RAYZ, an "amount" of 0 means that the output is equal to the input. The default "amount" is 1.0.

Video Safe

-videosafe <film|ntsc|pal> <intensity|saturation>

Xforms

Flip Flop

-flipflop [<rotate>] [<horizontal>] [<vertical>]

With no parameters set, this operation does nothing to the input image.

Resize

-resize [fit] <width>[f|p] <height>[f|p]

The optional "fit" argument will constrain the amount of scaling to be the same in both directions, using whichever is most. This is useful for doing letterboxing, for example.

To letterbox input into a PAL image size, the command would be

-resize fit 720p 576p
Transform

-rotate <angle> [<pivot_x>[f|p] <pivot_y>[f|p]]

Angles are given in degrees.

-scale <width>[f|p] <height>[f|p] [<pivot_x>[f|p] <pivot_y>[f|p]]

Scale is different from Resize in that Resize changes the actual size of the resulting image. Scale will position a smaller version of the input within a black image of the original size. If you scale up, the output will be the same size, and the parts which extend outside the incoming borders will be clipped out.

-translate <offset_x>[f|p] <offset_y>[f|p]

Comps

For all these, the b_input_image_file must be a valid file or files named on the spot, that is, something like

-add imageB.sgi 

You cannot nest operations to form a virtual b image; the following will generate an error:

-add -colorbars ntsc 75 8 rgb 

The image generated just before the comp operation is considered to be the a_input_image_file. So A over B is done as

% rayz imageA.sgi -over imageB.sgi -write sgi out.sgi

-add <b_input_image_file>

-atop <b_input_image_file>

-difference <b_input_image_file>

-dissolve <amount> <b_input_image_file>

-inside <b_input_image_file>

-multiply <b_input_image_file>

-outside <b_input_image_file>

-over <b_input_image_file>

-subtract <b_input_image_file>

-under <b_input_image_file>

Filters

-blur <size>[f|p]

-blurxy <xsize>[f|p] <ysize>[f|p]

-unsharpmask <mask_amount> <kernel_size>[f|p]

-xpresso <"expression">

Note that the quotes are required in order to get the expression to RAYZ intact. So for example, to construct a vector map to use for doing radial blur, you would do this

-xpresso "[0,x,y,0] = sin(angle); [0,x,y,1] = cos(angle);" 

Note also that Xpresso almost always wants to have float input to work properly, so you probably want to precede it with

-bitdepth 32

Conversion

If you are reading in Cineon images, there is currently no way to avoid converting them to 16 bit linear using the default parameters. This may not be what you want. The way to work around this is to immediately convert back to log, and then reconvert using the parameters you want. Since these operations concatenate, there will be no loss of precision in working this way.

As an example, say you want to specify a different log white point, say 983, for converting a group of Cineon images. The command for this would be

% rayz in.\$F4.cin -lintolog -logtolin 16 95 983 65535 0.6 1.7

-bitdepth <8|16|32> [<black_in>[f|p] <black_out>[f|p] <white_in>[f|p] <white_out>[f|p]]

-lintolog [<ref_black> <ref_white> <lin_white>[f|p] <film_gamma> <display_gamma>]

-logtolin <8|16|32> [<ref_black> <ref_white> <lin_white>[f|p] <film_gamma> <display_gamma> [<soft_clip>]]

Generating RAYZ Files

Using the RAYZ interface is not the only way to create and edit a node network. You also have the option of writing a script that describes it. A RAYZ script can be loaded into the interface and edited like any other file, and any file created in the RAYZ interface can be edited as a script.

The ability to modify imagery interactively while viewing the result is, of course, indispensable, and knowledge of scripting is unnecessary to build a shot in the RAYZ interface. But scripting is ideal for automating certain types of tasks, such as generating pre-comp files programmatically which can then be opened in the interface for further editing and refinement.

For example, you could write a script that imports all the image elements available for a shot and generates any other source nodes that might be needed. Then the scripted file could be opened in the RAYZ interface with all of the imagery pre-loaded into Image In nodes and all of the import options set appropriately. The script could even include a basic network of nodes to which the imported imagery would be connected: the script could specify that bluescreen elements be connected to Ultimatte nodes before sending the image data downstream to a composite node, and so on.

Scripting can save a lot of time that would be spent on repetitive setup tasks as well as ensuring that RAYZ files point to the correct image directories or use predetermined settings for certain operations.

Scripting Languages

A RAYZ script can be written using any scripting language you prefer: perl, tcl, python, or csh, for example. This means that you do not have to learn a whole new scripting language with its own set of conditionals, looping, and so forth. You only have to become familiar with the basic structure used in a RAYZ file to describe node operations and connections. Another advantage of this system is that interactive and script-generated RAYZ files always remain compatible, which means that a script can always be opened and edited in the interface, and vice versa.

The Structure of a RAYZ File

A RAYZ file contains the following categories of information:

All of the information listed above is optional except for the node information. If the layout and project preferences are not specified, the RAYZ defaults are used. (Strictly speaking, even the node information is optional, in that you can load an empty file into RAYZ.)

The best way to find out how RAYZ files are structured is to open one in a text editor and examine it, however, an overview of basic node syntax is provided below.

Node Syntax

This is the basic syntax used to describe the node information in a RAYZ file:

nodename = nodetype(input_node1, input_node2, ...)

{

parametername1: value;

parametername2: value;

...;

}

The parameter specifications are optional; at minimum, you could use the following syntax to create a node with no input connections and all parameters set to default values:

nodename = nodetype ( );

All statements end with a semicolon, and groups of statements are contained in braces (curly brackets).

Take the simple example of a brightness operation on color bars. The following would create a Color Bars node named "cbars" with its output connected to the primary input of a Brightness node named "bright1":

cbars = colorbars( );
bright1 = brightness(cbars);

You do not have to list parameters unless you want to change their default values. To specify a change to the brightness (the default values for the Brightness node do not change the output), specify the parameter and the value:

bright1 = brightness(cbars)
{
brightness: 0.5;
}

The Brightness parameter is actually the master value for a channel group. To change the brightness of all channels except the Red channel, you could specify a change to the master brightness value and then offset it in the Red channel as follows:

bright1 = brightness(cbars)
{
brightness: 0.5;
brightness.red: 0.5;
}

The above example would bring the brightness of the Red channel back up to 1.0, because individual channel parameter values are always stored as deltas of the master value, as explained in Channel Groups in chapter 7.

The same effect could also be achieved by specifying a decrease in the Green and Blue channel parameter values, without changing the default master value:

bright1 = brightness(cbars)
{
brightness.green: -0.5;
brightness.blue: -0.5;
}

For nodes that accept multiple inputs, connections are made in the order listed. In the following example, the output of the Color Bars node would be connected to the primary input of the Brightness node, and the output of a Gradient node named "grad1" would be connected to the optional mask input:

bright1 = brightness(cbars, grad1);

Node Names

The names you should use to identify node types in RAYZ 2.2 script files are the same as the default name given to a new node of that type, minus the incremental number at the end.

For example, when you create a new Multi-comp node in the RAYZ GUI, it is given the name "multicomp1" by default. To designate a Multi-comp node in a script, therefore, you would use "multicomp" (all lowercase, no spaces, no numeral at the end).

Parameter Names

For node parameters, use the same name that is used to identify them in the Keypoint Viewer of the Curve Editor (see also Editing Keypoints Numerically in chapter 8). If the parameter cannot be animated and is therefore not displayed in the Keypoint Viewer, such as the frame range parameters in the source nodes, save a RAYZ file with the same type of node and open it in a text editor.

The parameter most commonly used in writing RAYZ scripts is probably the file path in Image In:

nodename = imagein()

{

full.file_info.file_id: "/directory_path/filename.$Fn.ext";

}

To specify proxies:

nodename = imagein()

{

full.file_info.file_id: "/directory_path/filename.$Fn.ext";

medium.file_info.file_id: "/directory_path/filename.$Fn.ext";

low.file_info.file_id: "/directory_path/filename.$Fn.ext";

}

Script Errors

When RAYZ finds an error in a script, it will open the file if possible and generate an error message. If you misspell the name of a node type, for example, the error dialog will tell you that RAYZ was unable to create the node, but the file will still be opened with the other nodes specified in the script.

If you specify an input to a node that does not accept an input, such as Color Bars, RAYZ will give you an error message about the connection but still create the Color Bars node.

If you give multiple nodes the same name, RAYZ will append a number to them, incrementing it as necessary (cbars, cbars1, cbars2, etc.), without generating an error.