CIBC:Documentation:SCIRun:UserGuide:StartingSCIRun

Prev Next Contents

Preparation

Preparation for Unix, Mac, Linux, etc.

Preparations must be made before starting SCIRun and its PowerApps. Commands below are typed in a terminal emulation application (e.g., xterm).

See SCIRun's Initialization File--.scirunrc and Dynamic Compilation for additional information.

Change your current working directory to SCIRun's build directory

cd SCIRun/bin

and type:

./scirun [ [-e] network_file ]

Note

Do not start SCIRun in the background, i.e.,do not type: scirun &.

The scirun command may take the name of a SCIRun network file (network files have a .srn extension) for SCIRun to load. The -e tells SCIRun to execute the network after it is loaded. Network files are discussed in a later section.

Mac OS X 10.4

Run SCIRun in the X11 Terminal.

Preparation for Windows

In Windows, SCIRun may be started as in the unix section, by opening a "Windows Command Prompt" (Start->Run... and type in 'cmd' in the Run dialog). Alternatively, you can start it up by browsing My Computer or Windows Explorer to the directory that contains scirun.exe and just double-clicking on it.

If you install the Windows binary version of SCIRun or associate .srn files with SCIRun, you can also double-click on any scirun network file (.srn) and it will run SCIRun with that network file. To associate srn files with SCIRun, do the following:

 Open a Windows Explorer window, click the Tools menu and select Options
 Click the File Types tab, and select New
 In the Dialog that appears, type srn and click OK
 In the Details for SRN extension frame, click Change and navigate to scirun.exe

Post startup

If the name of a network file is not provided, SCIRun starts with an empty window as shown below.

SCIRun may encounter errors during start up. Errors, warnings, and other messages are displayed in SCIRun's Message frame. Errors should be reported to the SCIRun development team via the SCIRun Bugs Wiki.

Anatomy of the Main Window

The SCIRun main window consists of the Menu Bar, the Global View frame, the Message frame, and the Net Edit frame.

Menu Bar The menu bar is used to load networks, save networks, quit SCIRun, create network modules, and perform other tasks. The menu bar consists of the following menu items:

File The File menu contains the following items:

Load Loads a networf from a file

Insert Adds a network to the NetEdit frame without overlap.

Save Saves a network to a file

Save As... Saves a network to a new file

Clear Network Removes all modules and connections from the NetEdit frame

Select All Selects all modules.

Execute All Executes all modules.

Wizards Contains the Create Module Skeleton option which guides a user through the creation of a basic module.

Network Properties Adds network specific notes to the current network. Notes should be used to document the purpose of the network

Quit Quits SCIRun. Pressing key combination Control + Q also quits.

SCIRun The SCIRun menu is used to create modules (from the SCIRun package) for use in the Net Edit frame.

This menu is composed of sub-menus. Each sub-menu corresponds to a category within the SCIRun package. A category is a group of related modules. Each menu item in a category sub-menu creates a specific module and places it in the NetEdit frame.

The NetEdit frame pop-up menu also provides access to the SCIRun and BioPSE (and possibly other) package menus. Activate the NetEdit frame pop-up menu by clicking Btn3 (right mouse button). The BioPSEPackage has an overview of the SCIRun package.

BioPSE The BioPSE menu creates modules (from the BioPSEpackage) for use in the NetEdit frame. It consists of category sub-menus and module menu items The SCIRun Package has an overview of the BioPSEpackage.

Other Package Menus There may be other package menus if other packages have been installed. They also have category sub-menus and module menu items.

Global View Frame The Global View Frame is located in the upper left corner of the main window. It is used to navigate complex networks.

Message Frame Messages during program startup are displayed in the Message frame. The Message frame is located in the upper right corner of the main window. Errors on startup may mean SCIRun has been installed incorrectly or has been installed from a buggy distribution. Please report these errors.

NetEdit Frame The NetEdit Frame occupies the bottom of the main window. It is used to build and execute networks.

The Global View, Message, and Net Edit frames can be resized by moving their borders vertically/horizontally. The horizontal border separating the Net Edit frame from the Global View and Message frames can be moved up or down. The vertical border separating the Global View and Error frames can be moved left or right. To resize a frame, position the mouse pointer over a border, press (and hold) mouse button 1, and drag the mouse. A frame is removed entirely from view by dragging a border to the window's edge.

The Terminal Window

After starting, SCIRun runs a shell-like application in the terminal window called the SCIRun shell. The SCIRun shell displays the prompt scirun>. This program is a modified Tool Command Language (TCL) shell program. It is possible to type TCL'ish SCIRun commands at the prompt. A later section describes use of the SCIRun shell.

SCIRun's Environment

SCIRun responds to a number of variables to alter its default behavior. They can be in two places: the .scirunrc file, or in environment variables.

When started by a user the first time, SCIRun creates a default version of .scirunrc in the user's home directory (for unix-based environments) or in the directory that you compiled or installed scirun.exe in (for windows). Users may modify their default .scirunrc file.

