CIBC:Documentation:SCIRun:UserGuide:Networks

Prev Next Contents

---

Overview

This section describes how to create, save, load, execute, and edit networks.

The following conventions are used when describing mouse and keyboard actions performed by the user:

Button1

   Left mouse button

Button2

   Middle mouse button

Button3

   Right mouse button

Press

   ``Press means press and hold a key or mouse button.

Click

   ``Click means press and release a mouse button.

Type

   ``Type means press and release a key.

ButtonN-Drag

   Press ButtonN, then drag the mouse.

C-ButtonN

   Press the Control key, then press or click ButtonN

C-key

   Press and hold the control key, then type key key 

Anatomy of a Module

All modules are similarly represented by a graphic within the NetEdit frame. The graphical front end is the same for all modules and consists of the following elements:

Module Name

A module's name.

Input Ports

Zero or more input ports located on the top of the module. Each port corresponds to a data type and each data type has a unique color. The table below maps port colors to data types. Input ports connect to other modules' output ports. Connections can only be made between ports of the same type. Some modules have a dynamic input port. When a connection is made to a dynamic input port a new instance of the port will be created.

Data Types and their Port Colors

Data Type	Port Color
Bundles	Orange
Camera Path	Brown
Color Maps	Purple
Field	Yellow
Field Set	Green
Geometric Objects	Magenta
ITK Datatype	Pink
Matrices	Blue
Nrrd Data	Cyan
Strings	Green

Output ports

   Zero or more output ports located on the bottom of the module. Output ports connect to other modules' input ports. Every module has at least one input or one output port.

UI button

   Pressing the UI button displays the module's control dialog. Some modules have no dialog, some have simple dialogs, and some have complex dialogs that allow elaborate control over the module. Figure 5.2 shows the control dialog for Show Field module. Most module control dialogs (except for read/writer modules) contain the following buttons:

   Close
       Closes the control dialog.

   Execute
       Executes the module. This may cause other modules in the network to execute or ``fire (see Executing a Network).

   Find
       Highlights the module in the NetEdit frame that owns the control dialog being edited.

   ?
       Displays a module's help information.

   Reader/writer module control dialogs contain the following button set:

   Set
       Sets the read/writer module's filename value to the chosen filename then closes the module's control dialog. In a network with multiple reader/writer modules, Set (rather than Execute) should be used to establish each reader/writer module's filename parameter before executing the network.

   Execute
       Sets the read/writer module's filename value to the chosen filename, executes the module (reads file contents and sends data downstream), and closes the module's control dialog.

   Cancel
       Closes the control dialog without setting the module's filename value.

   Find
       Highlights the module in the NetEdit frame that owns the control dialog being edited.

Pop-up Menu

   Pressing Button3 while the mouse pointer is over a module activates a module's pop-up menu. The content of the pop-up menu changes depending on the state of the NetEdit window. The following items are available in the pop-up menu:

   Package_Category_Name_Instance
       This item is a label (not a selectable item). It provides the module's name and the category and package to which the module belongs. ``Instance is a unique number that distinguishes multiple instances of the same module.

   Execute
       Tells the module to execute (or re-execute). This may cause other modules in the network to execute or``fire (see Executing a Network).

   Help
       Displays the module's help window.

   Notes
       Displays a module's note pad. The note pad is used to document the purpose of a module in a network. See Displaying Module Notes.

   Destroy Selected
       Destroys the selected modules. See Destroying Module(s).

   Destroy
       Destroys the module See Destroying Module(s).

   Duplicate
       Duplicates the module, its input connections, and its control dialog state.

   Replace With
       Replaces the module with the chosen one. Replace With is a pop-up menu listing modules that accept the same connections as the current module. The chosen module replaces the current module.

   Show Log
       Displays the module's message log. Most modules write messages to their log during the course of their execution (see Viewing a Module's Log).

   Make Sub-Network
       Creates a sub-network from selected modules. See Creating a Sub-Network.

   Expand Sub-Network
       Reverses the action of menu item Make Sub-Network. This menu item is available only in a sub-network's pop-up menu. See Expanding a Sub-Network.

   Disable
       Disables a module (or selected modules). See Disabling/Enabling Modules.

   Enable
       Enables a module (or selected modules). See Disabling/Enabling Modules.

Anatomy of a Connection

A connection lets data flow from one module's output port to (usually) another module's input port. Sometimes a connection will connect a module's output port to its input port.

Connections are colored grey if they are disabled.

Pressing Button3 while the mouse pointer is over a connection activates a connection's pop-up menu. The content of the pop-up menu changes depending on the state of the connection. The following items are available in the pop-up menu:

Delete

   Deletes a connection.

Insert Module

   Creates and inserts a module ``into a connection. Insert Module is a pop-up menu listing modules that contain at least one input and at least one output port matching the connection. The chosen module is created and then the connection is routed into the left-most matching input port and out of the left-most matching output port.

