Map3d: Scienti c visualization program for multichannel time series

Map3d: Scienti c visualization program for multichannel time series data on unstructured, three-dimensional meshes. Program User's Guide Robert S. MacLeod3 ([email protected]), Phil R. Ershler3 ([email protected]), Christopher R. Johnsony ([email protected]), and Michael A. Mathesonz UUCS-94-016

3 Nora

Eccles Harrison Cardiovascular Research and Training Institute and y The Department of Computer Science at the University of Utah Salt Lake City, UT 84112 USA and z Silicon Graphics Incorporated. September 26, 1994

Contents 1 Introduction

6

2 Usage

6

2.1 Typical examples : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

7

2.2 Global Parameters : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

8

2.3 Surface parameters : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

9

2.4 Data parameters : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

10

3 New Features

12

3.1 Applying transformations to data : : : : : : : : : : : : : : : : : : : : : : : :

12

3.2 Command line parsing: : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

12

3.3 Single versus multiple windows : : : : : : : : : : : : : : : : : : : : : : : : :

13

3.4 Landmark display : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

13

4 Input les

14

4.1 Default settings les : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

14

4.2 Geometry input les : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

16

4.2.1 .pts/.fac les : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

16

4.2.2 Standard geometry (.geom) les : : : : : : : : : : : : : : : : : : : :

16

4.3 Potential and gradient data les : : : : : : : : : : : : : : : : : : : : : : : :

17

4.3.1 .pot and .grad les : : : : : : : : : : : : : : : : : : : : : : : : : : : :

17

4.3.2 CVRTI data (.data) format les : : : : : : : : : : : : : : : : : : : :

18

4.4 Leadlinks and Channels : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

19

4.4.1 Description of leadlinks and channels information : : : : : : : : : : :

19

4.4.2 Source of leadlink and channel information : : : : : : : : : : : : : :

20

4.4.3 Display of lead/channel information : : : : : : : : : : : : : : : : : :

23

4.5 landmark les : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

23

5 Display features

25

5.1 Scalar display : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

25

5.1.1 Managing the scalar window : : : : : : : : : : : : : : : : : : : : : :

27

5.2 Data Scaling : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

27

5.3 Clipping Planes : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

29

5.4 Perspective view and depth cueing : : : : : : : : : : : : : : : : : : : : : : :

29

5.5 Bounding cube : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

30

6 Control of map3d

30

6.1 Menus, keyboard mapping, mouse and dial function : : : : : : : : : : : : :

30

6.2 Feedback Reporting Level : : : : : : : : : : : : : : : : : : : : : : : : : : : :

31

6.2.1 Keyboard mapping : : : : : : : : : : : : : : : : : : : : : : : : : : : :

31

6.2.2 Dial box : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

31

6.2.3 Keypad Control : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

33

6.2.4 Mouse control : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

33

7 Picking mode

34

7.1 Picking Nodes : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

36

7.2 Picking Triangles : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

36

7.3 Triangulating : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

36

7.4 Triangle ipping : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

37

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

38

8.1 Postscript dump : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

38

8.2 Image capture : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

39

8.3 Video output from map3d : : : : : : : : : : : : : : : : : : : : : : : : : : : :

40

8.4 Additional video controls : : : : : : : : : : : : : : : : : : : : : : : : : : : :

41

8.5 Photographing from the Display : : : : : : : : : : : : : : : : : : : : : : : :

41

8.5.1 Direct photography from the screen : : : : : : : : : : : : : : : : : :

41

8.5.2 Photography via the Macintosh : : : : : : : : : : : : : : : : : : : : :

43

