map3dgl Version 3.0 Documentation -- User's Guide

Author: Rob MacLeod ( -- Last update: February 21, 2002

Nora Eccles Harrison
Cardiovascular Research and Training Institute


1 Introduction

This document describes the function and usage of the program map3dgl, a scientific visualization application used at the CVRTI to view model geometry and scalar (potential) and vectors (current) field distributions. The program is highly interactive and makes extensive use of the full VGX features of the Silicon Graphics Library (GL). map3dgl is a program written in C using the SGI GL library for interactive display of both geometry and data assigned to elements of that geometry on the Silicon Graphics 4D/210 VGX workstation. The program can read multiple surfaces, each with multiple associated potential/current data files.

2 Usage

  map3d [-b -iv -ss -v -vm -nw\
         -c  default_mesh_colour \
         -df default_filename \
         -if default_image_filename \
         -dp datafile_pathname \
         -gp geomfile_pathname \
         -rl report_level \
         -vw xmin ymin ]
         -f geomfilename \
         [-ac \
         -as xmin xmax ymin ymax \
         -at xmin xmax ymin ymax
         -c colour \
         -cg colour \
         -ds \
         -dp datafile_pathname \
         -gp geomfile_pathname \
         -lm landmark_filename \
         -p potfilename -s num1 num2 -i increment \
         -ph maxpotval -pl minpotval \
         -cs contour-spacing \
         -ps scaling_value \
         -ll leadlinks-filename \
         -cl channels-filename \
         -sl surfnum \
         -t trace-lead-number ]

2.1 Typical examples

Typical cases of usage of map3dgl are given below:

Note that if the series number is not specified at startup, the user is presented with a file box from which the desired series is selected. Likewise, if the frame numbers are not given in the command line, the user is presented with a power curve in which to window the data to be displayed. See section 4.3.2 for more information in how to access .data files.

2.2 Global Parameters

The following general parameters affect the entire display:

= open each window without borders. This provides a neater look in multiple-window displays and by using the alt-key and right mouse button, movement or re-scaling of the windows is possible after they are placed on the screen.

= initialize video equipment in VISSGI.

= make sure all windows have the same scaling applied to the geometry.

-v] = show current version of the program and exit.

= run program in video mode. This thickens lines, and sets a reduced range of colours, for the purpose of making videos from graphics output. This also initializes the video equipment in VISSGI.

= for multiple surfaces (i.e., more than one set of points and triangles), place each surface data in a new window. By default, map3dgl opens a single window for all surfaces.

= for multiple surfaces (i.e., more than one set of points and triangles), place all surface data in the same window. By default, map3dgl opens a new window for each new data surface. (This is the default and is hence redundant.)

-c default_mesh_colour
= colour index to use on all surfaces for which there is no specific colour specification.

-df filename
= read the defaults file filename for start-up settings for the program. This overrides any defaults files read by the program (see below) or any defaults set within the program.

-if basefilename
= base filename for any image files that are generated in this run of the program.

-dp datafile_pathname
= directs the search for data files accessed via a .data file to another directory. This occurs most often with data files that actually point to .pak or .raw files on the Vax. Using an alternate pathname, you can override the original directory specification for the files and get them from, say, an optical disk. This value can also be specified in the defaults file (see section 4.1) or via an environmental variable called MAP3D_DATAPATH, which you can set at any time before executing map3dgl. You may specify this option either globally for all surfaces by inserting is before the first -f filename in the command line, or separately for each surface.

-gp geomfile_pathname
= directs the search for geometry files accessed via a .data file to another directory. The most common case of this is when the name of the geometry file is stored in the data file, usually without directory specification. This value can also be specified in the defaults file (see section 4.1) or via an environmental variable called MAP3D_GEOMPATH, which you can set at any time before executing map3dgl. You may specify this option either globally for all surfaces by inserting is before the first -f filename in the command line, or separately for each surface.

-rl report_level
= set the report level for this execution of map3dgl. The legal values are 0 (no reporting) to 3 (full debug-level reporting). This values overrides the one set in the default file, bit should be specified after the default file if the -df option is used.

-vw xmin ymin
= Set the lower left hand corner of the video window to a particular spot on the screen. Units are in screen coordinates, same as for the -as and -ts commands described below.

-f geomfile.geom or
= filename of the .geom (geometry) or .data file containing points and connectivity information. Note: this is the minimal input for successful function of map3dgl. If a .data file is used, it is assumed to contain explicit reference to the associated .geom file containing the geometry. All surfaces are read from the geometry file.

2.3 Surface parameters

For each new surface, a subset of the following surface-specific parameters may be used. Note that if these parameters are to be used with data that are read from .data or .geom files, the last of the three forms specified in section 2.1 above must be used. Otherwise, all surfaces are read at once and the user must accept the default settings for each surface.

-f geomfilename
= root filename of the geometry files (.pts, .fac, .tetra, .geom, or .data) for the triangularized surface to be displayed, eg., -f RL-torso for the files RL-torso.pts, RL-torso.fac, and RL-torso.tetra. If a .geom file is the source of geometry, a single surface may be selected by appending the surface number N to the filename in the form ``@N'', e.g., geomfile.geom@3 to read surface 3 from .geom file geomfile.geom.

= do not shift the origin of the points to the centroid of the pointset but leave values as they are in the input geometry files.

-as xmin xmax ymin ymax
= set the absolute location in pixels of the surface window most recently defined. This can be used to set up multiple window displays in which the location of each window is set beforehand. The full screen of the SGI 4D has 1280 by 1024 pixels.

-c colour
= desired colour for the mesh of a particular surface
1 = red 4 = cyan
2 = green 5 = magenta
3 = blue 6 = yellow
7 = white  

-cg colour
= desired colour for the vectors in any grad files read for this surface. This is meaningful when the amplitudes of the vectors have no intrinsic meaning (e.g., fiber-orientation vectors).
1 = red 4 = cyan
2 = green 5 = magenta
3 = blue 6 = yellow
7 = white  

= make this surface the dominant surface in a master/slave relationship used in the program for moving surfaces independently of one another.

-dp datafile_pathname
= same as above but for this surface only.

-gp geomfile_pathname
= same as above but for this surface only.

-lm landmark_filename
= read from the file landmark_filename a set of coronary arteries, or any other landmark information stored as a series of points, with a radius associated with each. See section 4.5 below for details.

2.4 Data parameters

For each set of potentials on the surface:

-p potfilename
= base filename for the potential and current data files. If the -s option is used, a number and the extensions .pot for potential and .grad for currents will be append to this base filename (see -s option), for .data files, the -s option specifies the frame numbers to be read from the file. Otherwise singles .pot or .grad files named potfilename.pot and potfilename.grad will be searched and read in, or the user will have to interactively specify the run number and frame numbers to be read from the .data file. If a specific run of a .data file is desired, append the run number N in the form ``@N to the end of the filename, e.g., -p to read run number 4 from the file (see section 2.1).

-s num1 num2
= range of frame numbers to read. If we are reading data from .pot or .grad files, these values are appended to the value of potfilename to make complete pot filenames.
eg., -p lux_map -s 1 3 expands to: lux_map001.pot lux_map002.pot lux_map003.pot
If we are reading from a .data file, frames num1 to num2 are read from the file.

-i increment
= difference between each frame number. For .pot and .grad files this affects the string appended to potfilename for each new file.
eg., -p lux_map -s 1 6 -i 2
expands to: lux_map001.pot lux_map003.pot lux_map005.pot For .data files, the frames are read with an increment of increment from the file.

-ph maxpotval
= maximum data value in ``user'' scaling mode. The user can select between ``local'', ``global'', and ``user'' scaling modes using the mouse menus (see below).

-pl minpotval
= minimum data value in ``user'' scaling mode.

-cs contour-spacing
= spacing between contours set by the user.

-ps scaleval
= scaling value multiplied by each potential value as it read in from the file(s).

-ll leadlinks-filename
= file in leadlinks format containing a list of the node locations that correspond to a subset of the leads, e.g., the measurement lead locations on the ventricle surface. The nodes identified by the leadlink file are displayed as cubes (or spheres), with the lead number (not necessarily the same as the node number; this is, after all, the purpose of the leadlink file in general) optional drawn beside it. See the l command below to toggle display of the leads in the leadlink file. See section 4.4 for more information.

-cl channels-filename
= file in channels format containing an entry for each node in the geometry which points to the associated location in the data array. The value of this pointer is also the number that is written next to lead locations when lead numbers are displayed. See section 4.4 for more information.

-sl surfnum
= surface number to which the scaling for this surface is to be slaved. The idea here is to have surfaces locked in the way they scale and display the data.

-t trace-lead-number
= number of the node to be used for the display of a scalar signal in its own window. The number refers to the channel number of the data source or the lead number if a leadlinks file is also present. Multiple invocations of this option are possible for each surface. At any time after this the user can select a lead via the pick mode menu item and have the scalar data from that lead displayed.

-at xmin xmax ymin ymax
= set the absolute location in pixels of a scalar window associated with the current surface. This can be used to set up multiple window displays in which the location of each window is set beforehand. The full screen of the SGI 4D has 1280 by 1024 pixels. map3dgl3d supports multiple invocations of this command for each surface.

2.5 Command line parsing: Background:

The parsing of the command line has been completely rewritten for all versions of map3dgl after July, 1994. This should not mean a great deal to the look and feel of the program, but should make it more robust and predictable than was previously the case. However, until the dust all settles, please do not be surprised if things do not go quite as expected. This may be a sign of changes in the structure of the command line parsing, but also of bugs in the new version. Please document the behavior carefully and let me know. Usage:

This change has allowed two interesting features:
  1. map3dgl can be started with nothing more that a single argument which contains the name of the .data or geometry files; the -f is not necessary. Note, however, than this is not true if more than one argument is passed

  2. map3dgl will soon support selection of the time series to be viewed from with the same invocation of the program. Stay tuned...

3 New Features

In this section, we highlight the latest additions to map3dgl in the (vain?) hope that people will read at least this much of the manual and be able to quickly make use of the latest and greatest that the program offers.

3.1 February 2001 new features

Added a description of the frame controls in Section 6.3.

Also renamed the program to map3dgl to indicate the transition of the original program to OpelGL.

3.2 September 1999 new features

Well, I have a new feature in Map3d for you to play with. This is the option tnat allow you to specify intervals between contours at the command line when starting map3d. Not the final functionality we want, but at least a start and something we can experiment with.

The option is called

-\texttt{cs value}

cs stands for "contour step" and value is a numeric value in the same units as the scalar data you are viewing.

So a map3d command might look like
map3d -f daltorso.geom -p -cs 5 for contour spacing of 5 units.

You can still use all the other contour options and have two places to select or deselect the values in the -cs option. Look in the "Scaling Model" and the "Number of Contours" menus for these controls.

The logic for -cs spacing I have implemented (and this is subject to discussion) for the different scale mapping is as follows:

contours start at the smallest value in the range and go up in increments of "spacing" units to as close to the maximum value in the range as possible. The range is defined by the usual scale scope controls.

