INDEX

### Scripting

#### NVIZ - Introduction

Sometimes it is desirable to automatically generate arbitrarily complicated changes to Nviz when creating an animation. The tools presented so far allow the user to create camera movement as well as add custom animation channels (e.g. the cut plane channel) to the key frame animator. However, the user would be required to add several complex channels to the key frame animator to capture the most general behavior. The purpose of the scripting environment is to allow the user to develop a one-time script file which can handle arbitrarily complex changes to the Nviz environment. Script files are extremely application dependent and, in general, will not be usable with other applications. However, they are the most convenient mechanism for capturing specific behavior quickly.

Scripting is controlled by the commands provided in the scripting pulldown menu (see figure below). By default, when scripting has been activated every user event in Nviz is recorded and output to a script saved as a text file. This script file may be played back in Nviz by using the Play Script option in the menu. Thus, most scripts are simply a carbon copy of the user performing certain actions. Scripting can become more powerful, however, by adding loops around a sequence of script events, or by using higher-level tools. The more advanced features of scripting are described in the Script Tools section below. The next section is devoted to describing basic scripting. Be sure to read this section carefully as the discussion of advanced features assumes the knowledge of this material.

### Script Pulldown Menu

#### Basic Scripting

Basic scripting entails designating a script file, turning scripting on and off, and sending commands directly to the script. Before doing anything with scripting it is necessary to designate a script file. This is done by selecting the Scriptfile option in the script pulldown menu. The user is queried for a file to use as the new script file. If the designated file already exists then scripting will overwrite the old contents of the file.

Once a script file has been selected, scripting is turned on and off by selecting the On radio button in the scripting menu. The status of this radio button indicates whether or not scripting is active. As soon as scripting becomes active, literally everything the user does is recorded in the script file. Since this can lead to extremely large script files, it is suggested that scripting be turned on only when the next few user events are critical to the script. When you are finished adding commands to the script, select Close Script to close the script file.

To make the script files somewhat more legible and useful, two additional commands are available in basic scripting: Add Script Line and Add Script Cmd. The difference between these two commands is subtle but important. We will delay a discussion of the differences between these two commands for now. For our purposes, the difference between these two commands is as follows: Add Script Line adds a command directly to the script being written and will not affect the state of Nviz; Add Script Cmd adds a command to the script which will affect the state of Nviz. A script in Nviz is really a Tcl script with a slightly specialized format. Hence, legal script commands are things like comments marked with the # character, expressions like set i [expr $i + 1], and so on. Add Script Line is intended to add commands which directly affect the Tcl code in the script. Thus comments can be added making scripts more readable, variables may be accessed, and conditionals may be inserted allowing the script to select different execution paths depending on script variables. Commands added by Add Script Cmd may also be Tcl commands. However, these commands are executed directly in the Nviz environment and affect the current state of Nviz directly (but do not affect the state of the script). Thus commands like Nsurf10001 set_att topo y90o.1, which will set the topology attribute of a particular surface to a particular file, are meaningful commands to add.

The combination of Add Script Line and Add Script Cmd provide the most general tools for controlling script files short of directly editing the text of a script. It is expected that these commands will rarely be used. However, Add Script Line in particular is useful for placing comments to separate distinct portions of a script and make the overall script file more readable.

#### Script Tools

The Script Tools menu selection pops up the script tools menu which provides higher level script manipulation facilities. It is possible to do everything a script tool does by using Add Script Line and Add Script Cmd described above. However, the script tools are much more convenient and should be used instead. Currently, there are three types of tool covering the five selections in the script tool popup. Open Loop and Close Loop allow iteration using a numeric loop variable. Open File Seq. Loop and Close File Seq. Loop allow iteration over a series of files. Finally, the File Sequence Tool allows very general iteration over a variety of attributes associated with surface, vector and site maps. Be sure that scripting has been turned on (by selecting On) before using a script tool. The File Sequence Tool does not necessarily require scripting to be on, but for now we assume scripting has been activated.

##### Open and Close Loop

The simplest tool is the Open/Close Loop pair. This tool defines a loop variable given the name lpX where X is the current loop being defined (starting with 1). The loop variable is iterated over a numeric range as specified by the user. The user may add commands (using Add Script Line) which reference the loop variable. The most general functionality provided by this tool is the ability to repeat some script activity a specified number of times.

