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:

  1. ASCII file, no special characters permitted;
  2. 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;
  3. Each line may also optionally contain a group number as a fourth element (although at present, map3d does not use this group information);
  4. 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:

  1. ASCII file, no special characters permitted;
  2. Each line contains a triplet of integer values pointing to the nodes of the geometry. Node numbers begin at 1 not 0!;
  3. 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;
  4. Each line may contain an optional fourth values which is the group number for the triangle (not used by map3d);
  5. 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:

  1. Each separate surface is either a structure (See the MATLAB documentation for structures ). To include multiple surfaces requires an array of structures.
  2. Within a surface structure, the following fields contain the geometry:

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 \times N$ array defined to contain the node locations, facarray is a $3 \times 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.1.5 Landmark geometry file support

map3d can also read geometry from a landmark file (See Section 6.5 below), where you specify a series of connected points and radii. map3d will automatically connect and triangulate them, and will also associate scalar data with them. Note that currently there is no channels support for landmark geometry.


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 three 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, one is a binary format developed at the CVRTI, and the third is MATLAB.


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:

  1. Each line of the files contains one scalar data value, assumed to be a real number in single precision floating point format.
  2. 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.
  3. Each .pot file must end with a blank line.
  4. 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.
  5. The extension .pot must be used.


6.3.2 CVRTI data (.tsdf and .tsdfc) format files

One 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. Each time series data file (.tsdf files) holds an entire sequence, or time series of scalar data in a single file, along with some information about the contents, type, units, and global (i.e., that apply to all channels) temporal fiducials from the time series. For more details on this file format see www.cvrti.utah.edu/~macleod/docs/graphicsio.

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 (tsdfc):

There is an extension to the graphicsio library that defines a container file format for a set of time series data (.tsdf) files, and can contain parameters extracted from the associated time series. These files are actually small databases and we use a modified (patched actually) version of the GNU Database Library (GDBL) to manage them.

Examples of programs and libraries that provide support for .tsdfc files include Everett, a program by Ted Dustman for initial processing of mapping data, Matmap, a set of MATLAB uilities by Jeroen Stinstra with a similar functionality, and tsdflib (as yet undocumented), a library created by Ted Dustman, Rob MacLeod, Jenny Simpons, and Jeroen Stinstra that provides C-language access to container files.

For more information on container files, see the documentation for the graphicsio library at www.cvrti.utah.edu/~macleod/docs/graphicsio/.


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 \times 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:

Note that only the 'potvals' field is required. A matlab array may be one instance of these fields, a cell or struct array of them, or simply an $N \times M$ array of data. To read a matlab file with many time time series, specify the time series on the command line with the '@' symbol (See Section 4.4) or specify the time series in the file browser. It will be shown by the label specified in the matlab file.

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'
    >> sockdata.lavel = 'A set of cool sock data'
    >> save mysockdata.mat sockdata


6.3.4 Fiducial (ascii) files

A fiducial can be input currently also in three ways: via a .tsdfc file, where the potential and fiducial values are stored together, via a .fids file, a simple ASCII file containing the values for each node, or by means of the MATLAB file that contains the time series data.

6.3.4.1 MATLAB file format for fiducials

The fiducial information in a MATLAB time series data file is stored in a array of structures called fids, where each element of the array represents one set of fiducials. This way, for example, there can be a set of $N$ activation times, another set of $N$ recovery times, and a set of $N$ Q-onset times. Each element of the array is, in itself, a structure, so that the set of fiducials contains enough information for map3d to do a useful display.

The legal elements of a fids structure are as follows:

Here is an example of creating the structures for some fiducials in MATLAB:

   matdata.potvals = potvals;
   matdata.unit = unit;
   matdata.label = label;
   matdata.fids(1).type = 10
   matdata.fids(1).value = fidvals(:,1);
   matdata.fids(2).type = 13;
   matdata.fids(2).value = fidvals(:,2);
   save (outfilename, 'matdata');

The first three lines set up the time series data, as we have seen above. The lines 4 and 5 create a set of fiducials of type 10 and loads the values into that part of the data structure. Lines 6 and 7 do the same thing for a second set of fiducials, which have type 13. The final line saves the contents of the structure into a file.

The type value for fiducials is important as map3d associates colors to fiducial types to provide consistent display. Moreover, each type has an associated text label that map3d uses in the interface. The list of current fiducial types and their numbers is as follows:


Fiducial Types
Number Type
0 pon, pstart
1 poff, pend
2 qon, qrsstart, qrson
3 rpeak, qrspeak
4 soff, qrsend, qrsoff
5 stoff, tstart, ton
6 tpeak
7 toff
8 actplus
9 actminus
10 act
11 recplus
12 recminus
13 rec
14 ref, reference
15 jpt, jpoint
16 baseline
30 pacing

6.3.4.2 ASCII file format for fiducials

The characteristics of a .fids file are as follows:

  1. ASCII file
  2. must have the following at the top of the file, on each line:
    1. number of time series, e.g., 1 (map3d only allows 1)
    2. series number (space) pak number
    3. number of nodes (space) list of fiducial types
  3. each successive line contains the node number followed by a list of fiducial values, one corresponding to each type specified on the line with the node numbers

    Example:
    1
    1 -1
    256 activation recovery
    1 8 212
    2 16 225
    3 9 214
    ...
    255 39 248
    256 25 237


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.

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 ``${\rm V_{1}}$''.
 
indirection

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.

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 ${\rm channels}(k)$. If ${\rm 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 ( ${\rm 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:

  1. the first number is the number of the lead, as it should appear in any labeling of the associated node.
  2. 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:

  1. the first number is simply a running counter that indicates the node number with which to associated the second value in the row.
  2. 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:

    352 Nodes
    1    123
    2    632
    .    .
    .    .
    22   -1
    23   432
    .    .
    .    .
    352  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. 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.8 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 [segindex] [segcolor] segment number (1), type, number of points, with optional index number and color (color is a RGB triple, 0-255 each)
3 X, Y, Z, radius [label] point location and radius of point 1, with optional label to be drawn at the point
4 X, Y, Z, radius [label] 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 [segindex] [segcolor] segment number (2), type, number of points, with optional index number and color
. X, Y, Z, radius [label] point location and radius of point 1
. X, Y, Z, radius [label] point location and radius of point 2
. . .
. . .
. X, Y, Z, radius [label] 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 adjustable by the user, either via the Landmark menu, or by specifying a color for the segment

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 2007-03-01