Subsections

4 Usage

 
  map3d  -b -nw -nv
         -f geomfilename 
           -as xmin xmax ymin ymax 
           -al xmin xmax ymin ymax
           -at xmin xmax ymin ymax 
           -t time-signal-number 
           -c mesh colour
           -p scalar data (potentials) filename 
             -s num1 num2 
             -i increment 
             -ph maxpotval 
             -pl minpotval 
             -cs contour-spacing 
             -ps scaling_value 
             -ch channels-filename 
             -sl surfnum
           -lm landmarks-filename
           -ll leadlinks-filename
           -lh

4.1 Typical usage examples

Here are some typical examples of using map3d:

Display the contents of a geometry file:
```
      map3d -f geomfilename.pts
      map3d -f geomfilename.fac
      map3d -f geomfilename.geom
```
The first form reads only the node points (.pts file extension) while the second form also reads the connectivities from a .fac file and displays both mesh and nodes. The third form assumes that a binary geometry file (.geom extension) exists that contains both nodes and connectivities. We describe all these forms of geometry files in Section 6.1.3.
Map scalar values from a single time instant stored in a ``pot'' file (described in Section 6.3.1):
```
      map3d -f geomfilename.fac -p datafilename.pot
```
When there is a mapping required between the potentials and the geometry, e.g., when the order of values in the .pot and .pts file are not identical, we require a channels file (see Section 6.4 for details of the channels files),
```
      map3d -f geomfilename.fac -p datafilename.pot -ch thefile.channels
```
To display a time series of scalar values on the geometry, the basic format is the same
```
      map3d -f geomfilename.fac -p datafilename.tsdf
```
with the time series stored in a datafile described in Section 6.3.2.
Geometry can also be stored in a binary file in the CVRTI format (described in Section 6.1.3). The command format is essentially unchanged
```
      map3d -f geomfilename.geom -p datafilename.tsdf
```
except that channel information is usually contained in the .geom file and thus seldom needs to be specified explicitly.
A time series data file (.tsdf) contains a sequence of potentials, as described in Section 6.3.2. To select a subset of the time series for display, append the parameters -s and, optionally, -i, for example,
```
      map3d -f geomfilename.fac -p datafilename.tsdf -s 1 100 -i 2
```
to select time instants 1 to 100 with an increment between instants of 2 (i.e., 1, 3, 5, 7, ..., 99).
Another way to describe a time series is through a series of .pot files that are numbered in sequence. For example to read a sequence of the files mapdata001.pot, mapdata002.pot, mapdata003.pot, ... mapdata009.pot
```
      map3d -f geomfilename.fac -p mapdata -s 1 9
```
Geometry files can contain more than one geometry so that we need to select a specific collection of nodes and connectivities for the display, but means of a suffix to the geometry filename specification. The calling string
```
      map3d -f geomfilename.geom@2 -p datafilename.tsdf
```
will select geometry #2 from the file geomfilename.geom.
Multiple instances of -f create multiple surfaces, which by default all appear in the same window. Adding the -nw option creates a separate window for each of the surfaces. So a typical call would look like
```
      map3d -f geomfile1.fac -p thedata1 -f geomfile2.fac -p thedata2
```
However, you can include all the regular features for each of the surfaces so that things can get much more complex. For multi-surface displays, it is often better to use script files (see Section 5) below.

This version of map3d does not provide an interactive means of specifying geometry numbers from a .geom file or time instants from a time series data file. If this information is not in the command line, the program takes the first surface and the entire time series, respectively. We will have this fixed soon, real soon...

4.2 Global Parameters

The following general parameters affect the entire display:

-b: = open each individual window without borders placed within a master window that still has the usual borders. To move individual windows, hold the Alt (meta) key and use the left and middle mouse buttons, respectively.
-v: = show current version of the program and exit.
-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.
-nv: = to NOT check validity of geometry files. This can have a large impact on startup performance if map3d needs to load large geometries.

4.3 Geometry specifications

The basis for display in map3d are one or more geometry descriptions, which are usually in the form of surfaces, but can also be a set of line segments or tetrahedra; hence we can picture each set of nodes and connectivities as a ``meta-surface'', which we generally refer to as a ``surface''. For each such surface, map3d needs the set of node locations in three-dimensional space and usually some connectivity information that defines the (meta) surface. The geometries must exist in discrete form and be stored in files that map3d can read (see Section 6.1.3 for details of the file formats). There is no provision at present for analytically defined geometries.

To tell map3d where to look for this geometry information, each occurrence of -f in the command line indicates that beginning of a new surface. All parameters that follow before the next occurrence of -f refer to the current surface.

-f geometry-file

= filename of the geometry file(s) containing points and connectivity information. Legal formats for the file specification are:

nodes (.pts) file will read and display only the nodes from the geometry; no display of the potentials is possible with just this information;
triangles/tetrahedra (.fac/.tetra) file will read both the connectivities and the nodes (provided both exist and share the same root filename);
binary geometry (.geom) file contains both nodes and connectivity information and may also contain channel mapping. At present, multi-surface geometry files must include a specific indication of the desired surface (@surfnum); otherwise, map3d reads all surfaces in the file.

