8 Control of map3d

This section describes all the means of controlling the function of map3d, at least all the ones we are willing to tell you about.

8.1 Control by surface

There is an ever growing number of parameters that the user can alter for displaying the surfaces in map3d. Some of the more important (and stable) include the following:

Visibility:

of points, mesh, potentials, vectors, etc, can all be controlled individually by using the appropriate function key (see Section 8.2.2),

Lead markings:

of the nodes in the geometry according to their node number, channel number, lead number or even value,

Landmarks:

appearance of the landmarks on the surface.

Since this level of control is provided for each surface, it is possible to have points showing on one surface, mesh on another, and rendered potential shading on a third, and so on.

8.1.1 Selecting which surface to control

To control the display of each surface, be that a surface in its own window or sharing a single window with other surfaces, a user must select that surface. Otherwise, display options will affect all the surfaces. There are two different multi-surface situations and each has its own method of selecting the surface:

Selecting surfaces for display controls
Multi-surface layout	Selection method
One surface per window	Mouse location establishes currently active window.
Several surfaces in one window	Up/down arrows selects the surface. Hitting the up-arrow key after selecting the last surface selects all surface.

Note that in the surface window, the lock icons in the lower left corner indicate if parameter settings act on all surface (locks visible) or just single surfaces (locks invisible). Each lock controls a different aspect of map3d:

General Lock:

is represented by the yellow (or first) lock icon. When this lock is active, menu items and keyboard commands pertain to all surfaces. To turn this lock off and on use the up and down arrow keys.

Transformation Lock:

is represented by the red (or second) lock icon. When this lock is active, rotation and translation pertain to all surfaces. To turn this lock on and off, use the ``t'' key.

Frame Lock:

is represented by the blue (or third) lock icon. When this lock is active, frame advancing, retreating, and resetting pertain to all surfaces. To turn this lock on and off, use the ``f'' key or select from the menu under Frame Controls.

Note: in the case where all surfaces are in the same window, unlocking the general lock by means of the up or down arrow keys selects the single surface to display. However, when the general lock is active and either of the other locks is disabled, the active surface mesh appears in a different color (blue by default). This identifies the selected surface and all modifications apply to this surface. To select the desired surface use the (/) keys; ``('' selects the next surface and ``)'' selects the previous.

8.2 Mouse control, keyboard mapping, dials, and menus

Direct interactive control of map3d is by the keyboard and mouse. Many option are available via the menus controlled with the right mouse button, while others can be activated or toggled with single keystrokes. Variable (non-binary) adjustments usually occur through dialogues, or by repeating keystrokes. Below are tables of all the current control devices and their function. When the program launches, the user sets one or more windows which can be resized and moved at any time. When launching the program with the -b option, the resulting borderless sub-window(s) can still be moved and resized within a main window using the Alt-key together with the left and middle mouse buttons respectively. In Mac OS X and other operating systems where the Alt-key is mapped to another function you may use the CRTL+SHIFT keys as an alternative to the Alt-key.

8.2.1 Mouse control

The mouse can be used for different purposes. Figure 3 shows the various actions of the mouse buttons.

Figure 3: Mouse action for map3d. Picking makes intensive use of the mouse, as does moving objects in the surface window.

 

8.2.1.1 In surface windows:

when the mouse is over a surface window, mouse buttons have the following actions:

Mouse Actions
Control Key	Button	Action
None	Left	rotation objects
	Middle	scale objects (downwards increases size, upwards decreases size)
	Right	activate pull-down menu
Cntrl	Left	pick a node (and if time series data is present, select the channel to display in the time series window)
	Middle	no action
	Right	no action
Shift	Left	translate objects
	Middle	scale objects (rotates clipping planes if they are active - more info later)
	Right	no action

8.2.1.2 In borderless windows:

when the mouse is over a surface within a borderless main window (-b option), the buttons have the following additional actions:

Mouse Actions
Control Key	Button	Action
Alt(Ctrl+Shift)	Left	Move a single surface subwindow
	Middle	Resize single surface subwindow (no indication of change until release of mouse button).
	Right	no action

Note: if map3d does not respond as described in these tables, it may be that your window manager is grabbing the mouse/key combinations for its own purpose or maps the keys a little differently. This will require some setting changes for the window manager. In Linux there is usually a control panel or utility application to manage all window system interactions.

8.2.2 Keyboard controls

Each key of the regular keyboard, the function keys, and the keypad may be mapped to some function of the map3d. Some keyboard keys serve as toggles to change between a mode being on or off, e.g., ``n'' toggles the display of node markings. Others cycle through a set of choices, e.g., ``m'' runs through a series of display options for the mesh. Several lists of the keyboard keys and their functions are shown in Tables 1-4.

Table 1: Keyboard controls for Geometry Window in map. When control contains both lower and upper cases of a letter, one cycles through a parameter in one direction and the other in the reverse direction.

