6.2 Using the VPE

A visual program is a collection of interconnected tools that acts upon one or more inputs to create one or more outputs (for example, an image). You derive program inputs from the output of tools in the program, or by setting the input values to constants. Tools that provide output values as input to other tools are (in alphabetical order):

• Colormap Editors (see 6.3 , "Using the Colormap Editor")
• Interactors (see "Using Interactors")
• Macros (see 7.2 , "Creating and Using Macros")
• Modules (see Chapter 1. "Data Explorer Tools" in IBM Visualization Data Explorer User's Reference)
• Picks (see "Using Pick")
• Probes (see "Using Probes (Cursors)")
• Sequencers (see "Using the Sequencer")
• Transmitters and Receivers (see "Using Transmitters and Receivers").

Before building a visual program, you should be familiar with the information presented in this chapter as well as the information on Data Explorer modules presented in Chapter 1. "Data Explorer Tools" in IBM Visualization Data Explorer Programmer's Reference.

Chapter 2. "Tutorial I: Using Data Explorer" in IBM Visualization Data Explorer QuickStart Guide introduces the Data Explorer graphical user interface. Chapter 3. "Tutorial II: Editing and Creating Visual Programs" in IBM Visualization Data Explorer QuickStart Guide introduces the basic aspects of working with visual programs. These tutorials will familiarize you with the user interface as well as some of the commonly used Data Explorer modules.

Creating a Visual Program

To create a visual program, use the Visual Program Editor (VPE) window, in which you place and connect tools and specify values for those tools. Figure 47 illustrates the VPE window and a sample visual program.

Figure 47. VPE Window

The title bar of the VPE displays the name of the current visual program file. On the left side of the window is a palette. You can expand the cateogries by clicking on the (+) sign next to the category name to list the tools associated. The large area on the right side of the window is called the canvas. You place tools on the canvas to construct a visual program.

In some cases, the visual program may be too large to be displayed all at once on the canvas. On the right and bottom sides of the canvas are scroll bars, which allow you to move the display to different parts of the visual program. To display a different part of the visual program, click on the arrows at the end of the scroll bars, or click and hold the button on the bar between the arrows and move it until the desired portion of the visual program is displayed. Scroll bars may also appear in the tool palette, if the list of tools is too long to fit.

When you place a tool onto the canvas, it is represented by an icon. Figure 48 illustrates an example of a tool icon.

Figure 48. Example of a Tool Icon

The tool icon, which has a highlighted border when selected, consists of a rectangle displaying the name of the tool, plus one or more tabs on the top, the bottom, or the top and the bottom of the rectangle. The rectangle is the active area and is used for selecting and moving the tool. The tabs on the top represent inputs to the tool, and the tabs on the bottom represent outputs. It is possible for a tool to have either no inputs or no outputs. Some of a tool's input tabs may be hidden (i.e., not displayed). It is possible to reveal the hidden tabs or hide additional tabs. It is also possible to add or remove input tabs for tools that allow a variable number of inputs. On many tools, one or more of the inputs are highlighted with a different color, indicating that the input is required. These tabs are discussed in more detail in "Specifying Values for a Tool's Inputs".

The basic steps in creating a visual program are:

1. Select and place the desired tools on the canvas.
2. Connect tool outputs to inputs.
3. Set values for the tools.
4. If you plan to change input parameters frequently while viewing an image (e.g., an isosurface value), then you should build a Control Panel and set interactors (see "Building Control Panels" and "Using Interactors").

Placing Tools on the Canvas

1. Click on the (+) next to the desired category. The names of the tools in that category appear below the category name. All palette lists are presented in alphabetic order.
2. Select the appropriate tool name from the palette by clicking on the tool's name. Clicking on an already selected tool deselects that tool.
3. It is also possible to locate a tool by placing the cursor of the Tools list and begin typing the first few letters of a desired tool.

To place one instance of the selected tool on the canvas:

1. Move the cursor to where you want to position the tool on the canvas. Note that the style of the cursor changes when you move it onto the canvas. Exact placement of the tool depends on the grid settings (see "Customizing the VPE Window").
2. Click the mouse. The tool icon appears at the specified location. When you have placed the tool, its name is no longer highlighted in the tool palette.

1. Double click on the tool name in the tool palette.
2. Click the mouse on the canvas to place one instance of the tool. Repeat this step for further instances of the tool.
3. To stop placing the same tool, deselect the tool's name in the palette by clicking on any tool name.

To deselect a tool name in the palette, do one of the following:

• Click on the tool name.
• Select another tool name.
• Select another category.
• Press the space bar with the cursor located over the Tools palette.

Selecting, Moving, and Deleting Tool Icons

To select a tool icon, click on it.

To select a group of tool icons, use one of these methods:

• Hold down the Shift key and click on each tool icon in turn.

• Position the cursor on the canvas near a corner of the group and drag the mouse to draw a selection box around the tool icons you want. To select the tool icon, you must completely enclose it in the selection box. As a tool icon is encompassed by the selection box, it is highlighted (indicating that it is selected).

  Note:

  If you have tools selected already and you want to select more, hold down the Shift key and either click on a single icon, or drag the selection box over several icons to select them. To select all icons on the canvas, use the Select All option of the Edit pull-down menu.

To deselect an icon, shift-click on it.

To deselect a group of tools, use one of these methods:

• Shift-click on each icon.

• Shift-drag to draw a box around the tools you want to deselect. As a selected tool is encompassed in the box, it becomes unhighlighted. Release the button to deselect the tools.

To move a tool icon:

1. Press and hold the left mouse button on the tool icon and drag it to the desired location. While you are dragging the tool, an outline of the tool icon follows the motion of the mouse, but the tool icon remains in the original location.
2. Release the mouse button at the desired location. The tool icon moves to that location. Any lines connecting to other tools are rerouted to the tool's new location.

or

1. Select a tool icon to be moved.
2. Press the up, down, left, or right cursor keys to move the tools one pixel at a time in the direction pressed.

To move a group of tool icons:

1. Select a group of tool icons to be moved.
2. Position the cursor on any member of the group and drag it. An outline of each tool icon follows the motion of the mouse.
3. Release the mouse button. The icons representing the tools move to the new location. Any affected connections are rerouted.

To delete tool icons:

1. Select the tool icon or group to be deleted.
2. Press the Ctrl+Delete accelerator key or click on the Delete option of the Edit menu.

Specifying Values for a Tool's Inputs

To provide the values of a given input for a tool, use one of these methods:

• Connect the output tab of another tool to the desired input tab.
• or
• Use the tool's Configuration dialog box.

When you specify an input value for a tool, the corresponding tab on the tool's icon automatically folds in. If you do not specify an input value, the input tab remains folded out, indicating that the input is unbound and the tool uses its default for that input. The default values are given in the Configuration dialog box. The tabs that are folded in give you a visual representation of the inputs that have user-specified values. Some tabs require an input; those tabs remain highlighted in a different color until you specify an input with a connection or through a Configuration dialog box. Some of the tabs are not displayed, termed hidden. The hidden tabs can be revealed or additional tabs can be hidden (see "Revealing and Hiding Input Tabs"). Also, some tools allow you to add or remove input tabs (see "Adding and Removing Input and Output Tabs"). Figure 49 illustrates tools whose inputs have been specified.

Figure 49. How Tabs Work. An input tab folds in when its input is supplied through a connecting "arc" or is defined in the module's configuration dialog box. When the default input is used, the tab remains up. An output tab folds in when it is connected to another module by an arc.

A tab that is folded in but has no connecting line leading to it indicates that its input was specified using the tool's Configuration dialog box.

Creating, Deleting, and Moving Tab Connections

To connect tabs:

1. Click and hold the mouse button on the output tab. This causes the cursor to change to a downward pointing arrow. When the cursor is placed over the output tab, the name of the tab is displayed in the tool icon.
2. While pressing the mouse button, drag the cursor to the desired input tab. While you are dragging the cursor from the output tab, a white line appears indicating that a connection is being created.
3. When you enter the area encompassing a tool icon, the tabs that are compatible with the output tab you are trying to connect will change color. When the cursor is placed over an input tab, the name of the tab is displayed in the tool icon.

   Note:

   You can also connect tabs by starting at the input tab. Simply press and hold the mouse button on the desired input tab; this causes the cursor to change to an upward pointing arrow. Drag the cursor to the desired output tab. When the cursor enters the area encompassing a tool icon, the output tabs that are compatible with the input tab will change color.

4. Place the pointer over the input tab you want and release the mouse button. If you release the mouse button in the rectangle area of the icon, the line automatically connects to the leftmost of the newly colored tabs.

   When you release the mouse button, the white temporary line is replaced with a black line, and the corresponding tabs fold in.

   Note:

   Sometimes, when tools are placed too close together on the canvas, a connection that you made is not visible. In this case, the affected input tabs are still folded in, and a dark line is visible on each one, but the connecting line is not visible. To correct this, move one of the affected tools to another spot on the canvas.

You can connect an output tab to more than one input tab (either on different tool icons or on the same tool icon). Therefore, you can make a connection from an output tab even though the output tab is folded in.

An input tab can receive a value from only one source, either from a connection to an output tab or from a value entered in a Configuration dialog box. Once an input tab folds in, you cannot make a new connection to the tab until the tab is released.

Because output tabs can have multiple destinations, connections can only be moved or deleted from an input tab.

To delete a tab connection:

1. Depress the mouse button on the input tab.
2. Drag the cursor to an empty space on the canvas (away from the active area of the tool). A white line from the output tab follows the mouse pointer. If you decide at this point not to break the connection, you must place the cursor back on the input tab where the connection was, and release the mouse button.
3. Release the mouse button. The connection is deleted and the input tab released.

To move a tab connection:

1. Depress the mouse button on the input tab.
2. Drag the cursor to an empty input tab (one that has not already been folded in).
3. Release the mouse button. The connection is rerouted to the new input tab.

Moving and Copying Tools

The Drag and Drop capability provided by Data Explorer allows you to move or copy selected tools within a Data Explorer window (e.g., the VPE or a control panel) or between different Data Explorer windows (i.e., between two different VPE windows). You can also drag interactor stand-ins to control panels to create interactors.

To initiate a drag and drop, first select the tools you want to move or copy, either by rubber-band or shift selection. Then place the mouse cursor over one of the selected tools and press the middle mouse button. Keeping the button pressed, move the cursor to an empty spot on the canvas and release the button. A copy of the selected tool will be placed where the mouse button was released. To do a cut and drop (move), use Shift-middle mouse button.

When dragging and dropping tools from the VPE, you may drop the tools on a VPE in another Data Explorer session or in another VPE (i.e., macro editor) of the same Data Explorer session. Interactors in control panels can only be dragged and dropped between panels in the same visual program.

If you drag a set of tools to an inappropriate window (e.g., from a control panel to a VPE), no action will occur. If you drag a set of tools that includes transmitters, the latter (along with their corresponding receivers) will be renamed to wireless-1, wireless-2, and so on.

Note: To include an existing .net file in the VPE, use the Insert Visual Program option of the Edit pull-down menu in the VPE. The inserted visual program is placed to the right of the rightmost tool in the existing network.

Using Transmitters and Receivers

It is possible to create large visual programs in Data Explorer. Data Explorer provides two tools, Transmitter and Receiver, to maintain the modularity and readability of large programs. These tools allow connections between input and output tabs without using a visible connecting line. Using the Transmitter and Receiver tools allows you to separate visual programs into logical blocks. For example, the output of several logical blocks can be transmitted to another block that receives them, collects them, and produces the image. Macros, described in 7.2 , "Creating and Using Macros", provide another way to structure visual programs into logical blocks.

To remotely connect input and output tabs:

1. Select the Transmitter tool, which appears under the Special category in the tool palette, and place it near the output tab.
2. Connect the tool's output tab to the input tab of the Transmitter.
3. Select the Receiver tool (also in the Special category), and place it near the input tab to be connected to the output tab above.
4. Connect the Receiver's output tab to the receiving tool icon's input tab.

   The Receiver automatically assumes the same name as the Transmitter. There can be multiple instances of a Receiver corresponding to a single Transmitter. These Receivers assume the same name until a new Transmitter is selected.

   The name of a Transmitter and Receiver can be changed using the notation field of the Configuration dialog box (as described in "Entering Values in a Configuration Dialog Box"). When you change the name of the Transmitter, all Receivers that share a name with that Transmitter also change their names. However, when you change the name of a particular Receiver, the associated Transmitter and the other Receivers are not affected.

Adding and Removing Input and Output Tabs

Most of the tools have a fixed number of inputs and outputs, but some, such as Collect and Compute, allow the number of inputs to vary. For example, the default number of inputs for Compute is two, but you may want to use the output from an expression that has six inputs. Data Explorer lets you change such tools to accommodate the extra inputs.

To add input tabs to a tool on the canvas:

1. Select the tool icon by clicking on it.
2. Select the Add Input Tab option from the Input/Output Tabs option from the Edit pull-down menu. (You can also use the Ctrl+A accelerator key.)

   Note:

   If the tool you selected has a fixed number of inputs, the Add Input Tab option is grayed out.

The appropriate number of input tabs are added to the tool icon. Typically, the Add Input Tab option adds one tab to the icon. In the case of some tools, such as CollectNamed, that require inputs in pairs, two input tabs are added. To add multiple tabs, repeat the previous steps.

When you change the number of input tabs on the tool icon, the tool's Configuration dialog box is updated to reflect the change.

To remove input tabs from a tool on the canvas:

1. Select the tool by clicking on it.
2. Select the Remove Input Tab option from the Input/Output Tabs option from the Edit pull-down menu. (You can also use the Ctrl+R accelerator key.)

   Note:

   If the tool you selected has a fixed number of inputs, or if the icon has only the minimum number of tabs required for that tool, the Remove Input Tab option is grayed out.

   The appropriate number of input tabs are removed from the right-side tool icon. If the tabs that are removed previously had connections to them, those connections are broken. It is possible for some tools to have zero input tabs. For example, you may want the Compute module to contain only an expression, with no inputs. The output would be the result of the expression.

Entering Values in a Configuration Dialog Box

The Configuration dialog box displays the current state of a tool's inputs. You can modify the contents of the box directly. The contents are also automatically updated when changes in the visual program or in interactors in a Control Panel affect a tool's inputs. In general, specifying input values using the Configuration dialog box should be reserved for those values that remain constant during a visualization session. Use an interactor set in a Control Panel to specify values that are likely to be changed frequently.

This section describes a typical Configuration dialog box, illustrated in Figure 50. The Configuration dialog box for the Compute module, which is unlike the other Configuration dialog boxes, is described in "Using the Compute Module Configuration Dialog Box".

Figure 50. Typical Configuration Dialog Box

You can open a Configuration dialog box in one of the following ways:

• Double-click on the rectangular portion of a tool's icon.
• Select the icon and click on the Edit menu Configuration option (or use the Ctrl+F accelerator key).

A typical Configuration dialog box consists of four major parts:

• Notation
• Inputs section
• Outputs section
• Pushbuttons

The following sections describe the elements in a Configuration dialog box.

Notation Field

By default, the Notation field displays the name of the tool. You can use this field to enter a short notation about the use of the tool in the current visual program:

1. Select the field by clicking on it.
2. Edit the field as a normal text field (i.e., using Backspace, Delete, and the alphanumeric keys).

In the case of Transmitter, Receiver, Probe, ProbeList, and Pick tools, use the Notation field to rename the tool, thus changing the name appearing on the tool icon.

Inputs Section

Outputs Section

Pushbuttons

The seven buttons at the bottom of the Configuration dialog box are labeled boxes that perform an action when you click on them. The buttons are:

OK	Applies new values and closes the box.
Apply	Saves newly entered values. Once you click on the Apply button, you can no longer restore previous values.
Expand	Causes all hidden inputs to be displayed in the Configuration dialog box. You can then unhide hidden tabs using the Hide toggle button.
Collapse	Causes all hidden input tabs to be removed from display in the Configuration dialog box.
Description	Displays a window with descriptions of the input and output parameters of the tool.
Restore	Restores previous values that were present when you opened the box or when you last clicked on the Apply button.
Cancel	Restores previous values that were present when you opened the box or when you last clicked on the Apply button, and then closes the box.

Revealing and Hiding Input Tabs

Most of the tools have more input tabs than are displayed when a tool icon is initially displayed. For example, the Isosurface module has six inputs, but when an Isosurface tool icon is initially placed on the canvas, only three input tabs are displayed. The displayed tabs represent those that are most frequently used.

To reveal the hidden input tabs:

1. Select the tool icon by clicking on it.
2. Select the Reveal All Tabs option from the Edit pull-down menu. (You can also use the Ctrl+L accelerator key.)

Once the input tabs have been revealed, they can be hidden.

To hide input tabs:

1. Select the tool icon by clicking on it.
2. Select the Hide All Tabs option from the Edit pull-down menu. (You can also use the Ctrl+H accelerator key.)

Hiding input tabs in this way will cause all tabs that are not connected to another module to be hidden.

If you wish to hide or reveal individual inputs, use the hide toggle button in the Configuration dialog box (see "Inputs Section").

Using the Compute Module Configuration Dialog Box

The Configuration dialog box for the Compute module, illustrated in Figure 51, differs in some respects from the other Configuration dialog boxes. It consists of:

Notation	See "Notation Field" for information.
Name	These fields allow you to enter names for the parameters of the expression. By default, the names are labeled a and b, but you can change them to a name more relevant to the particular computation. (You can have fewer or more than two inputs to the Compute module; see "Adding and Removing Input and Output Tabs".)
Source	See information on Source fields.
Expression	The expression is entered in this field. See Compute in IBM Visualization Data Explorer User's Reference for more information.

Figure 51. Typical Dialog Box for the Compute Module

Locating Tools: The Find Tool Dialog Box

The Find Tool... dialog box provides you with an easy way to locate tools on the VPE canvas. You may find this dialog box especially useful if you are editing a large visual program. The dialog box can also be used to locate transmitters and receivers by the names you give them. You open this dialog box by selecting the Find Tool... option from the Edit pull-down menu.

Figure 52. Find Tool Dialog Box

Figure 52 illustrates the layout of the Find Tool dialog box. The dialog consists of three parts:

Tool list	Displays an alphabetized list of all the tools in the visual program currently displayed on the VPE canvas. If the visual program contains transmitters, receivers, probes or picks, then the tool name (e.g., Transmitter) is displayed instead of the user-supplied name.
Selection	Displays the current tool to be located. When the dialog first appears, this field is blank. To change the selected tool either click on the desired tool name, or click on the Undo or Redo buttons, or type the name of the tool, transmitter or receiver directly in the selection text field. The next time you open the dialog box, the selection field will display the last selection you made.
Pushbuttons	Find initiates the search for the selected tool. Undo undoes the last find and updates Selection. Redo redoes an undone find and updates Selection. Restore restores the canvas to the location at the time the dialog box was opened. Close closes the dialog box.

To locate a particular tool on the canvas:

1. Click on the tool name.
2. Click on the Find button. This will initiate the search for the first occurrence of the tool icon on the canvas. When the tool is found, the portion of the canvas that is displayed may be updated to include the located tool icon.

If you wish to find another occurrence of the same tool, simply click on Find again. This can be repeated as many time as you desire. When no more occurrences of the tool can be found, a message is displayed. If you click on the Find button again, the search will be reset and the first occurrence of the tool icon will be located.

If the selected tool is a transmitter, receiver, probe, or pick, occurrences of the tool will be found independently of the user-supplied name. To locate a transmitter, receiver, probe, or pick tool by name:

1. Enter the name of the transmitter, receiver, pick or probe in the Selection: text field.
2. Click on the Find button.

You can initiate the search for a different tool at any point. If you wish to retrace your steps, the Find dialog provides an Undo button, allowing you to undo up to 10 previous searches. When you click on the Undo pushbutton, the name of the tool (or transmitter or receiver) that was previously located will appear in the Selection: text field and the canvas is updated to reflect the location of the tool icon.

The dialog box also provides a Redo button. This enables you to repeat a search that was undone with the Undo button.

If you wish to return the canvas to its former "state" (i.e., to the set of tool icons it displayed) prior to the first search, click on Restore button.

Note:

Clicking on Undo, Redo, or Restore will deselect the tool that is selected in the Tools palette.

Customizing the VPE Window

Under the Options menu bar category are selections for customizing the window:

Tool Palettes	Use as a toggle by clicking to close the palettes and make the working area on the canvas larger.
Grid...	A dialog box, illustrated in Figure 53, appears for you to enter new values.

Figure 53. Grid Dialog Box

The Grid... option allows you to specify whether the tools you place on the canvas automatically align on a grid pattern. You can enable the grid pattern by clicking on one of the following:

1D Horizontal
1D Vertical
2D

You can control the spacing of the grid pattern by changing the number of vertical and horizontal pixels. Specify how the tools are to be aligned on the grid by changing the alignment toggle buttons. For example, the dialog box in Figure 53 specifies grid spacing of 50 pixels, with the center of a tool being placed at a grid position.

Adding Comments to a Visual Program

For your own documentation purposes, you can add comments to your visual program. These comments are saved and restored as you save and restore the program.

To add a comment to the visual program:

1. Select the Comment... option from the Edit pull-down menu. A window opens with space for a large text field. If a comment has been entered previously, it is displayed in the text field.
2. Enter the desired comment in the text field. Edit the field the same way you edit any text field. This text field has multiple lines; you can generate line breaks using the Enter key, or type continuously and have the line breaks added automatically.

You can view these comments by using the Comment... option of the Edit pull-down menu in the VPE, or by using the Application Comment option of the Help pull-down menu in any primary window.

Adding Annotation to a Visual Program

You can also add annotation directly to the canvas. Select the Add Annotation option from the Edit pull-down menu. A cursor appears. Click on the canvas where you would like to place annotation. You can modify the text in the annotation by double-clicking on the annotation. A text-entry dialog appears.

By default, the annotation text is visible on the canvas. You can choose the Hide Text option on the text-entry dialog, in which case only a "marker" appears on the canvas.

Creating pages in the VPE

You can structure your visual program to make it more readable by using pages. A visual program can consist of a number of pages. Each page contains a set of modules completely disconnected from modules on other pages. Receivers and transmitters are used to connect modules on different pages.

To use pages, select the Pages... option in the Edit menu of the VPE. A cascade menu allows you to create an empty page, create a page containing the currently selected tools, delete the currently displayed page, or configure the page, that is, change its name or position.

Automatic Graph Layout of a Visual Program

Saving and Restoring a Visual Program

The Save As... and Open... options of the File pull-down menu use similar dialog boxes. A sample Save As... dialog box is illustrated in Figure 54.

Figure 54. Save As Dialog Box

File Selection Dialog Boxes

You can use the scroll bars provided on the right side and the bottom of the directories and file listings to view file and path names that are either too long or too numerous to fit in the available space.

Saving a Visual Program

When saving a visual program, Data Explorer saves the following files:

• The visual program, with a .net extension
• The configuration settings, with a .cfg extension

An existing file can be saved in the following ways:

• Under the same name, replacing the previous version of the file

• Under a new name or directory, thus creating a new file and preserving the previous version.

Replacing a Previously Saved File

To save a program that has been named and saved previously, press Ctrl+S or select the File menu Save option. This replaces the previous version of the file. A named visual program has its name displayed in the title bar of the VPE window.

Saving a Visual Program as a New File

To save program as a new file:

1. Select the Save As... option from the File pull-down menu. The Save As... dialog box appears (see Figure 54). The Selection field displays the current file path.
2. Click on the Selection field and add the new file name. If you want to save the file to a different directory, change the file path in the field as well.
3. Press the Enter key or click on OK.

The file is saved and the Save As... dialog box disappears.

Restoring a Previously Created Program

To restore a previously created visual program, select the File menu Open option.

The Open dialog box appears (Figure 55).

Figure 55. Open Dialog Box

It lists all file names in the current directory that are found through the specified file filter. A file can be selected in one of the following ways:

• Double-click on the file name under the Files heading.

• Click on the file name under the Files heading. The file name appears in the Selection text box. Click on OK.

• Click in the Selection text box and type the file name, then press Enter or click on OK.

Note that a complete file name must be specified in the Selection field to read in a file. A file name may be highlighted under the Files heading without appearing in the Selection field. To select the file, click on its name under the Files heading.

To see any comments that might be associated with a visual program before you load it, select a file by clicking on its name once or by entering its name in the Selection text box, then click on the Comments button. If the visual program has comments associated with it, they are displayed; otherwise, a message appears telling you that there are no comments.

To see a different list of files, change either the file filter or the file directory ("File Selection Dialog Boxes").

When you open a file, its name is displayed in the title bar of the VPE.