Subsections

6 Input files

In this section, we describe the contents and formats of all the input files that map3d uses to get geometry, data, and much more.

6.1 Geometry input files

The input of geometric data for map3d occurs via files and we support three different formats at present. The simplest (and oldest) is a set of ASCII files that contain the points or nodes of the geometry--stored 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). To satisfy a need for more comprehensive and compact storage of geometry information, we have developed a binary file format and created the graphicsio library to manage these files. Finally, in recognition of the ubiquity of MATLAB, as of version 6.1, there is support for reading .mat files, which have an internal structure that included node and connectivity information. Below, we describe each of these files and how map3d uses them.

6.1.1 Points (.pts) file

The characteristics of a .pts file are as follows:

ASCII file, no special characters permitted;
Each line contains one triplet, ordered as x, y, and z values; one or more spaces between values, which are assumed to be real, floating point numbers;
Each line may also optionally contain a group number as a fourth element (although at present, map3d does not use this group information);
the order of points in the file is the implicit order of the nodes in the geometry; connectivities are based on this ordering.

6.1.2 Triangle (.fac) files

The characteristics of a .fac file are as follows:

ASCII file, no special characters permitted;
Each line contains a triplet of integer values pointing to the nodes of the geometry. Node numbers begin at 1 not 0!;
The order of triangle vertices (nodes) is not strictly controlled, however, it is recommended that order reflect a common convention in graphics--a counterclockwise sequence of vertices when viewed from the outside of the triangle;
Each line may contain an optional fourth values which is the group number for the triangle (not used by map3d);
Order of triangles in the file is not meaningful except for internal bookkeeping; user will notice ordering only when a triangle is picked for interrogation.

6.1.3 Binary (.geom) geometry files

At the CVRTI we have developed a binary file system for efficient storage of complex geometry and associated attributes, a part of what we call the graphicsio library. Extensive documentation of this format is available from Rob MacLeod (macleod@cvrti.utah.edu) (www.cvrti.utah.edu/~macleod/docs).

Briefly, each graphicsio geometry file contains one or more sets of node locations and, optionally, connectivities for polygonal elements composed from those nodes. It is possible in graphicsio files to associate scalar, vector, and tensor values to nodes or elements, the most relevant example of which are channel pointers, stored as a set of scalar values associated with the nodes of the geometry. Each graphicsio geometry file can contain any number of sets of geometries, each with different nodes and connectivities. A typical example for map3d would be a single .geom file that contains information from multiple surfaces that we might want to display together.

map3d is capable of reading surface geometry from either single surfaces or from all surfaces contained in a multi-surface geometry file. Command line arguments controls the selection, as we describe in the next section.

6.1.4 MATLAB geometry file support

map3d can read .mat files generated by MATLAB as long as they are organized according to the following guidelines:

Each separate surface is either a structure (See the MATLAB documentation for structures ). To include multiple surfaces requires an array of structures.
Within a surface structure, the following fields contain the geometry:
- .pts or .node contains the node locations, usually in a 3 x N array (although map3d will check and accept either 3 x N or its transpose, N x 3), where N is the number of nodes.
- .fac or .face contains the triangle connectivities, usually in a 3 x M array (again, map3d will accept the transpose) where M is the number of triangles.
- .seg or .edge contains the line segment connectivities,
- .tet, .tetra, or .cell contains tetrahedral connectivities, and
- .channels contains the channel information in a one-dimensional vector, in which each element of the vector points to the associated data channel.

To prepare a structured .mat file is very simple, for example using the following commands:

     >> geom.pts = ptsarray;
     >> geom.fac = facarray;
     >> geom.channels = 100:164
     >> save mygeom.mat geom

where ptsarray is a 3 x N array defined to contain the node locations, facarray is a 3 x M array of triangle connectivities, and mygeom.mat is the name of the resulting .mat file. The channels information indicates that there are 64 nodes in the geometry and they expect to get time signals from channels 100-164 of a data file. (See Section 6.4 for more information on channels.

6.2 Command line control of geometry files

In map3d the -f option determines in which files the geometry is to be found. Starting from the filename that follows -f, which may or may not include a file extension, the program looks for all possible candidate geometry files and queries the user for resolution of any ambiguities. Thus, with the arguments map3d -f myfile, map3d3d looks for myfile.geom, myfile.mat, myfile.pts, myfile.fac, etc, and tries to resolve things so that a valid geometry description is found. It is possible to direct this process by typing the geometry filename with an extension according to the following rules:

Extension	Effect
none	look for files with the extensions .pts, .fac, .tetra, and .geom and if an incompatible set are present (e.g., both .pts and .geom), 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 graphicsio geometry file and ignore any others present.
.mat	take the MATLAB file and ignore any others present.

A further way to read geometry into map3d is to use the geometry filename that can be optionally contained within the time series file (see Section 6.3) that contains the potentials. This requires that the .tsdf file be created with the geometry filename included; adding this after the fact is difficult. Note that even if a geometry filename is found in the .tsdf file, it can be overridden by the geometry file name specified in the argument list of map3d.

6.3 Scalar data files

There are two ways of storing scalar values (typically electric potential in our applications) so that map3d can recognize and read them. One is a simple ASCII file and the other a binary format developed at the CVRTI.

6.3.1 .pot files

One way to package the scalar data values that are assigned to the points in the geometry is the .pot file. In the default condition, the scalar values in the .pot files are ordered in the same way as the node points in the geometry file with simple one-to-one assignment. With a channels file, it is possible to remap this assignment, as described in Section 6.4).