Disable (or Enable)

   Disables (or enables) a connection.

Notes

   Displays a connection's note pad.

Creating a Module

To create a module, select its name from one of the package (e.g., SCIRun) menus' category sub-menus. Package menus are accessed from the main window's menu bar or from the NetEdit frame's pop-up menu. The NetEdit frame's pop-up menu is activated by pressing Button3 (right mouse button) while the mouse pointer is in the NetEdit frame (but not over a module or connection). The pop-up menu contains a list of category sub-menus from the SCIRun package and other installed packages. Each category sub-menu provides access to modules within the category.

After creating a module, its gui is placed in the NetEdit frame.

Setting Module Properties

To change a module's properties, click its UI button. This displays the module's control dialog. Use the dialog to change the module's properties. Each module's reference documentation explains the use of its control dialog. A module's reference documentation can be displayed by clicking a module's ? button. The figure below shows the control dialog for the Show Field module.

Selecting Modules

Some operations (moving, destroying, disabling, and enabling) act on a group of selected modules (see Moving Module(s), Destroying Module(s), and Disabling Modules). Groups of selected modules can be created two ways:

1.Perform Button1-Drag while the pointer is in the NetEdit frame, but not over a module or a connection. This starts a selection box, allowing the user to select multiple modules. Modules overlapping the selection box are selected. Release Button1 to complete the selection. Additional groups of selected modules are created by performing C-Button1-Drag

2. Select the first module by clicking Button1 while the pointer is over a module. Then add modules to the group by clicking C-Button1 on additional modules. All previously selected modules remain selected.

Selected modules are colored differently from unselected modules.

Destroying Modules

To delete a module, choose menu item Destroy from a module's pop-up menu.

Multiple modules can be deleted at one time. Select one or more modules, then choose menu item Destroy Selected from a module's pop-up menu.

Moving Modules

Modules can be moved in the NetEdit frame. To move a module, perform Button1-Drag while the pointer is over a module, and move the module to its new location.

Multiple modules can be moved at one time. Select one or more modules, then perform Button1-Drag while the pointer is over any one of the modules in the selected group.

Two modules may be moved by dragging one of the connections between them. To move two modules, perform Button1-Drag when the pointer is over a connection between two modules.

The NetEdit frame will scroll when a module is moved to the frame's edge.

Disabling and Enabling Modules

Modules may be temporarily disabled. Disabled modules do not execute and data does not flow through them.

To disable modules, select one or more modules, then choose menu item Disable from a module's pop-up menu.

Disabling a module disables all incoming and outgoing connections to the module and prevents the module from executing during execution of the network. Disabled modules are drawn in a darker shade of grey.

To enable disabled modules, choose Enable from a disabled module's pop-up menu. Enabling one module enables all selected modules.

See also Disabling/Enabling Connections.

Editing and Displaying Module Notes

Module notes allow the user to document the purpose of each module by attaching notes to each module in the NetEdit window. Notes can be displayed or hidden.

To create or edit module notes, choose menu item Notes from a module's pop-up menu. The note editor dialog can also be activated by clicking Button1 on notes displayed in the NetEdit window. Enter new notes or edit existing notes in the note editor dialog.

Notes may be hidden, displayed in tooltips, or displayed in the NetEdit frame. The note editor provides the following note display options: Default, Tooltip, Top, Left, Right, or Bottom. Choose a display mode by clicking Button1 on the appropriate button.

Choose Tooltip to display notes as tooltips. Notes are displayed only when the mouse pointer hovers over a module.

Choose one of Default, Top, Left, Right, or Bottom to display notes in the NetEdit to the right, top, left, right, or bottom of the module respectively.

Choose None to hide module notes. Displayed notes can be hidden by clicking Button2 when the pointer is on the notes. Hiding notes does not delete notes.

Click button Text Color to change the color of notes displayed in the NetEdit frame.

Click button Cancel to abort note editing.

Click button Clear to erase notes.

Click button Done to accept edited notes.

Viewing a Module's Log

Each module supports a message log. The module writes error messages or other types of messages to its log.

To display a module's log, choose Show Log from a module's pop-up menu or click Button1 on a module's message indicator.

Creating a Connection

To connect the output (input) port of one module to the input (output) port of another module, use Button2.

To make a connection, position the mouse pointer over a module's input (output) port. Then perform Button2-Drag and drag the mouse pointer toward another module's output (input) port.

When Button2 is pressed, the program shows all valid connections as black lines. It also draws one red colored connection, which is the connection made if the drag is stopped by releasing Button2.

Make the connection by releasing Button2 when the pointer is over the desired destination port, or when the red colored connection is the desired connection. The connection is drawn using the color corresponding to the connection's data type.