Regular keyboard
a/A-key	Switch colour tables
c-key	Toggle contour draw
d-key	Toggle depth cuing
f-key	Toggle frame lock (also in Time signal window)
g-key	Toggle style of Gouraud shading (between texture-mapped and non-texture-mapped)
i-key	Toggle ``direction'' (invert) of color table
l-key	Toggle use of lighting
m/M-key	Step through mesh/node drawing options
n-key	Toggle display of node labels (some node marking must be selected)
p-key	Toggle information in time signal (pick) window (also in Time Signal Window)
q-key	Quit or destroy a sub-window - Legend Window and Time Signal Window only (Escape quits the whole program)
r-key	Reset to startup conditions
R-key	Reset shading model (to wireframe rendering)
s/S-key	Cycle through the various surface data draw options
t-key	Toggle transformation lock
w-key	Write an image to a file. This will append a 4-digit number representing a image sequence number to the base filename (before the extension). The base filename can be set at start-time with the -if flag (see Section 4.2), or in the Save... Dialog (Section 8.3.2).
x-key	Draw axis
Escape	Quit the program, if pressed in a Geometry Window, or Destroys a Time Signal Window if pressed there.
+/- key	Increases/Decreases size of of currently-selected object (see Section 8.5.3)
( & ) keys	Change which surface inside a window will be affected when the general lock is on but the transform or frame lock is off (see Section 8.1.1)

Table 2: Clipping plane controls

Clipping Controls
<-key	Toggle front clipping plane
>-key	Toggle rear clipping plane
[ & ] keys	Move front clipping plane in (initially) +z/-z direction respectively
{ & } keys	Move rear clipping plane in (initially) +z/-z direction respectively
,-key	Lock/Unlock clipping plane rotation with object rotation (when unlocked, shift-Middle-click rotates clipping planes)
.-key	Lock/Unlock clipping planes from each other. When active, clipping planes move together

Table 3: Control of map3d via the arrow keys

Arrow Keys
Left Arrow Key	Retreat by current frame step (Also in Time Signal Window)
Right Arrow Key	Advance by current frame step (Also in Time Signal Window)
Up Arrow key	Select next surface
Down Arrow Key	Select previous surface

Table 4: Keypad controls in map3d - have NUM-Lock off for these to work properly. Again, based on how you have your keys mapped, you might have to use the non-keypad keys, but something should work for you for each key.

Keypad Keys
Ctrl-Keypad Left-arrow	Y-axis rotate, CW (left)
Ctrl-Keypad Right-arrow	Y-axis rotate, CCW (right)
Ctrl-Keypad Up-arrow	X-axis rotate, CCW (down)
Ctrl-Keypad Down-arrow	X-axis rotate, CW (up)
Ctrl-Keypad Home	Z-axis rotate, CCW
Ctrl-Keypad PgUp	Z-axis rotate, CW
Ctrl-Keypad End	Zoom down
Ctrl-Keypad PgDn	Zoom up
Alt(or CRTL+SHIFT)-Keypad Left-Arrow	-X-translation (left)
Alt(or CRTL+SHIFT)-Keypad Right-Arrow	+X-translation (right)
Alt(or CRTL+SHIFT)-Keypad Down-Arrow	-Y-translation (down)
Alt(or CRTL+SHIFT)-Keypad Up-Arrow	+Y-translation (up)
Alt(or CRTL+SHIFT)-Keypad Home	-Z-translation (away)
Alt(or CRTL+SHIFT)-Keypad PgUp	+Z-translation (towards)
Plus/Minus key	Increase/Decrease size of currently-selected object. (see Section 8.5.3)

8.2.3 Menu layout

Access to the menus is by means of the right mouse button, as per the usual OpenGL convention. Below is a series of tables of the menu layout for map3d's Geometry Window.

.

Table 5: The overall menu structure in the Geometry Window

Overview of Geometry Window menus
Files	Opens the Files Window (see Section 8.3.1)
Save	Opens the Save Window (see Section 8.3.2)
Contours	number or spacing and display features of the contours
Fiducials	Fiducial display features - Currently only opens the fiducial dialog. (See Section 8.5.6)
Frame Controls	modifying frame controls
Graphics	general display features such as lighting, clipping, and depth cuing
Landmarks	features for toggling and displaying landmarks
Mesh	display features of the mesh
Node marking	marking of the nodes
Picking	selecting times signals, mesh information, or other direct interactions with the display via the mouse
Scaling	links between data values and color
Surface Data	display features of the scalar data displayed on the mesh
Use +/- to select	Select a feature to change interactively with + or -
Window Attributes	features of the windows such as color and text labels

Table 6: Menus for contour spacing/number.

Contour Menus
Set Contour Num/Spacing		Opens a dialog to change user-specified spacing or number of contours. See Section 8.5.5.
Draw style
	Dashed line for negative values	draw positive contours in solid, negative in broken lines
	Solid lines for all contours	draw all contours in solid lines
Line size		set the line thickness
Toggle contours		toggle display of contours without changing settings

Table 7: Frame Controls.

Frame Control Menus
Lock Frames		toggle whether frames operations affect one surface or all surfaces
Set Frame Interval
	Set Frame Step	Opens a dialog to interactively set User-specified frame step. Affected surfaces are determined by the lock status.
	User-specified Interval	use the value of interval specified in the -i option of the command line or the value set in the frame step dialog.
	value	select between 1 and 90 for frame animation step
Reset Frames to 0		positions the surface at the first position in time
Align meshes to this frame num		Positions all surfaces' frames to the current surface. What 'current surface' means will vary based on the status of the locks (see Section 8.1.1)
Set time to zero		Set current frame to be time zero.

Table 8: Graphics menus. These control general graphic rendering options.

Graphics Menus
Light source		select the source for the lighting model
	From above
	From below
	From left
	From right
	From front
	From back
	None	no lighting (turn lighting off)