A simple Open/Close Loop is created as follows:

- Select Open Loop from the script tools menu.
- Fill in numeric values for "Loop Start Value", "Loop End Value" and "Loop Increment Value" in the resulting popup (see figure below), and press "Accept".
- Continue scripting as usual adding all activities over which you wish to iterate.
- Close the loop by selecting Close Loop from the script tools menu.

##### Simple Loop Popup

Note that simple loops may be nested by repeating the above process from within a simple loop. Each additional loop uses the same naming scheme, thus the outer loop will be lp1, the first nested loop is lp2 and so on. Internally a stack of loop names is maintained so that selecting Close Loop closes the most recently opened loop.

##### Open and Close File Seq. Loop

Simple open/close loops work well when looping behavior is relatively simple. However, simple loops are restricted to iterating over numeric values. A common scenario is for some map object in the scene to display a sequence of map files. That is, we need to be able to iterate over lists of files. The Open/Close File Seq. Loop pair provide this functionality. This tool, when activated, forces any mapBrowser activities within the scope of the loop to use the current loop iteration value rather than the value entered by the user when the script is created. Creating a file loop is slightly awkward but follows these basic steps:

- Select Open File Seq. Loop from the script tools menu.
- Select a sequence of files using the Map Browser tool (see figure below), and press "Done".
- Continue scripting as usual adding all activities over which you wish to iterate.
- If you wish to apply the file sequence to a particular map, modify the appropriate map as if you were loading a file from the file sequence (see the example below).
- Close the loop by selecting Close File Seq. Loop from the script tools menu.

##### File Sequence Loop Popup

Like simple loops, file sequence loops may be nested as well as mixed with simple loops (make sure that you use the appropriate "Close" button however!). File sequence loops use a naming scheme similar to simple loops. File sequence iteration values can be accessed using the variable lseqX where X starts at 1 for the first loop and increments by 2 for consecutive loops (thus the next loop is 3, then 5, and so on).

To help clarify how the file sequence loop value can automatically be used by map browser activities, consider the following explicit example:

Suppose we want the topology of a surface map to sequence over a list of files (for example, the four file sequence shown in the map browser image above). We can use the file sequence loop tool to do this as follows:

1. Turn on scripting as usual.
2. Set up the state of Nviz just prior to iterating over the list of files. This includes loading the surface we wish to modify during the loop.
3. Open the file sequence loop with Open File Seq. Loop.
4. Select the list of files we wish to iterate over as above.
5. Load some arbitrary file into the topology attribute of the surface we wish to modify in the loop.
6. Close the file sequence loop with Close File Seq. Loop.

When the script event corresponding to changing topology (step 5 above) is replayed in Nviz, the current value of the file sequence loop is used instead of the value supplied during script creation. Thus, during each iteration of the loop the topology attribute is set to the current value of the file sequence loop.

Be aware that the file sequence loop affects all map browser activities within the scope of the loop. Thus any script events added within the scope of a loop which also require a map browser will have their value replaced during script playback with the current value of the file loop.

##### File Sequence Tool

##### Introduction

The final script tool, the File Sequence Tool, is the most complicated but also the most flexible. This tool is designed to allow iteration over several attributes of several maps in Nviz. Unlike the two previous tools, the File Sequence Tool is capable of automatically producing a stand-alone script file which can be played back within Nviz.

Creating a script using the File Sequence Tool consists of two major steps: creating a state file, and creating a file sequence. State files were discussed in the appropriate section above. For the purposes of scripting, the File Sequence Tool can use a state file as a basis for the script it creates. Usually, the user sets up Nviz in a configuration just prior to the beginning of file iteration and saves the state of Nviz. The script created by the File Sequence Tool can then load this state file automatically before performing file iteration. The example below should help clarify these activities. For now, let us take a detailed look at the File Sequence Tool control window.

The File Sequence Tool control window is activated by selecting File Sequence Tool from the script tools popup:

##### File Sequence Tool Window

The File Sequence Tool operates on the concept of fields. A field identifies some attribute of a surface, vector, or site map which will be modified during an animation. The lower area of the File Sequence Tool is used to display all the fields currently set. In the example above, a single field is defined which modifies the topography attribute of a surface in Nviz. The buttons under Fields: are used to manipulate the current list of fields. Pressing Add will create a new field. Pressing Delete will allow the user to delete one of the fields. The State: button is used to determine the state file which the current fields will use a basis for script creation.