the larger (by magnitude) of the positive and negative ends of the scalar data range determine the range of this scaling. There is a contour at zero and then a set in each of the positive and negative directions with "spacing" units between them. So if the range were -12 to +17 and spacing were 5, the contours would be -15, -10, -5, 0, 5, 10, 15.

here the positive and negative halves are treated independently. So for the same case as above, the contours would be -10, -5, 0, 5, 10, 15.

At least this is how it is supposed to work (-:

Still to do:

3.3 July 1998 new features

  1. Select a reference channel to subtract from all other leads. This works the same as subtracting means, but uses a single time signal rather than the mean of all time signals. User can control the lead to subtract using picking as well as toggle the subtraction. See Section 5.4 for details.
  2. Restored time series selection via the main menu (still pending replacement using Tcl/Tk interface).
  3. Fixed some bugs in selecting lead display and other surface-by-surface features. Basic rule is not that if all surfaces are drawn, then any changes in parameters (e.g., lead display) get applied to all surfaces. If only a single surface is drawn, then that surface is the one whose parameters are changed. When there are multiple windows, then all surfaces get drawn all the time so the user must monitor the window from which map3dgl is launched to see whether one or all surfaces are selected. Hitting the up and down arrow keys selects the surface.
  4. Fixed marking of the selected scalar lead and reference lead to be more consistent with the other lead markings and added a range of size settings (user controlled) for the size of spheres that get drawn to mark nodes.
  5. Restored function for displaying vectors.

3.4 October 1997 new features

  1. Display mode with banded colouring, similar to that produced by VGX already but that Indigo dithers over, called as b-shading in the Shading/contour/vectors menu under Shading Model.
  2. Multiple instances of scalar leads set up at invocation time from the command line (or a script); simply use -at and -t options as often as desired within the scope of a surface.
  3. New colour maps in B-R mode, especially noticeable in video colour mode.
  4. Video scalar: a place to hide special layouts for the labeling and layout of the scalar leads. See Rob MacLeod ( for details.

3.5 September, 1996 new features

Some new features in a little more detail:

Subtracting mean values:
This option subtracts the mean value across all leads of a surface for each frame of data. The means are computed as soon as the pot data are first read in and these means ore maintained with the original data. This allows us to remove, and then restore the mean values at will. The effect can be useful for reducing noise or giving a new baseline to the time signals. To toggle between having the means removed or restored, use the main menu and look in the Scale Scope or Scale Mapping submenus. Note that the toggle works on a surface by surface basis. See the surface option selection rules below for guidance on controlling this.
Surface option selection rules:
Most of map3dgl's features act on a surface-by-surface basis, e.g., if you adjust the lead display, it can affect a single surface, or all surfaces, but how do you tell which? The key lies in whether we are viewing all surfaces or a single surface; if a single surface is visible, then controls affect only that surface, if all surfaces are visible, then change we make will toggle all suraces. (Note that toggling means reversing the setting, not forcing all surfaces to the same state.) But this only appears useful when all surfaces are in the same, single window; what happens when there is a separate window for each surface? The situations are actually identical as far as the program is concerned, as is the control of surface selection. If the up arrow key is pushed often enough so that ``drawing all surfaces'' appears in the text window from where map3d was started, then all changes affect every surface. Once the down arrow is pushed even once, selecting a single surface for display, then all changes affect only one surface, the surface in which the cursor sits! So, to change the lead marking on a single surface, just make sure to push the down arrow once, then move the cursor to the window of the surface that needs to be changed, and make the desired alterations.
Surface selection with multiple scalars:
This feature is an experiment and I appreciate feedback. When you have a multi-surface display in a single window, the normal way to select which surface(s) is displayed is with the up and down arrow keys. If, however, there are also multiple scalars selected that come from different surfaces, there is a new way to control the surface displayed. By simply moving the mouse cursor into the scalar window, the surface associated with that scalar is the one selected in the main window for display. This permits rapid switching between a set of surfaces and easy identification for each scalar lead of the surface to which it belongs. Try it and let me know what you think -- remember, for the moment it is a feature, not a bug!!

3.6 Still more features

Deleting nodes:
it is now possible to delete nodes from a geometry. All polygons that include that node are also deleted. Once a node is gone, it is gone!!! The original geometry file is not changed but the one created at the end of the run will not include any deleted points or their elements.

3.7 In the works (``vapourware'')

A small sampler of things that are in the works:

4 Input files

4.1 Default settings files

The program map3dgl looks for files containing default settings for virtually all parameters that are relevant to the control of the program. The order of precedence is as follows:

  1. The -df filename option defines the file with highest precedence default settings.
  2. A file named .map3drc in the current directory (the one from which the application was launched) is used next.
  3. If no .map3drc files is found in the current directory, it is searched for in the user's home directory (see the HOME environmental variable). This file has the lowest precedence and is only used of the other two options are not found.
  4. The program map3dgl has a set of internal defaults which are used if there are no external default files found.

The format of the default file is as follows:

           # comment line (ignored by map3d)
           parameter = value

where the parameters and values are taken from the following list:

Parameter Values Meaning
shadingmodel GOURAUD Use Gouraud shading of triangles
  FLAT Use flat shading of triangles
scale_scope GLOBAL_SURFACE Scaling global over each surface
  GLOBAL_FRAME Scaling global over each frame of data
  GLOBAL_GLOBAL Scaling global over all data
  LOCAL Scaling local to each frame and surface
  USER Scaling by user-supplied values (-pl -ph)
scale_model LINEAR Use linear scaling of contours
  LOG Use logarithmic scaling
  EXP Use exponential scaling
  LAB7 Use logarithmic in 7 levels scaling
  LAB13 Use logarithmic in 13 levels scaling
scale_mapping SYMMETRIC scale symmetrically around both side of zero
  SEPARATE scale separately for + and - data values
  TRUE_MAP scale from most - to most + values
color_map RG Use full red-to-green colour map
  RG2 Use red-and-green (2-colour) colour map
  FULL Use blue-to-red (full) colour map
  BTW Use black-to-white colour map
  WTB Use white-to-black colour map
lead_marking1 LEADS mark nodes with lead (channel) numbers
  NODES mark nodes with node numbers
  VALUES mark leads with potential values
  CUBES mark leads with spheres/cubes
  MINMAX_LABELS mark extrema with lead numbers
  MINMAX_CUBES mark extrema with cubes
  SCALAR mark the selected scalar node
num_cols value number of colours to use in shade display
num_conts value number of contour levels in display
draw_bbox TRUE/FALSE set bounding box on or off
datafile_path pathame alternate path to the .pak/.raw files in .data file.
geomfile_path pathame alternate path to the .geom files in .data file.
report_level value level of error reporting ( 0-3 )

Note that these parameters and values are not case sensitive and that they can all be overridden during execution of the program, typically via the mouse menu (right mouse button). See section 5.3 for details on the different scaling options. The list of parameters possible will also certainly grow with the program.

To save the current settings in a file, there is an option in the main menu of map3dgl which dumps all the settings to the file ./.map3drc, that is, the file .map3drc in the current directory. That way, when you start the program again from that directory, the same settings will be loaded. The .map3drc file is just a normal text file, but like all ``rc''-files, it is hidden from the ls command unless you add the -a option (the alias la is set up by default to do a long listing of all files, including hidden files). Dumping a copy of the settings is also the easiest way to see what settings are currently being maintained by map3dgl and also forms the best starting point to setting up your own customized default settings files.

4.2 Geometry input files

The input of geometrical data may occur via a family of simple ASCII files used to describe geometry. These include the points or nodes of the geometry in a file with the extension .pts and the connectivities that described polygonal links between nodes, stored as line segments (.seg files), triangles (.fac files), and tetrahedra (.tetra files). A more recent consolidation of geometry information has resulted in a binary file format with the extension .geom. These files contain everything in their ASCII cousins, but also additional information, such as the channel information found in a .channels file (described in section 4.4 below). A .geom file can also hold this information for any number of surfaces, thus allowing the representation of a very complex geometry in a single file.

Rules for .pts files:

  1. ASCII file;
  2. Each line contains one triplet, ordered as x, y, and z values; one or more spaces between values (assumed to be reals);
  3. Each line may also contain a group number as a fourth element;
  4. order of points in the file is the implicit order of the nodes in the geometry, and the ones used by the .fac file.

Rules for .fac files:

  1. ASCII file:
  2. Each line contains a triplet of integer values pointing to the nodes of the geometry; node numbers begin at 1 not 0!
  3. Order of triangle vertices (nodes) is not strictly controlled, however, it is recommended that they be ordered such that they represent a counterclockwise sequence of vertices when viewed from the outside of the triangle.
  4. Each line may contain an optional fourth values which is the group number for the triangle.
  5. Order of triangles in the file is not meaningful except for internal bookkeeping; user will notice this only when a triangle is picked for interrogation.

To facilitate the creation and management of .geom files, there are programs which convert between the two formats. The simplest of these is called gconvert and carries out conversions in either direction, either by leading the user through a dialog or via a control file containing the names of the files to be converted. With gconvert it is possible to construct any .geom file from sets of .pts/.seg/.tri/.tetra and .channel files. At present there is not documentation for gconvert, it was only written as temporary fix...three years ago. See Rob MacLeod ( for details.

In map3dgl the -f option determines directly in which files the geometry is to be found. Starting from the filename that follows -f, which may or may include a file extension, the program looks for all possible candidate geometry files and queries the user for resolution of any ambiguities. Thus if the program is called with the argument map3d -f myfile, map3dgl3d looks for myfile.geom, myfile.pts, myfile.tri, etc, and tries to resolve things so that a geometry description is found. This can be controlled to some extent by typing the geometry filename with an extension according to the following rules:

Extension Effect
none look for .pts and .geom and if both are presents, ask user which to take
.pts take only the .pts file and ignore any connectivity or .geom file
.fac take .pts and .fac and ignore any .geom files present.
.geom take the .geom file and ignore any others present.

A further way to read geometry into map3dgl is to use the geometry filename contained within the .data file that contains the potentials. This requires that the .data file be created with the geometry filename listed; adding this after the fact is difficult. Even if a geometry filename is found in the .data file, it can be overridden by the geometry file name specified in the argument list of map3dgl.

4.3 Potential and gradient data files

4.3.1 .pot and .grad files

The scalar data values that are assigned to the points in the geometry are input via .pot files, while vectors are input via .grad files. Scalars are ordered in the same way as the node points as a simple one-to-one assignment is performed, although a channels file can be used to provide indirection (see section 4.4) . Vector information is self-contained since it is expressed as start points and vector components in 3-D coordinates and may, therefore, be ordered in any way the user wishes.

The rules for .pot files are:

The rules for .grad files are:

A set of files that contains a time sequence of data should have filenames of the form base-filename001 to base-filename NNN, with the numeric suffix (NNN) being a three-digit value, which can run in any regular increments. For example, pot-file001.pot, pot-file005.pot, pot-file009.pot, pot-file013.pot, ...

4.3.2 CVRTI data (.data) format files

The newly developed standard data files (.data files) are capable of holding not only the scalar and vector data found in the older .pot and .grad files, but also links into existing ``pak-tape'' files, the name of the suggested geometry files, and various other bits of information that could be useful to map3dgl.

There are some concepts of the data file structure that should be understood to appreciate the different modes of operation described in section 2.1.

Series or runs
By a series or run, we refer to the basic structural entity of a .data file: .data files contain a header, and then runs of data. Data within a run belong together, typically because they have been recorded at the same time. A run of data is often multiplexed, i.e., it has numerous leads of data, potentially over numerous surfaces. If map3dgl is launched without information specifying the run number, a window will appear containing a list of the titles given to each of the runs of data in the .data file. The user then selects the run that should be displayed. The desired run number can also be appended to the .data filename with a ``@'', as in
                map3d -f
which selects run 2 from the .data file
Links to geometry
The links between the leads of data in the .data file and the nodes of the surface[s] over which they are displayed is established via channel array information, which is often stored as associated scalars to the nodes of the geometry file (see documentation on Geometry and Data files elsewhere). Section 4.4 contains more information on channels and leadlinks arrays.
By frames of data, we mean instants in the data representing single moments in time. For each frame, there is a map. If map3dgl is launched without specific information on which frames are to be displayed, a window then pops up containing the power curve for the entire run and the user sets both the start and stop frames and then clicks on ``accept''. To explicitly specify frame numbers, the third form described in section 2.1 must be used to launch map3dgl. For example
        map3d -w -f geomfile.geom@1 -p -s 10 130 -i 2
specifies that surface 1 from the geometry file geomfile.geom should be used to display frames 10 to 130, taking every second frame, from run 2 of the .data file

4.4 Leadlinks and Channels

4.4.1 Description of leadlinks and channels information

Leadlinks and channels files, and the arrays they contain, are identical in structure, but not in function. A program may require both, either, or neither of these, depending on the structure of the data files and geometries. The basic function of both leadlinks and channels information is to offer linkages between recording locations and the data that is to be associated with those locations. One , leadlinks, describes the connection between ``leads'', a measurement concept, with ``nodes'', and geometrical concept. The channels information, on the other hand, links the nodes to ``channels'' of data in a data file. Or, in more detail,

The leadlinks information is primarily used to identify, and give numbers to, measurement leads within a set of nodes that make up the geometry. This can mean selecting a subset of the nodes, as would be used, for example, to identify the actual recording sites from a set node locations over which the data were interpolated. Leadlinks could also be used to renumber all the nodes of the geometry to reproduce the experimental setup.

In the leadlinks array, each entry refers, by its location in the array, to a particular lead; the array value at that location gives the number of the node in the geometry file to be associated with this lead. For example if lead 4 has a leadlinks entry of 22, then node 22 in the geometry will be displayed with a ``4'', not ``22'', when lead markings are selected in map3dgl.

The most recent change in the leadlinks structure has been the addition of the leadlinknums array, which has the same structure as the leadlinks array, but contains the actual lead number associated with each lead. This arrangement became necessary when there were cases of jumps in the lead numbers, for example when a lead is corrupted or damaged in recording, it is not available later, and should not be included in the list of leads of a display. Since the leadlinks array works purely by location in the array, we needed another level of indirection.

Hence we have the situation of a lead number K actually being called lead number L, pointing to node number M in the geometry. The map3dgl program now handles this additional indirection, and other programs are bound to follow suit as the need arises.

The channels information is used to relate nodes in the geometry to locations in the data file(s). For example, if we wish to find the data associated with node K in the geometry, then the value in location K of the channels array (channels(k)) will point to the correct channel in the data file.

Note that channels arrays are used at the time the data is loaded into the internal data storage arrays! The most frequent use of channels information is to unpack multiplexed data. This data come from input files with an inherently different structure in terms of geometry nodes and need to be sorted so that their spatial arrangements are known. The channels array provides the information needed to perform the sorting. An example would be data collected from multiple needles. The data are stored in a block, with no preconception of what spatial relationship individual electrodes on those needles might have to one another. These relationships can only be fixed by the geometry information of where each electrode was located and what surfaces these locations are grouped into. To untangle this mess, a separate channels array is used for each surface, to point to the measured data values which belong to that surface, and to determine which data value is associated with each node location.

If data and geometry nodes match one-to-one, there is no need for a channels array. In programs like pscont, on the other hand, a channels array is almost always a necessity because of the mapping from a three- to a two-dimensional geometrical representation. There are single points in the three-dimensional version of the geometry that have two equivalent points in the two-dimensional version of the geometry used for map display. Hence, pscont stores those channel filenames internally and associates then to a particular choice of plot geometry. In map3dgl, there are many cases in which channels information is not needed.

The figure 1 shows an example of lead and channels information layered one on top of the other. See the figure caption for details.

Figure 1: Example of the indirection possible in map3dgl through the use of leadlinks leadlinknums, and channel information. Lead number 4 points, via the leadlinks array to node number 22. This, in turn, points via the channels array to location 92 in the multiplexed data buffer, which causes the value at location 92 to be loaded into location 22 in the model_pots array. In a separate, leadlinknums array, shown below the leadlinks array, the entry in lead 4 says that that lead should actually be called lead 6, and so any labeling of the leads should reflect this additional indirection.
\begin{figure}\centerline{\epsfig{file=figures/map3d-indirection.epsf,height=4in}} \end{figure}

4.4.2 Source of leadlink and channel information

The source of both channels, leadlinks, and leadlinknums information can be either the geometry (.geom) file or the data (.data) file, or two explicit files, called ``leadlinks'' and ``channels'' files, which are described in the next sections below. The .data and .geom files

Information for the channels array is stored as an associated scalar with the data information in the standard .geom files. At present, there is no leadlinks array stored in the .geom file but this could change at an time. The .leadlinks file

A leadlinks file is an ASCII file, the first record of which contain a line nnn leads, where nnn is the number of leads to be described in the file (and also one less than the total number of lines in the file). Each following record contains two integer values:

  1. the first number is the number of the lead, as it should appear in any labeling of the lead, the leadlinknum information.
  2. the second entry in each row is the leadlink information for that lead.
For example, the file for a surface which reads:
    32 Leads
    1   1   
    2   42  
    4   31  
    7   65  
    .   .   
    .   .   
    .   .   
    32  11     <---- 32nd entry in the file, at line 33 of the file.
indicates that there are 32 leads to be linked, and that lead 1 is called lead 1 and is node 1 in the geometry file. Lead two is at node 42, but lead 3 is called ``4'' and is found at node 31. Likewise, lead 4 is called 7, and is located at node 65, and so on, up to lead 32, called 32, at node 11.

Nodes listed in a leadlinks file passed to map3dgl with the -l option can be marked either with coloured cubes (spheres) or labeled with the numbers of the lead or the number of the corresponding node, depending on the setting of the ``Toggle node display'' menu item. When we mark all the nodes, by selecting ``Mark nodes with node numbers'' in the ``Toggle node display'' menu, all nodes are labeled, not just those which are leads.

Likewise, the nodes at which the maximum and minimum potential values are found to occur, and the location used for the scalar lead display (see section 5.2) can be marked. The .channels file

A .channels file is an ASCII file, the first record of which contain a line nnn nodes, where nnn is the number of nodes to be described in the file (and also one less than the total number of lines in the file). Each following record contains two integer values:

  1. the first number is simply a running counter that indicates which node number the second values in the row is
  2. The second element in each row is the channel number for that node.
For example, the file for a surface which reads:
    352 Nodes
    1    123
    2    632
    .    .
    .    .
    32   12
indicates that there are 352 leads to be linked, and that the data value for the first node is located at location 123 of the data file. For node 2, the data value is to be found at location 632, and so on.

4.4.3 Display of lead/channel information

With so many options for defining a node, and the lead or channel associated with it, there is room for ambiguity in the numbers that appear in a display next to the nodes. The conventions used in map3dgl are show in the following table:

Node number display conventions
Lead Marking Lead/channels file present
  None Channels Leadlinks
Node numbers same as in geometry files, starting at one for each surface unaffected unaffected
Lead numbers2 same as in geometry files, consecutive over all surfaces channel numbers leadnumber from leadlinks info
Data values potential value potential value potential value

4.5 Landmark files

These files contain what I refer to as ``landmarks'' on the surface(s) of the geometry, whose primary purpose is to provide visual references for orientation when viewing the map3dgl display. Initial use was primarily for coronary arteries, but the idea has been expanded to incorporate a number of different orientation landmarks. The original coronary artery class of landmarks requires only that each can be described as a series of connected points, with a radius defined for each point. The coronary landmark is then displayed as a faceted ``pipe'' linearly connecting the points at the centre, with a radius, also linearly interpolated between points, determining the size of the pipe. The landmark file can contain numerous, individual segments of such pipe-work, each of which is drawn separately.

Other classes of landmarks are described below, but all of them can be described in a file with the following general format:

Line number Contents Comments
1 nsegs number of landmark segments in the file
2 1 type nsegpts seglabel segment number (1), type, number of points, label_number
3 X, Y, Z, radius point location and radius of point 1
4 X, Y, Z, radius point location and radius of point 2
. . .
. . .
nsegpts + 2 X, Y, Z, radius point location and radius of last point in segment 1
. 2 type nsegpts seglabel segment number (2), segment type, number of points, and label
. X, Y, Z, radius point location and radius of point 1
. X, Y, Z, radius point location and radius of point 2
. . .
. . .
. X, Y, Z, radius point location and radius of last point in segment 2
. . .
. . .
. . .
. . .

The landmark types defined to date are the following:

Name Graph. object Description
Artery faceted pipe a coronary artery/vein segment
Occlusion coloured sphere an experimental occlusion that could be open and closed
Closure coloured sphere a permanent occlusion that cannot be opened
Stimulus coloured sphere a stimulus site
Lead coloured sphere a particular electrode or lead location
Plane rectangular parallolopiped a cutting plane through the geometry
Rod lines rod inserted into needle track to digitize needle electrode locations.
PaceNeedle sphere location of a pacing needle entry point
Cath facetted pipe location of catheter in a vessel
Fiber arrow local fiber direction indicator
RecNeedle sphere location of recording needle entry point
Cannula tube? coronary vessel cannulus

Specifying snare, closure, and stimulus requires a single point in the landmarks files, and the resulting sphere is coloured according to a set of values defined in the drawsurflmarks.c routine. At present, the values used are:

Occlusion cyan
Closure blue
Stimulus yellow

and they are not (yet) adjustable by the user, except by using the ``regular'' trick of playing interactively with the colour map with the cedit program.

To specify a plane landmark requires three ``points''

Point X,Y,Z Radius
1 First point of plane Radius of the plane
2 Second point of plane Thickness of the plane
3 Third point of plane not used
The plane is drawn as a polygon with a number of sides controlled by a program variable. Contact Rob MacLeod ( any changes in the way the plane is drawn. Filename conventions:

The standard extension of a landmark file is .lmarks and the filename is specified by the -lm parameter for each surface. Control of landmark display:

Landmark shading can be altered with some cheap lighting tricks to give a variety of different appearances. These tricks are cheap in the sense that they were relatively easy to implement but also in that they require minimal computational overhead. To play with the display options of the landmarks, select the ``Drawing Landmarks'' menu option, then one or more of the lighting models and colours. The options are set up as follows:
Draw default shaded landmarks:
this is the same mode as was used previously.
Draw eye-point shaded landmarks:
this is the simplest of light models in which the colour shading varies with angles away from a line between an imaginary eye location and the center of the object. Use this,together with the ``Select eye-point location'' item to give a different look to the landmarks.
Landmark shading colour:
This selects the colour used to draw the landmarks. There are only a few basic colours implements at the moment, but this can be expanded at any time. Note that by interactively altering the colour map, different colours can be tested, but only with major limitations since the colour intensity varies with the lighting model.
Draw mesh landmarks:
This mode is primarily for debugging the definition files for the landmark files and shows each landmark in its elemental segments, with labeling of each segment.
No landmarks:
As before, this option turns off display of the landmarks.
Draw plane:
switches the display of any landmark planes in the landmark files on and off.
Plane colour:
selects the colour to be used to draw the landmark plane.

5 Display features

5.1 Multiple surfaces

The idea of map3dgl has always been to display multiple sets of data on multiple surfaces; the limitation has been how much flexibility to included into a single invocation of the program. At present, map3dgl will handle either multiple surfaces in a single window, or multiple windows with a single surface in each, but not multiple windows with more than one surface in each. Selecting which surface to control:

To control the display of each surface, be that a surface in its own window or sharing a single window with other surfaces, that surface must be selected. Normally, selection occurs by using the up and down arrow keys to select the desired surface. Hence there are two basic modes for surface control: single surface and all surfaces--all changes made will apply according the mode (and the single surface that has been selected). When there are multiple surfaces and multiple windows, then all surfaces are usually drawn all the time; hence it is not obvious which surface is selected. The only good way to tell is to use the up/down arrows and watch the window from which the program started. It will indicate which surface is selected (or if all surfaces are selected). With any single surface selected, simply moving the mouse to the associated window will select that surfaces. This my moving up/down arrow keys and/or moving the mouse, it is possible to select any single surface. Pressing the up arrows often enough eventually selects (and displays if there is only one window) all surfaces. Control parameters:

There are an ever growing number of parameters that can be altered on a surface-by-surface basis. Some of the more important (and stable) include the following:

of points, mesh, potentials, vectors, etc, can all be controlled individually by using the appropriate function key (see 6.2.1).
Lead markings:
can also be set for each surface, using the menus. Note that there is some intelligence in reconciling potential conflicts of the lead marking, e.g., marking the points with node numbers and data values.

Since this level of control is provided for each surface, it is possible to have points showing on one surface, mesh on another, and rendered potential shading on a third, and so on.

5.2 Scalar display

When the -t trace-lead-num option is used, data from the incoming frames of map data are collected as a time sequence and used to construct a scalar plot of a the lead selected by the value of trace-lead-num. The value of trace-lead-num is interpreted in different ways depending on whether leadlinks information (see section 4.4) is present: if there is leadlinks information, then the lead number is passed through this indirection before being connected to a node in the geometry/data. If there is no leadlink information, then lead number = node number.

Figure 2 shows the layout and labeling of the scalar window. Font sizes adjust with the window size and the type of units may be explicit if the .data files contain this information.

Figure 2: Scalar window layout. Use the left mouse button to grab the cursor and move it to any location on the time axis. Likewise, clicking at any point on the time axis will jump the cursor to the point, and adjust the frame number of the data displayed in the other windows.
\begin{figure}\centerline{\epsfig{file=figures/scalar.epsf,width=6.5in}} \end{figure}

An easier way to control the display of a scalar lead information is to let the program start without a lead selection and then choose a lead interactively. To do this,

  1. Move the cursor into the window containing the surface you would like to pick a scalar lead from.
  2. Select ``Pick mode'' from the main menu, then ``Pick scalar lead'' from the ``Toggle Pick Action'' sub-menu.
  3. The cursor should now turn to a cross hairs spanning the whole screen.
  4. Move the cursor over the node you would like the scalar lead from. Note that rotations, translations, and other object manipulations are all still possible even though you are in picking mode. Only the function of the left mouse button is different.
  5. Select the node by clicking on the left mouse button. The cursor should change back to the arrow.
  6. An outline window should appear at the cursor tip, allowing you to place and size the scalar window as desired. Move the mouse to locate the window, then anchor it with a push of the left mouse, hold the button down and drag it to size the scalar window.
  7. The scalar window can now be used to select time instants and scroll through the data, as described in section 5.2.1 below.
  8. Select pick scalar a second time or ``no scalars'' while in pick mode, cancels the original request.

Note: there is an option in the pick menu that toggles between each new scalar making its own window, and each new scalar replacing an existing one--i.e., there are two modes now, one in which each surface has one scalar and another in which there can be as many scalars as desired.

The format of the scalar display is fairly simple and self-evident, with a red vertical bar moving along the time axis as the frame number is advanced. The time axis is derived from the frame numbers of the files, not simply the number of files which are read in, i.e., if frames (or pot file number) 10-20 are read in with an increment of 2, then time will begin at 10, and go through 12, 14, 16, 18 and end at 20, and will not begin at 0 or 1 and go to 5 (the number of frames of data actually read). This is also reflected in the display since the time axis always begins at 0.0; data from later in time appears shifted to the right, to a degree determined by the starting frame number.

5.2.1 Managing the scalar window

In order to facilitate rapid movement through large datasets, the user can control the frame number being displayed by interacting with the scalar window itself. If the user moves the cursor to the scalar window and pushes the left mouse button, the vertical time bar will jump to the nearest sample to the cursor location. The user can then hold the left button down and slide the time marker left and right and set a desired frame. Once the mouse button is released, the map display is updated. Movement on a frame by frame basis, via the left and right arrow keys, works as it always has. The only other command allowed when the cursor is within the scalar window is the ``q''-key , to shut down just the scalar window. Any other attempt at input will cause the bell to ring and an error message to be printed.

5.3 Data Scaling

Scaling is performed in a number of different ways in map3dgl, and is applied to potential and current data, both in the contour lines constructed from potential distributions, and in the colours used to display shaded and contoured potential data and current vectors. The type of scaling depends on the following parameters set by the user interactively via the mouse menus (right mouse button) or from the .map3drc file at startup:

Shade type
This item selects the type of shading done when potential data are rendered. Gourard shading generates colours which represent a bilinear interpolation over each triangle area. For flat shading, each triangle is shaded in a single colour which represents the mean potential value of the three vertices.

# Shades/Contours
This menu choice allows the user, via a sub-menu, to set the number of shades of colour that are used for shaded renderings, or the number of lines to be used in contouring, of the potential data. The user selects amongst a number of fixed values.

Colour Map
There are five different colour maps presently implemented with every chance of more to come. This menu item allows the user to select which colour map is to be used. The choices currently implemented are:
Red (+) to Green (-)
Largest negative value is coloured bright green, dark grays are for the region near zero, and positive values appear red.

Red (+) to Blue (-)
Colours range from dark blue (for negative extrema) through greens (near zero) to Red (positive extrema).

Red (+) and Green (-)
Red is once again positive and green negative, but there is no gradation with value, i.e., this is a colour map of only two colours.

Black (+) to White(-)
Grey shades from black for small values to white for large ones.

White (+) to Black(-)
Grey shades from white for small values to black for large ones.

Scale Scope
The scope of the scaling determines which data are used to determine the extrema. In global scope, all the data in the entire dataset are used, even those not presently visible on the display. In local scaling, only the data presently visible are scanned for extrema. The user scaling scope uses the current user-selected values for maximum and minimum for the scaling (see -pl and -ph input parameter).

Scale Model
The scale model describes the way in which data are mapped to colours (or contours). The choices are: The linear model simply maps the data to a range of colours in a completely linear fashion, i.e., colour = K$ \phi$. In logarithmic and exponential scaling models, the full range of data are mapped to the colour range in a non-linear way. The logarithmic scaling highlights the lower level data values at the cost of poorer resolution at the higher levels i.e., colour = A log($ \phi$) + B and exponential scaling does the opposite, compressing the smaller levels and expanding the higher ones to span a wider colour range, i.e., colour = AeB$\scriptstyle \phi$. The two schemes with fixed numbers of contours, log/7-levels and log/13-levels both map the upper decade ( $ \phi_{max}^{}$ to $ \phi_{max}^{}$/10.) of the potential data range into a fixed set of logarithmically spaced values. These values are composed of a mantissa from the standard E6 (1.0, 1.5, 2.2, 3.3, 4.7, 6.8, and 10.) and E12 (1.0, 1.2, 1.5, 1.8, 2.2, 2.7, 3.3, 3.9, 4.7, 5.6, 6.8, 8.2, and 10.) number series, and an exponent such that the largest mantissa falls into the range 1.0 to 10. Hence as long as the extrema is known, it is possible to read absolute values from the individual contour lines.

Scale Mapping
There are several different ways to manage the way positive and negative data are treated in the scaling transformations in map3dgl. The symmetric scale mapping always sets the positive and negative extrema symmetrically: the larger (in the absolute value sense) determines both maximum and minimum data values. In the separate scale mapping, on the other hand, the positive and negative extrema are treated completely separately: `half' the colours (and contours) are used for the positive values, half for the negative values. This is equivalent to producing maps with the same number of contours for both positive and negative values, even when the positive data have a different absolute maximum value than the negative data. The third scale mapping is the simplest, true mapping, in which the data are used as they come: half the colours are used for data below the mean, half for data above the mean. True mapping is assumed for any display of current vectors since the magnitude of the vector is used to determine its colour.

5.4 Potential Reference

Related to scaling--and controlled from the same menus--is the reference potential used for the displayed data. By default, the potential (or any other scalar) values are assume to already have the right reference and nothing is done to change that. The user can, however, select a new reference, and then subtract that reference from all signals in the surface. There are at present two types of references the map3dgl supports: Mean as reference:

When selected from the Scale Scope or Scale Mapping menus, subtracting the means results in the average value for each instant in time over each of the surfaces being subtracted from the scalar data. This is equivalent to taking the (square root of the) power curve and using that as the reference potential. The control for this feature is a toggle that is managed from either the Scale Scope or the Scale Mapping main menus. Selected lead as reference:

It is also possible to select a single channel of data and use that as the reference signal. Control of this happens in two stages, first the user must select a channel to use as the reference; the pick mode called ``Pick reference lead'' performs this operation. The second component is to apply that reference to the rest of the signals. Control for this is in the Scale Scope or the Scale Mapping main menu. Selecting a new reference lead works properly, i.e., the effect is not cumulative but first restores the data to the original state, than applies the new reference.

5.5 Clipping Planes

The use of clipping planes is one feature of map3dgl which is undergoing constant development. At the moment, we have the capability of setting a single cutting plane at a point perpendicular to any of the six major axis of the 3D space. Once set, a clipping plane may be interactively shifted along the axis so that different regions of the data can be visualized. A second method of clipping the data is to translate the entire dataset so that it impinges upon one of the sides of the cubic bounding space (frustum). By moving the data, eg., forward until it meets, and is clipped by, the front plane of the frustum, then sliding a clipping plane along the same axis from the back towards the front, a slab of data space can be isolated for viewing. Both of these operations require use of the dial box (see section 6).

A further degree of freedom with the clipping planes is whether the plane moves with the data during rotation and translation of the geometry, or whether the clipping planes stays fixed (with regard to the screen) while the data rotates and shifts through it. The Clipping Planes menu offers the user a choice between locked mode, in which the clipping planes rotates with the geometry, and unlocked mode, in which data moves through the fixed plane, i.e., clipping plane and geometry are unlocked.

5.6 Perspective view and depth cueing

In map3dgl the default view mode is orthogonal and there is no depth cueing. Both can, however, be switched on at the user's request. To toggle between orthogonal and perspective views, use the o-key. Currently, the modeling transformations (rotation, translation, scaling) are all reset when you switch modes, but this will hopefully be handled better in the future. Note that in perspective mode, scaling and translation can be used to change the degree of perspective in the display. By moving the object further away (with the translate dial) and then increasing the scaling, the degree of perspective is reduced, while by pulling the object closer and reducing the scaling, the opposite occurs. The use of the bounding cube (see next section) can serve as additional visual feedback on the spatial definition of the object in the display.

Depth cueing works by reducing the intensity of lines and points in the display as a function of the distance from the viewer (eye location). The distance from objects in the display to the viewer is stored in a separate ``z-buffer'', which has a value for each pixel in the screen. Depth cueing is useful when viewing geometries or objects which would otherwise be drawn with constant colour, but is misleading and invalid when the colour is already being used to convey other information (e.g., colour-coded contour lines). Hence, use depth-cueing at your own discretion. At the moment (February 21, 2002), depth cueing is only supported for drawing points and lines in map3dgl. It can be combined with perspective view to get fairly realistic images of three-dimensional objects which are drawn as a wire mesh or as points.

To control depth cueing, use the d-key to toggle, and two menu items in the ``Set Clipping Plane'' menu to tune. The menu items ``Z-buffer near'' and ``Z-buffer far'' allow the lower right (clipping plane) dial to be used to move the front and back (near and far) z-buffer planes either closer to (counterclockwise dial rotation) or farther from (clockwise rotation) the viewer. The trick to using this feature effectively is to note that when the near z-buffer plane moves through an object, ever pixel that is in front of it is drawn at full intensity (no depth cueing). The far z-buffer plane has the opposite effect in that as it moves forward through an object, pixels located behind it are drawn at minimal (often black or background) intensity. The region between the two z-buffer planes is spanned by the range of colour intensities which are set in the program (currently 20 linear steps span the full range of each colour). Note that this is not the same effect as moving the clipping planes around since the change in intensity is gradual, and the result depends on which z-buffer plane is used. If the two z-buffer planes meet, the object becomes invisible (for obvious reasons), a situation which map3dgl permits, but hardly encourages.

5.7 Bounding cube

If desired, a three-dimensional bounding box can be drawn around the object(s) in the display. This box can be useful when viewing in perspective mode, and may even add a decorative touch to some images. To remove it, use the ``Bounding Box'' option on the menu pull-down menu. Any suggestions for enhancement of this sort of thing are welcome!

6 Control of map3dgl

6.1 Menus, keyboard mapping, mouse and dial function

Control of map3dgl is by the keyboard, mouse, and dials. Many option are available via the menus initiated with the right mouse button, while others can be activated or toggled with single keystrokes. Variable (non-binary) adjustments usually occur with the dials, if they are present, or by repeating keystrokes. Below are tables of all the current control devices and their function. When the program launches, the user sets one or more windows which can be resized and moved at any time. When launching the program with the -b option, the resulting borderless window(s) can still be moved using the alt-key together with the right mouse button.

6.2 Feedback Reporting Level

In order to control the amount of printed feedback map3dgl provides (which is posted in the window from which the program was launched), the user can select a value between 0 and 3 from the a sub-menu of the main menu titled Report level. The settings and level of output are as follows:

Report Level Types of output
0 minimal output -- just changes in status
1 report extrema
2 report some warning messages
3 debug mode

6.2.1 Keyboard controls

Each key of the regular keyboard, the function keys, and the keypad are mapped to some function of the map3dgl. Most keyboard keys serve as toggles to change between a mode being on or off, i.e., ``m'' toggles the display of the geometry mesh. A list of the keyboard keys and their functions is shown in table 1; table 3 describes the action for each of the function and arrow keys, and table 4 the actions of the keypad keys.

Table 1: Keyboard controls in map
Regular keyboard
A-key Switch colour table
B-key Toggle clipping plane
C-key Toggle contour draw
D-key Toggle depth cueing
E-key Toggle backfacing visibility
F-key Shift focus to next window
G-key Toggle display of gradients (currents)
H-key Set the location of the video box
I-key Toggle between display of all or single surfaces
L-key Toggle display of leads in leadlinks file
M-key Toggle mesh draw
O-key Toggle ortho/perspective views
P-key Toggle point draw
Q-key Quit picking mode (Escape quits program)
R-key Reset to startup conditions
S-key Toggle shaded potential data draw
T-key Whatever Rob is currently testing
U-key Toggle locking of clipping planes
V-key Toggle video mode
W-key Write an image to a file
X-key Draw axis
Z-key Rotate about z-axis in steps
Escape Quit the program

6.2.2 Dial box

Perhaps the most intuitive control of map3dgl occurs via the dial box. This device allows ``analog'' control over any GL application that makes use of dial input by allowing the user infinite control over any control parameter linked to the dials. In map3dgl, the primary continuous interaction with the program is in placing the object in the display, choosing the viewing angle and the scale factor, and adjusting the clipping planes. Hence these functions are mapped to the dials, as described in table 2 and figure 3 below.

Note that all rotations via the dial box are relative to the screen coordinate system. This system has the x-y plane aligned with the screen, the x-axis pointing from left to right, the y-axis from bottom to top, and the z-axis pointing away from the viewer, perpendicular to the screen. One can picture the rotation dials as being attached to the positive ends of the three axis. See figure 3 for a description of this.

Table 2: Dial controls for map3dgl
Dial Box Mouse Control
Dial 0 (Bottom left) Scale display Left Button Rotation/picking
Dial 1 (Bottom right) Clipping/z-buffer Middle Button Image scaling
Dial 2 (2nd row left) Z-rotate Right Button Menu selection
Dial 3 (2nd row right) Z-translate    
Dial 4 (3rd row left) Y-rotate    
Dial 5 (3rd row right) Y-translate    
Dial 6 (top left) X-rotate    
Dial 7 (top right) X-translate    

Figure 3: Dial layout for map3dgl. Rotation dials act as if they were attached to the ends of the main x, y, and z-axes, as indicated in the right hand panel of the figure.
\begin{figure}\centerline{\epsfig{file=figures/dials.epsf,width=4in}} \end{figure}

6.2.3 Keypad Control

Providing the computer has a keypad that GL recognizes, map3dgl now also supports a keypad interface to the rotation and translations that was previously only available through the dials, and to a limited extent the mouse. See the table 4 below for details of the mapping.

6.2.4 Mouse control

The mouse can be used for different purposes depending on the current mode. This is especially important when picking is selected. Note that the middle mouse button selects the most recently selected picking action, unless the ``Turn off picking mode'' option is selected in the ``Toggle Picking'' submenu. Figure 4 shows the various actions of the mouse buttons.

Figure 4: Mouse action for map3dgl. Mouse action of both the left and middle mouse buttons depends on the current mode. Picking makes intensive use of the mouse, as does moving the mouse into a scalar window.
\begin{figure}\centerline{\epsfig{file=figures/mouse.epsf,height=2in}} \end{figure}

Table 3: Control of map3dgl via the function and arrow keys
Arrow Keys Function Keys - apply to current surface
Left Arrow Key Rewind one image F1-Key Toggle point visibility
Right Arrow Key Advance one image F2-Key Toggle triangle visibility
Up Arrow key Advance one surface F3-Key Toggle potential visibility
Down Arrow Key Rewind one surface F4-Key Toggle current vector visibility
    F5-Key Toggle tetrahedra visibility
    F6-Key Toggle lead display
    F11-Key Toggle surface locking
    F12-Key Dump image to video

Table 4: Keypad controls in map3dgl
Keypad Keys
Keypad 4 Y-axis rotate, CW (left) Keypad 6 Y-axis rotate, CCW (right)
Keypad 2 X-axis rotate, CCW (down) Keypad 8 X-axis rotate, CW (up)
Keypad 7 Z-axis rotate, CCW Keypad 9 Z-axis rotate, CW
Keypad 1 Zoom down Keypad 3 Zoom up
Keypad 0 Shift clip plane Keypad . Shift clip plane
Shft-Keypad 4 -X-translation (left) Shft-Keypad 6 +X-translation (right)
Shft-Keypad 2 -Y-translation (down) Shft-Keypad 8 +Y-translation (up)
Shft-Keypad 7 -Z-translation (away) Shft-Keypad 9 +Z-translation (towards)
Plus key Increase movement Minus Key Decrease movement

When more than one surface window are used, certain manipulations apply to the window which currently has focus (the one in which the mouse cursor sits), while others may apply to all windows synchronously. Rotation and translation can apply to one or all windows (select which via the menu or F11 key), while scaling modes, colour maps, and frame numbers are applied to all windows concomitantly.

6.3 Frame contol

With the time signal (scalar) window, it is possible to move the frame counter with the mouse by clicking at a new location along the time axis or by clicking and dragging the vertical frame marker bar. Normally, this will control all surfaces at once, i.e., the frame counters are locked. It is sometimes useful, however, to unlock the frame marker and to this end, we have the main menu item ``Frame Control''. Likewise, it is often nice for the display to adjust the time value on the time series window to a new zero. This makes it easy to measure time durations from any point in the time signal. Finally, map3dgl assumes a default sampling rate of 1000 samples/s in the display; to change this, we have a submenu.

The options of the Frame Control menu are as follows:

Toggle frame lock:
which toggles the locking of frame numbers across surfaces. It will be marked if the surfaces are locked.
Reset time to zero:
which sets the time (but not the frame counter) to zero at the current position.
Set time step:
a submenu that adjusts the time step between frames to a value other than 1.

The most frequent use of the frame locking control is to time align data from mutliple time series. The steps for this are:

  1. Select the Toggle frame lock item and make sure the frame count moves independently for each surface.
  2. Move the mouse into each time series window and select the time point to align; continue until all signals are properly aligned.
  3. Select the Toggle frame lock item again and tis time, make sure the frame count are locked again.

To add this information to a map3dgl shell script, do the following:

  1. After aligning all the frame markers, move frame marker to start frame of the desired time window. This will not be the same frame number on all surfaces (unless you did not have to align in the first place),
  2. Write in the script for each of the associated surfaces, the start frame number using the -s option, e.g., -s 24,
  3. Now move the (locked) frame marker to the end of the desired time window,
  4. Finish the -s arguments for each surgace with the last frame from each, e.g., -s 24 327.

7 Picking mode

By ``picking'' we mean selecting some piece of the display in the current window using the mouse (with buttons). In map3dgl there are a number of different pieces that can be picked, nodes, triangles, scalar leads, etc., all of which either return some information, or affect the display, or even the geometry of the display. To select what is to be picked, use the main menu and choose ``Pick Mode'' and then one of the choices in the ``Toggle Pick Action'' submenu. Below we describe each of the picking option in more detail.

Note that after picking, the program remembers what the last pick mode was and allows you to instantly go back to that pick mode by clicking the middle mouse button. To have the ``normal'' function of the middle mouse button restored, select ``Turn picking off'' from the ``Toggle Pick Action'' submenu.

To adjust the size of the picking window, the keypad plus/minus keys can be used, much as they are to alter the sensitivity of the dials to rotation and translation. Experience suggests that a larger window makes triangulating (selecting nodes) easier while a small window makes selecting triangles (to remove or flip them). Each picking mode maintains its own picking window size so that changes affect only the current picking mode.

7.1 Picking Nodes

This mode simple returns the location, in the same coordinates in which the point data was originally read into the program (the points are shifted to keep the object at the center of the screen's coordinate system).

7.2 Picking Triangles

When simple triangle picking is selected, the node numbers of each of the vertices of the triangle are displayed, along with the coordinates of the nodes at those vertices.

7.3 Triangulating

You can edit the triangulation of the mesh by selecting the ``Triangulate'' option from the ``Toggle Pick Mode'' submenu. In this mode, the left mouse is used to select the nodes that you wish connected into a triangle. Note that the cursor changes each time you select a valid point (see figure 5). If there is no change,then you either hit no points, or two points. Adjust the display, or the sensitivity of the picking window (keypad plus/minus keys) and try again. The window from which map3dgl was launched will tell you more, and on the Indigo(s), sound effects provide audio feedback.

Figure 5: Triangulation modes and cursor changes. Before picking the first point of the triangle, the cursor is a short cross-hair. After successful picking of the first point, the cursor gets a horizontal mark (one side of the triangle) added. Selecting the second point adds another side to the triangle and picking the third point returns to the original cross-hair. Always pick in a counterclockwise pattern as seen from the outside of the surface for proper triangle orientation. The middle mouse can be used to remove a triangle from the mesh.
\begin{figure}\centerline{\epsfig{file=figures/triangulate.epsf,width=\columnwidth}} \end{figure}

Pushing the middle mouse button selects the nearest triangle and kills it, removing it from the list.

Files with the latest version of the connectivity are updated each time you leave triangulate mode, which you can do by either hitting the ``Q'' key or selecting ``Turn picking off'' option. The filenames are created in a random fashion and are (optional) removed when you end the session and save the latest version of the geometry in a file of you choice. When you go to exit map3dgl, you will be asked for the basefilename into which you wish the updated version of all surfaces (points and connectivities) to be stored. At the moment, these files are .pts/.fac files, which can easily be converted to .geom files if needed.

7.4 Triangle flipping

Often it is necessary to know the orientation of the triangles in the geometry. While this can be computed, there remains a 180-degree ambiguity as to which way the normal points. To resolve this, triangles nodes should be ordered in a counterclockwise direction as viewed from the ``outside'' of the surface to which the triangle belongs. This convention is used by GL to decide which triangles to show in ``hide backfacing triangles'' mode (which you can toggle with the E-key in map3dgl). Unfortunately, it is not always possible when constructing geometric models to tell which way the triangle is to be viewed -- this is still something humans do better than computers -- and so we often need to edit a geometric model so that the triangles are 'flipped' the right way. Hence, the ``Flip triangle'' option in the ``Toggle Pick Action'' submenu.

To check a model for correct triangle orientation and flip the offending triangles, select ``Flip triangle'' from the ``Toggle Pick Action'' submenu. The cursor will change shape (to a cross-hairs with triangle around it) and map3dgl will go into ``hide backfacing triangles'' mode. This means that only the front-facing triangles are drawn and the holes indicate which triangles need flipping. Then the cursor in each triangle you want to flip and hit the left mouse button. If you were successful, the triangle will fill in.

This option, like triangulating, produces a new connectivity file, which is saved temporarily in a random filename each time you leave triangle-flip mode. When the program finishes, you will be prompted for the base filename of a new set of points and fac files, thus preserving the original files for later use.

8 Editing Geometry

map3dgl provides a number of tools for editing the geometry at the heart of the display and also saving those changes in new versions of the geometry files. An example of this is described in the previous section 7.3 for altering the node connectivity. Other examples include the ability to apply the current viewing transformation to the geometry and save the result, typically for use in another graphics program (see section 8.1).

8.1 Applying transformations to data Background:

The idea of this feature is to be able to apply the same translations and rotations that are possible within map3dgl to the geometry data itself, and save the result for use elsewhere. The application was to produce 2D projections from 3D meshes and save the results in a projection that made it useful for 2D plotting programs like the infamous Z and less famous pscont. Usage:

Access to this command is from the menu, and requires the following steps:
  1. Bring up the geometry and select the surface(s) to be transformed.
  2. Rotate and translate until the desired project (view) of the geometry is fixed.
  3. Select from the main menu, the ``Rotation/Translation'' submenu, then the ``Apply Current Rotation to Geometry'' choice.
  4. This will cause only subtle visible changes on the screen, but if the axis are turned on (X-key), they will flip back to the default position, while the image of the geometry remains fixed, a sign that translations have been applied to the geometrical data and not just the transformation matrices maintained within map3dgl.
  5. When leaving map3dgl, make sure you check the window from which it was launched for the dialog that directs the saving of the transformed data in a new file. Choices include the geometry file form (.pts/.fac or .geom) (see section 4.2 for detail) and the basefilename, to which appropriate suffix(es) are applied to make the final filename(s).

9 Capturing images for animation, printing, or photos/slides

While screen images are lovely to look at, we need to be able to get the output from the screen to some transportable medium like paper, video tape, or film. This section describes some of the methods available for this process.

9.1 Postscript dump

With the addition of the psgl software (after significant modification), we are able to generate postscript files from map3d. There are still some restrictions and bugs in the system, but the essentials work and I encourage its use. To create a postscript file, run map3dgl and set up the view you want. Then push Control-Shift-PrntScreen, all at the same time. You will see some activity in the window you started map3dgl from, and the name of the output file will be listed somewhere in the output.

You can view the resulting postscript file with xpsview or gv and print it directly using the printit command. The psgl software produces proper postscript files, not images dumped to postscript so the output quality is excellent.

At the moment, the system defaults to producing true colour postscript but the option exists to convert the image to black lines (or gray shades) on a white page. To select this, go to the Shading/Contours menu or the Colour Maps menu and select Toggle Postscript background. Dashed lines are also printed by psgl, if you have previously selected the ``Dashed lines for negative values'' option in the Colour Map menu.

Problems and known bugs include the fact that numbers that a clipped out of the view, appear to the right had side of the image, overwriting themselves and some potentially useful stuff on the page. This is a bug on the underlying SGI software and I am still not clear what the best fix will be. At present, the only option is to edit the postscript directly. Another weakness is that postscript does not perform Gouraud shading and so coloured surface facets come out in a constant colour. This too, we are working on.

9.2 Image capture

There are no standard provisions in GL for generating output from the images generated by map3dgl. However, using an SGI utility (the same one used in the program snapshot) it is, in fact, possible to capture the contents of any area of the screen and save it as a file. Once preserved, this file can be viewed later, either by itself or as part of a sequence of images, with an animation program called movie. The contents of the file can also be converted either into other image formats for transport to other computers or conversion to Postscript for generation of hard copy.

To capture an image using map3dgl simply set the image you want to preserve and hit the ``w''-key. There will be a pause of between 5-30 s and then the workstation should beep and a line will appear in the control window telling you where the image has been stored. Filenames for image storage are generated automatically, using either the name of the geometry files (if no data is present), the name of the current potential (or gradient) file if data has been read into the program, or the filename specified with the -if option. Appended to this base filename are sets of four digits, denoting the frame number currently in the display, starting with ``0001''. Thus, for example, if the geometry files `daltorso.pts and daltorso.fac are being displayed, with data from the file daltorso-pot004.pot (which was read as the fourth frame of potential data), the first file produced would be daltorso004-0000.rgb. Note the .rgb file extension, standard for this sort of file, which is also referred to as an ``r-g-b'' file. If, on the other hand, the user started map3dgl with the string -if movierun, then the images files will be named movierun-0001.rgb, movierun-0002.rgb, etc,.

The screen area captured in this mode is the smallest rectangle that contains all the windows currently managed by the current invocation of map3dgl. This often requires with careful placement of the windows or setting the background window for the display to black or something that matches the background of the map3dgl display.

To view a file, or a set of files again on the screen, use the movie program, or the moviemaker. Simply call the program and append to it the name(s) of the files you want to view. To view a set of image files with a common root, e.g., daltorso000-001.rgb to daltorso000-010.rgb, use the calling sequence movie daltorso000-*.rgb. The result is an animated sequence, which can be stepped through, looped, or 'swung' back and forth. Once the images are loaded, control of movie is with the right-hand mouse button, pull-down menu. (See the man page on movie)

9.3 Conversion of image files

A frequent task when capturing images from the screen of a map3dgl session is the conversion of image formats from the native ``RGB'' mode of the SGI to something more portable. While the manual already describes the necessary steps in performing such conversions (see section 9), there is now a utility (a shell script, written by Rob MacLeod ( available to perform a variety of conversions in a flexible manner. The utility is called ``rgbto'' and it has the following usage:

  Usage: rgbto [-i -c -b -a] infilename 
   -i to invert image colors (default is to leave alone) 
   -c to leave in colour (default is black/white) 
   -b to use black and white (default is gray shades) 
   -a to product (Apple) pict file output (default is postscript)

The input is assumed to be one or more rgb files, and the output is either in postscript or pict format. The controls allow for the conversion from colour to grey shades or black and white (by a simple thresholding), as well as an inversion of the colours. It will accept more than one filename as input so that invocations such as, for example,

   rgbto -ca *.rgb
are possible.

9.4 Video output from map3dgl

With the frame buffer card in the SGI, and the video local area network (V-LAN) hardware, we can generate animation sequences on video tape from map3dgl. Control of the sequence, which may be a geometrical movement of objects in the display, or a series of sets of data on a stationary geometry (or both concurrently), is by the program animator described elsewhere. In effect, animator submits commands to the event loop of map3dgl and then captures the images from the GL window, moves them to the frame buffer, and then to video tape.

The most obvious feature of video recording in map3dgl is that the user can (actually must) select a window somewhere on the screen that defines what portion of the display is actually captured for video. If the -v option is used to launch the program, the user will see a red, rectangular box, together with a smaller, white text window with instructions. When the left mouse button is held down, moving the mouse now moves the rectangular video box; when the middle mouse button is pushed the location of the video box is fixed. The region within the innermost rectangle fairly accurately represents what will make it to the video screen. To relocate the video outline, return to the white text window and click the left mount button.

9.5 Additional video controls

With the separation of animation from video output and the desire to have thicker lines for photos without the video colour scheme, map3dgl now offers independent control of the various aspects of what was formerly video control. There is now a menu for video control, which includes options to turn the video window on (similar to the H-key), to toggle video colours (similar to the V-key) and to set the line width that is used.

9.6 Photographing from the Display

There are now too different ways to convert images from map3dgl (or any other output on the screen of the SGI terminal) into photographs or slides. The first, and most direct, is to set the camera up in front of the screen and blast away. The second involves grabbing images from the screen, converting them to a form understood by a Macintosh and then reading (and editing) them with an appropriate Mac program.

9.6.1 Direct photography from the screen

This process is simple and actually works very well (well enough to make the cover of journals) if you proceed as follows:

  1. Use a tripod and the motor driven Canon cameras (we have two identical cameras for this purpose).
  2. Square the display screen so that it is parallel to the wall, turn the intensity up to near maximum, and clean the paw prints from the glass with glass cleanser.
  3. Either use the remote plunger or the delayed self-exposure mechanism to work the shutter. Otherwise vibrations from your touching the shutter will blur the images. Select the 2-second delay for minimal waiting time between shots.
  4. Most pictures can be taken at the 2-second exposure time. Only with very bright images is it necessary to reduce the time and I have never needed a longer time.
  5. Select manual operation of the camera -- the light meter will be correct only for the case of a relatively bright, evenly illuminated image.
  6. Set the f-stop at least one full f-stop larger (smaller aperture) than what the light meter suggests for anything but bright images that are very consistently illuminated. I usually take three exposures starting at this setting and moving in full-f-stop steps toward larger f-stop values. In the case of contour line images, this usually means starting at 3.5 and shooting again at 5.6 and 8.3. For shaded images, the f-stop will be larger to start with and will depend on the colour scheme used.

Some tips that I have found useful for making photos are as follows:

9.6.2 Photography via the Macintosh

The method here is very similar to the image capture and conversion described in sections 9.2 and 9.3, except that instead of converting the image to Postscript, we convert it to a form that the Macintosh can read. The form we have used with best success so far is the ``pict'' file, a native Apple format that can be read and written by most Macintosh applications. To convert the .rgb file filename.rgb produced by snapshot into the pict file filename.pict, use the rgbto command with the -a option, e.g.,

         rgbto -a filename.rgb

Now the file is in a form which is directly readable by the Macintosh. The file still resides on the SGI but can either be copied to the Mac using ftp (accessible from either NCSA Telnet or Versaterm), or the Macintosh program fetch.

For more information on the hard- and software in the Graphics Lab, talk to Phil or see the documentation he is preparing on these facilities.

10 Script Files

Using script files to control map3d has numerous advantages, for example:

  1. complex layouts and specifications can be created and then held for later reuse,
  2. execution of the program reduces to a single word that starts the script,
  3. scripts are shell programs and can include logic and computation steps that automate the execution of the program; the user can even interact with the script and control one script to execute many different actions.

10.1 What are script files?

A script files are simple programs written in the language of the Unix shell. There are actually several languages, one for each type of shell, and the user is free to select. At the CVRTI we have decided to use the Bourne shell for script programming (and the Korn shell for interactive use) and so all scripts will assume the associate language conventions. The shell script language is much simpler to use and learn than a complete, general purpose language such as C or Fortran, but is very well suited to executing Unix commands; in fact, the script files consist mostly of lists of commands as you might enter them at the Unix prompt. Even more simply, a script file can consist of nothing more than the list of commands you would need to type to execute the same task from the system prompt.

10.2 How to make script files

Script files are simple text files and so are usually created with an editor such as emacs. You can, however, also generate a script file from a program, or even another script. But all script files can be read and edited by emacs and this is the way most are composed.

To learn about the full range of possibilities in script files requires some study of a book such as ``Unix Shell Programming'' by Kochan and Wood but the skills needed to make map3dgl script files are much more modest; any book on Unix will contain enough information for this. The instructions and examples below may be enough for many users.

Here are some rules and tips that apply to script files: Use a new line for each command

This is not a requirement but makes for simpler files that are easier to read and edit. If the command is longer than one line, then use a continuation character ``
'', e.g.,
         map3d -f geomfilename.fac \
               -p \
              -cl channelsfilename

Make sure that there are no characters (even blank spaces) after the continuation character!!! This has to be the most frequent error when the script file fails to run or stops abruptly. Make script files executable

Script files can be executed by typing . scriptfile but the simplest thing is to make then executable files so that they work simply by typing their names. To do this, use the chmod command as follows:
         chmod 755 script_filename Use the .sh extension for scripts

This convention makes it easy to recognize shell scripts as such, but also invokes some editor help when you edit the file in emacs. The mode will switch to shell (much like Fortran or C mode when editing programs with .f and .c extensions) and has some automatic tabbing and layout tools that can be helpful. Variables in scripts

The shell script is a language and like any computer language there are variables. To define a variable, simply use it and equate it to a value, e.g.,
         varname="some text"

Do not leave any spaces around the ``='' sign or the command will fail and set the variable to an empty string.

Once defined, the variables can be used elsewhere in the script as follows:

         map3d -f ${geomdir}/${geomfile} -p $datafile

The curly braces are required when the variable name is concatenated with other text of variable names but is optional otherwise. To concatneate text and variables you simply write them together (e.g., geomdir/geomfile.pts comcatenates the two variables with a ``/'' and the extension ``.pts''. Environment variables in scripts

All the environment variables are available and can be set in the script. For example:

sets the variable $mydir equal to the user's home directory. Likewise,
         export MAP3D_DATAPATH
defines and ``exports'' the environment variable used by map3d to find .pak files.

10.3 Examples

Below are some sample scripts, from simple, to fairly complex: Set the geometry, data, and window size and location

         map3d -f ${HOME}/torso/geom/dal/daltorso.fac \
               -as 100 500 300 700 \
               -p ${HOME}/maprodxn/andy3/10feb95/data/ \
               -s 1 1000 Set some environment variables, then layout the whole display

# A script for the spmag 1996 article
$map3d -b -nw \
	-f $basedir/geom/525sock.geom \
	-as 150 475 611 935 \
	-at 150 475 485 610 -t 237 \
	-p $basedir/data/ \
	-s 65 380 \
	-f $basedir/geom/525sock.geom \
	-as 476 800 611 935 \
	-at 476 800 485 610 -t 237 \
	-p $basedir/data/ \
	-s 65 380 \
	-f $basedir/geom/525sock.geom \
	-as 150 475 176 500 \
	-at 150 475 50 175 -t 237 \
	-p $basedir/data/ \
	-s 65 380 \
	-f $basedir/geom/525sock.geom \
	-as  476 800 176 500 \
	-at  476 800 50 175 -t 237 \
	-p $basedir/data/ \
	-s 65 380 A script with command arguments and built in logic

If you can figure this one out, you are a shell script guru! Running it is child's play and it displays epicardial and tank surface potentials for two different runs from any Andy2 tank experiment. The beats are time aligned based on the values in a separate parameter file that must exist for the particular experiment.

# Filename:
# Display epicardial and torso potentials from two runs of the same file
# using a standard layout and a file or parameters to feed the script
# with all it needs to know.
# The minimum argument of this script is the name of the parameter script
# as without it, we have no idea what to do.
# The parameters are stored in a file, that when executed, sets them
# Format is therefore very flexible.
# Assumptions:
#    That geometry is in ${date}_sock.pts and .fac
#    That landmarks are in ${data}_cor.lmarks
#    That we have 64 lead socks with the standard channels (193--256)
#    That the 192 lead torso geometry is used.
# Last update: Sun Jun  2 18:12:42 1996
#    - fixed a few things in the run number entry
# Last update: Wed Dec 13 12:28:46 1995
#    - still trying to expand and generalize
# Last update: Tue Oct 24 10:22:10 1995
#    - created
#### Set up parameters ####

USAGE="\nYou can run this script with arguments as follows:\n\
     $0 paramfile.m3dp [-ocsd0145etc] n1 n2, where\n\n\
     paramfile.m3dp is a script that sets the local parameters\n\
     -o = optical disk\n\
         0=odisk0; 1-odisk1; 4-odisk4; 5-odisk5\n\
     -b = backup disk\n\
     -s = scratch disk\n\
     -d = data disk\n\
     -e = show epi only \n\
     -t = show torso only \n\
     -c = show coronaries\n\n\
     -v = show V1-V6 on tank\n\n\
     -i = show integral maps\n\
     n1 and n2 are the first and second run numbers\n\n\
     Make sure to GROUP ALL ARGUMENTS into one block!!! \n\n\
        e.g.,  $0 -co1 2 5\n\
     to get data from odisk1 and use runs 2 and 5 and show coronaries\n"

##### Check arguments #####
if [ $# -lt 1 ]
  echo "\n *** Error in entry "
  echo " *** We need at least the name of the .m3dp (parameter) file ***"
  echo "$USAGE"

##### Execute script to set local params #####
. $paramfile

##### Check other input #####
#echo "Arguments are  $*"

if [ $# -gt 0 ]
  while getopts bceiostvd0145 optval
    case $optval in
      o | d | s | b) dataloc=$optval
      c)         showcor=1
      e)         epionly=1
      i)         showint=1
      v)         showvleads=1
      t)         torsoonly=1
      0 | 1 | 4 | 5)  odisknum=$optval
      \?)        echo $USAGE
                exit 2;;
#  echo "Arguments after getopts are $*"
  if [ $doshift ]
#    echo "Do the shift"
  # Read in the run numbers for first and second runs
  if [ -n "$1" ]
  if [ -n "$1" ]
#  echo "Arguments are $*"
#  echo "dataloc = $dataloc"
#  echo "odisknum = $odisknum"
  if [ "$dataloc" = o ]
#    echo "Check odisk value = $odisknum"
    if [ "$odisknum" != 0 -a "$odisknum" != 1 -a "$odisknum" != 4\
      -a "$odisknum" != 5 ]
      echo "+++ Odisk number was $odisknum so we set it to 0"
  echo "$USAGE"
  echo "\n We need some more input information"
  echo "\n If we need to know where to look for Vax data files"
  echo " where should we go?"
  echo " Enter the location of the Vax data files"
  echo " Optical disk drive 0 ................. 0"
  echo " Optical disk drive 1 ................. 1"
  echo " Optical disk drive 4 ................. 4"
  echo " Optical disk drive 5 ................. 5"
  echo " Datadisk ............................. d"
  echo " Scratchdisk .......................... s"
  echo " Backupdisk ........................... b"
  echo " $MAP3D_DATAPATH ............... return"
  echo "   Your entry? \c"
  read inchar
  case "$inchar"
    0) dataloc=o
    1) dataloc=o
    d) dataloc=d;;
    s) dataloc=s;;
    b) dataloc=b;;

