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.
By using the appropriate command line option, you can also perform some basic functions, such as resizing images, and render the modified image files without creating a RAYZ project file.
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.
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.
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.
This is the basic syntax used to describe the node information in a RAYZ file:
nodename = nodetype(input_node1, input_node2, ...)
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:
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);
Here is a list of names used to identify node types in RAYZ 2.0 script files:
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:
full.file_info.file_id: "/directory_path/filename.$Fn.ext";
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";
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.
You can execute some RAYZ node operations from the command line using rayz -exec. The syntax to use is
The commands you can use include
-brightness <brightness_value> <offset_value>
-over <b_input_image_filename>
-resize <pixel|fract> <width> <height>
-write <file type> <output_path>
-color <width> <height> <8|16|32> <a|rgb|rgba> <color_values_per_channel>
The pipe (|) in the above command options separates multiple choices; choose one to specify the option.
Values for brightness, offset, and color channels should be in fractional (floating point) units; that is, use 1 to represent maximum value in 8-bit or 16-bit colorspace rather than 255 or 65535.
For the most up-to-date list of scripting commands and usage, type:
rayz -file -help
For a complete list of file formats you can use with the -write command, type the following command at the prompt:
rayz -help-file-types
To create a frame of solid white (as in a Color node) that is, say, 3 channels, 8-bits per channel, and video resolution, you would type the following command:
rayz -exec -start 1 -end 1 -color 720 486 8 rgb 1 1 1 -file color_field.tif
Most commonly you will use these scripting commands to modify existing files, as to create versions in a different file format and/or resolution.
For example, you would use the following command to create JPEG versions of a sequence of images called "my_files.$F.tif:
rayz -exec -file my_files.\$F.tif -write <jpeg> some_path/my_jpeg_files.\$F.jpg
To modify a specific range of frame in the sequence, add -start and -end; the following command specifies frames 1 to 100:
rayz -exec -start 1 -end 100 -file my_files.\$F.tif -write <jpeg> some_path/my_jpeg_files.\$F.jpg
To scale the output by 50 percent, add the -resize command:
rayz -exec -start 1 -end 100 -file my_files.\$F.tif -resize fract 0.5 0.5 -write <jpeg> some_path/my_jpeg_files.\$F.jpg
To rescale using pixel dimensions, the form of the -resize command would be -resize pixel 360 243 (or whatever pixel values represented the size the output files should be).