Abstract There are many examples in biomedical research of recording time signals with multi-sensor arrays whose elements are arranged in irregular, three-dimensional grids [1, 2, 3, 4]. If the nodes in such arrays can be connected into \surfaces", it is possible to employ linear interpolation techniques to display scalar data values on the grid, provided the node locations, and their connectivities, are known. The program map3d was developed to provide exible interaction with such grids, and the data values associated with them. Brie y, map3d provides interactive display of the nodes of the sensor array, and the connectivity mesh (described as line segments, triangles, or tetrahedra), with capabilities for manual editing of the connectivities and subsequent storage of the results. If scalar data are available associated wth the nodes of the mesh, map3d will display this data as either colour-coded contour lines or Gouraud or at shaded surface elements. If there are series of such scalar data (typically in time), the time signals for selected channels can be displayed and used to select which dataset to display. The program has extensive scaling options for data value to colour mapping, dierent colour maps, and a variety of methods of determining the scope of data scaling. Above all else, the program allows intensive interrogation of both the geometrical mesh and the data values mapped to it. This technical report describes the design concepts and user interface of the map3d program. The code was written in ANSI complient C and makes extensive use of the Graphics Library (GL) routines from Silicon Graphics. The code has been ported, in a somewhat limited edition, to the IBM RS-6000 running AIX, as well as to the Sun Sparc architecture using both Dupont Pixel's and Portable Graphics' (NPGL) GL emulation software. It does not run under OpenGL at this time. The code is not in the public domain, however, the author ([email protected]) will consider reasonable requests for information.

1 Introduction This document describes the function and usage of the program map3d , a scienti c visualization application used at the CVRTI to view model geometry and scalar (potential) and vectors (current) eld distributions. The program is highly interactive and makes extensive use of the full VGX features of the Silicon Graphics Library (GL). map3d 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 les.

2 Usage map3d [-b -iv -ss -v -w -nw\ -c default_mesh_colour \ -df default_filename \ -dp datafile_pathname \ -gp geomfile_pathname \ -rl report_level \ -vw xmin ymin ] -f geomfilename \ [-ac \ -as 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 \ -ps scaling_value \ -ll leadlinks-filename \ -cl channels-filename \ -sl surfnum \ -t trace-lead-number \ -at xmin xmax ymin ymax]

2.1 Typical examples Typical cases of usage of map3d are given below:  Read data from a .data le and get the geometry lename from the header of that

.data le.

map3d -nw -f datfilename.data

The -nw option sets a new window for each surface of data. A modi cation of this if the number of the data series is known in advance is map3d -f datfilename.data@seriesnum

This would load the series seriesnum from the le datfilename.data and place all surfaces in a single window.  Read data from one .data le and geometry from a speci c .geom le.

map3d -w -f geomfilename.geom -p datfilename.data

This overrides the geometry le speci ed in the header of the .data le. The same modi cation as above is permitted here | if the speci c series number is already known, use the form map3d -w -f geomfilename.geom -p datfilename.data@seriesnum

This reads series seriesnum from datfilename.data and displays it on the geometry from geomfilename.geom.  A third, potentially very powerful mode is permitted in which the surface number for

the geometry is speci ed explicitly, i.e.,

map3d -w -f geomfilename.geom@surfnum -p datfilename.data

which speci es that surface surfnum is to be read from the geometry le and that only data associated with this surface will be read from the data le datfilename.data . Here too the option of explicitly specifying the series number is provided. For example,

map3d -w -f geomfile.geom@surfnum -p datfile.data@seriesnum