Toggle clipping		toggles particular clipping plane options
	Front plane	toggles front clipping plane
	Back plane	toggles rear clipping plane
	Locking planes together	makes planes translate together
	Locking planes with object	rotate surface with the planes or rotate surface through the planes
Toggle Depth cue		apply/disable depth cuing (fog)
Adjust Depth cue		Opens a dialog to adjust the front and rear planes to where the depth cuing occurs.

Table 9: Submenus for the Mesh Display menu

Mesh render menu
Render as
	None	Do not render the mesh
	Elements	render filled surfaces for all elements
	Connectivity	render connectivity mesh
	Elements and connectivity	rendered front facing triangles as elements and back facing as connectivity
	Points	render points
	Points and connectivity	render both points and connectivity
Line/point size	set the size of the mesh's points and lines
Color	set the color of the mesh
Secondary Mesh Color	set color of active mesh when multiple surfaces are in same window
Show Legend Window	display mesh's legend window
Hide Legend Window	turn off display of mesh's legend window
Reload Geometry	reload file associated with this geometry
Reload Surface Data	reload file associated with this geometry's surface data
Reload Both Geometry and Data	reload files associated with this geometry and its data

Table: Menus for marking nodes in the display. If all surfaces are currently displayed, any of these settings will affect all surfaces based on the rules in locks section (see Section 8.5.3). If we have a single or current) surface only, then change only that surface.

Node Marking Menus
All		Make all the nodes in this (or all) surface(s)
	Sphere	mark each node with a sphere
	Map data to spheres	mark each node with a sphere, whose color reflects its scalar data value
	Node #	mark each node with the node number in the geometry
	Channel #	mark each node with the associated data channel number
	Data value	mark each node with the associated data value
	Color	set the color for marking all nodes
	Size	set the size of all node markings
	Clear all marks	remove all node marking settings
Extrema		Make all the nodes that are the extrema
	Sphere	mark each extrema with a sphere
	Node #	mark each extrema with the node number in the geometry
	Channel #	mark each extrema with the associated data channel number
	Data value	mark each extrema with the associated data value
	Size	set the size of all extrema markings
	Clear all marks	remove all extrema marking settings
Time signal		Make all the nodes that identify the location of time signals shown in the display
	Sphere	mark each times signal location with a sphere
	Node #	mark each times signal location with the node number in the geometry
	Channel #	mark each times signal location with the associated data channel number
	Data value	mark each times signal location with the associated data value
	Color	set the color for marking all times signal locations
	Size	set the size of all time signal markings
	Clear all marks	remove all time signal marking settings
Lead links		Make all the nodes that identify the features from leadlinks file (see Section 6.4) shown in the display
	Sphere	mark each lead location with a sphere
	Node #	mark each lead location with the node number in the geometry
	Channel #	mark each lead location with the associated data channel number
	Data value	mark each lead location with the associated data value
	Lead labels	mark each lead with the label from the leadlinks file.
	Color	set the color for marking all lead locations
	Size	set the size of all lead markings
	Clear all marks	remove all lead marking settings

Table 11: Pick mode menus, part 1. Picking is based on a mode (selectable in this menu), and is done with CTRL-left mouse button unless otherwise specified.

Picking Menus I
Time Signal (new window mode)	create a new time signal window with each pick of a node
Time Signal (refresh window mode)	update the last time signal window with each pick of a node
Display node info mode	Picking will cause certain node information to be dumped to the console.
Display triangle info mode	Picking will cause information about the triangle you click in to be dumped to the console. It may be easier to pick triangles with clipping planes on.
Triangle construction/deletion	Normal picking (ctrl-clicking on nodes) will select points to form a triangle (triangulate). Clicking the first two nodes in this fashion will display the selected nodes, and then a line between the two. When the third is clicked, a new triangle is displayed and added to the geometry.
	CTRL-middle clicking selects a triangle (and not nodes) to be deleted. Again, it may be easier to pick triangles with clipping planes on.
Flip triangle mode	Will change the order of drawing the triangle's points. This will cause front-facing triangles to become back-facing and vice-versa.
Edit node mode	Will allow you to pick a point and translate it with the keyboard transform controls (see Section 8.2.2, keypad controls)
Edit landmark point mode	Will allow you to pick a landmark point and translate it with the keyboard transform controls (see Section 8.2.2, keypad controls)
Delete node mode	Will remove from the geometry any node that you pick and any triangles associated with it.

Table 12: Pick mode menus, part 2. Picking is based on a mode (selectable in this menu), and is done with CTRL-left mouse button unless otherwise specified.

Picking Menus II
Reference lead, single value	Causes all values to be measured against the node which you pick
Reference lead, mean value	Causes all values to be measured against a mean value of all the nodes
Reset Reference	Causes the reference and values to be reset to its original value. You must reset the reference if you want to change the reference more than once.
Show Time Signal Window info	Toggles display modes in time series window. When there is no info, the graph takes up more room in the window. This is equivalent to pressing 'p' in a geometry window or selecting the toggle display mode option of a time series window's menu.
Show all pick windows	Causes all Time Series (Pick) Windows associated with this geometry to become visible.
Hide all pick windows	Causes all Time Series (Pick) Windows associated with this geometry to become hidden.
Size of picking aperture	select the size of the region around the mouse pointer that will register a ``hit'' when picking; larger values will make it easier to pick an object but also easier to hit multiple objects.
Size of triangulation node mark	when triangulating, a node mark will appear on the node(s) selected. Adjust that mark's size.

