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.3.1). You can also launch map3d with some command line options and then modify the associated settings using interactive menus and the files window.

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
             -ff fidfile
           -lm landmarks-filename
           -ll leadlinks-filename
           -lh

map3d also has other parameters it accepts that are designed for the use of a .map3drc or script file, and those parameters will be shown in table 21.

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.3.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.3.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.

-slw 0

= do not show any legend windows at startup.

-fs interval

= Sets the run-time interval between frames as accessed by the arrow keys. Note that this is independent of the -i option below, which subsamples the data as it is being read in. This feature can be changed via the menus at runtime.

-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 colour

= colour value 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. See the mesh-specific -c colour below for colour examples.

-bg colour

= colour value to use as background of all windows 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 windows.

-fg colour

= colour value to use as text colour for all windows 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 windows.

-if basefilename

= base filename for any image files that are generated in this run of the program.

-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.

-bgi image_filename

= An image file (in jpg or png) to display in the background. Used in conjunction with -bgp.

-bgi x1 y1 z1 x2 y2 z2

= Coordinates in world space to display the image specified with -bgp. If unspecified, the image will fill the geometry window.

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:

1. nodes (.pts) file will read and display only the nodes from the geometry; no display of the potentials is possible with just this information;

2. triangles/tetrahedra (.fac/.tetra) file will read both the connectivities and the nodes (provided both exist and share the same root filename);

3. 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.
4. binary matlab geometry (.mat) file contains both nodes and connectivity information and may also contain channel mapping. If there are multiple surfaces in the matlab file, the same restrictions apply as in the .geom files.

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

-fg colour

= desired colour for the screen information of a particular window, if this will be 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

-bg colour

= desired colour for the background of a particular window, specified as a red, green, and blue value triplet. See the -fg option for examples.

-c colour

= desired colour for the mesh of a particular surface, specified as a red, green, and blue value triplet. See the -fg option for examples.

-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.

-slw 0

= do not show the legend window for this surface.

-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

= filename for the potential and current data files. The legal file types for scalar data are:

1. Pot files (.pot) (see Section 6.3.1 are text-based files which contain one file per time instance.

2. Time-series data files (.tsdf) are binary files where all time instants are stored in one file.

3. matlab files (.mat) are also stored in binary format. Matlab files can also contain multiple time series.

4. Time-series container files (.tsdfc), contain references to at least one .tsdf file, along with other information about the time series. See Section 6.3.2 for more information.

The -s option determines how many frames to load. In the case of pot files, this controls which pot files to open (If -s is omitted, it will only open the pot file specified). For binary files, the -s option specifies the start and end frame numbers to be read from the file. With no -s option, map3d 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, .tsdf, .mat, or .tsdfc extension for you.

For files with multiple time series (matlab or tsdf containers), you may specify the time series by the command line with the ``@'' suffix appended to the filename followed by the time series index within the file.

eg., -p file.mat@1 reads the first time series and eg., -p file.tsdfc@2 reads the second time series.

-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. However, you must run map3d with the full pot filename (one of the pot files in the series).
eg., -p good-map001.pot -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. With the last few versions, this would still read in all the frames, but this version acts more like the versions prior to that, and subsamples the data.

-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. See section 6.1.5.

-ff fidfile

= Ascii file containing fiducial information. Information may be specified for each node for an arbitrary set of fiducial data. See section 6.3.4.

-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.

4.5 Other usage parameters

map3d accepts many other command-line parameters to customize the display. These are optimally used in a script, but here is a reference of options not described above.

4.5.1 Additional global parameters

These parameters affect all surfaces or windows in map3d.

-bw borderWidth titleHeight

Specifies the border width and the height of the title bar in pixels used in window placement calculations.

-l general transformation frame

Specifies whether the general, transformation, and frame locks should be turned on. Specify a 1 or a 0 for each, where 1 signifies to enable the lock, and 0 to disable.

-pm mode

Specifies the pick mode, where mode is an integer.

    0  New Window Mode
    1  Refresh Window Mode
    2  Node Info Mode
    3  Triangle Info Mode
    4  Triangulate Mode
    5  Flip Triangle Mode
    6  Edit Node Mode
    7  Edit Landmark Mode
    8  Delete Node Mode

-sc range function mapping

Describes the scaling model, with the specified scaling range, function, and mapping, each being an integer.

    Range (data min and max is relative to):
    0  Local
    1  All frames in current surface
    2  All surfaces in current frame
    3  All surfaces and frames
    4  All surfaces in current group in current frame
    5  All surfaces and frames in current group
    6  Slave scaling in current frame
    7  Scave scaling in all frames
    
    Function
    0  Linear
    1  Exponential
    2  Logarithmic
    3  Lab7
    4  Lab13
    
    Mapping
    0  Symmetric
    1  Separate
    2  True
    3  About Midpoint

4.5.2 Additional surface parameters

These options affect the current surface, if placed after the first [-f] on the command line, or all surfaces if placed before.

-sf size

Size of the small font, from 0-9

-mf size

Size of the medium font, from 0-9

-lf size

Size of the large font, from 0-9

-cm map

Which colormap the data will use, where map is an integer:

  0  Rainbow
  1  Green to Red
  2  Grayscale
  3  Jet

-sm mode

Selects the shading mode of surface data, where mode is an integer:

  0  No shading
  1  Flat
  2  Gouraud
  3  Banded
  4  Textured Gouraud

-rm mode

Selects the mesh rendering mode, mode being an integer:

  0  No rendering (mesh is not displayed)
  1  Points Only
  2  Mesh Elements
  3  Mesh Connectivity
  4  Elements and Connectivity
  5  Points and Connectivity
  6  Render only the mesh elements with no surface data

-ic num

Whether or not to invert the colormap, 1 meaning yes, 0 meaning no

-nco num

Sets the number of contours to num

-rq w x y z

Sets the rotation of the surface to the quaternion formed by (w,x,y,z)

-tc x y z

Sets the translation of the surface to (x,y,z)

-zf vfov

Sets the ``zoom factor'' or field of view to vfov

-el num

Whether or not to light the surface, 1 meaning yes, 0 meaning no

-ef num

Whether or not to display the surface with fog, 1 meaning yes, 0 meaning no

-gn num

Assigns the group number to num for group scaling

-sco num

Whether or not to show contours, 1 meaning yes, 0 meaning no

-nc num

Whether or not to show the negative contours as dashes, 1 meaning yes, 0 meaning no

-x num

Whether or not to show axes, 1 meaning yes, 0 meaning no

-xc r g b

Specifies the axes' color, with RGB numbers from 0-255

-sit num

Whether or not to show informational text, 1 meaning yes, 0 meaning no

-sli num

Whether or not to show the lock icons, 1 meaning yes, 0 meaning no

-nma sphere mark value

Settings for Node Marking: all. Sphere indicates whether to draw spheres for all nodes, 1 meaning yes, 0 meaning no. Value indicates whether to color the spheres based on their data value, 1 meaning yes, 0 meaning no. Mark indicates what to display at the nodes, mark being an integer:

    0  nothing
    1  Node number
    2  Channel number
    3  Data value

-nme sphere mark

Settings for Node Marking: extrema, where sphere and mark have the same meanings as [-nma], except the affect the extrema nodes

-nmp sphere mark

Settings for Node Marking: pick, where sphere and mark have the same meanings as [-nma], except the affect only the nodes that have an active ``Time Series'' Window open.

-nml sphere mark

Settings for Node Marking: leadlinks, where sphere and mark have the same meanings as [-nma], except the affect only the nodes that are represented in the active leadlinks file, except that a mark of 3 will display the lead label instead of the data value.