The rules for .pot files are:

Each line of the files contains one scalar data value, assumed to be a real number in single precision floating point format.
The order of the values within the file must either agree with that of the associated set of nodes or a channels file must be supplied to redirect the links between potential value and nodes.
Each .pot file must end with a blank line.
A single .pot file can contain only the data values associated with a single surface at a single instant in time. To represent a sequence of time steps (frames) requires a sequence of files, typically with filenames ending in a three-digit series, e.g., mapdata001.pot, mapdata002.pot, mapdata003.pot, .... Section 4.4 explains how to specify such a series of .pot files to map3d and Section 4.1 shows examples.
The extension .pot must be used.

6.3.2 CVRTI data (.tsdf) format files

The more efficient and flexible way to store scalar values is by means of the time-series data file format developed at the CVRTI, also as part of the graphicsio library. These files (.tsdf files) are capable of holding an entire sequence, or time series of scalar data in a single file, along with information about the contents, type, units, and temporal fiducials from the time series. For more details on this file format see www.cvrti.utah.edu/~macleod/docs or the information under the graphicsio library at www.cvrti.utah.edu/computing.shtml.

Here are some concepts of the time series data file structure that are relevant to the different modes of operation described in this manual.

Links to geometry

The links between the channels of data in the .tsdf file and the nodes of the surface[s] over which they are displayed is established via channel array information, which is available stored as associated scalars to the nodes in the geometry file (see Section 6.1) or in explicit channels files (see Section 6.4).

Frames

By frames of data, we mean instants in the data stream representing single moments in time. For each frame, there is a set of values that for a spatial distribution or map and map3d needs to know what subset of frames are to be included in the display. To explicitly specify frame numbers, use the -s and -i options described in Section 4. As an example, the command line

        map3d -w -f geomfile.geom@1 -p datafile.tsdf -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 time series data file datafile.tsdf.

6.3.2.1 Time series container files:

The graphicsio library also defines a container file format that can describe a set of time series data (.tsdf) files, and can contain parameters extracted from the associated time series. At present, map3d does not read such container files, but this will change soon...

6.3.3 MATLAB data file support

You can also store and read scalar values in .mat files, as a structure with a single field called ``.potvals'', that contains a N x M array, where N is the number of data channels and M is the number of time instants. There are additional fields in the structure that mimic the information available in the graphicsio .tsdf file so--the complete list is as follows:

.potvals, .data, .field, or .scalarfield scalar values as N x M array, where N is the number of data channels and M is the number of time instants.
.unit the type of units for the data, ``um'' for microvolts, ``mv'' for millivolts and ``V'' for volts.

There will be more of these as we develop the format further so stay tuned.

The commands to make a suitable .mat file are very easy in MATLAB, for example, to load 128 channels of time signals with unit of millivolt from an array sockinfo in MATLAB to a file called mysockdata.mat

    >> sockdata.potvals   = sockinfo(1:128,:);
    >> sockdata.unit = 'mV'
    >> save mysockdata.mat sockdata

6.4 Channels and leadlinks

6.4.1 Description of leadlinks and channels information

Channels and leadlinks files, and the arrays they contain, are identical in structure, but they have important functional differences. A run of map3d may require both, either, or neither of these, depending on the structure of the data files and geometries. The basic function of both channels and leadlinks information is to offer linkages between nodes in the geometry and the data that is to be associated with those nodes. The first file type, the channels file, links the nodes in the geometry to specific time signals in a data file; without channel mapping, the only possible assumption is that each node i in the geometry corresponds to the same time signal i in the data file. Any other linkage of geometry and data channel requires there to be channel information, typically either from a separate .channels file or stored with the binary .geom file as an associated scalar value for each node.

