Subsections

4 Usage

This version of map3d provides two ways to load files. The first is via the command line, which is described in this section. The second is via the files window (see Section 8.5.1) This is a subset of map3d's usage:

 

  map3d  -b -nw -nv

         -f geomfilename 

           -w

           -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

      map3d -f geomfilename.pts

      map3d -f geomfilename.fac

      map3d -f geomfilename.geom
```
The first instance will run map3d and allow you to input files interactively (see Section 8.5.1). The first form with arguments 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, by means of an ``@'' suffix to the geometry filename specification. Calling
```
      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 provides an interactive means of specifying geometry numbers from a .geom file or time instants from a time series data file (see Section 8.5.1).

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 or resize individual windows, hold the Alt (meta) key and use the left and middle mouse buttons, respectively. Most of these can be anywhere on the command line. Also, if you use -b without any other arguments, map3d will allow you to select the files interactively and add them to this master window.
-v: = show current version of the program. If this is the only argument, the program will 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.
-c default_mesh_colour: = colour index to use on all surfaces for which there is no specific colour specification. This option must be set before any surfaces are read, since the same option sets the colors for individual surfaces.
-dp datafile_pathname: = directs the search for data files accessed to another directory. Using an alternate pathname, you can override the original directory specification for the files and get them from, say, an optical disk. This value can also be set with an environmental variable called MAP3D_DATAPATH, which you can set at any time before executing map3d. With this option, map3d looks in datapath/filename.

4.3 Geometry specifications

The basis for display in map3d is 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 (except for global options) 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. (It will do the same for data files as well.) Where there are multiple, potentially conflicting files with the same root, e.g., file.pts and file.geom, map3d will select binary over text files. See Section 6.2 for more details on the rules for specifying and reading geometry files.

-w

= place this and subsequent surfaces in a new window. This option will do nothing if the -nw option is set or if this is the first surface

-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. 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. Note also that if you omit the extension, as with geometry files, it will try to match a .pot or .tsdf extension for you.
-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. You can select other ranges from the menu and can select this one again with Scaling->Range->Command-line specified range.
-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. You can select other numbers of contours from the menu and can select this again with Contours->Number of Contours->Command-line spacing
-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.6 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 2004-04-08