###### Check fore silly combos #####

if [ "$epionly" -a "$torsoonly" ]
  echo "*** Entry error: You cannot use -e and -t or there is nothing to see"
  exit 1

###### Get the run numbers manually #####


if [ -z "$run1" -o -z "$run2" ]
elif [ "$numruns" -gt 0 ]
  if [ "$run1" -gt "$numruns" -o "$run2" -gt "$numruns" ]
if [ -n "$needruns" ]
  echo " Now enter the first and second run numbers"
  echo " ? \c"
  read run1 run2
if [ "$run1" -le 0 ]
if [ "$run2" -le 0 -o "$run2" -le "$run1" ]
  run2=`expr $run1 + 1`
if [ -n "$numruns" -a "$run2" -gt "$numruns" ]
#echo "run1 = $run1 and run2 = $run2"

###### Now see about the optical disk drive and set up some variables. #####

if [ $dataloc = o ]
  echo " Make sure the optical disk called RMSPACK-1A is in drive $odisknum"
elif [ $dataloc = s ]
elif [ $dataloc = b ]
elif [ $dataloc = d ]
echo "\n MAP3D_DATAPATH exported as $MAP3D_DATAPATH\n"

if [ ! -n "$ROBHOME" ]
   export ROBHOME

###### DO we have cor file? #####

