This chapter explains, step by step, how to use IRIS Explorer tools to create and run maps. It describes how you:
launch modules from the Module Librarian
wire modules into a computational network, or map
use the map to visualize numerical data
select modules with compatible data types
change the values of module parameters
set parameter relationships in the Parameter Function Editor
incorporate modules on remote systems into a map
fix some common problems
In the Map Editor, you create an IRIS Explorer map. A map is a collection of modules of different kinds, connected in sequence, which process numerical data to accomplish a task. A module is a processing unit in a map. Each module accepts data, acts on it, and sends the result to the next module downstream. The Map Editor is the environment in which maps are created and executed, or fired.
Maps can be used to perform a variety of tasks, for example, generating a visual image from a specific dataset. A patient may arrive at a medical clinic with an injured leg. The doctor generates a 3D CT scan, which shows a compound fracture of the femur. The CT scan data can be fed into an IRIS Explorer map and visualized as a 3D or volume image of the bone. The doctor may extract a 2D slice from the CT scan data along a plane close to the break in the bone. Then, if necessary, another slice can be taken from a slightly different angle for further elucidation. In this way, the doctor acquires a unique understanding of the fracture, which can help when deciding on an appropriate treatment.
Data is read into IRIS Explorer by the first modules in a map sequence, and the succeeding modules determine what form the results will take, and for what range of data values. For example, you can pinpoint areas where the bone is badly damaged by coloring the image according to bone density values.
The Module Librarian displays available maps and modules. You can launch single modules from the Module Librarian, arrange them in the Map Editor, and connect them to one another by their data input and output ports. These ports allow the flow of data between modules, the connections appearing as wire-like blue lines. Maps are usually arranged so that the data stream flows from left to right across the screen. You can also launch complete maps.
The Map Editor and Module Librarian menus provide you with options for manipulating the modules in a map. The modules themselves are accessible through their maximized control panels. These are rectangular panels, displayed on-screen, which contain widgets, the means of adjusting module parameters.
The Map Editor (see Figure 2-1) is the work area in which you assemble modules for the purpose of organizing them into an operational map. A map is analogous to an application, in that it comprises a series of algorithms performing mathematical operations on data. Each module represents one discrete operation on the data.
To bring up the Map Editor, double-click on the IRIS Explorer icon in the IRIS Explorer for Windows program group.
The Module Librarian, the Map Editor, and the Log Window appear.
To exit from the Map Editor, open the File menu and select Exit. When you do this, you also quit IRIS Explorer after confirmation at the prompt.
You can select, copy, duplicate, delete or move, single or multiple modules by using the Map Editor. The modules may be free-standing or already wired into a map.
Use the Map Editor pull-down menus to:
launch and save modules or maps in the Map Editor, and add remote hosts if you are using a map distributed over several systems (File menu).
duplicate, cut, copy, paste, destroy, enable, disable, disconnect and reconnect modules (Edit menu). The operation is applied to all selected modules. In Figure 2-1 only the Render module is highlighted as selected.
Some of the Edit menu options have keyboard shortcuts listed next to them.
group modules together, and open, close, edit or compile groups (Group menu).
control layout within the Map Editor, such as the connecting wires and the execution highlighting (Layout menu).
display or remove from view features such as the Main Log window, Toolbar, Librarian, module Control Panels and Skm window (View menu).
set various configuration options (Configuration menu).
display information about the version of IRIS Explorer and the IRIS Explorer Centers (Help menu).
Once a map is set up in the Map Editor, you can run it so that the modules fire and send data to one another. You can also incorporate several modules into a group or an application (see Chapter 5, "Creating Groups and Applications").
The object visualized in Figure 2-1 is a curved torus, generated by GenLat.
The Module Librarian (see Figure 2-2) is a file browser and selector that provides access to IRIS Explorer modules and maps through its scrolling columns and Librarian shelf.
Use the Module Librarian and its menus to:
update the contents of the Librarian or create new categories for modules and maps to be arranged into (Display menu)
search for modules with input or output ports of a particular type or keywords in the module help files (Search menu)
launch or obtain help for a module or map, or, additionally for a module, launch an example map illustrating the use of the module or find maps which contain that module. A module Properties window, containing information about the module's location and creation time, can also be displayed (from each module's or map's pop-up Launch menu)
Categories in the Module Librarian can be either closed (showing a + icon) or open (with a - icon). Open and close a category by clicking on the icon with the left mouse button. When the category is open, its contents (maps and modules) are visible. Modules are indicated by an icon of a module, while maps are indicated by an icon showing three modules on a Map Editor.
You can use the Librarian search facilities to search for modules in a variety of different ways. The easiest way to search for a module by name is to click on the status bar at the base of the Librarian and type the first characters of the name you are searching for. <Backspace> deletes the last character typed. <Return> terminates the search string; any subsequent characters start a new search. <Escape> deletes the search string and the contents of the search window. The search is not case-sensitive.
Select the Ports option on the Search menu to find modules by specifying the type of either their input ports, or their output ports, or both. (The data types which are passed between modules are described in Section 2.8). The search will return all modules which have at least one input and/or output port of the specified type(s). Thus, using this option, it is possible to search for all modules which receive, say, lattices and output geometry. If a type is not specified for the input or output port, then the search will return modules having any type on that port.
You can also select Keyword from the Search menu to find modules and maps by searching for a specific keyword in the module and map help files.
The results of the search appear in the search pane of the Module Librarian (see Figure 2-2).
There is also the possiblity of a Repeat Search. This option, which allows a series of searches to be combined together, may be toggled by clicking with the left mouse button on the Module Librarian status bar (at the bottom of the window), and then pressing <Tab>. Alternatively, click with the left mouse button in the leftmost section of the status bar (the keyword REP appears here when the Repeat Search option is turned on). When repeat searching is in force, searches combine together, so that only the results of the previous search are used as input to the next search. For example, using this option, it is possible to combine three searches in order to find (for example) all modules beginning with B that accept lattices and output geometry and which mention Isosurface in their help files. Note that, if the search window isn't empty (i.e., if a search has just returned some results), turning on repeat searching causes the results of this most recent search to be used as input to the next search. If the search window returns no matches, the repeat search option is turned off.
To find which maps utilize a particular module, click with the right mouse button on the module name in the Librarian and select Find maps containing this module from the pop-up menu. The results appear in the search pane at the bottom of the Librarian.
To jump to the location of a particular module or map within a category in the Librarian,
make the Librarian the active window,
expand the module category which is to be traversed,
and type the first letter or two of the module or map name. For example, if you want to launch the Render module, place the cursor on the list and type re. The list scrolls down to the first module name starting with re. The Librarian is not case-sensitive, so you could also type RE.
Finally, you can simply scroll through the categories in the Librarian. Place the cursor in the scrolling channel above or below the scroll bar and click on the mouse. The left mouse button moves you up or down one page at a time.
The act of bringing a module or map from the Module Librarian into the Map Editor and activating it is called launching. To launch a module or map, you can:
Place the cursor on a module or map in the Module Librarian and drag it to the Map Editor while holding the left mouse button down. Then drop it in place (the drag and drop technique).
Place the cursor on a module or map in the Module Librarian and double-click with the left mouse button (the double-clicking technique).
If you use the file browser to launch a module or map from a directory, the module comes up in the current launch position, which is the active point in the Map Editor.
To launch a module or a map from a remote system, click on the New Host option on the File menu to select the remote host Librarian, and then select the maps or modules you want.
You can launch as many copies of a module as you like, although some modules might require special window server resources. If you have more than one copy of a module in a map, the second copy will have the number <2> after its name. The third will have <3>, and so on.
Maps, in the Module Librarian, are indicated by an icon showing three modules on a Map Editor. You can launch a new map in the Map Editor using either the drag and drop or the double-clicking technique from the Module Librarian (see Section 2.3.2).
If the map you want is not listed in the Module Librarian, you can select Open Map from the Module Librarian File menu. Use the file browser to find the directory and then choose the map.
The top left module in a map is always launched at the launch point.
If you want to start IRIS Explorer and launch a particular map at the same time, you can use the command line option -map with a filename.
IRISExplorer -map filename.map
The Map Editor opens and the map is launched and displayed automatically. You can get a command line through the Run option on the Start menu. You can also type the command in an MS-DOS Command Prompt window.
If you are not in the directory where the map resides, either change to that directory before typing the command (this applies only when you type in an MS-DOS Command Prompt window), or use the full pathname of the map, for example, %EXPLORERHOME%\maps\cfd.map, where %EXPLORERHOME% is the root directory where IRIS Explorer is installed on your machine.
Use the Map Editor File menu to save your maps. You must save all IRIS Explorer maps with the filename extension .map; otherwise, IRIS Explorer will not be able to find the file when you try to open it again.
Click on the module title bar to select a module. The title bar and access pads will be highlighted in white. (See Section 220.127.116.11).
A file browser comes up, and you are required to enter a filename for the map, for example, NewMap.map.
From the File menu you can select:
Save or Save As..., which saves everything in the Map Editor, or
Save Selected, which saves only the highlighted modules into the map
Modules can be saved only as part of a map, but you can save incomplete maps and bring them up later for further work.
You can remove some or all modules from the Map Editor at a time.
To remove the current map completely, select Destroy All from the Map Editor Edit Menu.
To destroy only some of the modules in the map, highlight the modules (see Section 18.104.22.168) and select Destroy from the Map Editor Edit menu.
To remove a single module, select Destroy from the module pop-up menu (see Section 22.214.171.124).
To bring up a new version of the module, launch the module again from the Module Librarian. The new version of the module will be numbered <2> (or <3>, if it is the third version to be launched).
This example illustrates how to launch an existing map from the Module Librarian and carry out some simple operations.
In the Module Librarian, find the map called simple.
Drag and drop the simple map into the top left corner of the Map Editor. The map opens to show the control panel of each module in the Map Editor.
Figure 2-4 shows the map you should see on your screen. It visualizes the data in the file %EXPLORERHOME%\data\lattice\testVol.lat.
The simple map is a three-module map, consisting of:
ReadLat, which reads in a file containing data for a lattice (lattices are discussed in Section 2.8.1)
IsosurfaceLat, which creates an isosurface, a surface of uniform value in the test volume
Render, which visualizes the selected isosurface of the lattice
All the module control panels are displayed with their wiring connections to one another visible. There is also a full-scale control panel for Render's volume visualization. For more information on control panels, see Section 126.96.36.199.
When you first launch a map, all the module title bars and access pads are highlighted in white, to show they are selected. You can move the entire map by dragging on one title bar.
Before you can move individual modules, you must deselect them. Do this by clicking on the background of the Map Editor. A module is reselected if you click on the title bar.
Click on the square Maximize button to bring up the full-scale control panel of IsosurfaceLat.
Turn the dial on the IsosurfaceLat module control panel to change the threshold value of the isosurface, and hence, change the shape of the object displayed in Render.
Experiment with the menus on the Render window menu bar and the decoration icons around the border (see Section 3.6.5).
For more information on using Render, see Chapter 3, "Using Modules".
Modules are the individual units in a map. They are the mathematical engines, powered by data, that make maps work. Although their functions vary, they all share a basic structure (see Figure 2-5). Each module has a visible form, its control panel, by means of which you can direct the internal (and invisible) engine, or core.
The internal portion of the module consists of:
module wrappers, which mediate between the core and the control panel
the module core itself, which consists of a mathematical algorithm. Each module has a different algorithm, hence it carries out a different function in IRIS Explorer.
See Section 2.1 of the IRIS Explorer Module Writer's Guide (Windows NT/2000) for more information on creating a user function for the module core.
The visible portion, or control panel, which appears in the Map Editor, is a rectangular window that contains:
The control panel has two forms, which are described in Section 2.4.2. You can direct the activity in the module core through the ports and widgets on the module control panel.
Modules accept data on their input ports, and pass it along via their output ports after they have modified it. When a module acts on data, or executes, it is said to fire. A module may be turned off, or disabled; and it can be fired on a computer other than the one where you are running the Map Editor.
IRIS Explorer modules can be grouped according to their general function (see Table 3-1). They can:
read in data files (input modules, such as ReadLat)
generate data from other data, such as extracting a planar slice or computing a numerical result from a volumetric dataset (feature extraction and analysis modules, such as DisplaceLat)
process data to create a visual form (geometric representation modules, such as IsosurfaceLat)
display the geometric representations on-screen (the Render module)
write data to disk files (output modules, such as WriteLat)
Of these, the Render module stands on its own. It is the means whereby the data passing through the map is visualized and is likely to be an integral component of most maps. Once the data has been visualized as an object in the Render window, you can use the graphic capabilities of Render itself to enhance certain aspects of the object and to view it from various angles.
The other modules operate on the data in various ways to produce a geometric object that makes it easier to understand, interpret, and extrapolate from the original data. Render and some of the more commonly used modules are described fully in Chapter 3.
To decide which modules you want in a map, you need to have more information about what each one does, what data it accepts, and what it produces for other modules to use, as well as what parameters it can have.
You can find information in these places:
All the available IRIS Explorer modules are listed in the Module Librarian. You can move them from one category to another in the Librarian. For details, see Section 2.10.
To find an example of the use of a module, select the Sample Map from the module's Launch menu in the Module Librarian (see Figure 2-3).
In addition, selecting Find maps containing this module from the Launch menu will find further examples of the use of the module. The results of the search appear in the search pane of the Module Librarian (see Figure 2-2).
A large number of modules are listed by function, in Table 3-1.
When you launch a module from the Module Librarian, the module control panel (see Figure 2-6 and Figure 2-7) appears in the Map Editor. Module control panels are rectangular windows that give you access to the capabilities of the module core via two main channels:
the input and output ports, which allow you to pass data into and out of a module, and between modules in a map (see Section 2.5). They appear on the micro form of the control panel.
the widgets, including buttons, dials, and sliders, which allow you to set module parameters (see Section 2.9). They appear on the full-scale form of the control panel.
The micro control panel has:
a title bar, which contains the module name and access pads for the input and output ports (see Figure 2-6).
a sizing button, to bring up the full-scale control panel.
a pop-up menu, which provides access to the module help files, parameter function editor, and other control options (see Figure 2-8).
Before you can move or save a module, or use any of the Edit Menu operations on it, you must select it.
To select a single module, click on the module title bar with the left mouse button. The title bar and both access pads are highlighted. You can move the module around the Map Editor by holding down the left mouse button and dragging the mouse.
To select more than one module at a time, you can lasso them by clicking in the background of the work area, holding down the left mouse button, and sweeping out a rectangle that encloses the desired modules. When you release the mouse button, all modules that are completely enclosed by the lasso will be selected. Alternately, you can hold down the <Shift> key and click on each module in turn.
To select all the modules currently in the Map Editor, open the Edit menu and click on Select All.
Use the <Shift> key with the sweep gesture to add more modules to an already selected group.
To deselect all selected modules, move the cursor off the title bar and click the left mouse button. To deselect one module, hold down the <Shift> key and click on the module.
The sizing button lets you bring up the full-scale form of the module control panel. When you first launch a module, it appears in the micro form (see Figure 2-6), which shows the title bar, and port access pads. Click on the Maximize button to open the full-scale, or maxi, control panel (see Figure 2-7); the micro panel remains in the map.
The full-scale panel shows details of the widgets and the parameter values. You can move it outside the Map Editor window and enlarge it as much as you wish. You can also use the Windows Maximize button to open the maxi control panel to full-screen size.
The maxi control panel shows the names, ranges, and current values for widgets. It also has a menu bar with a Help menu, but does not show the ports.
To close a maxi control panel click on the rightmost button of the title bar. The full-scale panel disappears but module remains in the network with a micro control panel in the Map Editor.
You can toggle the appearance of the module control panels by using the Control panels option on the Map Editor View menu. The option has a tick mark against it when the control panels are visible. Another way to make the control panels reappear is to click on Maximize button on the micro control panel of any of the modules in the map.
The module pop-up menu (see Figure 2-8) appears when you click on the title of the module control panel with the right mouse button. You can choose any one of these options:
The module fires and sends processed data to the next module downstream.
Makes a copy of the module, which you can wire into the map.
Temporarily deactivates the module. A disabled module will not fire until you enable it again. However, you can still set its widgets.
Opens the Parameter Function Editor, which lets you establish relationships among module parameters. It is described in Section 4.5.
Brings up the module Log window, which displays all the module output resulting from the current map operation (see Section 2.7).
Explains the purpose of the module and lists its ports and parameters.
Brings up information about the module's author.
Shows information about the location of the module's files and their creation time
Replaces the module with a newly-launched module with the same connections and parameter settings.
Replaces the module with a newly-launched module with the same connections and parameter settings and also brings up the debugging window for the module.
Completely removes the module from the Map Editor.
Each module has a Help window associated with it, which explains the purpose of the module and lists its input ports, output ports, and parameters.
To open this window, click on the title bar of the control panel with the right mouse button and select Help from the pop-up menu (see Figure 2-8).
To close the Help window, click on the Windows Close button at the far right of the title bar.
The modules are listed alphabetically and described in detail in the IRIS Explorer Reference Pages and in their individual Help files.
Replace provides a convenient one step method of disconnecting, destroying, re-invoking and reconnecting a module! This is particularly useful when developing a module. The module can be replaced, with the new version of the executable, in one easy step. The new module is re-invoked with all the old module's existing connections, P-Func and Widget values. You instigate a replace by using the Replace option on the control panel's pop-up menu.
This example illustrates the first steps in creating a map.
Launch these modules from the Module Librarian by dragging and dropping each one in turn into the Map Editor:
a ReadLat module (to read data in a lattice format)
a Contour module (to create a contour plot of the lattice data)
a GenerateColormap module (to colormap the contours according to value)
a Render module (to visualize the contoured data)
You now have the basic components of a map in the Map Editor.
Save these modules as a map by selecting Save As... from the Map Editor File menu. This will pop up a file browser.
When the file browser appears, in the File name type-in slot, enter the name of the file in which to save the map. You can change directory, by using the buttons at the top of the file browser.
A map name must have .map as a suffix for IRIS Explorer to recognize and treat it as a map, for example, incomplete.map.
When you have typed in a name, click on the OK button.
Now destroy the modules in the Map Editor by selecting the Destroy All option from the Map Editor's Edit menu. This will allow the saved map to be loaded onto a "clean slate".
To load the saved map, select the Open Map... option, from the File menu in the Map Editor. When the file browser appears, in the File name type-in slot, enter the name of the map you saved previously; you may also need to change directory using the buttons at the top of the file browser.
You can add the map to the list in the Module Librarian by editing your personal configuration settings. This procedure is described in Appendix A, "Configuring Your IRIS Explorer Environment".
To launch this map and connect the modules, go to Section 2.5.2.
Modules communicate by passing data from one to the next through their input and output ports (see Figure 2-9 and Figure 2-10). Once you have modules in the Map Editor, you can connect them together individually or severally, disconnect them, change your mind about connecting them, and alter the appearance of the connecting wires.
Each module control panel has two port access pads, one for input ports and parameters on the left of the control panel, and one for output ports and parameters on the right. A single module can have several input and/or output ports.
Data port names are listed first on the port menu, parameter port names are listed next, followed by synchronisation port(s). The port name is followed by the IRIS Explorer data type that it can accept; that is, Lattice, Pyramid, Geometry, Parameter, and Pick. If the port is optional, the type is followed by (Opt).
A connection is required on a module port unless the port is marked as optional (Opt). For example, GenerateColormap has an optional input port. A module will not operate properly in a map unless all its required ports are connected to compatible ports on other modules and are receiving data.
Each Parameter port is associated with a widget. In addition, the parameter port will also appear on the list of input and output ports, unless the designer of the module has decided not to show the parameter in the port list (see Section 4.2.2). For example, BlendImg has two data input ports and one parameter input port for Blend (see Figure 2-9). It has one data output port and a corresponding parameter output port for Blend (see Figure 2-10). Parameters are passed through the output ports and you can set and connect them so as to control widgets on other modules.
The synchronisation ports Fire and Firing Done are present on all modules, and as their names suggest can be used to control a firing sequence. See Section 2.6.2. A Firing Done output port can be connected to a Fire input port. Loop controller modules have an additional output port Loop Ended. See Section 3.7.
To select an input or output port, click on the associated access pad using the right mouse button. A list of the input or output ports and parameters associated with that module appears (see Figure 2-9 and Figure 2-10). Select the required port by clicking on it with the left mouse button. To select the port with just one mouse click, click on the access pad with the left mouse button and hold it down while you highlight the required port.
IRIS Explorer makes use of five data types: Lattice, Pyramid, Geometry, Parameter, and Pick. They are explained in Section 2.8. You can connect only input and output ports that accept the same data type.
For example, you can connect an output port called Colormap -- Lattice to the input port called Input -- Lattice but not to one called Input -- Pyr. Only an output port of type Pyramid is compatible with the latter.
When you click on an output port to select it, it is highlighted in green and all the compatible input ports on other modules in the Map Editor are highlighted in blue. Likewise, when you select an input port, all compatible output access pads light up in blue. Incompatible ports are not highlighted and cannot be selected.
Since a lattice can assume many forms, the Map Editor does type-checking for types of lattices and lets you connect only those modules that accept and produce the same type of lattice. For more information on lattices, see Chapter 3, "Using the Lattice Data Type" in the IRIS Explorer Module Writer's Guide (Windows NT/2000).
Wiring modules together is a simple process. You can wire input to output port or output to input port. Figure 2-11 shows a connection from the output port of ReadPhoenics to an input port of ChannelSelect.
To make the connections, follow these steps:
Click on the access pad of the first module and select a port from the cascading menu. The access pads on other modules in the Map Editor that have compatible ports are highlighted and you are in wiring mode.
Click on one of the highlighted pads and select a matching port from the port menu. Once you click on the second port, the highlight disappears and a blue wire is shown running between the ports, signifying that a connection has been made.
To cancel an incomplete connection, when only one port has been selected, click on the background of the Map Editor.
You exit the wiring mode automatically once a connection has been made.
You can wire more than one input port to a given output port, and vice versa, provided that the data types on the ports are compatible. This is called fanning connections out and in.
Figure 2-12 shows a SampleCrop module with two connections on its output port, one to the input port of WireFrame and one to the input port of NAGAxis. To make these connections:
Select the output port of the module you want to connect (SampleCrop in Figure 2-12).
Select the input port of the second module (WireFrame). A connection is made between SampleCrop and WireFrame.
Select the output port of the first module (SampleCrop) again. This port now has one other connection to it.
The cascaded port menu shows the names of the output module and port already connected, below a <CONNECT> bar. Click on the <CONNECT> bar to add a new output port to the list (in this case, NAGAxis).
Select the input port of the third module (NAGAxis). A connection is made between SampleCrop and NAGAxis. The highlighting disappears, indicating that the connection has been made.
If you now select the output port of SampleCrop, the cascaded port menu is as shown in Figure 2-12. The number following the data type on the port menu indicates how many connections the port has.
To connect an input port to the output ports on several different modules, follow the same procedure.
You may wish to disconnect a module or a number of modules completely from the map, or you may wish to simply break a single connection, between two modules. To break a single connection between two modules, follow these steps:
Choose either of the modules in the linkage and click on the access pad of the wired-up port. The cascaded port menu shows the name of the other module port connected to it (see Figure 2-12).
Select the connected port by clicking on its name (not on the <CONNECT> bar).
The connection between the modules is broken and the blue wire disappears. This method is useful if you wish to break only one connection.
If you wish to break all a module's connections then it is easier to "disconnect" the module, rather than breaking each connection in turn:
Use the Disconnect sub-menu from the Map Editor Edit menu to break the connections of a selected module or a number of selected modules. There are three options to the Disconnect sub-menu:
All - breaks all connections
Input - breaks input connections only
Output - breaks output connections only
When you use Disconnect, IRIS Explorer will ‘remember’ a module's connections so that they can be re-wired later if desired using Reconnect. If another disconnect operation is applied to it, only the connections most recently broken will be "remembered".
The Reconnect operation, using the Map Editor Edit menu can be applied to a module after a Disconnect. This operation will attempt to restore its connections to the state prior to the last Disconnect. If an individual connection to another module cannot be re-instated, for example the other module has been destroyed, then that connection will be skipped. If a connection has already been re-instated, for example the user has already manually wired it up, then again the connection will be skipped. The operation will also work on a module that has been destroyed and re-launched.
You can change the appearance of the map in the Map Editor by choosing new visual properties for the wires which connect the modules together. Changing the appearance of the wires has no effect on the way in which the map functions.
By default, each wire is colored according to the data type that is being passed along it, with the exception of the control arc in a loop (see Section 188.8.131.52), which is always colored magenta. The colors used for each type are:
Parameter - mauve
Lattice - orange
Pyramid - violet
Geometry - bright blue
Pick - olive green
Generic - pink
Unknown - black
User-Defined Type - grey
Fire - red
(see Section 2.8 for details of the IRIS Explorer data types). In addition, the default behaviour is to display each connection between modules. That is, two modules which pass more than one piece of data between them are displayed as being connected by multiple wires. The multiple connections are illustrated in Figure 2-13, which shows wires colored according to datatype for Lattice, Pyramid, Parameter, Geometry, Pick and Fire, together with a loop control arc.
You can change the colors which are used for the different data types, and/or switch to displaying a single wire between modules (irrespective of the number of connections between them) via the Wire Settings... entry on the Configuration menu. Clicking on the Change... button next to any of the datatypes listed on this control panel brings up a color palette from which you may select any color. Alternatively, you may define new custom colors from a temporary palette (this palette is emptied when you exit from the Map Editor, although any colors that are applied to wires are saved). This control panel also allows you to choose whether to show multiple connections between modules.
Finally, a special option is available to switch the colors of all wires (except for loop control arcs) to blue, and to turn off multiple connections. The file %EXPLORERHOME%\blue_wires.reg contains values for the appropriate Windows system registry settings; you can set these values in the registry by, for example, double clicking on the file in Windows Explorer. The changes will take effect the next time that IRIS Explorer is started.
You can change the direction, or slant, of the wires that connect the modules in a map using Wires on the Map Editor Layout menu. Each option to Wires changes the alignment of the wires between modules, as their titles indicate.
To change the slant of the connecting wires, choose one of the three options, Pt to Pt, Right Angle, or Diagonal. Click on each one in turn to see its effect. The option that is currently in force is greyed out and cannot be selected.
The wire settings (both for color and routing) are saved when you exit from the Map Editor.
It is an art to keep the wires in a map distinct and disentangled. However, no damage results from their being crossed or threaded underneath a module. The map merely becomes a little harder to read.
You can create more aesthetic maps by collapsing several modules into a group module. In this case all the selected modules disappear and are replaced by one control panel of your own design. For more details, refer to Chapter 5, "Creating Groups and Applications".
This example illustrates how to connect modules to make a functioning map (see Figure 2-15). In the previous example, you saved a set of four modules.
Launch the map by dragging and dropping it in the Map Editor. Then wire the modules together and set widgets as follows:
Connect the Output -- Lattice port of ReadLat to the Input -- Lattice port of the Contour module.
Type a filename into the file browser of the ReadLat module. A good lattice data file is in %EXPLORERHOME%\data\lattice\testVol.lat.
Open the full-scale control panel for Contour by clicking on the square Maximize button (for more information, see Section 184.108.40.206).
Set the minimum and maximum values for Contour by turning the dials to 2.0 and 7.0.
Connect the Lattice output port of GenerateColormap to the Colormap -- Lattice (Opt) port of Contour.
Notice that Contour has two connections on its input pad, but they go to two separate input ports.
Connect the Output -- Lattice output port of ReadLat to the Data In -- Lattice (Opt) input port of GenerateColormap. Notice that ReadLat now has two connections going out from its Output -- Lattice port. Set the Output? widget on the GenerateColormap module from BUILD to RUN.
Connect the Contours -- Geometry output port of the Contour module to the Input -- Geometry input port of the Render module. An object appears in the Render window representing contour curves of equal value through the data in the lattice file.
Move the slider on Contour to create more sets of contour lines.
Break the connection to Render. Notice that the contour lines disappear. Connect it up again and they reappear.
Disconnect GenerateColormap from Contour and see what happens.
If you want to keep the finished map, remember to save it again.
When a module is activated, it fires and the user function operates on the data it has received from its input ports. As the module fires, its title bar turns yellow, and stays yellow until the module has completed execution. The color change is called execution highlighting. (This highlighting can be turned off by toggling the Exec Hilite option on the Layout menu). This might take a fraction of a second or several minutes, depending on the complexity of the user function and the amount of data it is processing.
Firing can occur at several different stages of the map-building process. A module fires when:
it is launched in the Map Editor, provided it has all the data it needs on its input ports
modules upstream of it in the map fire, sending data to it
a module upstream of it in the map fires, that has a connection to its Fire port.
one of its parameter values is changed
you choose Fire Now from the module pop-up menu
you connect it to an upstream module which has already fired and produced data on its output port
you connect its Fire port to an upstream module which has already fired
it is triggered by an external event; for example, data arrives on a port from an external file or process
You can force a module to fire by:
Selecting Fire Now from the module pop-up menu.
This is useful for modules that have no parameters, for example, many of the image-processing modules, or if you do not want to change a parameter value.
Changing the value of a module parameter. You change the value of a parameter by moving the widget that controls the parameter of interest. You can type in a text slot, turn a dial, move a slider up or down, or switch a button off or on (see Section 2.9).
Each time you alter a parameter or change a connection in a map, in effect feeding in more or altered data values, the affected modules automatically fire again. This can cause a cascade of firings downstream of the module.
For an in-depth explanation of the mechanism behind module firing, see Appendix A, "The Firing Algorithm" of the IRIS Explorer Module Writer's Guide (Windows NT/2000).
When a module fires successfully a connection from its Firing Done port to a downstream module's Fire port can cause the downstream module to fire in exactly the same way that sending new data to the module would cause it to fire.
You can therefore use these synchronization ports to
control a sequence of module firings rather than allowing the module firing mechanism to determine the ordering. Normally this is controlled by the data flow, therefore these ports are useful when there is no need for any data to be transferred between modules. For example wiring modules as shown in Figure 2-16 will cause module firings to be sequential in the order D, C, B, when A is fired. Omitting the Firing Done to Fire port connections would cause the modules B, C and D to attempt to fire simultaneously.
control successive firings of a module, for example a module that sends out a sequence of data on one of its output ports. The AnimateCamera module sends out a series of cameras, usually to Render. A new camera will be sent each time an upstream module that is connected to its Fire port, fires. Modules that are designed to fire repeatedly are usually wired into a loop, rather than a map with a linear dataflow. See Section 3.7 for further discussion.
There are a number of ways in which module(s) can be disabled:
you can use the Disable option from the Map Editor Edit menu to disable a selected module or a number of selected modules temporarily. The Enable option reactivates it or them again.
You can also use the Disable/Enable toggle option on the control panel's pop-up menu to affect a single module.
Disabling a module is useful if:
You want to modify several module parameters without having the module fire every time you make a change.
Your map contains a module that takes several minutes to finish firing.
Each time you made a connection to the module or altered a parameter, you would have to wait several minutes while it fired before you could continue. You can avoid the wait by disabling the module while you complete your operations, then enable it again when you are ready to fire the complete map. If you disable a module that is connected in sequence with other modules, it will not send new data to the modules that follow it. If those modules rely entirely on the disabled module for data, they also cease to fire. The flow of data will be blocked, along this branch at least, until you re-enable the disabled module.
When modules fire in the Map Editor, they often generate informative text messages. For example, PrintLat, PrintPyr, and PrintPick all output text strings describing their data. Other modules may also produce messages in the course of a map cycle, all of which are logged by IRIS Explorer. You may be interested in seeing all generated messages, or only those put out by a particular module.
The Map Editor Log window captures all the messages generated by modules in the Map Editor. It is a read-only scrolling text window that typically appears below the Map Editor (see Figure 2-17). Messages in the window scroll upward, with new lines inserted until the size limit of the Log is reached. After that, lines are deleted. The Log lists the output from each module as it occurs, with the name of the generating module as a prefix to each line.
You can hide or display the Map Editor Log by toggling the Main Log option on the Map Editor View menu. By default, the log window is configured as a pane of the Map Editor window, and can be resized vertically by clicking and dragging its top edge. In addition, the log window is dockable, and can be dragged off the Map Editor window to become a separate window. To do this, click with the left mouse anywhere on its edge (outside of its text area, but inside the Map Editor border) and drag it until its outline doesn't intersect the Map Editor. Then release the mouse button. To put it back, click on its title bar and drag it until its lower edge overlaps the lower border of the Map Editor window.
To see text messages for an individual module without having to review the entire Map Editor Log, you can open and examine a Module Log (see Figure 2-18). Each Module Log displays messages generated by that module alone.
Open the Module Log by selecting Show Log from the module pop-up menu (see Figure 2-8).
You can cut and paste the information displayed in the Log windows into other windows. By selecting the Editable Log option from the Log window pop-up menu (see Figure 2-19) you can type further text into the window, if, for example, you wish to annotate the output. The menu appears when you click the right mouse button in the Log window. A tick mark appears against the option. To change the Log back to a read-only window (the default), click again on the Editable Log option, and the tick mark disappears. The other two options in the top part of the menu let you clear the window and save its contents into a file. In the next part, there are further editing options, allowing you to copy and paste parts of the log into other applications. A final option allows you to select the whole of the log output.
In IRIS Explorer, the data that modules accept and pass on is characterized by the data type. The data type is the form that data takes in IRIS Explorer. There are five IRIS Explorer data types: lattice, pyramid, geometry, parameter, and pick.
All data is passed through the module input and output ports, each of which accepts or outputs only one data type. Modules may, however, have several ports with a different data type on each one.
The IRIS Explorer data types are:
A series of arrays, in one or more dimensions, that hold dimension variables, nodal data values, and coordinate values. For example, data that defines a volume, such as a 3D CT scan of a bone, is in lattice format.
This is the most commonly used data type.
A hierarchy of lattices, with information on how the lattices are connected. The pyramid data type is used to manipulate finite element data and molecular data. For example, data describing a complex organic molecule and a finite-element mesh of a car body are both in pyramid format.
A collection of geometric primitives, including polygons, lines, and points, used to build a visual representation of a dataset. For example, a contour surface from a CT scan is a collection of polygons. The vertices of each polygon can have associated color and surface normals. Data is displayed in the Render module in geometry format.
A parameter holds a scalar value: an integer, real number, or string. The value of a parameter input to a module is controlled by a widget on the module control panel . You can also perform arithmetic functions on them (see Section 4.5).
Parameters are used to set values for slicing planes, error tolerances, quantities, and filenames.
A specialized data type that lets you select an area of an object in the display window of a render or image-display module and collect data about the selected area. This information can be fed to another module such as a query module.
It is possible to define new data types in IRIS Explorer, and you may find that the input and output port menus of some modules list data types in addition to those described here. Those are user-defined data types. They work exactly as IRIS Explorer data types do, handling data in a specific format.
All the data types are described fully in the IRIS Explorer Module Writer's Guide (Windows NT/2000).
The IRIS Explorer data types represent groups of data. A given instance of a data type on a port can be generic or highly specific. For example, a module may have an input port of Lattice type defined so that it will accept a wide variety of lattices of different sizes, or so that it will accept only 2D scalar lattices of real numbers with uniform coordinate mapping.
For example, the Contour module accepts a Lattice data type on its input port, but the lattice must have two or three dimensions. If you try to pass it data in the form of a 1D lattice, you get an error message.
The module definitions give the data type specifications for the ports on existing modules. When you build a module, you can define each port as you like. The more general the specification for a port, the more modules you can connect to it (but the harder the module is to write).
If you have any doubts about port compatibility when you connect modules into a map, you can check the data types acceptable to each module by:
calling up the Help window from the module pop-up menu
reading the module definitions in the IRIS Explorer Reference Pages
Certain modules can accept a pyramid or lattice data type and output a lattice or geometry data type after performing a data conversion. These include PyrToLat, LatToGeom, and Contour. Modules with several input ports may be able to accept two or more different data types, one on each port. For example, Streakline has input ports for a lattice and a pick and an output port for geometry. Render has input ports for geometry and parameter data and output ports for lattice, geometry, and pick data.
Table 2-1 lists some of the IRIS Explorer modules according to the data type (Lattice, Pyramid, Geometry or Pick) they can accept on an input port.
Some modules that accept lattices are further defined by whether they can accept 1D, 2D, or 3D lattices, or a combination. For details, refer to the input port specifications of each module in the IRIS Explorer Reference Pages.
|Input Port Data||Modules|
|Lattice||Ball, BallStick, BoundBox, ChannelSelect, ColorXform, Contour, CropLat2D, CropLat3D, DiffLat, DisplaceLat, GenerateColormap, Gradient, Graph, InterpLat, Interpolate, IsosurfaceLat, LatFunction, LatToGeom, LatToPyr, Legend, MagnitudeLat, Mixer, MultiSlice, OrthoSlice, PrintLat, ProbeLat, PyrToGeom, SampleCrop, ScaleLatNode, Shell, Slice, SubSample, Transform, Triangulate2D, Triangulate3D, VectorGen, VolumeToGeom, WireFrame, WriteLat|
|Pyramid||AtomicSurf, BallStick, BoundBoxPyr, CullPyr, CropPyr, IsosurfacePyr, PrintPyr, PyrToGeom, PyrToLat, Transform, WritePyr|
|Pick||Annotation, Ball, CropLat2D, CropLat3D, InterpLat|
Table 2-2 lists some IRIS Explorer modules according to the data type (Lattice, Pyramid, Geometry or Pick) they can produce on an output port.
|Output Port Data||Modules|
|Lattice||AtomicSurf, ChannelSelect, ColorXform, CropLat2D, CropLat3D, DisplaceLat, DisplayImg, GenerateColormap, GenLat, Gradient, Interpolate, LatFunction, MagnitudeLat, Mixer, OrthoSlice, PyrToLat, ReadLat, ReadPlot3D, Render, SampleCrop, ScaleLatNode, Shell, Slice, SubSample, Transform, TransformGen, WaveFormColormap|
|Pyramid||CullPyr, CropPyr, LatToPyr, ProbeLat, ReadPyr, ReadPDB, Transform, Triangulate2D, Triangulate3D|
|Geometry||Annotation, Ball, BallStick, BoundBox, BoundBoxPyr, Contour, CropLat2D, CropLat3D, DrawText, IsosurfaceLat, IsosurfacePyr, LatToGeom, Legend, MultiSlice, PyrToGeom, ReadGeom, VectorGen, VolumeToGeom, WireFrame|
All modules that have input ports for parameters also have output ports for them.
Table 2-3 lists some of the image processing modules provided. Image processing modules manipulate lattices and only accept and produce objects of the lattice datatype.
Module parameters allow you to set and change scalar values for each module. For example, a parameter called Min Range that accepts integers may let you set the minimum value for a range of temperature values for the module.
Parameters are controlled through widgets on the module control panel. Widgets are mechanisms for regulating a module's parameter values. The parameter names are given on the module's input port menu and on the full-scale control panel. A single control panel may contain a number of widgets, each controlling a different parameter.
Widgets include buttons, sliders, dials, text slots, scrolled lists, radio buttons (or boxes), option menus, and file browsers, as well as drawing areas.
Buttons are rectangular or circular widgets that let you select a value or switch a specific parameter on or off. They come in three styles (see Figure 2-20):
The one-shot button is rectangular in shape and is labelled with the name of the parameter. It is used to deliver a one-off message to the module, such as, for example, "set a value to zero", or "delete all points on a list", or "read the next data set".
The circular radio buttons offer a set of choices, only one of which is valid at a given time. They have a colored center when on, and are white when off. They are used to set a parameter which can have one of a number of discrete values. For example, "Axis" (X, Y or Z), "Data Type" (byte, short or float), or "Cell Type" (hexahedra or tetrahedra).
The square-shaped check box can be set on or off. It contains a tick when on, and is empty (white) when off. It is used to set a parameter which can have only two values, which can often be interpreted as yes and no. For example, "Calculate range?", "Output in ASCII format?", or "Display Axes".
Use the left mouse button to click the buttons on and off.
Sliders (see Figure 2-21) are either horizontal or vertical bars that let you increase or decrease the value of a parameter in discrete steps. Sliders generally have integer values.
Each slider has:
a title giving the name of the parameter
a thumb that moves from one end of the bar to the other allowing the sliders value to be changed
text slots showing the minimum, maximum, and current values of the parameter.
You can change any one of these values by clicking on the text slot to highlight it, typing in a new value, and pressing <Enter>.
To change a parameter value, place the mouse cursor on the thumb and hold the left mouse button down while you push or pull the slider along its bar. The current value changes as the thumb moves. When you release the mouse button, the new value is sent to the module.
To move the bar to the cursor position, place the cursor in the slider slot and click on the left mouse button.
Dials are circular widgets that allow the continuous adjustment of a parameter value between set limits (see Figure 2-22). Like sliders, each dial has a title and slots showing minimum, maximum, and current values. You can type new values into any slot (remember to press <Enter>), and you can also change the current value by turning the dial pointer. Dials generally have float values.
The dials have a vernier action, in that you can use the pointer for coarse settings. Place the cursor on the pointer and push it clockwise or counterclockwise while holding the left mouse button down. The values change linearly from minimum to maximum through a single revolution of the pointer.
To make a fine adjustment to the parameter value, place the cursor on the dial center and push it clockwise or counterclockwise. The values increment or decrement in minute steps, and the inner dial revolves 50 times for one revolution of the pointer. This is useful for fine-tuning adjustments to a parameter that spans a large range of values, or one that increments its value in minute steps.
Text type-in slots (see Figure 2-23) accept alphanumeric characters.
To type in data values or filenames, click once or twice in the slot until the upright text cursor appears. If necessary, the slot scrolls to the left to give you enough room for your text.
Text type-in slots appear in some input modules as part of a file browser widget (see below).
The file browser widget appears in modules that read or write files from or to the file system. See Figure 2-24.
To open the file browser, select Filename from the File menu on the maximized control panel. The file browser has a number of areas:
Look in:|Save in: is an option menu which displays the name of the folder which is currently being browsed. Clicking on the name opens the menu, which displays the hierarchy leading to the current folder. This menu may be used to access other areas (folders, disk drives, computers) to browse.
Buttons to the right of this slot may be used to move up one level in the hierarchy to the folder or disk drive or computer which contains the current folder. The remaining buttons may be used to perform other tasks such as creating a new folder and changing the display options for the contents of the current folder.
The large window beneath this area displays the contents of the current folder. Double-click on a folder or file to open it. Click on a file name to select it.
File name: gives the name of the currently selected file.
Files of type:|Save as type: is an option menu from which a file type may be selected. Only files of this type will be displayed in the folder contents window.
Open|Save opens or saves the currently selected file. The name of the file is sent to the module and the module fires.
Cancel closes the browser without sending anything to the module.
You can use the file browser in two ways:
Simply type the complete path for the file into the text slot on the closed file browser. This takes you directly to your destination.
Use the menus on the open file browser as described above (see Figure 2-24).
Option menus and scrolled lists let you select one or more items from a group of options.
Option menus present a menu from which you can choose one option at a time. The option may be a value, a range of values, or a property, such as uniform or curvilinear (see Figure 2-25). The option menus are rectangular, with a small raised bar containing an arrow, on the right.
Click on the raised bar to display the menu and select the item you want by clicking on it.
A scrolled list widget (see Figure 2-26) lets you select one or more items from a list of options that may extend beyond the current list window. You may be able to choose one option or several options at a time, depending on how the properties of the particular list were defined when the module was created.
Click on an item to select it. If the scrolled list allows you to select more than one item, click on all the items you want to select.
A drawing area is a blank rectangle on the maximized control panel only in which an image or visual object can be displayed (see Figure 2-27). For example, the modules DisplayImg and Render have drawing areas on their maximized control panels.
You can control the size, appearance, and orientation of the subject in the drawing area by using the widgets on the control panel. These vary from module to module, depending on the module's function.
The window may take up varying amounts of space on the control panel. When you enlarge the control panel, the drawing area is enlarged proportionally. Click on the Maximize button of the full-scale control panel to open up the control panel to full-screen size.
This example illustrates how you can affect an object in Render by using widgets to change parameter values. Launch the map named widgets (see Figure 2-28) by dragging and dropping it in the Map Editor. It contains five modules:
ReadLat reads in a lattice data file
Contour generates a contour surface of the volume
IsosurfaceLat generates an isosurface of the volume
WireFrame generates a box that defines the boundaries of the volume
Render visualizes the objects in its window
Open the full-scale control panels for Contour and IsosurfaceLat by clicking on the Maximize button.
Change the dial position on IsosurfaceLat. Notice what happens in the Render window.
Change the slider positions on the Contour module. Note the change in the Render window.
Modules and maps are organized into categories in the Module Librarian. Figure 2-29 shows one category, called Modules. You can reorganize the contents of these categories, displayed in scrollable columns, using the Librarian option on the Configuration menu in the Map Editor. This is described in Section A.1.1.2, where details are given on creating new categories and editing existing categories. The new settings are automatically stored for the current user in the Windows registry.
The Librarian shelf (see Figure 2-2) is a storage area for modules. It is like a bookshelf where you place books to which you often refer. For example, you might stack modules that you use a lot, such as Render, DisplayImg, or modules of your own creation, on the shelf. Shelved modules are still available from the Module Librarian as well.
To place a module on the shelf, use the drag and drop technique. Once a module is on the shelf, you can launch it immediately or leave it there to be launched later. You can launch it repeatedly from the shelf. Use the Delete option from the Module Launch menu to remove a module or map from the Librarian shelf.
When all the launched modules have been connected and your map is operational, the modules fire and an object becomes visible in the Render or DisplayImg window – in theory, perhaps. In practice, this does not always happen. Here are a few common problems and ways to fix them.
If a module port is required, then it must be receiving valid data from an upstream module in order to work properly. All ports are required unless marked as Opt(ional).
A message to this effect may appear when IRIS Explorer starts up. It means that you do not have enough disk space to run IRIS Explorer properly. You can:
Clean off your disk to make more disk space for the shared memory arena.
Create a temporary directory (tempdir) on another disk on your machine if you have one (for details, see Section A.1).
Reduce the size of your arena, which is the amount of disk space necessary to hold all the IRIS Explorer files, before you run IRIS Explorer (see the reference in step 2).
If nothing appears in your Render window, try the following procedure:
Make sure all the required input ports on each module are connected to upstream modules that can send them valid data.
Render might be looking in the wrong direction. Click the right mouse button in the Render window (which brings up a pop-up menu) and select Functions then View All.
This brings an object that may be out of the viewing area into the center of the window.
The module might not be reading in the data from disk. Make sure that modules that need data from files, such as ReadImg, have been given access to those files.
The module might be disabled. Enable the module by bringing up the pop-up menu from the control panel and selecting Enable. You can also select all the modules by using the Edit menu in the Map Editor, then choose Enable.
The widgets might not be set to values which can produce data. Check the settings: turn the dial or move the slider if you have an active threshold parameter.
If you have changed object parameters, but the changes do not appear in the object, try the following procedure:
Enable the module by bringing up the pop-up menu from the control panel and selecting Enable. You can also select all the modules by using the Edit menu in the Map Editor, and choosing Enable.
Make sure all the required ports have data by connecting them to valid ports in other modules.
Some modules, such as GenerateColormap, have Build/Run toggle buttons. If the module is in Build mode, it will not fire and send data downstream. Change the mode to Run.
If the lattice is 1D or 2D, such as an image:
Connect the input port of a LatToGeom module to the Output -- Lattice port of the module that is reading in or generating lattice data.
Connect the LatToGeom module's Output -- Geometry port to Render.
If the lattice is 3D, such as a volumetric dataset:
Select a module that will provide the visual representation you want, for example, IsosurfaceLat, Contour, Slice, OrthoSlice, WireFrame, or VolumeToGeom.
All these modules except Slice and OrthoSlice produce geometry. They can be connected to Render by wiring their Output -- Geometry ports to Render. The two slicers produce lattices, which must be passed through a LatToGeom module first.
See Section 3.4 for more information about using slicers.
If you want a map to be displayed in the Module Librarian after you use Update, the map must be in a directory that the module Librarian recognizes.
To ensure this:
Check that the directory in which you saved the map is in the module path. You can check this and/or add subdirectories to the module path by selecting the Librarian option from the Configuration menu in the Map Editor. See Appendix A, "Configuring Your IRIS Explorer Environment" for details.
The default directory is %EXPLORERHOME%\maps.
Check that you used the correct pathname when you saved the map. It might be in another directory that is not in the module path.
You need to save the map again. To prevent this from happening a second time:
Make sure you use Save from the Map Editor File menu to save modules that are not highlighted.
If you save certain modules only with Save Selected, the title bars of those modules must be highlighted, otherwise the map is saved without any modules in it.
When you select Destroy from the pop-up menu, IRIS Explorer sends the module a message to exit. If the module is busy computing, it may not get the message for a while. If you want it to quit immediately, select Destroy again from the module pop-up menu. This sends a kill message to the module's controller, which then shuts down the module without waiting for a response from the module itself.
Error messages that mention a shared library indicate that some part of IRIS Explorer is not properly installed on the remote system. For more information, see Section A.3.
You can check this in two ways:
The module may be connected to an incompatible port and is therefore receiving the wrong data type. Bring up the input and output port pads and check the port connections.
Verify that the module is producing the desired data type by connecting it to PrintLat or PrintPyr and printing the output. IRIS Explorer produces an ASCII file showing the structure and contents of the data, which you can look at to track down any errors.
 Modules such as Render and GenerateColormap may require a large number of colours for their display. They may be used with any monitor, but will be displayed to best advantage on those monitors that are able to display all colours.