Leadlinks are purely for visualization and describe the connection between ``leads'', a measurement concept, with ``nodes'', a geometric location in space. In electrocardiography, for example, a lead is the algebraic difference between two measured potentials, one of which is the reference; ``unipolar'' leads have a reference composed of the sum of the limb electrode potentials. It is often useful to mark the locations of these leads on the geometry, which often contains many more nodes than there are leads. The most frequent use to date has been to mark the locations of the standard precordial ECG leads within the context of high resolution body surface mapping that uses from 32-192 electrodes. Another common application is to mark subsets of a geometry that correspond to measurement sites (values at the remaining nodes are typically the product of interpolation). In summary, leadlinks allow map3d to mark specific nodes that may have special meaning to the observer.

Figure 1 shows an example of lead and channels information and their effect on map3d. See the figure caption for details.

**Figure 1:** Example of the indirection possible in *map3d* through the use of *leadlinks* *channels*, and *channellinks*. 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 values at time signal 92 to be loaded into location 22 in the internal data array (and displayed by *map3d*). In a separate, channellinks array, shown below the leadlinks array, the entry in lead 4 says that that lead should actually be labeled `` V₁''.
$\begin{figure}\centerline{\epsfig{file=figures/map3d-indirection.epsf,height=4in}} \end{figure}$

map3d handles this information in the following manner:

channels

The channels information links nodes in the geometry to individual channels or time series in the data file. For example, the data values associated with node k in the geometry are located in the data location specified by the channel array value channels(k). If channels(k) < 0, then there is no valid data for node k.

Note that map3d uses the channels arrays when loading scalar data into the internal storage arrays! Hence, the action of the channel mapping is not reversible. Should geometry nodes and data channels match one-to-one, there is no need for a channels array. It is also possible to define via a channels array the situation in which a single data channel belongs to two (or more) nodes in the geometry. The most frequent example of this occurs when three-dimensional geometries are ``unwrapped'' into surfaces in which what was a single edge is split and thus present at both ends of the surface.

leadlinks

The leadlinks information is primarily used to identify and mark measurement lead specific within the geometry. The typical use is to select a subset of the nodes to identify the measurement sites--values at other sites might be interpolated or otherwise computed. Leadlinks also provide a means to renumber the labels on the nodes of the geometry in order to, for example, reproduce the numbering scheme used in an experimental setup.

In the leadlinks array each entry refers, by its location in the array, to a particular lead #; the value at that location in the array 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 ( leadlinks(4) = 22), then map3d will display node 22 in the geometry as ``4'', not ``22'' whenever node marking with leads is selected).

channellinks

There is an extension of the basic scheme which includes a further level of redirection for giving the leads explicit text labels. Channel links are stored as a array of strings, one for each node of the geometry. The channellinks file is organized similarly to a leadlinks file, with each line containing information for one node. However, each line consists of two values, 1) the number of the associated channel and 2) the text string to be used as the label when map3d marks the nodes with channel numbers.

Hence we have the situation of a node number K in the geometry displaying time signals from channel L in the scalar data, but labeled with string ``XXX''.

6.4.2 Source of leadlink and channel information

The sources of channels, leadlinks, and channellinks information are files, or parts of files, as outlined in the following paragraphs.

6.4.2.1 In .geom files

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

6.4.2.2 In .mat geometry files

MATLAB geometry files can also contain an channels array is stored as a .channels field in the structure. See Section 6.1.4 for more details.

6.4.2.3 In .leadlinks files

A .leadlinks file is an ASCII file, the first record of which contains 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:

the first number is the number of the lead, as it should appear in any labeling of the associated node.
the second entry in each row is the value of the associated node number in the geometry.

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 (the geometry can, often does, contain more than 32 nodes), and that lead #1 is called lead ``1'' and is node 1 in the geometry file. Lead #2 is at node 42, 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 that is passed to map3d with the -ll option can be marked in a number of ways, described more fully in Table 10 in Section 8.2.3.

6.4.2.4 In .channels files

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). There is one line in the file for each node of the geometry to which we wish to associate scalar data. Each following record contains two integer values:

the first number is simply a running counter that indicates the node number with which to associated the second value in the row.
The second value in each row is the channel number for that node; a negative number signifies a node to which there is no data associated.

For example, the file for a surface which reads:

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. Node 22 does not have any scalar data associated with it.

6.4.3 Display of lead/channel information

To see how map3d can display the node and lead information, see Sections 7.7 and 8.

6.5 Landmark files

Landmark files contain information for visual cues or landmarks that map3d can draw over the surfaces in order to aid and orient the viewer. Initial use was primarily for coronary arteries, but the idea has 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 visible (but not functional) cutting plane through the geometry (Note: do not confuse this with the cutting planes that map3d provides for slicing 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	faceted 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 file, 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.

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 the number of sides controlled by a program variable.

6.5.0.1 Filename conventions:

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

6.5.0.2 Control of landmark display:

for details of how to control the display of landmarks, see Section 8.7.

Rob Macleod 2004-10-05