Table 13: Menu for scaling, the mapping from data value to color for rendering.

Scaling Menus
Scaling...	opens up the scaling dialog. (see Section 8.5.4)
Range
	Local	scale based on the local extrema for each surface and time instant
	Global over all frames in one surface	scale based on the extrema over the full times series
	Global over all surfaces in one frame	scale based on the extrema over each surface for the local time instant
	Global over all surfaces and frames	scale based on the extrema over all surfaces and all time instants
	Scaling over groups in one frame	scale based on the extrema over each surface in specified group for the local time instant
	Scaling over groups in all frames	scale based on the extrema over each surface in a specified group for all time instants
	Slave Scaling over one frame	scale based on the extrema over each surface's master surface (set with -sl in command line) for one time instant
	Slave Scaling over all frames	scale based on the extrema over each surface's master surface (set with -sl in command line) for all time instants
Function
	Linear	linear mapping between value and color
	Logarithmic	color changes as $\log({\rm value})$
	Exponential	color changes as $\exp({\rm value})$
	Lab standard	color reflects lab standard
	Lab 13 standard	color reflects lab 13 standard
Mapping
	True	use true extrema
	Symmetric about zero	take largest of absolute values of extrema to determine scaling
	Symmetric about midpoint	scale independently on both sides of the midpoint to determine scaling
	Separate about zero	scale positive and negative portions of the scale independently
Grouping
	Move to group #	Select a group to place the current surface (make sure the general (yellow) lock is off, or all surfaces will be placed in that group)

Table 14: Submenus to control the display of scalar data on the mesh.

Surface Display Menus
Color
	Rainbow	use rainbow color map to render scalar values on the mesh
	Green to red	use green to red color map
	White to Black	use black and white color map
	Invert	invert the sense of any color map, e.g., black becomes white and white becomes black
Render style
	None	Turn Shading off
	Flat	colour each mesh element in a constant color according to the mean value of scalar data over the vertices
	Gouraud	shade each polygon using linear interpolation
	Banded	draw the regions between contour lines as bands of constant color

Table 15: The Use +/- to interactively change sizes menu

+/- Adjust Menu.
Large Font Size	Change the largest font size (This is the title for the Colormap and Geometry windows)
Medium Font Size	Change the medium font size (This is all text not small or large)
Small Font Size	Change the small font size (This is the size for the node marks, the axis labels in the Time Signal Window, and the Contour Labels in the ColorMap Window)
Contour Size	Change the contour width
Line/Point Size	Change the width of Lines/Points in the mesh
Node Marks (all) Size	Change the width of node marks
Node Marks (extrema) Size
Node Marks (time signal) Size
Node Marks (leads) Size
Change in translation	Change how fast the keyboard translation happens
Change in scaling	Change how fast the keyboard scaling happens
Change in rotation	Change how fast the keyboard rotation happens

Table 16: Controls for the attributes of the map3d windows.

Window Attributes Menus
Screen info		select the text written to the screen. Note that screen info disappears when clipping is on.
	Turn screen info on
	Turn screen info off
	show/hide lock icons	toggle lock display
	Show Legend Window	Turns on Colormap window
	Hide Legend Window	Turns off Colormap window
Color		select window colors with the separate color selector
	Background	select background color for the window
	Foreground	select foreground color for the window
Size		select some size options
	value	set window to specified resolution
Axes		select options for axes
	Axes Color	Select axes color
	Axes Placement	select whether axes displayed per window or mesh
	Toggle Axes	turn on/off axes
Font Size		Use the Size Picker to adjust the font size
	Small Font Size	Size of node mark text or Colormap window contour ticks
	Medium Font Size	Size of window subtitles or text in Pick Window
	Large Font Size	Size of Window titles
Toggle Transformation Lock		toggle whether surfaces transform together or independently

Table 17: Controls for the attributes of the Time Signal Window.

Time Signal Window Controls
Axes Color	Select Axes Color
Graph Color	Color of data graph
Toggle Display Mode	Show basic values and graph, show detailed values and graph, or show larger graph

Table 18: Controls for the attributes of the Legend window.

Legend Window Controls
Orientation		Layout of information in Legend Window
	Vertical
	Horizontal
Number of Tick Marks		select number of ticks to appear on bar
	2,4,8	Either 2,4,8 ticks. These will not be colored as they do not directly correspond to contour values.
	Match Contours	Match number of contours in corresponding geometry

.

Table 19: Controls for the Legend Window Menu

Main Window Controls
Set Background Color	Select bg Color
Quit Map3D	Quit Map3D

8.3 Interactive GUIs - File Selection, File Saving, and Scaling Options, etc,

With the move to a dedicated GUI system (in our case, gtk), we make use of a number of different windows to select parameters and control map3d. This section covers the functionality of all of them.

8.3.1 Files Window

Figure 4: Files Dialog for map3d.

 

The most frequently used GUI window is the ``map3d Files'' window, allows you to interactively select filenames, data windows, etc. The others are for saving files, and for quick scaling changes. Figure 4 shows an example of such a file window, and access to this window is by means of the ``Files'' menu option of the main menu. This window displays one row for each surface, where each row shows the surface number, the window the surface appears in, the geometry filename, the geometry number, the data filename, the start frame number, the end frame number, a graph of the RMS curve, and a button to show other files. Most of these columns can be modified at any time. If you click on the ``New Surface'' button, an empty row will pop up, allowing you to add a surface from scratch.

