10.2 Understanding the Script Structure

The following example illustrate some of the more important characteristics of scripts; a detailed description of each of the elements follows. However, you may prefer to simply study these examples (and perhaps those in /usr/local/dx/samples/scripts) and then begin writing your own scripts.

Example 1. A Simple Script

In this example, the data found in /usr/...cloudwater is imported and assigned to the variable data. Then the Isosurface module is called on data (with no other parameters set) and the result is assigned to iso. A Camera is created using AutoCamera, and the isosurface is displayed using Display (note that the Image tool is not available in the scripting language.

data = Import("/usr/local/dx/samples/data/cloudwater");
iso = Isosurface(data);
camera = AutoCamera(iso);
Display(iso, camera);

Example 2. Setting Parameters

Suppose that in the previous example we wished to set the Isosurface "number" to 3. number is the third parameter to Isosurface. We can replace the second line of the script in Example 1 with:

iso = Isosurface(data, NULL, 3);

iso = Isosurface(data, number=3);

Example 3. Using a Macro

It is possible to create and use macros in the scripting language. A macro is defined using the keyword "macro," as in the following example.

macro make_iso(data, isovalue) -> (isosurface)
{
   isosurface = Isosurface(data, isovalue);
}

iso1 = make_iso(data, 0.1);
iso2 = make_iso(data, 0.2);
...

A macro can have as many inputs or outputs as desired. Note that it is not necessary to pass parameters into a macro; the parameters will be found in the environment outside of the macro if necessary. However, it is necessary to pass any parameters out of the macro that are intended to be used outside of the macro.

Example 4. Using Route in the Script Language

The Route module is used to choose between different destinations for a particular object. For example, you could choose to either write an image to a file or display the image to the screen.

In order to use Route in a script, the Route module and the tools that consume the outputs of Route must be contained in a macro.

data = Import("/usr/local/dx/samples/data/cloudwater");
iso = Isosurface(data);
camera = Autocamera(iso);
image= Render(iso, camera);
macro do_which(which, image)
{
   image_to_display, image_to_write = Route(which, image);
   Display(image_to_display);
   WriteImage(image_to_write);
}
do_which(1, image);

The call to the macro do_which with a value of 1 causes the first output branch (Display) to be executed. WriteImage is not executed. If do_which had been called with a value of 2, however, then WriteImage (and not Display) would have been executed.

Example 5. Using the Sequencer

You can use the Sequencer in script mode. The special variables you use are:

@startframe	the starting integer of the sequence
@endframe	the ending integer of the sequence
@deltaframe	the increment between frames (default = 1)
@frame	contains the sequence number of the current frame.

The keyword "sequence" identifies the macro that will be run each time @frame is incremented, and the keyword "play" will start the sequence.

The following script will call the macro "doit" with the values 0, 2, 4, 6, 8, 10:

@startframe =0;
@endframe =10;
@deltaframe =2;
macro doit(i)
{
   Echo(i);
}
sequence doit(@frame);
play;