if [ "$showcor" -a -z "$torsoonly" ]
  corfile="       -lm ${MAPRODXN}/andy3/${thedate}/geom/${thedate}_sock.lmarks"

###### DO we have vleads leadlinks file? #####

if [ "$showvleads" -a -z "$epionly" ]
  vleadsfile="       -ll ${ROBHOME}/torso/geom/andy3/leadset1_v1-6.leadlinks"

###### Set up the parameters fore running the program #####

# PArse datafilename four .data extension, and strip it
if echo $datafile | grep .data > /dev/null
  datafile=`echo $datafile | sed 's/.data//'`
  echo "Value of datafile updated to $datafile\n"

if [ -n "$showint" ]
  echo "Value of datafile updated to $datafile\n"

cd ${MAPRODXN}/andy3/${thedate}
#if [ -z "$numruns" ]
#  then
#  numruns=7
# while [ $runnum  -le $numruns ]
#   do
#   if [ $run1 = $runnum ]
#     then
#     echo "Match fore run1 = $run1"
#     start1=${onset}${runnum}
#     echo "Start1 = $start1"
#     end1=`expr $start1 + $duration`
#   fi
#   if [ $run2 = $runnum ]
#     then
#     start2=${onset}${runnum}
#     end2=`expr $start2 + $duration`
#   fi
#   runnum=`expr $runnum + 1`
# done