None of the changes made to this window will take effect until you click on the ``Apply'' button. The ``Close'' button will cause the window will close, but opening it again will reveal the same content.

Table 20: Options for the file window

File Window Options
Surf	Number of the surface
Win#	Number of the window that contains this surface. You can change this number to move the surface to any open window, or to a new window (by selecting the last number from the drop-down menu).
Geom File	Name of the geometry file of this surface. To change the geom file click on the ... button and then browsing for the desired file. You may reload the current geometry by selecting the ``Mesh$\Rightarrow$Reload Geometry'' menu entry.
Geom#	Number of surface within the geometry file (see Section 6.1.3). If there is more than one surface in the geometry file, an associated drop-down menu selects which one to insert.
Time Series File	Name of the data file of this surface. As with geometry clicking on the ... button launches a file browser to select a time-series data file. Selecting the ``Mesh$\Rightarrow$Reload Data'' reloads the data.
Start Frame	Start reading data at this frame. Left-clicking in the graph section and dragging will also select the correct frame.
End Frame	Finish reading data at this frame. Middle-clicking in the graph section and dragging will select the correct frame.
Graph	Graph of the root-mean-square signal calculated from all signals in the time series. Left- or middle-clicking in this graph selects the data window that map3d will read and display.
Other Files	This button will pop open another window in which to view/modify the channels, leadlinks, landmarks, or fiducial file to use with this surface.

Figure 5: Empty Files Dialog. map3d will start up this way if launched without arguments.

 

Note that the File window allows launching of map3d without any arguments. In this case an empty file window appears, as in Figure 5 so that the user can select all the files for display and set up the display interactively.

8.3.2 Saving Files

Figure 6: Saving Dialog.

 

The ``Save...'' Window will appear if after selecting ``Window Attributes$\Rightarrow$Save...'' from the main map3d menu. The first section is for saving geometry files, the second is for images, and the third for settings.

8.3.2.1 Saving Geometry

The Geometry section displays each surface number with its current geometry filename and next to each is a check box. If that check box is checked when the user clicks one of the save buttons, then that surface will be one of a set that is saved. If the second check box (labeled Transform?) is checked, then map3d will save the geometry will be saved with the current transformations (translations and rotations) applied.

Make sure to modify the filename or the current filename will be replaced ( clicking on ... launches a browser for a filename). If the filename ends in the extension .fac, it will save filename.fac and filename.pts. If the filename ends in .geom, it will save the file in the CVRTI binary file format (see Section 6.1.3). If Transforms is selected and there is a landmarks file, then a filename.lmark.

Clicking on the ``Save in 1 geom file'' button will save all of the geometry into one CVRTI binary file (see Section 6.1.3), choosing the filename of the first entry, which must have a .geom extension. Clicking ``Save individually'' will save each in its own filename. There is currently a known bug with saving .geom files under Windows and reading them back in again.

8.3.2.2 Saving Images

In the image section, select a filename (you can click on ... to browse for a filename) and click save. The filename may have the extension .ppm, ,png, or .jpg to save in one of those formats. The final filename also appends a 4-digit number before the extension, representing a number in a sequence of images. I.e., if the filename selected is map3d.png, the image will actually save in map3d0000.png, and subsequent images will be map3d0001.png, map3d0002.png, etc. The image that will saved is approximately the smallest rectangle that contains all open map3d windows.

NOTE: If there are windows that overlap, the one on top might not be the one map3d thinks is on top. So if after moving windows around, it is necessary to click inside the window (not the title bar), to tell map3d it is on the top. Otherwise, data that appears on the computer screen may end up obscured by other windows that appear to lie beneath.

If the Save... window is in the way, close it, and pressing the 'w' key will have the same effect as clicking the ``Save Image'' button.

8.3.2.3 Saving Animations

This section allows you to control automatic frame saving to put images together into movies. While map3d is not yet sophisticated enough to actually create the movies, this control can save the images you need and then you can use some external software to make a movie from them. See Section 9.1.2 for links to instructions of how to make movies from sets of images.

There are four controls to select when an image will be saved.

1. Save Frame on Transformation - will save a frame (image) every time you transform (rotate, translate, scale) any surface, either with the mouse or the keyboard.
2. Save Frame on Frame Advance - will save a frame when you move forward or backward in time with the arrow key, or change the time in the pick window.
3. Save Frame on Other Events - will save a frame when you interact with with the Geometry Window in any other way, via keyboard commands or menu controls.
4. Save Frame Every x milliseconds - A frame will be saved approximately every x milliseconds, depending on whether map3d is doing something else (like saving an image for one of the other controls). This option will only take effect if you select it while animations are not being saved.

Naturally, animations start recording when you click the ``Start saving animations'' button, and end when you click the ``Stop saving animations'' button. If you close the window while animations are being saved, they will keep recording (this is useful if the Save... window gets in the way of the images you want to save).

8.3.2.4 Saving Settings

map3d saves two types of settings files. There is the .map3drc file, which acts as a settings file which (if in your home directory or in the directory in which you run map3d) will load a list of options at start-time, so map3d can behave similarly each time you run it without having to reset options manually.