Note: by specifying a root filename without any extension, map3d will look for all valid geometry files and try and construct the most comprehensive set. Where there are multiple, potentially conflicting files with the same root, e.g., file.pts and file.geom, map3d will ask the user for a decision of which to use. See Section 6.2 for more details on the rules for specifying and reading geometry files. Note also that a geometry specification is the minimal input for successful function of map3d.

-c colour

= desired colour for the mesh of a particular surface, specified as a red, green, and blue value triplet ranging from 0 to 255 Check these values. Some examples are:

255 0 0	red
0 255 0	green
0 0 255	blue
255 255 0	yellow
255 0 255	magenta
0 255 255	cyan
255 255 255	white

-as xmin xmax ymin ymax

= set the absolute location in pixels of the surface window most recently defined. We assume an origin in the lower left corner of the screen and the typical full screen of an SGI workstation with a 19-inch monitor has 1280 by 1024 pixels. This option is useful for setting consistent layout of windows, especially when there are multiple surfaces, each in its own window.

-al xmin xmax ymin ymax

= set the absolute location in pixels of the surface window most recently defined's colormap legend window. There will be one of these windows per surface only if a valid data file is associated with it.

-lh

= Set the most recently defined surface's colormap legend window to have a horizontal instead of vertical layout.

-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 6.5 below for details.

-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 lead locations on the torso surface that correspond to the standard ECG leads. The point of identifying such leads is to display them with their own markings, either as spheres or with the lead number (typically not the same as the node number). For more information, see the menu options in Section 8.2.3 that determine the form of the display markings and Section 6.4 for more information on leadlinks files.

4.4 Scalar Data parameters

To display scalar data values on the geometry, we must specify the source of the data and how to link them to the geometry. As with the geometry, all arguments specified between two occurrences of -f in the command line refer to the currently valid surface. Within pairs of -f options, there can be only a single instance of any of the following options:

-p potfilename: = base filename for the potential and current data files. For pot files (see Section 6.3.1 for details of the format), if the -s option is used, map3d will append a number and the extensions .pot to this base filename (see -s option). For binary time series (.tsdf) files, the -s option specifies the start and end frame numbers to be read from the file. With no -s option, map3d searches for a single .pot file named potfilename.pot or for a time series file named potfilename.tsdf and will read in all time instants from the file.
-s num1 num2: = range of frame numbers to read. If we are reading data from .pot or .grad files, map3d appends each of the numbers between num1 and num2 to the value of potfilename to make complete pot filenames.
eg., -p good-map -s 1 3 expands to:
good-map001.pot good-map002.pot good-map003.pot
If we are reading from a time series (.tsdf) data file, map3d will read frames num1 to num2 from the file.
-i increment: = difference between each frame number (initially). Regardless of how the data file(s) are read in, all frames are read in (or if the -s option is specified, all frames between the two points are read in). This enables the user to change the interval between frames while map3d is running.
-ph maxpotval: = maximum data value in ``user'' scaling mode. This sets one option for setting the range used in scaling the data value to colours and contours.
-pl minpotval: = minimum data value in ``user'' scaling mode.
-cs contour-spacing: = spacing between contours set by the user. This provides a menu option for selecting contours by setting a constant spacing rather than deriving the spacing from the desired number of contours and the range of data values. Note that the spacing will not always be a the command-line set value - map3d will divide the range by the specified value and set the number of contours as that number, and then determine the contour values by using that number of contours with the currently- selected scaling function.
-ps scaleval: = scaling value by which map3d multiplies each potential value as it reads from the file(s). This option tries to make use of any unit information available in a time series data file and alters the unit value available to map3d for display. The resulting scaling of the data is permanent for the current instance of map3d.
-ch 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 node locations when channel numbers are displayed. See section 6.4 for more information on the channels file format.
-lm landmarks-filename: = file in landmarks format containing a set of landmark segments, divided into categories. Each category has a word depicting the landmark type. Each lines within the categories contains three points (x,y,z) and an associated radius, which may have a different effect based on the type of landmark.
-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; in this way, one can compare colors across surfaces to determine relative values of the local scalar data.
-t timesignal-lead-number: = number of the node to be used for the display of a time signal in its own window. The number refers to either a node number in the geometry or, if a leadlinks file is present, the lead number. This command is optionally used in conjunction with the -at command, to specify a node and place its window accordingly. If the -at option is not present, map3d will choose a default window location. Multiple invocations of this option are possible for each surface, providing the option to open several windows per surface. At any time during the operation of the map3d the user can select a new node via the pick mode menu item and have the time signal from that node displayed (see Section 8.5 for details).
-at xmin xmax ymin ymax: = set the absolute location in pixels of a time signal window associated with the current surface. As with the -as option, the origin is in the lower left corner of the screen and the full screen resolution of an SGI screen with 19-inch monitor typically supports 1280 by 1024 pixels. This command is optionally used in conjunction with the -t command, to specify a node and place its window accordingly. If the -t option is not present, map3d will choose a default node (the first node in the geometry). Multiple invocations of this option are possible for each surface, providing the option to open several windows per surface.

Rob MacLeod 2003-02-10