### 4 Basic Use of DX

This recipe introduces the basic use of DX. It covers creating and running a simple DX network. Only the very minimum set of features needed to create and run a network are mentioned; there are many features and facilities which are omitted. See the QuickStart Guide[1] and other IBM DX manuals for further details (the IBM manuals are listed in Table 1 of SUN/203[11]). The best way to use this recipe is probably to have a terminal on which you can run DX to hand and to work through the recipe trying the various points.

Unless otherwise noted, throughout this cookbook ‘click’ means click on the leftmost mouse button.

(1)
% dx

The following message should appear on your command terminal:

Starting DX user interface

and a new window similar to Figure (1) should appear.

(2)
Figure (1) shows the main window for the Visual Program Editor (VPE). You will use it to construct DX networks which in turn will generate visualisations.
• The large blank area is the canvas where the network will be constructed.
• A DX network consists of modules, represented by icons, each performing some function. The collection of modules is divided into categories of similar modules. On the left hand side of the VPE are two boxes containing lists of items. The top box, labelled ‘Categories:’, lists all the different categories of modules. The current category is highlighted (it is ‘Annotation’ in Figure (1)). The lower box, labelled ‘Annotation Tools’, shows all the modules in the current category.

To choose another category simply click on the category required. The new category will be highlighted and both the label and the contents of the lower box will be changed to reflect the new choice.

(3)
To place a module on the canvas (for subsequent inclusion in a network) proceed as follows:
(a)
select the appropriate category, so that the required module appears in the lower box,
(b)
click on the required module in the lower box, and it will be highlighted,
(c)
move the cursor to the desired position in the canvas and click again. The module will appear as a rectangular icon (see, for example, Figure 3).
(4)
If you want to move a module to another position in the canvas (for example, because you have inadvertently put it in the wrong place):
(a)
click in the body of the module and hold down the leftmost mouse button,
(b)
move the cursor to the new position (continuing to hold down the mouse button),
(c)
release the mouse button.
(5)
To delete a module from the canvas:
(a)
click in the body of the module. It should appear highlighted, with a white bar above and below it,
(b)
choose the ‘Delete’ option from the ‘Edit’ menu and the module should disappear from the canvas.
(6)
The icons representing modules usually have tabs projecting from their top and bottom sides.
• The tabs along the top represent inputs to the module.
• The tabs for mandatory inputs are coloured a brighter shade of green; optional (or defaulted) inputs are the same colour as the body of the icon.
• The tabs along the bottom represent outputs.

In DX data can only flow from an output tab to an input tab. An input tab can only be fed by one output tab. However, an output tab can feed an arbitrary number of input tabs.

(7)
To connect an output to an input:
(a)
click on the output tab and hold the leftmost mouse button down,
(b)
move the cursor to the input tab, continuing to hold the mouse button down,
(c)
release the mouse button.

A line should be drawn from the output to the input tab (not all input and output types are compatible; if the tabs are not compatible DX will not connect them with a line).

(8)
To remove the connection between an input and output:
(a)
click on the input tab and hold down the leftmost mouse button,
(b)
move the cursor to a blank portion of the canvas,
(c)
release the mouse button, and the connection will vanish.
(9)
At this juncture, practice positioning modules on the canvas, deleting them and connecting them, until you have got the hang of it.
(10)
Values for input tabs can be specified as defaults as an alternative to supplying a value from an output tab. This mechanism is often used to specify the name of the data file which a network is to operate on, as well as to supply other values needed by a network. The procedure is as follows:
(a)
double-click on the module for which an input value is to be set,
(b)
a new window, called the configuration window, should appear, showing the commonly used inputs for the module. Figure 2 shows this window for the ‘Import’ module,

(c)
each line of the ‘Inputs’ section of the window corresponds to a separate input; their names are listed on the right hand side. For module ‘Import’ the inputs are ‘name’, ‘variable’ and ‘format’,
(d)
click on the ‘Value’ box for the chosen input,
(e)
hold down the leftmost mouse button and drag it over the existing value, so that the existing value is highlighted,
(f)
type in the new value,
(g)
hit return (do not forget this step),
(h)
after you have hit return DX will display the value that you have entered, inside the box, in double quotation marks,
(i)
repeat the procedure until all the required inputs have been set, then click on the ‘OK’ button.

By default only the commonly used inputs for a module are shown. To show all the inputs (and outputs) click on the ‘Expand’ button.