The other type of setting file is a script (or batch) file (See Section sec:scripts). map3d will attempt to save exactly what you have loaded, including all files and window positions. The difference between a script and a batch file is that a batch file is designed for MS Windows, and a script is designed for everything else.

To save a script/batch file, click on the appropriate button and select a filename. If you choose to save a .map3drc file, you cannot change the filename.

The only real difference between scripts and the .map3drc file is that the .map3drc file saves global options and the options set on the first surface (which then will apply to all surfaces), and scripts save information about all surfaces. The options they save are the same, so they are grouped together.

These options are added to the command line. For the script, the options are saved as command line arguments, and for the .map3drc file the options are saved to a file and when map3d is executed, the options get inserted into the command line before any other arguments. Note that this also happens when you run map3d from a script. Also note that the options set in the .map3drc file may be overridden by subsequent arguments. (Naturally, both the .map3drc file and the script file may be edited by hand.)

These are three types of options that map3d can save: global options, which are set independent of any surface; surface transformations, which will save the rotation, translation, and scaling of the surfaces; and other surface options, which save everything else. You may select or de-select any of these three items as you wish. Note, if none of them is selected and save a .map3drc file, it will be empty. If none is selected and you save a script, then it will save the filenames and the window information.

The options are as follows (some of these are mentioned in the usage - Section 4). Some of the values are unclear (like the -sc scaling option) as to what the result will be if you edit it by hand. Future versions of map3d will make this more clear. See Section 7 for more information on these features.

Table 21: Settings options

Global Options
-b	Run map3d in borderless mode
-nw	Assign each surface its own window
-sc range function mapping	Sets the global range, function, and mapping based on each number. Range can be a number from 0-7, function from 0-4, mapping from 0-2.
-l general transform frame	general, transform, and frame are 0 or 1 based on whether or not the general, transform, and frame locks are set, respectively.
-rl level	Sets the report level to level
-pm mode	Sets the pick mode to mode (mode is a number from 0-12).
Surface Transformation Options
-rq w x y z	Rotation Quaternion. These are 4 floating-point values which represent the rotation info
-tc x y z	x, y, z translation coordinates
-zf factor	Zoom factor. This really applies to the window as opposed to the surface
Other Surface Options
-c r g b	Mesh Color, red, green, blue values
-sm mode	Shading model (flat, Gouraud, banded) - mode is a number between 0-3
-rm mode	Mesh render mode (dots, connectivity, etc.) - mode is a number between 0-5
-ic mode	Inverted Colormap - 1 for true, 0 for false
-slw mode	Show colormap legend window - 1 for true, 0 for false
-el mode	Lighting enabled - 1 for true, 0 for false
-ef mode	Fogging (depth cue) - 1 for true, 0 for false
-sco mode	Contours shown - 1 for true, 0 for false
-nc mode	Negative contours dashed - 1 for true, 0 for false
-x mode	Axes drawn - 1 for true, 0 for false
-xc r g b	Axes Color, red, green, blue values

8.4 Controlling the time signal window

There are two ways to create a time signal window:

1. Specify a -at xmin xmin ymin ymax on the command line (optionally with a -t trace-lead-number to specify the channel to use).
2. Using picking (Cntrl-left mouse) to select a lead to show in the time signal window, when the current pick mode is time signal new-window mode or time signal refresh mode. Note that subsequent time signal picking can be set to either a) update the last time signal window to the new data channel or b) add yet another time signal window.

The format of the scalar display is fairly simple , with a vertical bar moving along the time axis as the frame number is advanced. map3d derives the time axis label from the frame numbers of the signal relative to the time series data file, not relative to the subset of frame read in, i.e., if frames (or pot file numbers) 10-20 are read in with an increment of 2, then frame number will begin at 10, and go through 12, 14, 16, 18 and end at 20 rather then beginning at 0 or 1 and going to 10 (the number of frames of data actually read).

8.4.1 Adjusting the frame selector

In order to facilitate rapid movement through large datasets, the user can control the frame number being displayed by interacting with the scalar window itself. If the user moves the cursor to the scalar window and pushes the left mouse button, the vertical time bar will jump to the nearest sample to the cursor location. The user can then hold the left button down and slide the time marker left and right and set a desired frame. Once the mouse button is released,map3d updates the map display. The left and right arrow keys also shift the frame marker back and forth. The only other command allowed when the cursor is within the scalar window is the ``q''-key, to shut down just the scalar window, the ``f'' key, to toggle the frame lock, or the ``p'' key, to toggle the display mode. Any other attempt at input will not be accepted.

8.5 Color/Size Selection

It is frequently necessary to control color and size of elements of the map3d display and this, we have selection subwindows that appear as necessary and disappear upon selection.

8.5.1 Color Picker

Figure 7: Color Picker.

 

The Color Picker shows a number of colors to select from. There are only a limited number of colors so that the color selection can be easily reproduced on subsequent runs. When you open up the Color Picker, the current (original) color will be in a small box on the bottom left, whereas the box next to it will show the color that was most recently selected. There is a new ``Preview'' button which will change the color and let you see what it would do, but will also allow you to push the ``Cancel'' button and return to the original color, shown in the bottom left.

8.5.2 Size Picker

Figure 8: Size Picker.

 

