## Chapter 3. Tutorial II: Editing and Creating Visual Programs

Partial Table-of-Contents

- 3.1 Editing a Visual Program: The Basics
- 3.2 Creating a Visual Program: Two short examples
- A simple two-dimensional field
- A simple three-dimensional field
- 3.3 Importing Data
- Example 1
- Example 2
- 3.4 A thumbnail Sketch of the Data Prompter Choices
- 3.5 Importing Your Own Data
- 3.6 Visualizing 2-Dimensional Data
- Colors
- Contour Lines
- Streamlines
- RubberSheet
- 2-D Scalar Glyphs
- 2-D Vector Glyphs
- 3.7 Visualizing 3-Dimensional Data
- Isosurfaces
- Slices
- Streamlines
- 3-D Scalar Glyphs
- 3-D Vector Glyphs
- Volume Rendering
- 3.8 Tasks and Tools
- Adding Captions
- Adding Input Tabs to Tool Icons
- Connecting Scattered Data Points
- Controlling Execution with Switch
- Controlling Inputs: Configuration Dialog Boxes
- Controlling Inputs: Interactors
- Creating Animations
- Creating and Using Macros
- Data-driven Tools
- Modules: Using AutoColor
- Modules: Using Compute
- Modules: Using Map
- Modules: Using Plot
- Processing Images
- Saving and Printing Images
- 3.9 Scripting Language

  This tutorial will show you how to modify existing visual programs and create new ones. In the process, it will also introduce you to a number of the most commonly used modules. As you become more experienced using Data Explorer, you can explore more of each module's many options.

  Tutorial II Visual Programs

  - Visual programs and files required for Tutorial II all reside in the same directory and therefore have the same path name except for file name and extension. Thus where a visual program is referred to only by its file name and extension (i.e., `.../filename.ext`), the full path name is easily derived if needed:

        /usr/local/dx/samples/tutorial/filename.ext

  - The procedures you will be using most are:
    - 2.4 , "Opening and Executing a Visual Program"
    - selecting tools and placing their icons in the Visual Program Editor canvas (see "Selecting tools and placing icons")
    - opening and modifying a configuration dialog box (see "Specifying inputs: configuration dialog boxes" and also "Controlling Inputs: Configuration Dialog Boxes").

  ## 3.1 Editing a Visual Program: The Basics

  When you open the Visual Program Editor (VPE) with the `dx -edit` command, or by choosing `New Visual Program` in the Startup window, you will see a large blank area (the "canvas") and two "palettes" to its left (see Figure 4). The palette at top lists "categories" of tools (modules). The palette below it lists the tools in the currently selected (highlighted) category.

  #### Selecting tools and placing icons

  1. Click on a tool category (e.g., `Transformation`) in the upper palette. The tools in that category are now listed in the lower palette.
  2. Click on a tool in the lower palette (e.g., `AutoColor`) to highlight it.
  3. Move the cursor into the canvas area. Note that it becomes an inverted "L."
  4. Position the cursor at the point where you want the tool icon to appear and click again to generate the icon.

  #### Tool icons

  Each tool icon has one or more tabs on top and bottom. These tabs represent, respectively, input(s) to the tool module and output(s) from it.

  There are two ways to specify an input:

  - by specifying a value in the configuration dialog box associated with a particular tool
  - with an arc, or line, connecting the output tab of one icon to the input tab of another.

  #### Specifying inputs: configuration dialog boxes

  To open the configuration dialog box for a tool, either:

  - Double click on the tool icon in the canvas, or
  - Single click on (highlight) the tool icon in the canvas and select "Configuration" from the `Edit` pull-down menu.
  In the case of interactors, color maps, the Image tool, and the Sequencer, the first procedure invokes a "control box" (another kind of dialog box). The second procedure always invokes a configuration dialog box.

  Tabs and inputs to a tool module | Each input parameter in the configuration dialog box corresponds to an upper tab on the tool icon. The leftmost tab corresponds to the first parameter, and so on.
  Visible versus hidden parameters | At the bottom of the dialog box are `Expand` and `Collapse` buttons. The first button "expands" the dialog box, displaying additional parameters. The second button "collapses" the dialog box, hiding every parameter whose "Hide" toggle button is activated. (When a tool has no hidden parameters, both buttons are disabled, as indicated by their gray labels.)

  #### Specifying inputs: arcs and icons

  A visual program is a "network" of interconnected tool modules. In the VPE window, this network is represented as a set of tool icons connected to one another by lines ("arcs") representing the data (Figure 4 in Tutorial I shows such a network.)

  Connecting tool icons with arcs

  1. Position the cursor on an output tab of an icon and hold down the left mouse button: the cursor becomes a downward-pointing arrow, and a parameter or data name for that tab appears on the icon.
  2. Drag the cursor to another icon: the output tab remains connected to the cursor by a highlighted line (arc). If the connection is valid, the input tab(s) will be highlighted when the cursor arrow touches the icon. (If the connection is invalid, the tab(s) will not be highlighted, and an error message will appear.
  3. Release the mouse button to establish a connection to a valid input tab.

     Notes:

     1. If the "receiving" icon has two or more valid input tabs, if you release the mouse button when the cursor is on the main part of the icon, the connection to the first (leftmost) tab is automatic. To establish a connection to a different tab requires placing the cursor on that tab before releasing the mouse button.
     2. You can establish a connection starting with an input tab and dragging the arc to an output tab.

  Disconnecting or moving an arc

  Click on the input tab to which the arc is connected (e.g., the input tab on Sequencer): a highlighted arc, connected to an (Import) output tab appears:
  - Disconnect the arc by dragging the cursor to an empty spot in the canvas and releasing the mouse button, or
  - Move the arc by dragging it to another icon and releasing the mouse button to establish the new connection.

  #### Deleting a tool icon

  1. Highlight the tool icon by clicking on it.
  2. Select `Delete` in the `Edit` pull-down menu. .

  #### Moving a tool icon

  Select a tool icon and drag it to the desired location before releasing the mouse button.

  [ OpenDX Home at IBM | OpenDX.org ]