Users can connect a module's output port to the input ports of one or more modules by repeating the procedure just described.

Editing and Displaying Connection Notes

Connection notes allow the user to document the purpose of each connection by attaching notes to each connection in the NetEdit window. Notes can be displayed or hidden.

To create or edit connection notes, choose menu item Notes from a connection's pop-up menu. Enter new notes or edit existing notes in the note editor dialog. The note editor dialog can also be activated by clicking Button1 on notes displayed in the NetEdit window.

Notes may be hidden, displayed in tooltips, or displayed in the NetEdit window. The note editor provides the following note display options: Default, Tooltip and Top. Choose a display mode by clicking Button1 on the appropriate button.

Choose ToolTip to display notes as tooltips--notes are displayed only when the mouse pointer hovers over a connection.

Choose Default or Top to display notes on top of the connection.

Choose None to hide connection notes. Displayed notes can also be hidden by clicking Button2 when the pointer is over the notes. Hiding notes does not delete notes.

Click button Text Color to change the color of notes displayed in the NetEdit frame.

Click button Cancel to abort note editing.

Click button Clear to erase notes.

Click button Done to accept edited notes.

Highlighting Related Connections

To highlight the tree of connections affecting a connection, perform C-Button1 anywhere on a connection.

To highlight the tree of connections downstream an output port, perform C-Button1 on the output port.

To highlight the tree of connections upstream an input port, perform C-Button1 on the input port.

Disabling a Connection

To disable a connection, click Button3 on the connection to bring up the connection menu and select Disable. The connection appears grey.

Disabling a connection prevents data from flowing through, as if it were not connected.

Deleting a Connection

To delete a connection, choose menu item Delete from a connection's pop-up menu or click C-Button2 while the pointer is on a connection.

Undoing/Redoing a Connection

Type C-z to undo the last connection creation or deletion. Undo can be repeated.

Type C-y to redo the last undone connection creation or deletion.

Executing a Network

Network Execution means one or more modules must be executed in a coordinated fashion. SCIRun's scheduler manages the coordinated execution of modules.

Note that some modules need to be compiled before they are executed (see Dynamic Compilation). Compilation delays network execution. Usually, occurs only one time per module. After a module is compiled, it does not need to be compiled again. Modules change color during compilation.

The Basics

The scheduler is invoked when an event triggers a module's execution. The scheduler creates a list of all modules that must execute in coordination with the triggered module. Modules upstream (directly or indirectly) from the triggered module are put on the execution list if they have not previously executed. All modules downstream from the triggered module are put on the execution list. Once the scheduler determines which modules must be executed, it executes them (in parallel where possible).

Network execution is mostly transparent. That is, events that trigger module execution usually generate automatically. Sometimes, however, the user must manually generate a triggering event by choosing the Execute item from a module's pop-up menu.

Details

Each module executes in its own thread and blocks (waits) until its upstream modules can supply it with data. After a module completes its computation, it sends the results to its downstream modules. This completes a module's execution cycle. The module will not have another chance to receive data from its input ports and send data to its output ports until some event puts the module back on the scheduler's execution list.

This behavior prevents modules from computing in an iterative fashion (sending intermediate results to their downstream modules), because downstream modules cannot receive results until they are in their execution cycle. Downstream modules would need to be executed each time the upstream module posts an intermediate result.

Intermediate Results

Some modules are designed to be used in an iterative fashion. They use a method called send_intermediate to send the results of each iteration. When this method is used, the scheduler (re)executes downstream modules each time the upstream module posts its next result. Downstream modules are able to receive the results of each iteration as soon as the upstream module sends them.

Modules SolveMatrix and MatrixSelectVector (from the SCIRun package and Math category) are examples of modules that compute iteratively using the send_intermediate method.

Feedback Loops

Some modules are designed to be used in an iterative fashion. They use a method called send_intermediate to send the results of each iteration. When this method is used, the scheduler (re)executes downstream modules each time the upstream module posts its next result. Downstream modules are able to receive the results of each iteration as soon as the upstream module sends them.

Modules SolveLinearSystem and GetColumnOrRowFromMatrix (from the SCIRun package and Math category) are examples of modules that compute iteratively using the send_intermediate method.

Documenting a Network

It is useful to document the function of a network. A network's note pad is used for this purpose. To edit the network's note pad, select the Network Properties item from the main window's File menu. This displays the network's note pad editor. The editor allows the user to write notes on the purpose and use of the network.

Saving a Network

SCIRun can save networks to files. Network files have an extension of .srn (in the past they also had .net, .sr and .uin extensions).

To save a network, select item Save from the main window's File menu. A file browser dialog prompts for the name and location of the network file.

If changes are made to an existing network, Save saves changes made to an existing net file.