would read geometry from surface surfnum and data for that surface from series seriesnum of the le datfilename.data. In this mode, all the surface based attributes described below (e.g., colours, window locations, rst and last frame numbers of the data, etc. can be speci ed at startup time. Note that if the series number is not speci ed at startup, the user is presented with a le 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 les.

2.2 Global Parameters The following general parameters aect the entire display: -b = 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.

-iv = initialize video equipment in VISSGI. -ss = make sure all windows have the same scaling applied. -v = 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.

-nw = for multiple surfaces (i.e., more than one set of points and triangles), place each

surface data in a new window. By default, map3d opens a single window for all surfaces.

-w = for multiple surfaces (i.e., more than one set of points and triangles), place all surface

data in the same window. By default, map3d 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 of all surfaces for which there is no speci c

colour speci cation.

-df filename = read the defaults le filename for start-up settings for the program. This

overrides any defaults les read by the program (see below) or any defaults set within the program.

-dp datafile pathname = directs the search for data les accessed via a .data le to an-

other directory. This occurs most often with data les that actually point to .pak or .raw les on the Vax. Using an alternate pathname, you can override the original directory speci cation for the les and get them from, say, an optical disk. This value can also be speci ed in the defaults le (see section 4.1) or via an environmental variable called MAP3D DATAPATH, which you can set at any time before executing map3d . You may specify this option either globally for all surfaces by inserting is before the rst -f filename in the command line, or separately for each surface.

-gp geomfile pathname = directs the search for geometry les accessed via a .data le to

another directory. The most common case of this is when the name of the geometry le is stored in the data le, usually without directory speci cation. This value can also be speci ed in the defaults le (see section 4.1) or via an environmental variable called MAP3D GEOMPATH, which you can set at any time before executing map3d . You may specify this option either globally for all surfaces by inserting is before the rst -f filename in the command line, or separately for each surface.

-rl report level = set the report level for this execution of map3d . The legal values are

0 (no reporting) to 3 (full debug-level reporting). This values overrides the one set in the default le, bit should be speci ed after the default le 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 datafile.data = lename of the .geom (geometry) or .data le

containing points and connectivity information. Note: this is the minimal input for successful function of map3d . If a .data le is used, it is assumed to contain explicit reference to the associated .geom le containing the geometry. All surfaces are read from the geometry le.

2.3 Surface parameters For each new surface, a subset of the following surface-speci c parameters may be used. Note that if these parameters are to be used with data that are read from .data or .geom les, the last of the three forms speci ed 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 lename of the geometry les (.pts, .fac, .tetra, .geom, or .data) for the triangularized surface to be displayed, eg., -f RL-torso for the les RL-torso.pts, RL-torso.fac, and RL-torso.tetra. If a .geom le is the source of geometry, a single

surface may be selected by appending the surface number N to the lename in the form \@N ", e.g., geomfile.geom@3 to read surface 3 from .geom le geomfile.geom.

-ac = do not shift the origin of the points to the centroid of the pointset but leave values

as they are in the input geometry les.

-as xmin xmax ymin ymax = set the absolute location in pixels of the surface window

most recently de ned. 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 les read for this surface. This

is meaningful when the amplitudes of the vectors have no intrinsic meaning (e.g., ber-orientation vectors). 1 = red 4 = cyan 2 = green 5 = magenta 3 = blue 6 = yellow 7 = white

-ds = 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 le landmark filename a set of coronary ar-

teries, 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 lename for the potential and current data les. If the -s option is used, a number and the extensions .pot for potential and .grad for currents will be append to this base lename (see -s option), for .data les, the -s option speci es the

frame numbers to be read from the le. Otherwise singles .pot or .grad les 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 le. If a speci c run of a .data le is desired, append the run number N in the form \@N to the end of the lename, e.g., -p datafile.data@4 to read run number 4 from the le data le.data (see section 2.1).

-s num1 num2 = range of frame numbers to read. If we are reading data from .pot or .grad les, these values are appended to the value of potfilename to make complete pot

lenames. 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 le, frames num1 to num2 are read from the le.

-i increment = dierence between each frame number. For .pot and .grad les this aects

the string appended to pot lename for each new le. eg., -p lux_map -s 1 6 -i 2 expands to: lux_map001.pot lux_map003.pot lux_map005.pot For .data les, the frames are read with an increment of increment from the le.

-ph maxpotval = maximum data value in \user" scaling mode. The user can select be-

tween \local", \global", and \user" scaling modes using the mouse menus (see below).

-pl minpotval = minimum data value in \user" scaling mode. -ps scaleval = scaling value multiplied by each potential value as it read in from the

le(s).

-ll leadlinks-filename = le 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 identi ed by the leadlink le 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 le in general) optional drawn beside it. See the l command below to toggle display of the leads in the leadlink le. See section 4.4 for more information.

-cl channels-filename = le 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 single scalar

lead in its own window. If this is not speci ed, no scalar display is provided on startup. 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 the scalar window most

recently de ned. 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.

3 New Features In this section, we hightlight the latest additions to map3d 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 oers.

3.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 map3d to the geometry data, 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: steps:

Access to this command is from the menu, and is best described in the following

1. Bring up geometry and select the surface(s) to be transformed. 2. Rotate and translate until the desired project (view) of the geometry is xed. 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 ip back to the default position , while the image of the geometry remains xed, a sign that translations have been applied to the geometry. 5. When leaving map3d , make sure you check the window from which it was rst started for the dialog that directs the saving of the transformed data in a new le. Choices are for with .pts/.fac or .geom output les (see section 4.2 for detail).

3.2 Command line parsing: Background: The parsing of the command line has been completely rewritten in the latest version of map3d . This should not mean a great deal to 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. map3d can be started wit nothing more that a single argument which contains the name of the .data or geometry les; the -f is not necessary. Note, however, than this

is not true if more than one argument is passed