Before we discuss how to add fields, it is important to understand what types of fields may be added and how they may be changed. As mentioned before, a field identifies some attribute of a surface, vector or site map that we wish to change during each frame of an animation. For surfaces, we can modify the attributes topography, color, mask, transparency, shininess, and emission. For vectors and sites, we can only modify the current file. Furthermore, there are at least three simple ways we can change a field inbetween frames: we can load a new file in the place of the current file; we can unset the field so that it has no value; and we can leave the field unchanged. The File Sequence Tool supports all of the attributes we have listed plus the three simplest ways of changing these attributes inbetween frames.

##### Adding Fields

Adding a field is a two step process: the user must decide which attribute of which surface, vector or site to modify; and the user must specify the list of changes to the selected attribute. Pressing the Add button creates the following popup:

##### Add Button Popup

Field Type: refers to the type of map object this field will modify. Valid selections are Surface, Vector or Site. Field Attribute: refers to what attribute of the given type the new field will modify. For surfaces, valid selections are Topography, Color, Mask, Transparency, Shininess, and Emission. For vectors or sites, the only valid selections is File. Set From: refers to a surface, vector or site file in the current session of Nviz which will be used as the placeholder for changes in the new field. When a script is created, the Set From map object has the specified attribute changed according to the new field. Thus, the Set From map object should also be stored in the state file used by this file sequence.

After selecting an appropriate type, attribute and source map object, clicking Accept creates the file browser popup:

##### Field File List Popup

Normally, the file browser will have no selected files. However, for the sake of illustration we have already selected a few files in the image above. The MAPSETS and FILES lists operate just as in the Open/Close File Seq. Loop tool above. When a file is selected, its name is copied to the file list on the far right. File names may be entered explicitly in the type-in field on the top. The list of files on the far right indicates the sequence of changes the current field will undergo when a script is created. Recall that the File Sequence Tool supports three mechanisms for changing a field between frames: load a new file, unset the field, or leave the field alone. Selecting a file from the FILES list corresponds to loading a new file inbetween frames. By pressing the Blank button, the field is directed to unset the field for the next frame. This is indicated by storing -- blank -- as the next file in the file list. By pressing the Previous button, the field is directed to make no changes to the field and use the setting for the previous frame. This is indicated by storing (NO CHANGE) *** where *** is the previous entry in the file list.

For example, in the image above the file list changes can be described as follows:

1. a1.masked@helena is loaded.
2. Nothing is changed for frame 2.
3. The current field is unset and will not be displayed.
4. a3.masked@helena is loaded.
5. as.2m100@helena is loaded.

The Remove button removes the selected file entry from the file list. The Done button is used to indicate that you are finished creating the file sequence for the current field. Clicking Cancel will backup to the Add Button Popup. Clicking Cancel on the Add Button Popup will cancel the creation of a new field.

The file sequence for a particular field may be changed even after it has been added to the field list. Each field in the File Sequence Tool Window contains a button which indicates the type of map object this field modifies (see the image above). Clicking this button pops up the file browser as above except that the list of files is initialized to the current file list for the selected field.

##### Saving Fields

A particular configuration of fields can be saved for later editing by using the Load Fields... and Save Fields... options under the Options: heading. Save Fields... will save all of the current field configurations plus the name of the associated state file for later user. Conversely, Load Fields... will load a configuration of fields. Note that, in order to edit a group of fields in a different Nviz session, it will be necessary to re-load the state of Nviz that existed when the original fields were created. This is necessary so that the map objects which the original fields referenced will be present in the system if these fields are changed.

##### Building a Script

Once the user has created all the necessary fields for a particular script, it is possible to create a playable script file. There are two ways script information can be created: script information can be written to a script currently being created, or a separate, stand-alone script can be created. In either case, the script code created will only create the changes indicated by the given fields over the given number of frames. Extra code, such as code necessary for rendering and saving images after each frame, must be added separately. Since adding image saving code is a frequent activity, a comment is added to the code produced by the File Sequence Tool to aid the user in determining where to add code.

