Chapter 1: SCIRun Introduction (Geometry Visualization)

Chapter Sections

Appendices

Chapter Overview

SCIRun is a modular dataflow programming Problem Solving Environment (PSE). SCIRun has a set of Modules that perform specific functions on a data stream. Each module reads data from its input ports, calculates the data, and sends new data from output ports. In SCIRun, a module is represented by a rectangular box on the Network Editor canvas. Data flowing between modules is represented by pipes connecting the modules. A group of connected modules is called a Dataflow Network, or Net (see Figure 1.3). An infinite number of nets can be created, each solving a separate problem. Chapter 1 of this tutorial demonstrates the use of SCIRun to visualize a tetrahedral mesh. This chapter demonstrates the construction of a network comprised of three standard modules: FieldReader, ShowField, and Viewer. This chapter also instructs the user on reading Field data from a file, setting rendering properties for the nodes, edges, and faces (the nodes are rendered as blue spheres), and rendering geometry to the screen in an interactive ViewWindow.

Before Running SCIRun

Before running the scirun executable, an environment needs to be set up. (For more information about environment variables consult the User's Guide 4.4, "SCIRUN_DATA".)

The following environment variables need to be set in the shell. Note: another method of setting these variables is to run SCIRun once so that it will create a .scirunrc file in your home directory. Then edit this file and uncomment the above variables and point them to your data. This only needs to be done once. Environment variables set in the shell will override the .scirunrc values.

  • SCIRUN_DATA: points to the location of the SCIRunData directory on the system. Note: it is assumed the SCIRunData directory has been downloaded. (This is a separate download from the SCIRun build.)

  • SCIRUN_DATASET: indicates which dataset to load. (Note: example networks built in this tutorial can run with a variety of data inputs: e.g., sphere, brain-EG, and utahtorso-lowres.)

Set these environment variables to the following values (See Figures 1.0 (csh/tcsh) and 1.1 (bask,ksh,sh)):

  1. Set the SCIRUN_DATA variable to point to the location of SCIRunData (as shown in Figure 1.0). The "path_to_data" should represent the directory path where data is stored on the computer (e.g., /usr/local/SCIRunData/1.20.0).

  2. Set the SCIRUN_DATASET variable to "utahtorso-lowres".


Figure 1.0: Set environment variables using C-style shell (csh, tcsh).


Figure 1.1: Setup using a Borne-style shell (bash, ksh, sh).

Running SCIRun

Once these environment variables have been set, SCIRun is ready to run:

  • Move into the SCIRun executable directory and enter the command scirun. (Note: SCIRun cannot run as a background application.)

  • The SCIRun NetworkEditor window will appear on the screen (see Figure 1.2.) The NetworkEditor screen consists of three frames: the GlobalView frame in the upper left corner, the Message frame in the upper right corner, and the NetEdit frame. The NetEdit frame is the large area where networks of modules are constructed. Since the NetEdit frame is extensive, the GlobalView frame shows which part of the NetEdit frame is currently being viewed. The Message frame reports errors, warnings, and important information.


Figure 1.2: SCIRun initial NetworkEditor window.

For more information about the NetworkEditor consult the User's Guide 4.2, "Anatomy of the Main Window".

SCIRun Network Building Blocks: Modules and Connections

Lets begin constructing the network pictured in Figure 1.3. (Note: subsequent tutorial chapters expand on this network, adding more features and functionality.) This network loads a geometric mesh from a data file and renders it to the screen.


Figure 1.3: SCIRun NetworkEditor after building the Chapter 1 network.

Modules: A module is a single-purpose unit that functions within a dataflow environment. Modules have at least one input port for receiving data, located at the top of the module, or one output port for sending data, located at the bottom of the module (See Figure 1.4).

For a more complete description of modules, consult the User's Guide, Section 2.3 "Modules and Networks."

All modules have an indicator that alerts the user to messages that exist in a module's log. Different colors represent different types of messages. Gray means no message, blue represents a Remark, yellow a Warning, and red an Error. To read messages, click the module's indicator button to open the log window.


Figure 1.4: SCIRun Module Icon.

Pipes: Data is transfered from one module to another using dataflow connections,commonly refered to as Pipes. Each dataflow pipe transfers a specific datatype in SCIRun, denoted by a unique color. Pipes run from the output Port of one module to the input Port(s) of one or more other modules. Ports of the same color correspond to the same datatype and can be connected. These colors are described in detail in the User's Guide, Section 4.2, "Anatomy of a Module".

Two or more connected modules form a SCIRun network, or net.

FieldReader Module

Now it is time to begin creating a SCIRun dataflow net. First, create a FieldReader module, which will be used to load a SCIRun Field dataset from disk.

  • Select SCIRun->DataIO->FieldReader from the menu bar, as shown in Figure 1.5.


Figure 1.5: Module Creation Menu (FieldReader).

The FieldReader module will appear on the NetEdit frame. Now, set user interface parameters for this module, by pressing the UI button on the module. This brings up a standard file selection dialog (Figure 1.6). Select the utahtorso-lowres/utahtorso-lowres-voltage.tvd.fld input file. (Note: This file can be found in the SCIRunData directory. This directory should have been downloaded and installed when SCIRun was installed.) This dataset contains a low resolution tetrahedral mesh of a human torso.


Figure 1.6: Field Reader file selection GUI.

Once the file has been selected, the following will occur: Brief Field Overview

A Field contains a geometric mesh, and a collection of data values mapped on to the mesh. Data can be stored at the nodes, edges, faces, and/or cells of the mesh. In this case, a tetrahedral mesh with voltages defined at the nodes of the mesh has been selected.

The dimensionality of the mesh type determines the available storage locations. For example, a TriSurf mesh has nodes, edges, and planar faces, but not cells, which are assumed to be three-dimensional elements. As a result, a TriSurf cannot store data in cells, but can store data in edges or faces.

See Appendix 1 for a description of various types of geometric meshes, data values, and mappings SCIRun supports.

Hooking Modules Together

Now add a second module to the network. This module is used to visualize various Field types. Then connect the two modules in the canvas so data can flow between them.

  1. Create a ShowField module using the SCIRun->Visualization menu (use the same menus used to create the FieldReader module).

  2. Position the mouse pointer over the yellow output port on the FieldReader. Press and hold the mouse middle button. The name of the port and lines indicating possible data pipe connections will appear.

  3. Continue to hold the middle mouse button and drag the mouse toward the first yellow ShowField input port.

  4. The line turns red, showing the desired connection has been selected. See Figure 1.7.


    Figure 1.7: Pipe Selection Options.

  5. Release the mouse button. A yellow pipe showing a data flow connection between FieldReader and ShowField will appear (Figure 1.8).


    Figure 1.8: Connected Dataflow Pipe.

Dynamic Compilation

ShowField works with all SCIRun Field data types. However, these data types must first be compiled into a shared library (as needed) where they are saved for future use. This process is called "Dynamic Compilation."

Dynamic Compilation causes a delay when the module executes the first time. For more details, refer to "Dynamic Compilation."

In addition, the module turns light yellow while it compiles, and compilation output goes to the module's log as a remark. Note that SGI computers can take over 30 seconds to perform dynamic compilation. When compilation is done, the modules color returns to a light gray.

Setting the ShowField User Interface

The ShowField module has options for changing the visual representations of a Field's geometry. To illustrate the module's functionality, change ShowField parameters using its GUI. Specifically, change the color of the nodes to blue spheres.

  1. Select the UI button on the ShowField module.

  2. Select the Default Color button near the bottom of the GUI to change the default color and a separate Color Chooser GUI appears.

  3. In the Color Chooser GUI, use the sliders to adjust the color values. Set Red and Green to 0.00, and Blue to 1.00. The Alpha value remains at 0.50.

  4. Select the Apply button in the Color Chooser GUI. Notice that the Default Color swatch in the ShowField GUI has changed to blue. SCIRun and the ShowField GUI should now look like Figure 1.9.

  5. Close the Color Chooser GUI.

  6. Set the name of the Field to Voltage. This makes it easy to identify the Field in the Viewer Window (discussed later).


Figure 1.9: ShowField GUI.

Now change the scale and resolution of the nodes.

  1. In the ShowField GUI, a slider widget represents the Node Scale. The Node Scale interval can be increased or decreased by a power of 10 by pressing the + or - button. Set the Node Scale to 2. Make sure the Node Display Type is set to Spheres.

  2. Set the Sphere, Box and Disk Resolution to 5.

  3. Go to the Edges tab and turn off the display of edges by deselecting the Show Edges check box.

  4. Go the the Faces tab and repeat the same action.

  5. Close the ShowField GUI by pressing the Close button.

The ShowField module is ready to render the nodes as blue spheres. The module Interactively Updates, by default, to execute after every user GUI change. Users can select the Execute button only box to delay all changes until the Execute button is pressed. This is useful with large dataset,when rendering takes a long time.) Consult the User's Guide 5.22, "Executing a Network", for more details.