The Size Picker shows 10 sizes to select from, currently (to change later) represented by the size of boxes, where the width of the box represents the selectable size. When you open up the Size Picker, the current (original) size will be represented in a box on the bottom left, whereas the box next to it will show the size that was most recently selected. There is a new ``Preview'' button which will change the size and let you see what it would do, but will also allow you to push the ``Cancel'' button and return to the original size, shown in the bottom left.

8.5.3 Interactive Size Control

Rather than having to open the Size Picker over and over, map3d provides a few options that can be changed by a single keystroke. To do this, open the menu in the Geometry Window and select ``Mesh->Use +/- to select'' and then select a feature you wish to dynamically adjust. Then press + or - to adjust the size. However, most of these only have 10 possible sizes.

8.5.4 Scaling Options

Figure 9: The three tabs of the Scaling Dialog.

 

This three-tabbed dialog contains the same options as the Scaling Menu in the Geometry menu, but in dialog form for convenience. Click on the tab at the top of the scaling type you wish to change (Range, Function, or Mapping), and click on the check box of the feature you wish to select, and map3d will update. (see Section 8.2.3, scaling menu) and Section 7.4.1.

8.5.5 Contour Setting Dialog

Figure 10: Contour Spacing Dialog.

 

The contour setting dialog allows selection of the contour spacing, number of contours and scaling range. A side-effect of this dialog is that a change of one feature has consequences on other features. For example, changing the number of contours will likely also change the spacing between the contours. Alternatively, it could change the range of the scaling, i.e., the maximum and minimum used to map value to color. This interdependence of the control parameters can make this dialog somewhat obscure but it does allow broad flexibility of settings.

There are two controls that affect the interplay among features. The bar at the top contain two buttons: ``Keep spacing constant'' and ``Keep num contours constant''. The choice between these two will determine which parameter will remain constant when the range changes (the range can change by selecting a different contour or by setting the range explicitly).

A second, related control is the ``Default Range'' check box on each row. If it is checked, then changing the contour spacing will affect the number of contours and vice-versa. If it is unchecked, then changing the number of contours or the spacing will affect the range, and changing the range will affect the feature that is not held selected in the top bar. Also, unselecting ``Default Range'' will set the scaling range for this surface to the range specified in the contour dialog and will not reflect the default range parameter.

Upon pressing ``Preview'' or ``Okay'', the changes will take effect. Note that the exact contour spacing will only take effect if the scaling function is set to Linear and the mapping is set to True. Otherwise, an approximate contour spacing will result.

This description may sound confusing but some trial and error should hopefully provide complete control over the display of scaling features. Complexity is the cost of flexibility and when in doubt, we have always tended toward flexibility.

8.5.6 Fiducial Control

Figure 11: The Fiducials Control Windows.

 

There are two windows that allow control of the display of temporal fiducials in map3d. Fiducials are time markers in the signals, for example, indicating the time of activation or the start and end of the QRS complex in an ECG. Because the main application domain of map3d is cardiac electrophysiology, the selection of support fiducials is related to signals from the heart. However, there is not reason one could not add new fiducials (contact Rob MacLeod (macleod@cvrti.utah.edu))

There are two dialogs because there are two ways of viewing fiducials.

1) Single fiducial contour:

in this mode, map3d draws an isochrone line over top of the potential map that corresponds to the time value of the current potential map. This sounds complicated but it means that, for example, if the potential map has a time value within the range of activation times for the time series, then somewhere on the map will be an isochrone corresponding to that activation time. In practice, one sees the activation contour expand with each step in time and can also perform quality control of any fiducial detection algorithm

The lower window in Figure 11 allows control of the display of the contour, setting the contour thickness and the color associated with each time of fiducial.

2) Multiple fiducial contours or maps:

This is the more traditional model of fiducial map display in which the entire set of isochrone values maps up a map. To enable simultaneous viewing of potential and fiducials in this mode, map3d provides a number of options controlled by the upper interface window in Figure 11, the ``p''-key, and the ``s''-key. With various combinations, it is possible to display a) potentials as shaded maps with black isochrones, b) no potentials with colored isochrones, and c) potentials as black contours drawn over shaded color isochrone map. The window allows selection of the particular fiducial to display.

Figure 12: Examples of fiducial displays. Panels A, and B show different forms of activation contour display over shaded potential maps. Panels C and D show displays of shaded activation maps with superimposed potentials (Panel C) and a single activation contour (Panel D). Panel E shows a contour display of activation time.

 

Figure 12 shows different forms of display of activation times using the fiducial display options. The choice of which is most informative depends on the perspective of the user and the problem at hand. The images in Panel A and D are useful to perform a quick quality control of that fiducial map. Panel B supports a more detailed analysis by allowing the user to step through time and see fiducial contours associated with each time value superimposed on the potentials. In this way, the user can use spatial information to evaluate the quality of the fiducial values. For a more temporal view, the user can click on any number of time signals (see Figure 2) and see the fiducial markers superimposed as vertical lines that are color coded according to fiducial type.

8.6 Picking mode

By ``picking'' we mean selecting some piece of the display in the current window using the mouse. map3d currently supports selection of nodes or triangles with different actions, all of which either return some information, affect the display, or even alter the geometry of the display. The current choices include node information, triangle information, time signal displays, triangulation, triangle deletion, triangle flipping, node editing/deletion, landmark editing. Note that picking is successful and the desired results occur only when there is one (no more, no less) hit. To aid in getting the one hit, you may adjust the picking aperture or activate the clipping planes. In any picking mode where your geometry is modified, you might want to save your geometry (see Section 8.3.2). To control picking, use the top-level ``Picking'' menu. See Tables 11 and 12 for the available options.

