Appendix A - Configuring Your IRIS Explorer Environment

This appendix explains how to configure various aspects of your system in order to use IRIS Explorer more effectively. It includes:

• modifying your .explorerrc file
• configuration commands
• setting environment variables
• remote execution of modules
• running the X server

IRIS Explorer reads configuration information from files on start-up. This information tells IRIS Explorer, among other things:

• where to look for modules
• how to configure the Module Librarian
• what size the memory arena should be
• where and how to run remote modules

The first word designates the command, and subsequent fields designate arguments or modifiers to the command. Either single or double quotation marks may be used to surround arguments that contain embedded blank characters.

Most arguments to commands may encode UNIX environment variables using the shell dollar-sign notation. For example, $EXPLORERHOME will expand to the value of the environment variable EXPLORERHOME, as will ${EXPLORERHOME}. The C-shell tilde ~ notation for designating home directories is recognized as well. However, strings surrounded by single quotation marks (apostrophes) are not expanded in this manner.

If the file permissions are set to be executable, the file will be executed and the output read as the configuration file. If IRIS Explorer recognizes the #!CPP notation, the file is run through the C preprocessor and all environment variables are defined to the C preprocessor as C preprocessor symbols. This means you can use conditional statements for values such as hostname, which makes the file more flexible.

If you use the #!CPP notation in your .explorerrc file, then you must use ! rather than # at the beginning of a comment line.

This is an example of a typical _explorerrc file. Comments start with an exclamation point (!) in column 1.

! Look for modules in my local directory
modulepath -append ~/explorer/modules

! Set the directory where the arena and pipes go
set tempdir /usr/tmp/explorer

! Add some frequently used modules into the shelf
category shelf Render DisplayImg IsosurfaceLat ReadImg\ 
   ReadLat Contour

! Put the Geometric modules into their own category
category Geometry BoundBox Contour IsosurfaceLat \
   IsosurfacePyr LatToGeom PyrToGeom \
   PickLat ReadGeom VolumeToGeom

! Increase the maximum arena size for larger data sets
set arenasize 24mb

! Define some remote hosts
host willard

The commands that are accepted in an IRIS Explorer configuration file are described below. Optional portions are enclosed in square brackets. Ellipses denote that the previous argument may be repeated any number of times. Commands (reserved words) are shown in bold.

The module path is a list of directories in which IRIS Explorer looks for modules and maps. The default list contains only $EXPLORERHOME/modules, but the Explorer.config file shipped with IRIS Explorer extends it. You can reset module paths from scratch, or you can extend them using the -append or -prepend modifiers.

The modulepath command states where to look for modules.

modulepath [-prepend] path ...
modulepath [-append] path ...

This command defines a list of directories to be used. By default, the existing module path is extended by the list for directories (this is equivalent to using the -append modifier). The default path value is $EXPLORERHOME/modules. Used alone, the command clears the module path to the default path value. If the -prepend modifier is used, the path is added at the head of the current directory list.

You can use the set command to set the temporary directory and the size of the arena.

The set tempdir command states where to place any temporary files that may be needed during the course of execution, such as named pipes and shared memory arena files, if applicable. Typically, such files are placed in a uniquely named subdirectory of the directory. The default value for the base directory is /usr/tmp.

Because shared memory arenas can become large, it is often advantageous to place the tempdir somewhere else.

set arenasize

On some workstations, modules use shared memory for data communications. The shared memory is mapped into a file that resides on disk as determined by the set tempdir command above.

set arenasize string

For a shared memory system, make the maximum size of the shared memory arena the designated size.

string should be a number optionally followed by mb or kb for megabytes and kilobytes, respectively. This option may also be set from the command line. The default size is 32Mb.

Defines a new Module Librarian category with the name name and containing the list of modules given.

category name [-append] [-filter] [arg] modulelist

The -append modifier appends a list of modules to a specified category. The list of modules can contain module names, such as GenLat, or directory names. In the latter case, the directory is added to the module path, and all modules and maps in the directory are added to the category. For example,

category myModules ~/explorer/modules