2. map3d will soon support selection of the time series to be viewed from with the same invocatin of the program. Stay tuned: : :

3.3 Single

versus

multiple windows

At long last, I have changed the default for the -w option so that if not otherwise speci ed, all surfaces will appear inthe same window. TO have each surface in its own window, the argument -nw (= \new window") must be in the command line.

3.4 Landmark display Background:

The display of landmarks is now more exible than in previous versions, with some simple lighting models added to provide more colours and views of the landmarks. There is also a new landmark which describes a clipping plane through the geometry.

Usage: 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 before. 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 dierent 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 interactivly altering the colour map, dierent 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 de nition les for the landmark les and shows each landmark in its elemental segments, with labelling of each segment.

No landmarks: As before, this option turns o display of the landmarks. Draw plane: switches the display of any landmark planes in the landmark les on and o.

Plane colour: selects the colour to be used to draw the landmark plane. For a description of the new plane landmark and how to add it to a le, see section 4.5.

4 Input les 4.1 Default settings les The program map3d looks for les 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 de nes the le with highest precedence default settings. 2. A le named .map3drc in the current directory (the one from which the application was launched) is used next. 3. If no .map3drc les is found in the current directory, it is searched for in the user's home directory (see the HOME environmental variable). This le has the lowest precedence and is only used of the other two options are not found. 4. The program map3d has a set of internal defaults which are used if there are no external default les found. The format of the default le is as follows: # comment line (ignored by map3d) parameter = value

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

Parameter shadingmodel

Values GOURAUD FLAT scale scope GLOBAL SURFACE GLOBAL FRAME GLOBAL GLOBAL LOCAL USER scale model LINEAR LOG EXP LAB7 LAB13 scale mapping SYMMETRIC SEPARATE TRUE MAP color map RG RG2 FULL BTW WTB lead marking1 LEADS NODES VALUES CUBES MINMAX LABELS MINMAX CUBES SCALAR num cols value num conts value draw bbox TRUE/FALSE data le path pathame geom le path pathame report level value

Meaning Use Gouraud shading of triangles Use at shading of triangles Scaling global over each surface Scaling global over each frame of data Scaling global over all data Scaling local to each frame and surface Scaling by user-supplied values (-pl -ph) Use linear scaling of contours Use logarithmic scaling Use exponential scaling Use logarithmic in 7 levels scaling Use logarithmic in 13 levels scaling scale symmetrically around both side of zero scale separately for + and - data values scale from most - to most + values Use full red-to-green colour map Use red-and-green (2-colour) colour map Use blue-to-red (full) colour map Use black-to-white colour map Use white-to-black colour map mark nodes with lead (channel) numbers mark nodes with node numbers mark leads with potential values mark leads with spheres/cubes mark extrema with lead numbers mark extrema with cubes mark the selected scalar node number of colours to use in shade display number of contour levels in display set bounding box on or o alternate path to the .pak/.raw les in .data le. alternate path to the .geom les in .data le. 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.2 for details on the dierent scaling options. The list of parameters possible will also certainly grow with the program. 1

options are cumulative

To save the current settings in a le, there is an option in the main menu of map3d which dumps all the settings to the le ./.map3drc, that is, the le .map3drc in the current directory. That way, when you start the program again from that directory, the same settings will be loaded. The .map3drc le is just a normal text le, but like all \rc"- les, 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 les, including hidden les). Dumping a copy of the settings is also the easiest way to see what settings are currently being maintained by map3d and also forms the best starting point to setting up your own customized default settings les.

4.2 Geometry input les The input of geometrical data occurs via the \standard" .pts, .seg, .fac, and .tetra les, as well as the new .geom geometry le format. The map3d program, when fed a base lename with the -f option, looks for all possible candidate geometry les and queries the user for resolution of any ambiguities.

4.2.1 .pts/.fac les One .fac (.pts) le contains the connectivities (points) for a single surface, hence, multiple surfaces must be realized by building multiple les. If you have a .tri le containing single or multiple surfaces on the Vax, we can move it to the SGI and unpack it in such a way as to make it accessible by map3d . For viewing tetrahedral meshes, use the .tetra le format, together with the associated .pts les. A le in a format for viewing geometry composed of straight segments (two points connected by a line) is identi ed by the .seg. extension.

4.2.2 Standard geometry (.geom) les The map3d program is capable of reading geometry data from the new geometry le format (.geom les). See other documentation for a description of this le type and how to use it. The geometry in a .geom le can be speci ed in the -f option, or found indirectly via the lename stored in a .data le (see section 4.3.2 below)

4.3 Potential and gradient data les 4.3.1 .pot and .grad les The scalar data values that are assigned to the points in the geometry are input via .pot les, while vectors are input via .grad les. Scalars are ordered in the same way as the node points as a simple one-to-one assignment is performed, although a channels le 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 les are:  Each line of the les contains one data value, assumed to be real.  Order of the values must either agree with that of the associated set of points or a

channels le must be supplied to redirect the links between potential value and nodes.

 File must end with a blank line.  A single le can contain only the data values associated with a single surface at a

single instant in time.

 The extension .pot must be used.

The rules for .grad les are:  Each line of the les contains 6 ASCII strings, assumed to represent real data values

as follows:

{ First three values de ne the starting point of the vector in three dimensions, in the same coordinate system as the points of the geometry. { Second set of three values represent the X-, Y-, and Z-components of the vector.

 File must end with a blank line.  A single le can contain only the vectors associated with a single surface at a single

instant in time.

 The extension .grad must be used.

A set of les that contains a time sequence of data should have lenames of the form base lename001 to base- lename NNN, with the numeric sux (NNN) being a three-digit value, which can run in any regular increments. For example, pot- le001.pot, pot- le005.pot, pot le009.pot, pot- le013.pot, : : :

4.3.2 CVRTI data (.data) format les The newly developed standard data les (.data les) are capable of holding not only the scalar and vector data found in the older .pot and .grad les, but also links into existing \pak-tape" les, the name of the suggested geometry les, and various other bits of information that could be useful to map3d . There are some concepts of the data le structure that should be understood to appreciate the dierent 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 le:

.data les 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 map3d 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 le. The user then selects the run that should be displayed. The desired run number can also be appended to the .data lename with a \@", as in map3d -f datafile.data@2

which selects run 2 from the .data le datafile.data.

Links to geometry The links between the leads of data in the .data le 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 le (see documentation on Geometry and Data les elsewhere). Section 4.4 contains more information on channels and leadlinks arrays.

Frames By frames of data, we mean instants in the data representing single moments

in time. For each frame, there is a map. If map3d is launched without speci c 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 map3d . For example map3d -w -f geomfile.geom@1 -p datafile.data@2 -s 10 130 -i 2

speci es that surface 1 from the geometry le geomfile.geom should be used to display frames 10 to 130, taking every second frame, from run 2 of the .data le datafile.data.

4.4 Leadlinks and Channels 4.4.1 Description of leadlinks and channels information Leadlinks and channels les, 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 les and geometries. The basic function of both leadlinks and channels information is to oer 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 le. Or, in more detail,

leadlinks 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 le 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 map3d .

leadlinknums 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 map3d program now handles this additional indirection, and other programs are bound to follow suit as the need arises.

channels The channels information is used to relate nodes in the geometry to locations in the data le(s). For example, if we wish to nd 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 le.

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 les with an inherently dierent 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 xed 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 lenames internally and associates then to a particular choice of plot geometry. In map3d , there are many cases in which channels information is not needed. The gure 1 shows an example of lead and channels information layered one on top of the other. See the gure caption for details.

4.4.2 Source of leadlink and channel information The source of both channels, leadlinks, and leadlinknums information can be either the geometry (.geom) le or the data (.data) le, or two explicit les, called \leadlinks" and \channels" les, which are described in the next sections below.

The .data and .geom les Information for the channels array is stored as an associated scalar with the data information in the standard .geom les. At present, there is no leadlinks array stored in the .geom le but this could change at an time. The .leadlinks le A leadlinks le is an ASCII le, the rst record of which contain a line

nnn leads, where nnn is the number of leads to be described in the le (and also one less

than the total number of lines in the le). Each following record contains two integer values:

Indirections in map3d Array name:

leadlinks

model_pts X Y Z

channels

mux_data

model_pots

4 leadnum

22

22

22

92

92

leadlinknums leadnum

22

6

= points to = copy contents

Figure 1: Example of the indirection possible in map3d 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 buer, 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 re ect this additional indirection. 1. the rst 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 le for a surface which reads:

32 Leads 1 1 2 42 4 31 7 65 . .

. . 32

. . 11