Save an existing network under a new name using the Save As... menu item. A file browser dialog prompts for the new name of the network file. Subsequent uses of Save saves changes to the newly created file.

The position and size of open Viewer windows are saved to the network file.

A backup network will be saved in the form #filename# each time a module executes (or an Execute All is done). If no filename has been specified, SCIRun will save the current network to #MyNetwork.svn# to the current directory.

Network files are XML files. These files can be edited, however, reasons for doing so are beyond the scope of this guide.

Loading a Network

To load a network file, select the Load item from the main window's File menu. A file browser dialog prompts for the name and location of the network file. The loaded network replaces an existing network in the NetEdit frame.

Inserting a Network

To avoid merging networks, select the Insert item from the main window's File menu. This option allows the user to place one SCIRun network next to another, avoiding overlap. A file browser dialog prompts the user for the name and location of the network file.

The new network is inserted into the upper left corner of the NetEdit frame. If a network of modules already exists in the NetEdit frame, the Insert command places a new network to the immediate right of the existing network.

Clearing a Network

To remove all modules and connections from the NetEdit frame, select the Clear item from the main window's File menu. A text box appears, confirming whether the user wants to proceed with or cancel the clearing operation.

Navigating a Network

A complex network may not be entirely visible in the NetEdit frame. Use the NetEdit frame's scroll bars or the network view tool to view complex networks.

The Global View Frame shows the entire network world. The small rectangular region (outlined in black) in the Global View Frame is the network view tool and a window on the network world. The position of the view tool determines the part of the network visible in the NetEdit frame. To view other parts of the network, press Button1 while the pointer is anywhere in the Global View Frame--this moves the tool to the location of the pointer - then drag the tool to the new location.

Creating a Sub-Network

A sub-network is a group of modules that are treated as a single module. In a network, you may use a sub-network as you would a module.

To create a sub-network, select one or more modules, then choose item Create Sub-Network from any selected module's pop-up menu. Selected modules will be replaced by a sub-network graphic and the sub-network editor will activate. Sub-networks may be created in sub-networks. The section (Editing a Sub-Network) explains the use of the sub-network editor.

A sub-network editor button replaces the CPU time and Progress Bar in the sub-network graphic.

A sub-network's editor is activated by pressing the sub-network editor button.

Pressing button UI activates control dialogs of all modules in a sub-network. Control dialogs can be activated individually in the sub-network editor.

In a network, a sub-network behaves as does a module. A sub-network has input and/or output ports (orginating from modules within the sub-network) that can be connected to modules outside of the sub-network. Each sub-network has a pop-up menu and a set of editable notes (see Editing and Displaying Module Notes). A sub-network does not have a log. Logs of individual modules in the sub-network can be viewed in the sub-network editor window (see Viewing a Module's Log).

Expanding a Sub-Network

Expanding a network reverses the action of menu item Create Sub-Network--all modules in a sub-network are returned to the network containing the sub-network and the sub-network is destroyed. This action cannot be undone.

To expand a sub-network choose menu item Expand Sub-Network from the sub-network's pop-up menu.

Editing a Sub-Network

The sub-network editor is activated by pressing a sub-network's editor button. The sub-network editor works similarly to the NetEdit window. All network editing features of the NetEdit window are available in the sub-network editor--modules can be created, connections can be made, etc.

Sub-networks have input and/or output ports. These are created in the sub-network editor. Sub-network input ports are created by making a connection between the input port of a module (in the sub-network) and the top edge of the sub-network editor window. Sub-network output ports are created by making a connection between the output port of a module (in the sub-network) and the bottom edge of the sub-network editor window.

A sub-network can be renamed by entering its new name into the Name text entry widget.

Saving a Sub-network

Sub-networks can be saved for reuse in networks and sub-networks.

Sub-networks are saved in directory SCIRun/Subnets, in the user's home directory.

To save a sub-network, press the sub-network's editor button, which activates the sub-network's editor, then press the editor's Save Template button.

Saved sub-networks are listed as menu items in the Sub-network package menu (which is available in the NetEdit window's File menu and popup menu).

Loading a Sub-Network gives instructions for loading sub-networks into networks and sub-networks.

Loading a Sub-Network

Saved sub-networks are loaded into networks and sub-networks by selecting their names from the Sub-network package menu. Package menus are accessed from the main window's menu bar or from the NetEdit frame's pop-up menu. Unlike other package menus, the Sub-network menu has no category sub-menus.

A sub-network may be loaded one or more times in a network. Each time a sub-network is loaded a new instance of it is created in the network.

The SCIRun Shell

After starting, SCIRun runs a shell-like application in the terminal window. This shell displays the prompt scirun> in the terminal window.This program is a Tool Command Language (TCL) shell program extended with SCIRun specific commands.

It is possible to type TCL SCIRun commands at the prompt.

---

Prev Next Contents