Clicking Add To Script will add code to the current active script which will invoke the changes indicated by the field files. Make sure that scripting has been turned on (see above) before using this option.

Clicking Build Script... will build a stand-alone script file. Stand-alone scripts first load the state file, then the field changes are executed as specified by the field descriptions. As usual, code must be added to the script to render images and save them to files.

##### Example

The following step-by-step example should help clarify the creation of a script using the File Sequence Tool.

For this example, we will specify one surface with a vector and site file overlayed on top of it. At each frame, we will change the topography and color attributes of the surface, and the overlay files for the sites map. This animation will be a stand-alone animation. Recall that creating an animation with the File Seq. Tool requires two major steps: creating a state file and creating the field specifications. Since we will need all the appropriate maps loaded into Nviz before we can create the field specifications, we will go ahead and create the state file first:

1. Start up Nviz with "nviz -q".
2. Add the surface "y90o.1@helena" by pressing New on the surface panel.
3. Position the camera so that the surface is in full view.
4. Add the vector map "shore.ascii@helena" by pressing New on the vector panel.
5. Set the vector map so that it overlays the surface we added in step 2 above.
6. Add the sites map "y90mo.1@helena" by pressing New on the sites panel.
7. Set the sites map so that it overlays the surface we added in step 2 above.
8. Set an appropriate size for the sites map.
9. Save the state of Nviz by selecting Save State... from the File menu and choosing an appropriate name.

At this point, we have established the state of Nviz before our animation will begin. State files provide a convenient encapsulation of the state of Nviz just prior to beginning animation. In fact, we may alter state files independently of the scripts which require them as long as we do not change the map objects required by each script. This allows users to modify such features as colors, positioning, line sizes, lighting, etc. without having to remake scripts.

The next step is to set up the frame changes for the animation. We will require three fields: one to modify surface topography, one to modify surface color, and one to modify the sites source file. For the sake of brevity, our animation will only be five frames long. We can create the field changes as follows:

1. Load the script tools by selecting Script Tools under the Scripting menu.
2. Press the File Sequence Tool button on the script tools popup.
3. Press the Add button under Fields: in the File Sequence Tool.
4. Be sure that Field Type: is set to Surface, Field Attribute: is set to Topography and Set From: is set to "y90o.1@helena", then press Accept.
5. In the file browser popup, select the sequence of files:
   - y90o.1@helena
   - y90o.2@helena
   - y90o.3@helena
   - y90o.4@helena
   - y90o.5@helena
   and click Done.
6. We have just created the five frame changes for the topography attribute. Repeat steps 4 and 5 except set Field Attribute: to Color. This creates the five frame changes for the color attribute.
7. Repeat steps 4 and 5 except set Field Type: to Site. In the file browser popup , select the sequence of files:
   - y90mo.1@helena
   - y90mo.2@helena
   - y90mo.3@helena
   - y90mo.4@helena
   - y90mo.5@helena
8. Finally, set the state file to the file you saved in state creation above. State file is set by pressing the State File: button under Fields:.

At this point, the File Sequence Tool display should look something like the following:

##### File Sequence Tool Example

It may be wise to save your progress up to this point by clicking Save Fields... and choosing an appropriate file name. Saving the fields configuration is also a convenient way to use the same state file with different fields settings. For example, we could later modify our fields settings above by changing the list of files used in the frame sequence, adding new fields, etc.

Since we are generating a stand-alone script, press the Build Script... button and choose an appropriate file name for the new script. We will now edit the script so that it will render each frame after the field changes have been made. Load the script file into your favorite editor and do the following:

1. Find the line with the comment "# Put image saving code here". It is after this line that we will add commands to render frames.
2. Add the following four lines after the comment exactly as they appear here:

            SendScriptLine "Nsurf_draw_all"
            SendScriptLine "Nvect_draw_all"
            SendScriptLine "Nsite_draw_all"
            after 1000

3. Re-save the script file.

The four lines we have added are instructions to Nviz to render the all surface, vector and site files, then wait approximately one second before going on to the next frame. The SendScriptLine command is described in the next section. At this point, the script is purely stand-alone and can be played from within nviz. To play the script select Play Script from the Scripting menu and choose the script file you saved above. After a brief bit of initialization, the script will execute the field changes we specified above.