########### Set up the start and end of the frames numbers
# This is no elegant, and must be expanded when numframes climbs
# but is appears to work

case "$run1"
  1) start1=$onset1;;
  2) start1=$onset2;;
  3) start1=$onset3;;
  4) start1=$onset4;;
  5) start1=$onset5;;
  6) start1=$onset6;;
  7) start1=$onset7;;
  8) start1=$onset8;;
  9) start1=$onset9;;
 10) start1=$onset10;;
 11) start1=$onset11;;
 12) start1=$onset12;;
 13) start1=$onset13;;
 14) start1=$onset14;;
 15) start1=$onset15;;
 16) start1=$onset16;;
end1=`expr $start1 + $duration`
case "$run2"
  1) start2=$onset1;;
  2) start2=$onset2;;
  3) start2=$onset3;;
  4) start2=$onset4;;
  5) start2=$onset5;;
  6) start2=$onset6;;
  7) start2=$onset7;;
  8) start2=$onset8;;
  9) start2=$onset9;;
 10) start2=$onset10;;
 11) start2=$onset11;;
 12) start2=$onset12;;
 13) start2=$onset13;;
 14) start2=$onset14;;
 15) start2=$onset15;;
 16) start2=$onset16;;
end2=`expr $start2 + $duration`

if [ -n "$showint" ]