(11)
Various on-line help information is available within DX. In particular, it is possible to get help on individual modules, which is useful both for finding out what a module does and for determining the input which it needs. To obtain help on a module proceed as follows:
(a)
click on the ‘Help’ menu in the top right hand corner of the VPE (see Figure (1)),
(b)
choose menu-item ‘Context-Sensitive Help’; the mouse pointer will change to a ‘?’,
(c)
position the pointer over either the required module on the canvas or the name of the module in the list in the bottom left hand corner of the VPE, and click,
(d)
another window containing a detailed description of the module will appear. Note that this information is formatted as hypertext, with links being indicated by a box drawn around the linked text. Simply click inside the box to follow the link,
(e)
when you have finished perusing the text simply click on the ‘Close’ button.
(12)
Another useful trick is that if you position the pointer over an input or output tab and hold down the leftmost mouse button then while the button is depressed the name of the tab appears in the module icon. This feature is particularly convenient for identifying tabs.
(13)
Now clear the canvas ready to start building a network: select option ‘New’ from the ‘File’ menu.
(14)
Figure 3 shows virtually the simplest possible DX network. You are now going to create this network.

There are two ways to create the network. The first is to find the three modules, position them on the canvas and join them as shown. The second is to read in a prepared copy of the network from a file. For the second option proceed as follows.

(a)
Select ‘Open Program’ from the ‘File’ menu.
(b)
The ‘Open…’ window appears, as shown in Figure 4. You will use this window to specify the network file.

(c)
The ‘Filter’ box at the top of the window controls the files available for selection. It contains a wild-card file expression and all the files which match the expression are available for selection. Click on this box and enter:

$STARLINK_DIR/examples/sc2 A list of networks should appear in the ‘Files’ box on the right hand side of the window. By convention DX networks have file type ‘.net’. (d) Click on file ‘simple.net’ in this box. The full file name and directory specification of the simple network should now appear in the ‘Selection’ window. (e) Click on the ‘OK’ button. The ‘Open…’ window closes and the network is loaded onto the canvas. The network is now ready for use. (15) The purpose of the three modules of the network is: Import read in the field to be displayed from an external file, AutoColor colour a field ready for display, so that a range of values in the field map to a range of colours, Image display a field. In this network ‘Image’ will produce a volume rendering of a gridded dataset. However, it can accept various other sorts of input to produce different sorts of display. #### 4.1 Running a network Running a DX network to generate a visualisation comprises three stages: specifying the input (particularly the file to be read), running the network and examining the result. This example describes how to execute the simple network loaded in the previous section. It will be used to view an example data file, supplied with the cookbook, which contains a data cube of a simple Gaussian. This data cube is a ‘field’ in the context of DX; see Section 17 for an explanation of this term. (1) Double-click on the ‘Import’ module; the configuration window shown in Figure 2 should appear. (a) Set input ‘name’ to: $STARLINK_DIR/examples/sc2/field.general

This file is the DX ‘header’ file describing the data file. Files written by an external program and imported into DX are described by a separate header file. See Sections 5 and 6 for details. Note that it is the name of the header file, not the data file, which is given here. If the header file is in your current directory then the directory specification can be omitted.

(b)
Set input ‘variable’ to: Gaussian

This input specifies which field within the data file is to be read. In the current example the field is called ‘Gaussian’. Again see Sections 5 and 6 for details.

(c)
Set input ‘format’ to: general

Here ‘general’ means that the data file has been written by an external program and is described by a separate header file. The only other option which you are likely to encounter is ‘dx’ for a native DX format file.

(d)
When all the values have been set correctly simply click on the ‘OK’ button.
(2)
To run the network select ‘Execute Once’ from the ‘Execute’ menu. The network will probably take a few minutes to run.
(3)
After a few minutes a window containing the visualisation will appear. The options for this window allow you a great deal of choice in viewing the visualisation. The following couple of hints might be useful.
• DX is a bit lackadaisical about resetting the limits of the plot when a new visualisation is generated. If your visualisation does not neatly fill the plotting window (it may be either too big or too small) select the ‘Reset’ option from the ‘Options’ menu.
• By default DX generates a view perpendicular to one of the axes, which gives an unnaturally ‘flat’ appearance to the image. For a better perspective view select the ‘View Control’ option from the ‘Options’ menu. The ‘View Control’ window appears. Set the ‘Set View’ toggle to ‘Diagonal’ or one of the ‘Off…’ options.