adds all modules in directory ~/explorer/modules to the category myModules. You can use the -filter modifier with an arg to filter the list of modules against the argument pattern. The arg accepts shell wildcards such as *, ? and [. For example,

category Readers -filter Read* $EXPLORERHOME/Modules

puts all the Read* modules in directory $EXPLORERHOME/Modules in a category called Readers.

There is a designated category in the Module Librarian called shelf. Modules in the shelf category are displayed in a small panel at the bottom of the Librarian's window.

Modules are organized by categories and by hosts in the Module Librarian. When you execute IRIS Explorer, host names defined in the .explorerrc file will be listed on the Hosts menu in the Module Librarian window, and modules can be executed on those machines (provided contact can be established and permission is obtained to do so).

The command used by IRIS Explorer to start the LC (local communication server) on a remote host hostname is

remoteshellcommand hostname shellcommand

host hostname [-command rshellcommand]

If rshellcommand contains blanks it must be enclosed in quotation marks. For example, the specification

host bob -command "myrsh -x"

means that IRIS Explorer will use

myrsh -x bob shellcommand

when a request is made to run modules remotely on host bob. The command shellcommand is defined by IRIS Explorer and cannot be changed by the user. If the word HOST appears in remoteshellcommand the hostname is substituted in its place when executing the command. Therefore, you can use the command:

host bob -command "rsh HOST -l joe"

to start a remote LC under the account joe on bob. If the word HOST does not appear in the command, it is appended to the end. Hence, the following two lines are functionally equivalent:

host superhost -command "rsh HOST"
host superhost -command "rsh"

By default, the IRIS Explorer system is installed into the directory /usr/explorer.

Under normal circumstances there is no need to use the environment variable EXPLORERHOME, but if you choose to install IRIS Explorer in a directory other than the default, then you will need to set EXPLORERHOME to point to the installation directory.

If your display is not capable of displaying OpenGL, then you can configure IRIS Explorer to use the MesaGL rather than the standard OpenGL version of all rendering modules. The MesaGL version renders via X using version 1.2.8 of the Mesa 3-D graphics library. Modules for which there is an OpenGl and MesaGL version are ColorEditor, Render, RenderRemote, TransformGen, ViewGeom and VolumeRender.

The environment variable CXGLTYPE determines which version of the modules is going to be used. You will need to set this variable to mesagl if you require MesaGL rendering modules, while the value opengl will lead to using the OpenGL rendering modules (this is the default value).

There is no need to set this variable if you wish to use the standard OpenGL rendering modules.

IRIS Explorer uses a number of environment variables to set the font size, for example in the Librarian, the Map Editor, and all forms of the Module Control Panel. Suitable defaults are used for each platform, but occasionally you may wish to change a font. In particular, if you have a small display and are using modules with large numbers of input and output ports, you may find it difficult to connect some if the ports to other modules as the list of ports extends beyond the size of the display.

The default fonts are defined in the file $EXPLORERHOME/lib/X11/app_defaults/Explorer. You can override them by redefining the resources in your own .Xresources file. In particular, if you wish to reduce the font size on the input and output port popup menus on a module in the Map Editor from 14 (default value) to 13, say, copy the line

*mapEditor*XmMenuShell*XmPushButton*fontList:-*-helvetica-bold-o-normal-*-14-*

and change it into

*mapEditor*XmMenuShell*XmPushButton*fontList:-*-helvetica-bold-o-normal-*-13-*

Other variables that may be used are mapEditor*miniCpBase*fontList to change the font in the title bar of a mini control panel, Librarian.mainWindow*moduleItem.fontList to change the font for the module names in the Librarian and the shelf, and Librarian.mainWindow*networkItem.fontList to change the font of the map names in the Librarian.

A complete list of resource names is found in $EXPLORERHOME/lib/X11/app_defaults/Explorer.

The general idea of IRIS Explorer is that you initially run it on your own workstation, but then you can use it to run some modules on remote workstations.

Each machine that you use to execute modules remotely must have most of IRIS Explorer installed on it. In general, the version installed remotely must match the version installed on the local machine.

To start a local controller process on a remote machine use the New Host... option of the Hosts menu on the Librarian, and enter the host name in the pop-up window. On successful connection, a new Librarian window will appear from where it will be possible to launch modules on the remote machine which interact with modules running on the local machine, with data being passed from one module to another just as though all modules were running on the local machine.

The remote machine may be any of the Unix machines which can run their own versions of IRIS Explorer. In theory, there is no limit to the number of different machines that can be connected in this way.

IRIS Explorer provides an alternate command similar to rsh that can prompt for a password. This command, cxrexec, uses the rexec library call and prompts for a password in a small pop-up window. For example, if access to a host named securehost requires a password, the following line in .explorerrc will result in the password prompt being issued:

host securehost -command cxrexec

The command cxrexec has the same command line options as rsh. Either command can be modified in .explorerrc to add options. However, when additional rsh or cxrexec options are listed, the entire command must be enclosed in quotation marks:

host superhost -command "cxrexec HOST -l guest"

If IRIS Explorer is not installed in the directory /usr/explorer, then you must either:

The easiest thing to do is to install IRIS Explorer in the same location on all machines, which by default is /usr/explorer.

The character ` surrounding hostname in the previous example is an accent grave, not an apostrophe.

The type of visual you run on your X server determines the number of colors available for modification, and this affects how many GenerateColormap modules you can run at one time.

The X server supports several classes of color visuals. Each visual class uses a different method to display color. The GenerateColormap module is designed to function properly with the PseudoColor and TrueColor visual classes. The PseudoColor visual uses the hardware colormap to display a small number of colors from a much larger palette of possible colors. The TrueColor visual class writes colors directly to the graphics frame buffer.

The visual classes have a depth that specifies the number of bit planes it uses for display. A PseudoColor visual with a depth of 8 displays 256 colors at one time; one with a depth of 12 displays 4096 colors. The TrueColor visual supports depths of 24 and 12 bits. The 24-bit TrueColor visual can display 8 bits for red, green and blue, or over 16 million possible colors at one time. The 12-bit TrueColor visual displays 4096 colors at one time, with 4 bits for red, green and blue.

Choosing the best visual depends on your workstations hardware and the other applications you run. Your workstation must have at least as many bit planes as the depth of the visual that you choose. You generally want to run the 24-bit TrueColor visual if you can; otherwise, try the 12-bit TrueColor or PseudoColor visuals.

High-quality applications should run properly with any of these visuals, but other applications may not. Some applications, such as those that do color table animation, may not run with a TrueColor visual. Some applications may make assumptions about the depth of a PseudoColor visual, for example, that the color index will fit into 8 bits. You can start with the highest quality visual supported by your workstation, try your other applications, and then adjust the visual to fit your system's capabilities.

See your local documentation on how to reconfigure the X server.