if [ -z "$start1" ]
  echo "Start1 never set so exit"
  exit 1
elif [ -z "$start2" ]
  echo "Start2 never set so exit"
  exit 2

##### Now, set up the run string for the progr #####
        -f ${MAPRODXN}/andy3/${thedate}/geom/${sockgeom}.fac \n\
	-as 40 440 551 950 \n\
	-t ${epilead} \n\
	-at 840 1240 825 950 \n $corfile \n\
	-p data/${datafile}.data@${run1} -s $start1 $end1 \n\
	-cl ${ROBHOME}/torso/geom/socks/sock64/sock64.channels \n\
	-sl 2 \n\
	-f ${MAPRODXN}/andy3/${thedate}/geom/${sockgeom}.fac \n\
	-as 441 840 551 950 \n\
	-t ${epilead} \n\
	-at 840 1240 700 825 \n $corfile \n\
	-p data/${datafile}.data@${run2} -s $start2 $end2 \n\
	-cl ${ROBHOME}/torso/geom/socks/sock64/sock64.channels \n\
	-sl 2"

	-f ${ROBHOME}/torso/geom/andy3/leadset1.fac \n\
	-as 40 440 150 550 \n\
	-t ${torsolead} \n\
	-at 840 1240 400 525 \n $vleadsfile \n\
	-p data/${datafile}.data@${run1} -s $start1 $end1 \n\
	-cl ${ROBHOME}/torso/geom/andy3/leadset1.channels \n\
	-sl 4 \n\
	-f ${ROBHOME}/torso/geom/andy3/leadset1.fac \n\
	-as 441 840 150 550 \n\
	-t ${torsolead} \n\
	-at 840 1240 275 400 \n $vleadsfile \n\
	-p data/${datafile}.data@${run2} -s $start2 $end2 \n\
	-cl ${ROBHOME}/torso/geom/andy3/leadset1.channels \n\
	-sl 4 "