SCIRun then processes the .scirunrc file on each subsequent startup. The .scirunrc file contains assignments to environment variables that affect SCIRun's behavior. Lines beginning with '#' are ignored.

Users may also set SCIRun related environment variables in their shell. Values of variables set in the shell override values set in .scirunrc.

See the content of .scirunrc for a complete list of SCIRun related environment variables. The following is a partial list of variables understood by SCIRun.

The Initialization File--.scirunrc

SCIRUN_RCFILE_VERSION = [string]

  The version number of this .scirunrc file.
  Used in determining if the users existing.scirunrc 
  needs to be updated upon starup of SCIRun.

SCIRUN_RCFILE_VERSION = 3.0.0.0

SCIRUN_LOAD_PACKAGE = [comma-seperated list]

  The format of SCIRUN_LOAD_PACKAGE is a comma seperated list of
  package names.  This list specifies the package libraries to load
  when SCIRun is first brought up.
SCIRUN_LOAD_PACKAGE = BioPSE,Uintah,Teem

SCIRUN_SHOW_HIDDEN_MODULES = [boolean]

  Show modules that have been set to be hidden. These hidden modules include
  obsolete or unfinished modules. Use extra care when using these modules
  as they may be deleted in a future version or may cause scirun to crash
SCIRUN_SHOW_HIDDEN_MODULES = true

SCIRUN_DATA = [path]

  Directory location that 'Reader' modules will default to.
SCIRUN_DATA = /usr/sci/data/SCIRunData/$(SCIRUN_VERISON)

SCIRUN_DATASET = [name]

  Name of data set in SCIRUN_DATA to default to.
SCIRUN_DATASET = sphere

SCIRUN_NET_SUBSTITUTE_DATADIR = [boolean]

  If true, module filename variables will be automatically substituted for
  'SCIRUN_DATADIR' and 'SCIRUN_DATASET' in saved .net files.
SCIRUN_NET_SUBSTITUTE_DATADIR = false

SCIRUN_NET_RELATIVE_FILENAMES = [boolean]

  If true, SCIRun will save all filenames relative to the location of the 
  network file in the .srn files.
SCIRUN_NET_RELATIVE_FILENAMES = true

SCIRUN_MYDATA_DIR = [path]

  Directory, or list of directories separated by colons, 
  that data 'Reader' and 'Writer' modules will list as
  optional paths in the directories drop down menu.
SCIRUN_MYDATA_DIR = $HOME/data:/scratch/data

SCIRUN_ON_THE_FLY_LIBS_DIR = [path]

  User writable directory to build 'on-the-fly' .h, .cc, .o and .so files.
SCIRUN_ON_THE_FLY_LIBS_DIR = $(HOME)/SCIRun/on-the-fly-libs

SCIRUN_TMP_DIR = [path]

  Directory for writting temporary files - must be world read/writeable

SCIRUN_TMP_DIR = /tmp

SCIRUN_CONFIRM_OVERWRITE = [boolean]

  If false, SCIRun writer will not prompt the user before overwriting a file
SCIRUN_CONFIRM_OVERWRITE = true

SCIRUN_INSERT_NET_COPYRIGHT = [boolean]

  If true, adds SCI copyright to any SCI .net files that are created.
SCIRUN_INSERT_NET_COPYRIGHT = false

SCIRUN_FAST_QUIT = [boolean]

  If true, SCIRun will not ask the user to save a network before quitting
SCIRUN_FAST_QUIT = false

SCI_REGRESSION_TESTING = [boolean]

  If True, regression testing mode will turn on.  Execution starts after a
  network is loaded and SCIRun will exit immediately after creating an image.
SCI_REGRESSION_TESTING = false

SCIRUN_REGRESSION_TESTING_TIMEOUT = [integer]

  If set, and if SCI_REGRESSION_TESTING is True, SCIRun will automatically
  kill itself after specified seconds.
SCI_REGRESSION_TESTING_TIMEOUT = 300

SCIRUN_NO_PORT_CACHING = [boolean]

  If true then SCIRun will no longer cache intermediate results in
  its ports.  This will break interactive SCIRun usage as the
  program will be confused about which modules it needs to reexecute
  when a network is changed.  However it can save memory usage for
  batch-type operation.  Smarter caching should deprecate this option
  in the future.
SCIRUN_NO_PORT_CACHING = false

SCIRUN_DRAWARRAYS_DISABLE = [boolean]

  Turns off use of glDrawArrays.  This should be set to true if you wish
  to avoid drawing artifacts on _ATI_ Radeon cards under Linux or to fix
  cross-platform remote display problems.
SCIRUN_DRAWARRAYS_DISABLE = false