Time Signal (new window mode):

This mode opens up a new window and provides information about the node/channel. It tells the node number, channel number, the associated surface, the current frame number, and the value of the scalar data at the current time instance. In addition, it shows a graph of the scalar data associated with that node over time.

Time Signal (refresh window mode):

This mode provides the same information and graph as the new window mode, but displays the information in the most-recently created window (and creates one if one doesn't exist).

Node Information:

This mode outputs information of the selected node to the console: Surface number, frame number, node number, channel number, current data value, and the X,Y,Z coordinates of the point (as read by the geometry file).

Triangle Information:

This mode outputs information of the selected triangle to the console: Surface number, triangle number, and the numbers and X,Y,Z coordinates of the 3 triangle points (as read by the geometry file).

Triangle Construction (Triangulating) and Deletion:

In this mode, the left mouse is used to select the nodes that you wish connected into a triangle. Note that each time you select a valid point a change is made to the geometry. The first valid point you will see a new point on the mesh. The second will be similar except there will be a line connecting the two points, and the third time will add the completed triangle to the geometry

Pushing CTRL-middle mouse button selects a triangle and kills it, removing it from the list.

Triangle flipping:

Often it is necessary to know the orientation of the triangles in the geometry. While this can be computed, there remains a 180-degree ambiguity as to which way the normal points. To resolve this, triangles nodes should be ordered in a counterclockwise direction as viewed from the ``outside'' of the surface to which the triangle belongs. This convention is used by OpenGL to decide which triangles to show in ``hide back-facing triangles'' mode. Unfortunately, it is not always possible when constructing geometric models to tell which way the triangle is to be viewed--this is still something humans do better than computers--and so we often need to edit a geometric model so that the triangles are 'flipped' the right way. Hence, the ``Flip triangle'' option in the ``Picking'' menu.

Edit node:

If your surface isn't perfect, you can edit the positions of the nodes. Select this pick mode in the Picking menu, and pick a node. A mark will appear on the node that you pick. Then use the keyboard transformation controls to translate a node (see Section 8.2.2, keypad controls). Note that keyboard rotation won't work in this mode.

Edit landmark point:

If your landmarks aren't perfect, you can edit their positions. Select this pick mode in the Picking menu, and pick a landmark point. A mark will appear on the point that you pick. Then use the keyboard transformation controls to translate it (see Section 8.2.2, keypad controls). Note that keyboard rotation won't work in this mode.

Delete node:

In this mode, any node you pick and any triangle that connects with it will be removed from the geometry.

Reference lead, single value:

In this mode, the value of the node you pick will be used as the reference from which the other nodes will be measured.

Reference lead, mean value:

In this mode, a mean value of all the nodes will be used as the reference from which the nodes will be measured.

8.7 Control of landmark display

Table 22: Landmark menus. These control landmark display options.

Landmarks Menus
Coronary/Catheter		toggle and select color for coronary/catheter
	Toggle Coronary	toggle coronary artery
	Toggle Catheter	toggle catheter display
	Wireframe Coronary	show coronary artery as wireframe and pt. numbers
	Coronary Color	select coronary color
	Catheter Color	select catheter color
Points		toggle and select color for point landmarks
	Toggle temporary occlusions	toggle temporary occlusion display
	Toggle permanent occlusions (stitch)	toggle stitch display
	Toggle stimulation site	toggle stim display
	Toggle recording site (lead)	toggle lead display
	Occlus Color	select occlus color
	Stitch Color	select stitch color
	Stim Color	select stim color
	Lead Color	select lead color
	Toggle All Points	turn on/off point landmarks
Planes		toggle and select color for plane landmarks
	Toggle Plane	toggle plane display
	Toggle Plane Transparency	make plane transparent or opaque
	Plane Color	select plane color
Points		toggle and select color for point landmarks
	Toggle rod	toggle rod display
	Toggle recording needle	toggle recneedle display
	Toggle pace needle	toggle pace needle display
	Toggle fiber (lead)	toggle fiber display
	Toggle cannula (lead)	toggle cannula display
	Rod Color	select rod color
	Recneedle Color	select recneedle color
	Paceneedle Color	select paceneedle color
	Fiber Color	select fiber color
	Cannula Color	select cannula color
	Toggle All Rods	turn on/off rod-type landmarks
Toggle All Landmarks	turn all landmarks on/off

There are some lighting and colour controls for the display of landmarks that are useful to know about. Table 22 describes all the specific menus mentioned here.

Coronary/Catheter:

these are controls to adjust color and visibility of the vessel type landmark, the ones we use for arteries and also for catheters. You can also switch from a rendered version of this landmark type to a wire mesh that is labeled according to segment numbers--a debugging tool when the vessels are not going where you expect.

Points:

there are a range of point types in the landmark suite and this option allows you to control them turn them off and on, adjust color, etc.

Planes:

for the plane landmark, you can set color, but also the transparency level of the plane. Default is transparent and this usually works best.

Rods:

as with points, there are different rod type landmarks and with this menu you can control their visibility and color.

Toggle all landmarks:

this is the master switch and toggling it turns all the landmarks from on to off or vice versa.