Viewer module

The Viewer is the last module that will be added to the network. (More information about the Viewer can be found in the User's Guide 6.0, "Visualization with the Viewer.")
  1. Create a Viewer module by using the SCIRun->Render menu.

  2. Connect the output port from ShowField into the Viewer input port. Notice the Viewer module automatically creates a new input port; this is an example of a SCIRun module that has dynamic input ports. This allows the Viewer module to support an infinite number of geometry producing modules.

  3. Open the ViewWindow by pressing the Viewer's UI button.

  4. In the ViewWindow, there is a set of axes, representing X, Y, and Z directions. To make all of geometry piped to the viewer visible, press the Autoview button. (Note: any time the view is changed (scaled, rotated, or translated), and you want the viewer to re-display everything in the center of the screen, use the Autoview button.) At this point, the utah-torso voltage Field should appear in the Viewer window. It should appear similar to Figure 1.11, but will be somewhat different as the figure has been scaled and rotated.


Figure 1.11: ViewWindow showing the utahtorso-lowres-voltage data.

Navigating the ViewWindow

Since the Viewer is one of the most important SCIRun modules, we suggest reading User's Guide 6.1, "Anatomy of the ViewWindow" for a full description of the Viewer.
  • Please note, this tutorial was tested on a 1.8 Ghz Linux/Nvidia GForce 3 at approximately 7 fps (frames per second). On slower systems with a frame rate less than .3 fps, the GUI may appear to freeze.

Mouse Controls

In the Viewer, the mouse can be used to rotate, scale, and translate the image. The User's Guide 6.3, "Mouse Control in the Viewer Window" provides more complete information.

Translating the image (Left Button)

  1. Move the mouse to the center of the image.

  2. Click and hold the left mouse button.

  3. Move the mouse to translate the image.

  4. Release the button, and the image stays in its new location.

Rotating the image (Middle Button)

  1. Click and hold the middle mouse button.

  2. Move the mouse to rotate the image.

  3. Release the mouse button.

  4. If the mouse button is released while dragging, the image will continue to rotate.

  5. Click the middle mouse button to stop rotation.

Scaling the scene (Right Button)

  1. Click the right mouse button and drag the mouse.

  2. Move the mouse up or to the left to zoom the image out.

  3. Move the mouse down or to the right to zoom the image in.

Setting Visualization Parameters

Now review the controls at the bottom of the ViewWindow (see Figure 1.13). Buttons located at the bottom of the ViewWindow are used for the following functions:

  • Autoview: attempts to render all objects on the screen.

  • Set Home View: captures the setting of the current view (position, scale, angle, etc.) so it can be returned to by clicking the "Go home" button.

  • Go home: restores the current home view (set by the last press of the Set Home View button.)

  • Views: allows the user to select from a list of standard viewing angles and orientations.


Figure 1.13: Basic Viewer controls.

To access more display options:

  • The Extended Control Window contains additional Viewer settings.To access the Extended Control Window, press the "+" button in the lower right corner of the ViewWindow (see Figure 1.14). For a more complete description, read the User's Guide 6.4, "Extended Control Window.:"

    Notice that in the Objects list, the geometry is named "Voltage Nodes" based on the name given to the field using the ShowField GUI earlier.


Figure 1.14: Extended control window.


The Extended Control Window can be used to manipulate various settings for individual objects.

Saving and reloading networks

Now that a three-module network has been created, save the net to disk. The net can easily be reloaded in a future SCIRun session.

Saving a SCIRun network:

  1. Click on the File menu (at the top of the Network Editor window) and select "Save As."

  2. When the file browser appears, follow the prompt to choose a location and filename for the net. By convention, most nets are stored in the SCIRun/src/nets/ directory, but can be stored in another location.

  3. For this example, store the net as SCIRun/src/nets/show-torso-mesh.net, as in Figure 1.15. The .net suffix is used for SCIRun network files.

Please note, to avoid losing work, it is strongly recommended that nets be saved frequently.



Figure 1.15: "Save As" GUI.

  1. Click the Save button. The network is saved, and the dialog disappears.

  2. Exit SCIRun by selecting File->Quit from the NetworkEditor menu or pressing Ctrl-Q.

Loading a SCIRun network:

  1. Start SCIRun.

  2. From the File drop-down menu, select the the Load... option.

  3. Select SCIRun/src/nets/show-torso-mesh.net.


Figure 1.16: GUI for loading a network.

The net reloads into SCIRun, where it was previously saved. If the net was saved with any of the module UIs open, those UIs automatically re-open when loaded to the net. After changing module settings (e.g., rotating the image in the ViewWindow or changing the rendering color of the nodes in ShowField), there are two options for re-saving the net:

  1. Overwrite existing show-torso-mesh.net file by using File->Save from the drop-down menu.

  2. Save the net to a new file by using File->Save As...

Summary

Chapter 1 demonstrated the construction of a three module network to visualize the geometry of a mesh, and how to render that mesh to the viewing window. This chapter also instructed the user on saving and reloading networks.

Chapter 2 features additional tools to examine data values, and instructions for varying colors over the geometry.

Appendix 1: Overview of Field types

SCIRun has nine geometric meshes available for Fields:

PointCloudMesh: unconnected points

ScanlineMesh: regularly segmented straight line (a regular 1D grid)

CurveMesh: segmented curve

ImageMesh: regular 2D grid (see note below)

Structured Quad Surface mesh: surface made of connected quadrilaterals on a structured grid

Structured Hex Volume mesh: subdivision of space into structured hexagonal elements

TriSurfMesh: surface made of connected triangles

QuadSurfMesh: surface made of connected quadrilaterals

LatVolMesh: regular 3D grid

TetVolMesh: subdivision of space into tetrahedral elements

HexVolMesh: subdivision of space into hexagonal elements

PrismVolMesh: five faces, two triangular faces connected together by three quadrilateral faces.

The following data types can be stored in a Field:

  • tensor
  • vector
  • double precision
  • floating point
  • integer
  • short integer
  • char
  • unsigned integer
  • unsigned short integer
  • unsigned char

To continue the tutorial, go to Hooking Modules Together

Return to Top