if [ "$epionly" ]
  command="${MAP3D} -nw -b $epicommand"
elif [ "$torsoonly" ]
  command="${MAP3D} -nw -b $torsocommand"
  command="${MAP3D} -nw -b $epicommand $torsocommand"

##### And, finally, run the program #####
echo "Run program as $command"

11 Files

11.1 Demos

The easiest way to use map3dgl for complicated sets of surfaces and/or potentials files is to set up a script file. The composition of script files is described in Section 10 in more detail. Examples of such files are given in the directory  macleod/gl/demos. Any of these can be executed simply by typing the filename in a window on the SGI console. These files can also be copied and altered by anyone wishing to experiment with their own data. Examples of data files, both geometry and potential data, are to be found in subdirectories of  macleod/gl/cj/, eg,. cjb18 in multi/:

# A demo script to look at a set of surfaces 
cd ~macleod/torso/geom/dal
map3d -f daltorso.fac -f dalepi.fac

Also check in the directory  macleod/gl/demos on one of the new data disks of the SGI for other, and sometimes more stable (and stale?) , demo scripts.

11.2 Examples

11.2.1 Data and geometry filepaths

Here is a set of command line examples that all run the same data, and show some of the variability that is possible with map3dgl. All three examples access the geometry in the file  mapdata/bt25mar92.geom and the data in the file, which we assume are stored in  mapdata (home directory for the data account for Bruno Taccardi's group).

Version 1:

map3d  -f ~mapdata/bt25mar92.geom \
       -dp /vax/odisk0/bt25mar92pack/ \
       -p ~mapdata/

Note the use of ~mapdata to specify the home directory of the user (mapdata in this case), a good way to achieve some independence of which computer is actually running the script.

The data file for this example is assumed to be on the optical disk #0 an is set by the -dp option.

In this example, the geometry file is explicitly specified, which requires that we know the name of the geometry file for the particular .data file. It turns out that the .data file knows this already for us. But the geometry filename specified in the .data file has no directory and if the script is not run from mapdata's directory, map3dgl will not find the geometry file. We need a way to tell map3dgl that the geometry file is to be found elsewhere. We can state this explicitly, using the method above, or more generally, as shown in the next version.

Version 2:

map3d  -dp /vax/odisk0/bt25mar92pack/ \
	-gp ~mapdata/ \
	-f ~mapdata/

Here we use the -gp  mapdata line to tell map3dgl that any geometry file(s) listed in a .data file are to be found in mapdata's home directory.

The other thing to note in both these examples is that the directory in which the data files are to be found has been redirected to vax/odisk0/bt25mar92pack. This does not mean that the .data file is located here (the -p line in version 1 and the -p line in version 2 indicate where the .data file is located) but tells map3dgl that the directory where the .pak files that contain the actual numerical data is not the same as the one specified for the .data file. Instead, the .pak files can be found in /vax/odisk0/bt26mar92pack/, an optical disk on the Vax. The purpose of this is to gain flexibility in where the individual .pak (or .raw) files are located. You do not have to move files from the optical disk to the disk, for example, in order to read them with map3dgl.

A third version of the script does the same as version 2.

Version 3:

map3d  -f ~mapdata/ \
	-dp /vax/odisk0/bt25mar92pack/ \
	-gp ~mapdata/

The difference here is that the -dp and -gp arguments can be located either before the first -f filename, in which case they apply globally to all subsequent surfaces, or after the -f filename to which they should apply.

Another, even simpler form of the script could be used if we first specify an environmental variable to direct the search for .geom and .pak files.

Version 4:

To have this one work, you must have environmental variables specified as

eli:macleod> echo $MAP3D_DATAPATH
eli:macleod> echo $MAP3D_GEOMPATH

With these both set, then the map3dgl command becomes even simpler.

${HOME}/gl/cj/map3d -f ~mapdata/

These environmental variables can be set from within a script, or manually, and the method used depends on the shell you are using for Unix. The most common shell for the CVRTI is the Korn shell (ksh) and the method used here would be

     export MAP3D_DATAPATH
     export MAP3D_GEOMPATH
or for the C-shell (if you insist)
         setenv MAP3D_DATAPATH /vax/odisk0/bt25mar92pack

A further way to achieve the same end would be to define a defaults file (see .map3drc file in section 4.1) with the lines

geomfile_path = /vis/u/mapdata/
datafile_path = /vax/odisk0/bt25mar93pack/

And still another would be to use Phil's odisk program to interactively select the location of the .pak/.raw files. Just enter ``odisk'' from the console of either SGI workstation and select the optical disk, directory, and a single file from the list.

So, as always, there is more than one way to skin the cat, and you need only select the one that seems simplest to you.

11.3 Data Directories

The following directories contain data files (geometries and potentials) which can be used to play with map3dgl. They are all subdirectores of  macleod/gl/map3d and are read-accessible by anyone, and may even contain some bits of documentation as to what they are (but don't count on it).

= simulations using a dipole source and cubic volume conductor with anisotropic inhomogeneities
= data from the Dalhousie torso model with some potentials
= artificial data of potential distributions over multiple, triangulated spherical sections

11.4 Important files

a symbolic link to a script, which in turn calls the appropriate executable of map3dgl
executable version of map3dgl for elan level graphics
executable version of map3dgl for vgx level graphics
postscript file of the map3d documentation
HTML version of the map3d documentation


To many to even begin to contemplate. But if there are any you would like exterminated, see Rob MacLeod ( (I accept all foreign currency in large denominations but no credit cards).

About this document ...

This document was generated using the LaTeX2HTML translator Version 99.2beta6 (1.42)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 3 -no_white -link 3 -no_navigation -no_math -html_version 3.2,math -show_section_numbers map3d-manual

The translation was initiated by Rob MacLeod on 2002-02-21

Rob MacLeod 2002-02-21