SCIRUN_MPEG_LICENSE_ACCEPT = [boolean]

  License information describing the mpeg_encode software can be found
  in SCIRun's Thirdparty directory, in the mpeg_encode/README file:
  This software is freely distributed.  That means, you may use it
  for any non-commercial purpose.  However, patents are held by
  several companies on various aspects of the MPEG video standard.  
  Companies or individuals who want to develop commercial products 
  that include this code must acquire licenses from these companies.  
  For information on licensing, see Appendix F in the standard.
  For more information, please see the mpeg_encode README file.
  If you are allowed to use the MPEG functionality based on the above
  license, you may
  enable MPEG movie recording in SCIRun (accessible via the SCIRun
  Viewer's "File->Record Movie" menu) by setting the value of
  SCIRUN_MPEG_LICENSE_ACCEPT to "true".
SCIRUN_MPEG_LICENSE_ACCEPT = false

SCIRUN_USE_DEFAULT_SETTINGS = [boolean]

  Force the sizes for ShowField to calculate defaults when loading a new 
  Field.  Also Forces the Viewer to autoview whenever a new netork is
  loaded.

SCIRUN_USE_DEFAULT_SETTINGS = true

SCIRUN_DATA variables

The following environment variables need to be set in the shell for SCIRun to run the sample nets with the default data. These can either be set as environment variables or in the .scirunrc file (after SCIRun has run the first time).

• 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".

Setting environment variables

For unix environments, environment variables may be set as shown above in the SCIRUN_DATA section.

For windows environments, follow these directions: Click the Start button, select Control Panel, and then System. In the Advanced tab, click the Environment Variables button. Select New and enter the name and value of the environment variable. If it already exists, click on it and select Edit to modify it.

Remote Display

Normally, SCIRun's main window is displayed on a console that is part of the computer on which SCIRun runs. It is possible, however, to display SCIRun on a remote console. In the discussion that follows, the term local refers to the machine running SCIRun and the term remote refers to the machine displaying SCIRun.

Caveat: Advanced GL remote rendering is problematic. SCIRun is compiled against the GL driver on the local machine, but when displayed remotely, uses the remote machines GL driver. Many times the local and remote drivers are not compatible and will result in SCIRun crashing. For this reason, if possible, try not to run SCIRun in this manner.

To display SCIRun remotely, the value of the DISPLAY environment variable must be set correctly on the local machine. Also, the local machine must be allowed to send display commands to the remote machine.

Normally, the remote machine makes a connection to the local machine via the ssh command. In this case, ssh sets the value of DISPLAY in such a way that the local machine has permission to send display commands to the remote machine. However, ssh connections result in poor display performance because of encryption activity on the connection.

To increase performance, the value of DISPLAY is set as follows after establishing the ssh connection:

for a sh-style shell

export DISPLAY=remote-machine-name:0.0

for a csh-style shell

setenv DISPLAY remote-machine-name:0.0

Note that this technique defeats the encryption protection on the connection.

After overriding the value of DISPLAY set by ssh, the local machine will lack permission to send display commands to the remote machine. Use the xhost command on the remote machine to give permission to the local machine:

xhost +local-machine-name

Dynamic Compilation

Before executing SCIRun, be aware of the Dynamic Compilation feature.

Dynamic compilation is a technique used by SCIRun to discover and generate code for data types and algorithms used by modules in networks. This is done at runtime and once for each new data type and algorithm encountered. This technique provides a number of benefits not discussed here (see the publication Dynamic Compilation of C++ Template Code for details).

By default, code generated by dynamic compilation is stored in the binary directory's on-the-fly-libs. The location of dynamically generated code can be changed by setting the value of the environment variable SCIRUN_ON_THE_FLY_LIBS_DIR to the desired directory.

For example:

for Bourne-like shells (sh, ksh, bash, etc,)

SCIRUN_ON_THE_FLY_LIBS_DIR=~/SCIRun/on-the-fly-libs

export SCIRUN_ON_THE_FLY_LIBS_DIR

for csh-like shells

setenv SCIRUN_ON_THE_FLY_LIBS_DIR ~/SCIRun/on-the-fly-libs

SCIRUN_ON_THE_FLY_LIBS_DIR can be set in the user's .scirunrc file.

SCIRUN_ON_THE_FLY_LIBS_DIR=/home/me/on-the-fly-libs

Setting a unique value of SCIRUN_ON_THE_FLY_LIBS_DIR for each SCIRun user has the following benefits:

• Allows multiple users to run the same instance of SCIRun without dynamic compilation conflicts. For example, by specifying an on-the-fly-libs directory in their home directory, a user can run SCIRun installed in /usr/local that another user is already running.

• Allows a /usr/local installation of SCIRun to be secure because it does not require /usr/local/.../on-the-fly-libs to be writable by all (a potential security risk).

• Allows greater debugging and multiple build support by allowing the user to change dynamically compiled code locations between instances of SCIRun.

Dynamic compilation causes a delay the first time a module is executed. The module changes color while it is being compiled.

Exiting SCIRun

Exit SCIRun by selecting the Quit item from the File menu or by pressing control-q.

Do not press control-c to exit SCIRun. Doing this will drop SCIRun into a debugger.

Prev Next Contents